@snap-rail/plugin-kit 0.2.0 → 0.2.2

package/lib/build.js

@@ -156,7 +156,8 @@ function hostBundle(entry) {
 		platform: "node",
 		target: "es2024",
 		dts: false,
-		clean: false
+		clean: false,
+		fixedExtension: false
 	});
 }
 /**
@@ -172,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}.
 */
@@ -190,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",
@@ -207,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/index.js

@@ -1,7 +1,7 @@
 import { CLIENT_EXTERNALS, CONTRIBUTED_SEED_MODULES, SEED_ABI_REVISION, SEED_MODULES, checkSeedAbi } from "./seeds.js";
 import { clientBundle, hostBundle, seedImportGuard } from "./build.js";
 import { PLUGIN_KINDS, clientFaceSchema, seedAbiSchema, snapRailManifestSchema } from "./manifest.js";
-import { releaseFiles, releaseManifest, zipFileName } from "./pack.js";
+import { catalogEntryFromZip, releaseFiles, releaseManifest, zipFileName } from "./pack.js";
 import { packageNameOf, recipeDocumentSchema, recipePackageNames, recipeRowSchema } from "./recipe.js";
 import { RELEASE_METADATA_PATH, RELEASE_SIGNATURE_PATH, canonicalJson, releaseMetadata, sha256, signReleaseFiles, signReleaseMetadata, verifyReleaseFiles } from "./sign.js";
 //#region lib/types/slot-vocabulary.js
@@ -40,4 +40,4 @@ function defineSlotVocabulary(ids, options) {
 	};
 }
 //#endregion
-export { CLIENT_EXTERNALS, CONTRIBUTED_SEED_MODULES, CUSTOM_SLOT_PATTERN, PLUGIN_KINDS, RELEASE_METADATA_PATH, RELEASE_SIGNATURE_PATH, SEED_ABI_REVISION, SEED_MODULES, canonicalJson, checkSeedAbi, clientBundle, clientFaceSchema, defineSlotVocabulary, hostBundle, packageNameOf, recipeDocumentSchema, recipePackageNames, recipeRowSchema, releaseFiles, releaseManifest, releaseMetadata, seedAbiSchema, seedImportGuard, sha256, signReleaseFiles, signReleaseMetadata, snapRailManifestSchema, verifyReleaseFiles, zipFileName };
+export { CLIENT_EXTERNALS, CONTRIBUTED_SEED_MODULES, CUSTOM_SLOT_PATTERN, PLUGIN_KINDS, RELEASE_METADATA_PATH, RELEASE_SIGNATURE_PATH, SEED_ABI_REVISION, SEED_MODULES, canonicalJson, catalogEntryFromZip, checkSeedAbi, clientBundle, clientFaceSchema, defineSlotVocabulary, hostBundle, packageNameOf, recipeDocumentSchema, recipePackageNames, recipeRowSchema, releaseFiles, releaseManifest, releaseMetadata, seedAbiSchema, seedImportGuard, sha256, signReleaseFiles, signReleaseMetadata, snapRailManifestSchema, verifyReleaseFiles, zipFileName };

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,7 +1,10 @@
 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";
+import { createHash } from "node:crypto";
+import { unzipSync } from "fflate";
 //#region lib/types/pack.js
 /**
 * Final-format assembly: turn a built plugin package into the file set of
@@ -62,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);
 	}
@@ -135,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) {
@@ -144,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})`);
@@ -154,5 +172,50 @@ async function releaseFiles(spec) {
 function zipFileName(packageName) {
 	return `${packageName.replaceAll("/", "__")}.zip`;
 }
+/**
+* The one feed-entry emitter every producer shares: read a plugin zip's own
+* bytes back (release manifest + signature envelope), derive the
+* `index.json` entry from exactly what the zip carries, and digest the exact
+* bytes the client will download — the feed can never advertise something a
+* zip does not. The repo's pack/collect pipeline and the standalone
+* `snap-rail-plugin feed` command all converge here.
+*
+* @param zipped - the exact zip bytes the feed will serve.
+* @param file - the pure file name the entry advertises (no path).
+* @param fallbackName - the entry's name when the manifest carries none.
+* @param options.requireSignature - refuse unsigned zips (feed policy).
+* @param options.repository - an optional source-repository URL.
+* @returns the entry, unknown fields stripped by construction.
+* @throws when the zip has no readable manifest, or no signature while
+*   `requireSignature` is set.
+*/
+function catalogEntryFromZip(zipped, file, fallbackName, options = {}) {
+	const files = unzipSync(zipped);
+	const manifestFile = files["package.json"];
+	if (manifestFile === void 0) throw new Error(`catalog: ${file} 缺少 package.json`);
+	const manifest = JSON.parse(new TextDecoder().decode(manifestFile));
+	const signatureFile = files["META-INF/signature.json"];
+	if (signatureFile === void 0 && options.requireSignature === true) throw new Error(`catalog: ${file} 没有签名（META-INF/signature.json 缺失）`);
+	const signature = signatureFile === void 0 ? void 0 : JSON.parse(new TextDecoder().decode(signatureFile));
+	return {
+		name: manifest.name ?? fallbackName,
+		version: manifest.version ?? "0.0.0",
+		...manifest.description !== void 0 && manifest.description !== "" ? { description: manifest.description } : {},
+		...manifest.snapRail?.kind !== void 0 ? { kind: manifest.snapRail.kind } : {},
+		...manifest.snapRail?.title !== void 0 ? { title: manifest.snapRail.title } : {},
+		...manifest.snapRail?.category !== void 0 ? { category: manifest.snapRail.category } : {},
+		...manifest.snapRail?.requires !== void 0 ? { requires: manifest.snapRail.requires } : {},
+		...manifest.snapRail?.permissions !== void 0 ? { permissions: manifest.snapRail.permissions } : {},
+		...manifest.snapRail?.engines !== void 0 ? { engines: manifest.snapRail.engines } : {},
+		file,
+		sha256: createHash("sha256").update(zipped).digest("hex"),
+		size: zipped.length,
+		...signature === void 0 ? {} : { signature: {
+			algorithm: signature.algorithm,
+			keyId: signature.keyId
+		} },
+		...options.repository === void 0 ? {} : { repository: options.repository }
+	};
+}
 //#endregion
-export { releaseFiles, releaseManifest, zipFileName };
+export { catalogEntryFromZip, releaseFiles, releaseManifest, zipFileName };

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/index.d.ts

@@ -12,7 +12,7 @@ export { SEED_MODULES } from './seeds.ts';
 export { CLIENT_EXTERNALS, CONTRIBUTED_SEED_MODULES, SEED_ABI_REVISION, checkSeedAbi, type SeedAbi, type SeedAbiVerdict, } from './seeds.ts';
 export { clientBundle, hostBundle, seedImportGuard } from './build.ts';
 export { CUSTOM_SLOT_PATTERN, defineSlotVocabulary, type SlotIdOf, type SlotVocabulary, } from './slot-vocabulary.ts';
-export { releaseFiles, releaseManifest, zipFileName, type ReleaseSpec } from './pack.ts';
+export { catalogEntryFromZip, releaseFiles, releaseManifest, zipFileName, type FeedEntry, type ReleaseSpec } from './pack.ts';
 export { packageNameOf, recipeDocumentSchema, recipePackageNames, recipeRowSchema, type RecipeDocument, type RecipeRow, } from './recipe.ts';
 export { RELEASE_METADATA_PATH, RELEASE_SIGNATURE_PATH, canonicalJson, releaseMetadata, sha256, signReleaseFiles, signReleaseMetadata, verifyReleaseFiles, type ReleaseFileDigests, type ReleaseMetadata, type ReleaseSignature, type TrustedReleaseKey, } from './sign.ts';
 //# sourceMappingURL=index.d.ts.map

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>;
 }
@@ -75,5 +76,51 @@ export declare function releaseManifest(source: SourceManifest, main: string, ex
 export declare function releaseFiles(spec: ReleaseSpec): Promise<Record<string, Uint8Array>>;
 /** The zip file name a package's release takes under dist-plugins/. */
 export declare function zipFileName(packageName: string): string;
+/** One plugin entry the feed's `index.json` carries (feed facts only). */
+export interface FeedEntry {
+    name: string;
+    version: string;
+    description?: string;
+    kind?: string;
+    title?: string;
+    category?: string;
+    requires?: string[];
+    permissions?: string[];
+    engines?: {
+        snapRail?: string;
+        hostProtocol?: string;
+        renderer?: string;
+    };
+    /** The pure file name the entry advertises (no path). */
+    file: string;
+    sha256: string;
+    size: number;
+    signature?: {
+        algorithm: 'Ed25519';
+        keyId: string;
+    };
+    repository?: string;
+}
+/**
+ * The one feed-entry emitter every producer shares: read a plugin zip's own
+ * bytes back (release manifest + signature envelope), derive the
+ * `index.json` entry from exactly what the zip carries, and digest the exact
+ * bytes the client will download — the feed can never advertise something a
+ * zip does not. The repo's pack/collect pipeline and the standalone
+ * `snap-rail-plugin feed` command all converge here.
+ *
+ * @param zipped - the exact zip bytes the feed will serve.
+ * @param file - the pure file name the entry advertises (no path).
+ * @param fallbackName - the entry's name when the manifest carries none.
+ * @param options.requireSignature - refuse unsigned zips (feed policy).
+ * @param options.repository - an optional source-repository URL.
+ * @returns the entry, unknown fields stripped by construction.
+ * @throws when the zip has no readable manifest, or no signature while
+ *   `requireSignature` is set.
+ */
+export declare function catalogEntryFromZip(zipped: Uint8Array, file: string, fallbackName: string, options?: {
+    requireSignature?: boolean;
+    repository?: string;
+}): FeedEntry;
 export {};
 //# sourceMappingURL=pack.d.ts.map

package/package.json

@@ -1,10 +1,23 @@
 {
   "name": "@snap-rail/plugin-kit",
-  "description": "The plugin author's kit: snapRail manifest vocabulary, the renderer seed whitelist, and tsdown presets for installable host + client faces",
-  "version": "0.2.0",
+  "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.2",
   "type": "module",
   "main": "lib/index.js",
   "types": "lib/types/index.d.ts",
+  "homepage": "https://www.snap-rail.top/dev.html",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yansijian/snap-rail.git",
+    "directory": "packages/base/plugin-kit"
+  },
+  "keywords": [
+    "snap-rail",
+    "plugin",
+    "cordis",
+    "industrial",
+    "electron"
+  ],
   "exports": {
     ".": {
       "types": "./lib/types/index.d.ts",
@@ -43,7 +56,9 @@
   ],
   "license": "Apache-2.0",
   "dependencies": {
+    "fflate": "^0.8.3",
     "zod": "^4.4.3",
+    "@snap-rail/protocol": "^0.1.3",
     "@snap-rail/util": "^0.1.2"
   },
   "peerDependencies": {