@snap-rail/plugin-kit 0.2.1 → 0.2.2

package/lib/build.js

@@ -173,7 +173,13 @@ function hostBundle(entry) {
 * subpath to its module namespace, and the shell seeds
 * `<package>/<subpath>` ids from that map after requiring the face.
 *
-* @param packageName - the plugin's npm name (the module id it registers as).
+* A package that renders in more than one window calls this once per surface:
+* the main surface keeps the package name as its module id and `client` as its
+* file name, while an auxiliary surface passes `outName` and `moduleId` so its
+* bundle lands beside the main one (`lib-client/ball.js`) and registers as
+* `<package>/ball` — the id that surface's window requires.
+*
+* @param packageName - the plugin's npm name (asset URLs and the default module id).
 * @param entry - the renderer entry source file.
 * @param options - see {@link ClientBundleOptions}.
 */
@@ -191,7 +197,7 @@ function clientBundle(packageName, entry, options = {}) {
 		}
 	};
 	return defineConfig({
-		entry: { client: entry },
+		entry: { [options.outName ?? "client"]: entry },
 		outDir: "lib-client",
 		format: ["cjs"],
 		platform: "browser",
@@ -208,7 +214,7 @@ function clientBundle(packageName, entry, options = {}) {
 			seedImportGuard()
 		],
 		outputOptions: {
-			banner: `window.__ModuleLoader__.load({ id: ${JSON.stringify(packageName)}, factory: function (require, module, exports) {`,
+			banner: `window.__ModuleLoader__.load({ id: ${JSON.stringify(options.moduleId ?? packageName)}, factory: function (require, module, exports) {`,
 			footer: "return module.exports && module.exports.__esModule === true && \"default\" in module.exports ? module.exports.default : module.exports; } });"
 		}
 	});

package/lib/manifest.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { AUX_SURFACE_IDS } from "@snap-rail/protocol";
 import { PLUGIN_LAYERS } from "@snap-rail/util/manifest";
 //#region lib/types/manifest.js
 /**
@@ -25,11 +26,29 @@ const seedAbiSchema = z.object({
 	/** Base-package versions of the seeds the bundle requires, by seed id. */
 	versions: z.record(z.string().min(1), z.string().min(1))
 }).strict();
+/**
+* The auxiliary-surface entry map: one client bundle per extra surface the
+* package renders in. Keys are the auxiliary surface ids (`ball`) —
+* `main` is deliberately absent, since the main window's bundle is
+* `client.entry` and a package gets exactly one entry per window. Every
+* declared path is a CJS factory bundle inside the package, packed and
+* validated like the main entry; the surfaces a package does not declare
+* simply have no face and show the kernel's plain fallback.
+*/
+const clientSurfacesSchema = z.partialRecord(z.enum(AUX_SURFACE_IDS), z.string().min(1));
 /** The renderer face declaration: where the client bundle lives. */
 const clientFaceSchema = z.object({
-	/** Path of the CJS factory bundle inside the package (from its root). */
+	/** Path of the CJS factory bundle inside the package (from its root) —
+	* the **main** surface's entry. */
 	entry: z.string().min(1).default("lib/client.js"),
 	/**
+	* Extra surfaces this package renders in: one client bundle per auxiliary
+	* window (`ball`). Each bundle is loaded into that surface's own
+	* window with the same seed table, and its module id is
+	* `<package>/<surface>` (the main entry keeps the plain package name).
+	*/
+	surfaces: clientSurfacesSchema.optional(),
+	/**
 	* Subpaths this client face registers as contributed seeds (e.g. framework
 	* primitives like `./ui`): each becomes a `__ModuleLoader__` id other
 	* plugins' client bundles may `require` — same instance, one execution.
@@ -119,4 +138,4 @@ const snapRailManifestSchema = z.object({
 	}).strict().optional()
 });
 //#endregion
-export { PLUGIN_KINDS, PLUGIN_LAYERS, clientFaceSchema, seedAbiSchema, snapRailManifestSchema };
+export { PLUGIN_KINDS, PLUGIN_LAYERS, clientFaceSchema, clientSurfacesSchema, seedAbiSchema, snapRailManifestSchema };

package/lib/pack.js

@@ -1,4 +1,5 @@
 import { CLIENT_EXTERNALS } from "./seeds.js";
+import { clientSurfacesSchema } from "./manifest.js";
 import { createRequire } from "node:module";
 import { readFile, readdir } from "node:fs/promises";
 import { join, relative } from "node:path";
@@ -64,22 +65,25 @@ function basePackageOf(seedId) {
 	return seedId.startsWith("@") ? parts.slice(0, 2).join("/") : parts[0];
 }
 /**
-* Stamp the seed ABI a built client face was built against: the seeds its
-* bundle actually requires (a `require("…")` literal scan — externals are
-* the only bare requires the welded CJS output carries) plus each seed's
-* base-package version resolved from the package's own dependency tree.
-* Ids whose base package cannot be resolved here are omitted — the runtime
-* check compares only the intersection, so an omitted id is unchecked,
-* never failed. Returns `undefined` when the bundle requires no seeds or
-* none could be versioned (nothing to enforce).
+* Stamp the seed ABI a set of built client faces were built against: the
+* seeds their bundles actually require (a `require("…")` literal scan —
+* externals are the only bare requires the welded CJS output carries) plus
+* each seed's base-package version resolved from the package's own dependency
+* tree. A multi-surface package stamps ONE declaration for all its entries
+* (the union of their requires): every surface shares the shell's seed table,
+* so a per-face stamp would only repeat the same verdict N times. Ids whose
+* base package cannot be resolved here are omitted — the runtime check
+* compares only the intersection, so an omitted id is unchecked, never
+* failed. Returns `undefined` when the bundles require no seeds or none could
+* be versioned (nothing to enforce).
 *
 * @param packageDir - the package being packed (version resolution root).
-* @param bundleCode - the built client bundle's source text.
+* @param bundleCodes - the built client bundles' source texts, one per surface.
 */
-async function seedAbiStamp(packageDir, bundleCode) {
+async function seedAbiStamp(packageDir, bundleCodes) {
 	const seeds = new Set(CLIENT_EXTERNALS);
 	const required = /* @__PURE__ */ new Set();
-	for (const match of bundleCode.matchAll(/require\(\s*(['"])([^'"\n]+)\1\s*\)/g)) {
+	for (const bundleCode of bundleCodes) for (const match of bundleCode.matchAll(/require\(\s*(['"])([^'"\n]+)\1\s*\)/g)) {
 		const id = match[2];
 		if (id !== void 0 && seeds.has(id)) required.add(id);
 	}
@@ -137,6 +141,12 @@ async function releaseFiles(spec) {
 	if (spec.hostFace !== void 0 && spec.hostDir === void 0) throw new Error(`pack: ${spec.name} declares a host face without a hostDir`);
 	if (spec.hostFace === void 0 && spec.clientFace === void 0) throw new Error(`pack: ${spec.name} ships neither a host face nor a client bundle`);
 	const clientEntry = typeof snapRail?.client?.entry === "string" ? snapRail.client.entry : "lib/client.js";
+	let clientSurfaces = {};
+	if (snapRail?.client?.surfaces !== void 0) {
+		const parsed = clientSurfacesSchema.safeParse(snapRail.client.surfaces);
+		if (!parsed.success) throw new Error(`pack: ${spec.name} declares an invalid snapRail.client.surfaces (${parsed.error.issues.map((issue) => issue.message).join("; ")})`);
+		clientSurfaces = parsed.data;
+	}
 	const main = spec.hostFace ?? clientEntry;
 	const files = {};
 	if (spec.hostDir !== void 0) {
@@ -146,7 +156,13 @@ async function releaseFiles(spec) {
 	if (spec.clientFace !== void 0) Object.assign(files, await collectDir(join(spec.dir, spec.clientFace), spec.dir));
 	if (spec.hostFace !== void 0 && files[spec.hostFace] === void 0) throw new Error(`pack: ${spec.name} is missing its host face ${spec.hostFace} under ${String(spec.hostDir)}`);
 	if (declaredClient && files[clientEntry] === void 0) throw new Error(`pack: ${spec.name} declares client entry ${clientEntry} but the zip does not carry it`);
-	const seedAbi = declaredClient && files[clientEntry] !== void 0 ? await seedAbiStamp(spec.dir, new TextDecoder().decode(files[clientEntry])) : void 0;
+	for (const [surface, entry] of Object.entries(clientSurfaces)) {
+		if (entry === void 0) continue;
+		if (files[entry] === void 0) throw new Error(`pack: ${spec.name} declares the ${surface} surface entry ${entry} but the zip does not carry it`);
+		if (entry === clientEntry) throw new Error(`pack: ${spec.name} points the ${surface} surface at the main client entry ${entry} — each surface needs its own bundle`);
+	}
+	const clientBundles = [clientEntry, ...Object.values(clientSurfaces)].filter((entry) => typeof entry === "string" && files[entry] !== void 0).map((entry) => new TextDecoder().decode(files[entry]));
+	const seedAbi = declaredClient && clientBundles.length > 0 ? await seedAbiStamp(spec.dir, clientBundles) : void 0;
 	files["package.json"] = new TextEncoder().encode(releaseManifest(source, main, spec.exports, seedAbi));
 	for (const [subpath, target] of Object.entries(spec.exports ?? {})) if (files[target] === void 0) throw new Error(`pack: ${spec.name} exports ${subpath} to ${target} but the zip does not carry it`);
 	for (const path of Object.keys(files)) if (path.startsWith("src/")) throw new Error(`pack: ${spec.name} would ship a source file (${path})`);

package/lib/seeds.js

@@ -39,6 +39,7 @@ const SEED_MODULES = [
 	"@snap-rail/client-modules",
 	"@snap-rail/connection",
 	"@snap-rail/protocol",
+	"@snap-rail/shell/contract",
 	"@snap-rail/station-rpc/contract",
 	"@snap-rail/app-boot/contract",
 	"@snap-rail/equipment/contract",

package/lib/types/build.d.ts

@@ -50,6 +50,21 @@ export interface ClientBundleOptions {
      * by the entry, so the bundle carries its own styling.
      */
     css?: readonly string[] | undefined;
+    /**
+     * The emitted file's base name inside `lib-client` (default `client`, so
+     * the file is `lib-client/client.js`). Auxiliary surfaces build one bundle
+     * per window and name them after the surface (`ball`); the
+     * manifest's `client.surfaces` points at those files.
+     */
+    outName?: string | undefined;
+    /**
+     * The module id the bundle registers under (default: the package name).
+     * A package's **main** surface registers as the package itself, so
+     * `createClientRuntime` can require it by row name; an auxiliary surface
+     * registers as `<package>/<surface>` — one package, several windows, no
+     * two bundles fighting over one id.
+     */
+    moduleId?: string | undefined;
 }
 /**
  * The client face: a CJS browser bundle welded into the module-loader
@@ -64,7 +79,13 @@ export interface ClientBundleOptions {
  * subpath to its module namespace, and the shell seeds
  * `<package>/<subpath>` ids from that map after requiring the face.
  *
- * @param packageName - the plugin's npm name (the module id it registers as).
+ * A package that renders in more than one window calls this once per surface:
+ * the main surface keeps the package name as its module id and `client` as its
+ * file name, while an auxiliary surface passes `outName` and `moduleId` so its
+ * bundle lands beside the main one (`lib-client/ball.js`) and registers as
+ * `<package>/ball` — the id that surface's window requires.
+ *
+ * @param packageName - the plugin's npm name (asset URLs and the default module id).
  * @param entry - the renderer entry source file.
  * @param options - see {@link ClientBundleOptions}.
  */

package/lib/types/manifest.d.ts

@@ -19,9 +19,24 @@ export declare const seedAbiSchema: z.ZodObject<{
     revision: z.ZodNumber;
     versions: z.ZodRecord<z.ZodString, z.ZodString>;
 }, z.core.$strict>;
+/**
+ * The auxiliary-surface entry map: one client bundle per extra surface the
+ * package renders in. Keys are the auxiliary surface ids (`ball`) —
+ * `main` is deliberately absent, since the main window's bundle is
+ * `client.entry` and a package gets exactly one entry per window. Every
+ * declared path is a CJS factory bundle inside the package, packed and
+ * validated like the main entry; the surfaces a package does not declare
+ * simply have no face and show the kernel's plain fallback.
+ */
+export declare const clientSurfacesSchema: z.ZodRecord<z.ZodEnum<{
+    ball: "ball";
+}> & z.core.$partial, z.ZodString>;
 /** The renderer face declaration: where the client bundle lives. */
 export declare const clientFaceSchema: z.ZodObject<{
     entry: z.ZodDefault<z.ZodString>;
+    surfaces: z.ZodOptional<z.ZodRecord<z.ZodEnum<{
+        ball: "ball";
+    }> & z.core.$partial, z.ZodString>>;
     seeds: z.ZodOptional<z.ZodArray<z.ZodString>>;
     externalSeeds: z.ZodOptional<z.ZodArray<z.ZodString>>;
     seedAbi: z.ZodOptional<z.ZodObject<{
@@ -52,6 +67,9 @@ export declare const snapRailManifestSchema: z.ZodObject<{
     clientOnly: z.ZodOptional<z.ZodBoolean>;
     client: z.ZodOptional<z.ZodObject<{
         entry: z.ZodDefault<z.ZodString>;
+        surfaces: z.ZodOptional<z.ZodRecord<z.ZodEnum<{
+            ball: "ball";
+        }> & z.core.$partial, z.ZodString>>;
         seeds: z.ZodOptional<z.ZodArray<z.ZodString>>;
         externalSeeds: z.ZodOptional<z.ZodArray<z.ZodString>>;
         seedAbi: z.ZodOptional<z.ZodObject<{

package/lib/types/pack.d.ts

@@ -20,6 +20,7 @@ interface SourceManifest {
         clientOnly?: unknown;
         client?: {
             entry?: unknown;
+            surfaces?: unknown;
         } | undefined;
     } & Record<string, unknown>;
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@snap-rail/plugin-kit",
   "description": "The plugin author's kit: snapRail manifest vocabulary, the renderer seed whitelist, tsdown presets for installable host + client faces, release signing, and the final-format packer",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "type": "module",
   "main": "lib/index.js",
   "types": "lib/types/index.d.ts",
@@ -58,6 +58,7 @@
   "dependencies": {
     "fflate": "^0.8.3",
     "zod": "^4.4.3",
+    "@snap-rail/protocol": "^0.1.3",
     "@snap-rail/util": "^0.1.2"
   },
   "peerDependencies": {