@serverkgg/bridge 0.0.4 → 0.0.6

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@serverkgg/bridge",
-	"version": "0.0.4",
+	"version": "0.0.6",
 	"description": "Serverk game bridge — driver runtime, wire protocol, manifest schema, and maintainer CLI",
 	"homepage": "https://serverk.gg",
 	"license": "SEE LICENSE IN LICENSE.md",

package/src/cli/validate.ts

@@ -15,7 +15,7 @@ import {
 } from "../manifest";
 import type { BridgeDriver } from "../modules";
 import { isBridgeEventName } from "../protocol";
-import { validateDriver } from "../runtime/bridgeDriver";
+import { validateDriver, validatePortActivation } from "../runtime/bridgeDriver";
 import { directorySource } from "./directorySource";
 
 const HELP = `serverk-bridge validate [options]
@@ -214,10 +214,13 @@ const validateGamePackage = async (source: PackageSource, manifest: Manifest, di
 	}
 
 	validateDriver(driver);
+	validatePortActivation(manifest.container.ports, driver);
+
+	const conditionalPorts = manifest.container.ports.filter((port) => port.activeWhen.length > 0).length;
 
 	console.log(`${manifest.metadata.id} is valid`);
 	console.log(
-		`  manifest: ${manifest.container.ports.length} port(s), ${manifest.secrets.length} secret(s), ${manifest.guides.length} guide(s)`,
+		`  manifest: ${manifest.container.ports.length} port(s), ${conditionalPorts} conditional, ${manifest.secrets.length} secret(s), ${manifest.guides.length} guide(s)`,
 	);
 	console.log(
 		`  assets: logo ${assets.logo.dimensions.width}x${assets.logo.dimensions.height}, banner ${assets.banner.dimensions.width}x${assets.banner.dimensions.height}`,

package/src/core/bridgeAction.ts

@@ -3,6 +3,7 @@ export enum BridgeAction {
 	Install = "install",
 	Installed = "installed",
 	List = "list",
+	Preview = "preview",
 	Quiesce = "quiesce",
 	Read = "read",
 	Release = "release",
@@ -16,6 +17,7 @@ export enum BridgeAction {
 export const BRIDGE_READ_ACTIONS: readonly string[] = [
 	BridgeAction.Installed,
 	BridgeAction.List,
+	BridgeAction.Preview,
 	BridgeAction.Read,
 	BridgeAction.Sample,
 	BridgeAction.Search,

package/src/core/bridgeKind.ts

@@ -9,6 +9,7 @@ export enum BridgeKind {
 	Install = "install",
 	Lifecycle = "lifecycle",
 	Options = "options",
+	Preview = "preview",
 	Query = "query",
 	Settings = "settings",
 }

package/src/core/bridgePort.ts

@@ -2,3 +2,8 @@ export enum PortProtocol {
 	Tcp = "tcp",
 	Udp = "udp",
 }
+
+export enum PortJoin {
+	Combined = "combined",
+	Separate = "separate",
+}

package/src/manifest/manifest.test.ts

@@ -1,5 +1,6 @@
 import { describe, expect, test } from "bun:test";
 import { z } from "zod";
+import { PortJoin } from "../core";
 import { GameCategory } from "./category";
 import { guidePackageSchema, MANIFEST_SCHEMA_VERSION, manifestSchema, packageSchema } from "./manifest";
 
@@ -55,6 +56,40 @@ const failure = (input: unknown) => {
 	}));
 };
 
+const withPort = (extra: Record<string, unknown>) => {
+	const manifest = base();
+	const [game] = manifest.container.ports;
+
+	if (!game) {
+		throw new Error("fixture is missing its port");
+	}
+
+	return {
+		...manifest,
+		container: {
+			...manifest.container,
+			ports: [
+				{
+					...game,
+					...extra,
+				},
+			],
+		},
+	};
+};
+
+const withPortSrv = (srv: unknown) => {
+	return withPort({
+		srv,
+	});
+};
+
+const withPortActiveWhen = (activeWhen: unknown) => {
+	return withPort({
+		activeWhen,
+	});
+};
+
 describe("defaults", () => {
 	test("fills in the optional sections so consumers never guard", () => {
 		const manifest = manifestSchema.parse(base());
@@ -72,6 +107,193 @@ describe("defaults", () => {
 		});
 		expect(manifest.guides).toEqual([]);
 		expect(manifest.secrets).toEqual([]);
+		expect(manifest.container.ports[0]?.srv).toBeUndefined();
+		expect(manifest.container.ports[0]?.name).toBeUndefined();
+		expect(manifest.container.ports[0]?.hint).toBeUndefined();
+		expect(manifest.container.ports[0]?.join).toBe(PortJoin.Combined);
+		expect(manifest.container.ports[0]?.activeWhen).toEqual([]);
+	});
+});
+
+describe("port presentation", () => {
+	test("keeps the localized name, hint and join style a port declares", () => {
+		const manifest = manifestSchema.parse(
+			withPort({
+				name: {
+					ar: "بيدروك",
+					en: "Bedrock",
+				},
+				hint: {
+					ar: "العنوان في خانة والمنفذ في خانة ثانية",
+					en: "Address and port go in separate fields",
+				},
+				join: "separate",
+			}),
+		);
+
+		expect(manifest.container.ports[0]?.name).toEqual({
+			ar: "بيدروك",
+			en: "Bedrock",
+		});
+		expect(manifest.container.ports[0]?.hint?.en).toBe("Address and port go in separate fields");
+		expect(manifest.container.ports[0]?.join).toBe(PortJoin.Separate);
+	});
+
+	test("rejects a port name missing one language", () => {
+		expect(
+			failure(
+				withPort({
+					name: {
+						en: "Bedrock",
+					},
+				}),
+			),
+		).toEqual([
+			{
+				path: "container.ports.0.name.ar",
+				message: "Invalid input: expected string, received undefined",
+			},
+		]);
+	});
+});
+
+describe("port srv", () => {
+	test("keeps the service label a port declares", () => {
+		const manifest = manifestSchema.parse(
+			withPortSrv({
+				service: "_minecraft",
+			}),
+		);
+
+		expect(manifest.container.ports[0]?.srv).toEqual({
+			service: "_minecraft",
+		});
+	});
+
+	test("rejects a service label without its underscore", () => {
+		expect(
+			failure(
+				withPortSrv({
+					service: "minecraft",
+				}),
+			),
+		).toEqual([
+			{
+				path: "container.ports.0.srv.service",
+				message: "must be an underscore-prefixed service label such as _minecraft",
+			},
+		]);
+	});
+});
+
+describe("port activeWhen", () => {
+	test("keeps every condition a port declares", () => {
+		const manifest = manifestSchema.parse(
+			withPortActiveWhen([
+				{
+					variable: "SERVER_TYPE",
+					values: [
+						"paper",
+						"fabric",
+					],
+				},
+				{
+					variable: "CROSSPLAY",
+					values: [
+						"true",
+					],
+				},
+			]),
+		);
+
+		expect(manifest.container.ports[0]?.activeWhen).toEqual([
+			{
+				variable: "SERVER_TYPE",
+				values: [
+					"paper",
+					"fabric",
+				],
+			},
+			{
+				variable: "CROSSPLAY",
+				values: [
+					"true",
+				],
+			},
+		]);
+	});
+
+	test("rejects a condition that declares neither values nor empty", () => {
+		expect(
+			failure(
+				withPortActiveWhen([
+					{
+						variable: "CROSSPLAY",
+					},
+				]),
+			),
+		).toEqual([
+			{
+				path: "container.ports.0.activeWhen.0",
+				message: "declare values, empty, or both",
+			},
+		]);
+	});
+
+	test("rejects a condition whose values list is empty", () => {
+		expect(
+			failure(
+				withPortActiveWhen([
+					{
+						variable: "CROSSPLAY",
+						values: [],
+					},
+				]),
+			),
+		).toEqual([
+			{
+				path: "container.ports.0.activeWhen.0.values",
+				message: "Too small: expected array to have >=1 items",
+			},
+		]);
+	});
+
+	test("rejects a fifth condition", () => {
+		expect(
+			failure(
+				withPortActiveWhen(
+					Array.from({
+						length: 5,
+					}).map((_entry, index) => ({
+						variable: `RULE_${index}`,
+						empty: false,
+					})),
+				),
+			),
+		).toEqual([
+			{
+				path: "container.ports.0.activeWhen",
+				message: "Too big: expected array to have <=4 items",
+			},
+		]);
+	});
+
+	test("rejects a variable that is not an environment key", () => {
+		expect(
+			failure(
+				withPortActiveWhen([
+					{
+						variable: "crossplay",
+						empty: false,
+					},
+				]),
+			),
+		).toEqual([
+			{
+				path: "container.ports.0.activeWhen.0.variable",
+				message: "must be SCREAMING_SNAKE_CASE, starting with a letter",
+			},
+		]);
 	});
 });
 

package/src/manifest/manifest.ts

@@ -1,6 +1,7 @@
 import { z } from "zod";
-import { PortProtocol } from "../core";
+import { PortJoin, PortProtocol } from "../core";
 import { BridgeIcon } from "../panel/bridgeIcon";
+import { BRIDGE_OPTION_VALUE_LENGTH_LIMIT, BRIDGE_VISIBLE_VALUES_LIMIT } from "../protocol/bridgeLimits";
 import { GameCategory } from "./category";
 import { type GuideEntry, type GuideTag, guideEntrySchema, guideTagSchema } from "./guide";
 import { IMAGE_NAMESPACE } from "./image";
@@ -34,6 +35,20 @@ const manifestHostRangeSchema = z
 
 export type ManifestHostRange = z.infer<typeof manifestHostRangeSchema>;
 
+const manifestPortActivationSchema = z
+	.object({
+		variable: zEnvKey,
+		values: z
+			.array(z.string().min(1).max(BRIDGE_OPTION_VALUE_LENGTH_LIMIT))
+			.min(1)
+			.max(BRIDGE_VISIBLE_VALUES_LIMIT)
+			.optional(),
+		empty: z.boolean().optional(),
+	})
+	.refine((rule) => rule.values !== undefined || rule.empty !== undefined, "declare values, empty, or both");
+
+export type ManifestPortActivation = z.infer<typeof manifestPortActivationSchema>;
+
 const manifestPortSchema = z.object({
 	key: z
 		.string()
@@ -43,6 +58,30 @@ const manifestPortSchema = z.object({
 	containerPort: zPort,
 	protocol: z.enum(PortProtocol).default(PortProtocol.Tcp),
 	hostRange: manifestHostRangeSchema,
+	name: localizedText(48).optional().meta({
+		description: "Player-facing name of this port, such as Java or Bedrock. The key is shown when omitted.",
+	}),
+	hint: localizedText(160).optional().meta({
+		description: "One short line telling the player where this address goes in the game client.",
+	}),
+	join: z.enum(PortJoin).default(PortJoin.Combined).meta({
+		description: "How the game client takes the address: combined as host:port, or separate address and port fields.",
+	}),
+	srv: z
+		.object({
+			service: z
+				.string()
+				.regex(/^_[a-z0-9-]{1,15}$/, "must be an underscore-prefixed service label such as _minecraft"),
+		})
+		.optional()
+		.meta({
+			description:
+				"Publishes this port as an SRV record under the server hostname, so players join by name with no port.",
+		}),
+	activeWhen: z.array(manifestPortActivationSchema).max(4).default([]).meta({
+		description:
+			"Conditions on the server's variables that must all hold for the game to listen on this port. The port is still allocated; the panel hides the address otherwise.",
+	}),
 });
 
 export type ManifestPort = z.infer<typeof manifestPortSchema>;

package/src/modules/bridge.ts

@@ -9,6 +9,7 @@ import type {
 	BridgeCatalogProvider,
 	BridgeCatalogQuery,
 } from "../protocol/bridgeCatalog";
+import type { BridgePreview } from "../protocol/bridgePreview";
 import type { BridgeTerminalArg, BridgeTerminalCommand, BridgeTerminalRule } from "../terminal";
 import type { BridgeDriver } from "./bridgeDriver";
 import type {
@@ -22,6 +23,7 @@ import type {
 	BridgeInstallModule,
 	BridgeLifecycleModule,
 	BridgeOptionsModule,
+	BridgePreviewModule,
 	BridgeQueryModule,
 	BridgeRowAction,
 	BridgeSample,
@@ -54,6 +56,8 @@ export namespace Bridge {
 	export type Option = BridgeOption;
 	export type Options = BridgeOptionsModule;
 	export type Panel = BridgePanel;
+	export type Preview = BridgePreviewModule;
+	export type PreviewResult = BridgePreview;
 	export type Query = BridgeQueryModule;
 	export type Reply = BridgeReply;
 	export type Row = BridgeRow;

package/src/modules/bridgeModule.ts

@@ -2,6 +2,7 @@ import type { BridgeContext } from "../context";
 import type { BridgeKind, BridgeOption, BridgeRow, BridgeStream, BridgeValues } from "../core";
 import type { BridgeCatalogEntry, BridgeCatalogPage, BridgeCatalogQuery } from "../protocol/bridgeCatalog";
 import type { BridgeDescribeResult } from "../protocol/bridgeFrame";
+import type { BridgePreview } from "../protocol/bridgePreview";
 import type { BridgeTerminalCommand, BridgeTerminalRule } from "../terminal";
 
 export type BridgeDescription = Omit<BridgeDescribeResult, "supported">;
@@ -69,6 +70,11 @@ export interface BridgeOptionsModule {
 	list(context: BridgeContext): Promise<BridgeOption[]>;
 }
 
+export interface BridgePreviewModule {
+	kind: BridgeKind.Preview;
+	preview(context: BridgeContext, values: BridgeValues): Promise<BridgePreview>;
+}
+
 export interface BridgeSettingsModule {
 	kind: BridgeKind.Settings;
 	read(context: BridgeContext): Promise<BridgeValues>;
@@ -113,6 +119,7 @@ export type BridgePanelModule =
 	| BridgeCatalogModule
 	| BridgeCollectionModule
 	| BridgeOptionsModule
+	| BridgePreviewModule
 	| BridgeSettingsModule;
 
 export type BridgeModule =

package/src/panel/bridgePanel.ts

@@ -16,6 +16,10 @@ export interface BridgeOptionsRef {
 	module: string;
 }
 
+export interface BridgePreviewRef {
+	module: string;
+}
+
 export interface BridgeField {
 	key: string;
 	control: BridgeControl;
@@ -68,6 +72,7 @@ export interface BridgeFormSection {
 	title?: LocalizedText;
 	target: BridgeFormTarget;
 	module?: string;
+	preview?: BridgePreviewRef;
 	reinstall?: boolean;
 	restartHint?: boolean;
 	confirm?: BridgeConfirm;

package/src/protocol/bridgeLimits.ts

@@ -16,6 +16,8 @@ export const BRIDGE_FIELD_OPTIONS_LIMIT = 64;
 
 export const BRIDGE_VISIBLE_VALUES_LIMIT = 16;
 
+export const BRIDGE_PREVIEW_LINES_LIMIT = 8;
+
 export const BRIDGE_UPLOAD_EXTENSIONS_LIMIT = 8;
 
 export const BRIDGE_MODULES_LIMIT = 32;

package/src/protocol/bridgePreview.ts

@@ -0,0 +1,7 @@
+import type { LocalizedText } from "../core";
+import type { BridgeConfirm } from "../panel";
+
+export interface BridgePreview {
+	confirm: BridgeConfirm;
+	lines: LocalizedText[];
+}

package/src/protocol/index.ts

@@ -9,4 +9,5 @@ export * from "./bridgeFrame";
 export * from "./bridgeLimits";
 export * from "./bridgeLine";
 export * from "./bridgeManifest";
+export * from "./bridgePreview";
 export * from "./bridgeVersion";

package/src/runtime/bridgeActions.ts

@@ -13,6 +13,12 @@ export const actionsOf = (module: BridgePanelModule): string[] => {
 			];
 		}
 
+		case BridgeKind.Preview: {
+			return [
+				BridgeAction.Preview,
+			];
+		}
+
 		case BridgeKind.Settings: {
 			return [
 				BridgeAction.Read,

package/src/runtime/bridgeDriver.test.ts

@@ -1,7 +1,9 @@
 import { describe, expect, test } from "bun:test";
-import { BridgeKind } from "../core";
+import { BridgeKind, PortJoin, PortProtocol } from "../core";
+import type { ManifestPort, ManifestPortActivation } from "../manifest";
 import type { BridgeDriver } from "../modules";
 import {
+	BridgeConfirm,
 	BridgeControl,
 	type BridgeField,
 	BridgeFormTarget,
@@ -9,7 +11,7 @@ import {
 	type BridgeSectionAction,
 	type BridgeVisibleWhen,
 } from "../panel";
-import { validateDriver } from "./bridgeDriver";
+import { validateDriver, validatePortActivation } from "./bridgeDriver";
 
 const text = (value: string) => ({
 	ar: value,
@@ -110,6 +112,124 @@ const formSection = (id: string, fields: BridgeField[]) => ({
 	fields,
 });
 
+const driverWithPreview = (): BridgeDriver => ({
+	install: {
+		kind: BridgeKind.Install,
+		run: async () => {
+			return;
+		},
+	},
+	lifecycle: {
+		kind: BridgeKind.Lifecycle,
+		command: async () => [
+			"run",
+		],
+	},
+	modules: {
+		transition: {
+			kind: BridgeKind.Preview,
+			preview: async () => ({
+				confirm: BridgeConfirm.Normal,
+				lines: [],
+			}),
+		},
+	},
+	panel: {
+		tabs: [
+			{
+				id: "version",
+				title: text("Version"),
+				sections: [
+					{
+						...formSection("version", [
+							field("MC_VERSION"),
+						]),
+						preview: {
+							module: "transition",
+						},
+					},
+				],
+			},
+		],
+	},
+});
+
+const formSectionOf = (driver: BridgeDriver) => {
+	const [section] = driver.panel?.tabs[0]?.sections ?? [];
+
+	if (!section || section.layout !== BridgeLayout.Form) {
+		throw new Error("fixture is missing its form section");
+	}
+
+	return section;
+};
+
+const driverWithVariables = (): BridgeDriver => ({
+	install: {
+		kind: BridgeKind.Install,
+		run: async () => {
+			return;
+		},
+	},
+	lifecycle: {
+		kind: BridgeKind.Lifecycle,
+		command: async () => [
+			"run",
+		],
+	},
+	modules: {
+		modpacks: {
+			kind: BridgeKind.Catalog,
+			search: async () => ({
+				hits: [],
+				total: 0,
+				providers: [],
+				categories: [],
+				sorts: [],
+			}),
+			installed: async () => [],
+			install: async () => {
+				throw new Error("not installable in the fixture");
+			},
+			remove: async () => {
+				return;
+			},
+		},
+	},
+	panel: {
+		tabs: [
+			{
+				id: "version",
+				title: text("Version"),
+				sections: [
+					formSection("version", [
+						field("MC_VERSION"),
+					]),
+					{
+						layout: BridgeLayout.Catalog,
+						id: "modpacks",
+						module: "modpacks",
+						variable: "MODPACK",
+					},
+				],
+			},
+		],
+	},
+});
+
+const port = (activeWhen: ManifestPortActivation[]): ManifestPort => ({
+	key: "bedrock",
+	containerPort: 19_132,
+	protocol: PortProtocol.Udp,
+	hostRange: {
+		default: 19_132,
+		min: 19_132,
+		max: 19_232,
+	},
+	join: PortJoin.Combined,
+	activeWhen,
+});
+
 const driverWithTabs = (tabs: number, sections: number): BridgeDriver => ({
 	install: {
 		kind: BridgeKind.Install,
@@ -448,3 +568,85 @@ describe("visibleWhen", () => {
 		expect(() => validateDriver(driver)).toThrow('field "MC_VERSION" is visible when "SERVER_TYPE" matches nothing');
 	});
 });
+
+describe("form preview", () => {
+	test("accepts a variables form pointing at a preview module", () => {
+		expect(() => validateDriver(driverWithPreview())).not.toThrow();
+	});
+
+	test("rejects a preview ref to a module that is not a preview module", () => {
+		const driver = driverWithPreview();
+
+		driver.modules = {
+			transition: {
+				kind: BridgeKind.Settings,
+				read: async () => ({}),
+			},
+		};
+
+		expect(() => validateDriver(driver)).toThrow('references "transition", which is not a preview module');
+	});
+
+	test("rejects a preview on a form that writes settings", () => {
+		const driver = driverWithPreview();
+		const section = formSectionOf(driver);
+
+		section.target = BridgeFormTarget.Settings;
+		section.module = "config";
+
+		driver.modules = {
+			...driver.modules,
+			config: {
+				kind: BridgeKind.Settings,
+				read: async () => ({}),
+				write: async () => {
+					return;
+				},
+			},
+		};
+
+		expect(() => validateDriver(driver)).toThrow("declares a preview but does not target variables");
+	});
+});
+
+describe("validatePortActivation", () => {
+	test("accepts a variable a variables form or a catalog section declares", () => {
+		expect(() =>
+			validatePortActivation(
+				[
+					port([
+						{
+							variable: "MC_VERSION",
+							values: [
+								"26.2",
+							],
+						},
+						{
+							variable: "MODPACK",
+							empty: true,
+						},
+					]),
+				],
+				driverWithVariables(),
+			),
+		).not.toThrow();
+	});
+
+	test("rejects a variable nothing in the panel declares", () => {
+		expect(() =>
+			validatePortActivation(
+				[
+					port([
+						{
+							variable: "CROSSPLAY",
+							values: [
+								"true",
+							],
+						},
+					]),
+				],
+				driverWithVariables(),
+			),
+		).toThrow('port "bedrock" activeWhen[0] names "CROSSPLAY", which no variables form or catalog declares');
+	});
+});

package/src/runtime/bridgeDriver.ts

@@ -1,4 +1,5 @@
 import { BRIDGE_ID_PATTERN, BRIDGE_MODULE_ID_PATTERN, BridgeKind, type LocalizedText } from "../core";
+import type { ManifestPort } from "../manifest";
 import type { BridgeDriver, BridgePanelModule } from "../modules";
 import {
 	type BridgeField,
@@ -237,6 +238,18 @@ const validateSection = (modules: Record<string, BridgePanelModule>, section: Br
 				}
 			}
 
+			if (section.preview) {
+				if (section.target !== BridgeFormTarget.Variables) {
+					fail(`${where} declares a preview but does not target variables`);
+				}
+
+				const preview = moduleOf(modules, section.preview.module, where);
+
+				if (preview.kind !== BridgeKind.Preview) {
+					fail(`${where} references "${section.preview.module}", which is not a preview module`);
+				}
+			}
+
 			validateText(section.confirmText, "confirm text", where);
 
 			if (section.fields.length === 0) {
@@ -417,3 +430,39 @@ export const validateDriver = (driver: BridgeDriver) => {
 		validateTab(modules, tab);
 	}
 };
+
+const declaredVariables = (driver: BridgeDriver) => {
+	const declared = new Set<string>();
+
+	for (const tab of driver.panel?.tabs ?? []) {
+		for (const section of tab.sections) {
+			if (section.layout === BridgeLayout.Form && section.target === BridgeFormTarget.Variables) {
+				for (const field of section.fields) {
+					declared.add(field.key);
+				}
+			}
+
+			if (section.layout === BridgeLayout.Catalog && section.variable) {
+				declared.add(section.variable);
+			}
+		}
+	}
+
+	return declared;
+};
+
+export const validatePortActivation = (ports: ManifestPort[], driver: BridgeDriver): void => {
+	const declared = declaredVariables(driver);
+
+	for (const port of ports) {
+		for (const [index, rule] of port.activeWhen.entries()) {
+			if (declared.has(rule.variable)) {
+				continue;
+			}
+
+			fail(
+				`port "${port.key}" activeWhen[${index}] names "${rule.variable}", which no variables form or catalog declares`,
+			);
+		}
+	}
+};

package/src/runtime/bridgeRegistry.test.ts

@@ -2,7 +2,7 @@ import { describe, expect, test } from "bun:test";
 import { tmpdir } from "node:os";
 import { BridgeAction, BridgeKind, type BridgeRow, type BridgeValues } from "../core";
 import type { BridgeDriver } from "../modules";
-import { type BridgeConfig, BridgeEventName } from "../protocol";
+import { type BridgeConfig, BridgeConfirm, BridgeEventName } from "../protocol";
 import { createContext } from "./bridgeContext";
 import { createEventRing } from "./bridgeEvents";
 import { log } from "./bridgeLog";
@@ -38,8 +38,11 @@ const baseDriver = (): BridgeDriver => ({
 	},
 });
 
-const registryFor = (driver: BridgeDriver) => {
-	const settings = config();
+const registryFor = (driver: BridgeDriver, variables: Record<string, string> = {}) => {
+	const settings = {
+		...config(),
+		variables,
+	};
 
 	const supervisor = createSupervisor({
 		cwd: settings.cwd,
@@ -289,3 +292,137 @@ describe("collection row actions", () => {
 		]);
 	});
 });
+
+describe("preview modules", () => {
+	test("lists the preview action in the manifest", () => {
+		const registry = registryFor({
+			...baseDriver(),
+			modules: {
+				transition: {
+					kind: BridgeKind.Preview,
+					preview: async () => ({
+						confirm: BridgeConfirm.Normal,
+						lines: [],
+					}),
+				},
+			},
+		});
+
+		expect(registry.manifest().modules).toEqual([
+			{
+				id: "transition",
+				kind: BridgeKind.Preview,
+				requiresRunning: false,
+				refreshSeconds: null,
+				pageSize: null,
+				dependsOn: [],
+				actions: [
+					BridgeAction.Preview,
+				],
+			},
+		]);
+	});
+
+	test("shows the module the pending values as variables and leaves the rest as they are stored", async () => {
+		const seen: {
+			version: string | null;
+			count: string | null;
+			type: string | null;
+			args: BridgeValues;
+		}[] = [];
+
+		const registry = registryFor(
+			{
+				...baseDriver(),
+				modules: {
+					transition: {
+						kind: BridgeKind.Preview,
+						preview: async (context, values) => {
+							seen.push({
+								version: context.variable("MC_VERSION"),
+								count: context.variable("n"),
+								type: context.variable("SERVER_TYPE"),
+								args: values,
+							});
+
+							return {
+								confirm: BridgeConfirm.Strong,
+								lines: [],
+							};
+						},
+					},
+				},
+			},
+			{
+				MC_VERSION: "26.2",
+				SERVER_TYPE: "paper",
+			},
+		);
+
+		await registry.invoke("transition", BridgeAction.Preview, {
+			MC_VERSION: "1.21",
+			n: 3,
+		});
+
+		expect(seen).toEqual([
+			{
+				version: "1.21",
+				count: null,
+				type: "paper",
+				args: {
+					MC_VERSION: "1.21",
+					n: 3,
+				},
+			},
+		]);
+	});
+
+	test("returns what the module answers", async () => {
+		const registry = registryFor({
+			...baseDriver(),
+			modules: {
+				transition: {
+					kind: BridgeKind.Preview,
+					preview: async () => ({
+						confirm: BridgeConfirm.Strong,
+						lines: [
+							{
+								ar: "عالمك يبقى",
+								en: "Your world stays",
+							},
+						],
+					}),
+				},
+			},
+		});
+
+		expect(await registry.invoke("transition", BridgeAction.Preview)).toEqual({
+			confirm: BridgeConfirm.Strong,
+			lines: [
+				{
+					ar: "عالمك يبقى",
+					en: "Your world stays",
+				},
+			],
+		});
+	});
+
+	test("refuses an action a preview module does not answer", async () => {
+		const registry = registryFor({
+			...baseDriver(),
+			modules: {
+				transition: {
+					kind: BridgeKind.Preview,
+					preview: async () => ({
+						confirm: BridgeConfirm.Normal,
+						lines: [],
+					}),
+				},
+			},
+		});
+
+		await expect(registry.invoke("transition", BridgeAction.Read)).rejects.toThrow(
+			'module "transition" does not support "read"',
+		);
+	});
+});

package/src/runtime/bridgeRegistry.ts

@@ -228,6 +228,24 @@ export const createRegistry = (
 				break;
 			}
 
+			case BridgeKind.Preview: {
+				if (action === BridgeAction.Preview) {
+					const overlay: Record<string, string> = {};
+
+					for (const [key, value] of Object.entries(args)) {
+						if (typeof value === "string") {
+							overlay[key] = value;
+						}
+					}
+
+					const scoped = withVariables(context, overlay);
+
+					return await module.preview(scoped, args);
+				}
+
+				break;
+			}
+
 			case BridgeKind.Settings: {
 				if (action === BridgeAction.Read) {
 					return await module.read(context);