@snap-rail/plugin-kit 0.0.0-stage → 0.2.1

package/lib/pack.js

@@ -0,0 +1,205 @@
+import { CLIENT_EXTERNALS } from "./seeds.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
+* its installable zip. The zip is **the release artifact, not the source
+* tree** — a trimmed manifest whose `main` names the host face (or, for
+* `clientOnly` packages, the client bundle), the built faces themselves, and
+* an `exports` map covering the subpaths pool-resident importers resolve
+* (`./contract` and friends). The settings page's 安装插件, the CLI packer,
+* the feed publishers, and the offline combo assembler all consume the same
+* shape.
+*
+* @module @snap-rail/plugin-kit/pack
+*/
+/** Files a release never carries even inside a face directory. */
+function isBuildPlumbing(path) {
+	return path.endsWith(".d.ts") || path.endsWith(".d.ts.map") || path.endsWith(".js.map") || path.endsWith(".tsbuildinfo");
+}
+/**
+* Derive the release manifest: the npm identity plus `main` plus the trimmed
+* `exports` map. Everything else (scripts, dev dependencies) is workspace
+* plumbing the pool never reads and the zip never carries. A stamped seed
+* ABI merges into `snapRail.client` — the build-truth declaration replaces
+* anything a source manifest may have carried.
+*
+* @param source - the parsed source `package.json`.
+* @param main - the entry the manifest `main` names.
+* @param exports - subpath exports beyond `.`; the root voice is always
+*   included.
+* @param seedAbi - the pack-time seed-contract stamp for client faces.
+* @returns the manifest serialized for the zip root.
+*/
+function releaseManifest(source, main, exports, seedAbi) {
+	const snapRail = source.snapRail;
+	const manifest = {
+		name: source.name,
+		version: typeof source.version === "string" ? source.version : "0.0.0",
+		description: typeof source.description === "string" ? source.description : "",
+		type: "module",
+		main,
+		exports: {
+			".": main,
+			...exports
+		}
+	};
+	if (snapRail !== void 0) manifest.snapRail = seedAbi === void 0 ? snapRail : {
+		...snapRail,
+		client: {
+			...snapRail.client,
+			seedAbi
+		}
+	};
+	return `${JSON.stringify(manifest, null, 2)}\n`;
+}
+/** The base npm package of a seed id (`react/jsx-runtime` → `react`;
+* `@scope/name/sub` → `@scope/name`). */
+function basePackageOf(seedId) {
+	const parts = seedId.split("/");
+	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).
+*
+* @param packageDir - the package being packed (version resolution root).
+* @param bundleCode - the built client bundle's source text.
+*/
+async function seedAbiStamp(packageDir, bundleCode) {
+	const seeds = new Set(CLIENT_EXTERNALS);
+	const required = /* @__PURE__ */ new Set();
+	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);
+	}
+	if (required.size === 0) return void 0;
+	const require = createRequire(join(packageDir, "package.json"));
+	const versions = {};
+	for (const id of required) try {
+		const manifestPath = require.resolve(`${basePackageOf(id)}/package.json`);
+		const parsed = JSON.parse(await readFile(manifestPath, "utf8"));
+		if (typeof parsed.version === "string" && parsed.version !== "") versions[id] = parsed.version;
+	} catch {}
+	if (Object.keys(versions).length === 0) return void 0;
+	return {
+		revision: 1,
+		versions
+	};
+}
+/** Collect every file under `dir` (zip paths use forward slashes). */
+async function collectDir(dir, base) {
+	const files = {};
+	for (const entry of await readdir(dir, { withFileTypes: true })) {
+		const full = join(dir, entry.name);
+		if (entry.isDirectory()) {
+			Object.assign(files, await collectDir(full, base));
+			continue;
+		}
+		const rel = relative(base, full).replaceAll("\\", "/");
+		if (isBuildPlumbing(rel)) continue;
+		files[rel] = new Uint8Array(await readFile(full));
+	}
+	return files;
+}
+/**
+* Assemble one package's release file set: the release manifest, the declared
+* faces, and the exports targets. Fails loud when the source manifest drifts
+* from the spec or a declared face is missing on disk, so a broken build can
+* never ship as a plausible zip.
+*
+* @param spec - what the package ships and from where.
+* @returns the zip's files, keyed by package-relative path.
+*/
+async function releaseFiles(spec) {
+	let source;
+	try {
+		source = JSON.parse(await readFile(join(spec.dir, "package.json"), "utf8"));
+	} catch (cause) {
+		throw new Error(`pack: cannot read the manifest of ${spec.name}`, { cause });
+	}
+	if (source.name !== spec.name) throw new Error(`pack: manifest name ${String(source.name)} does not match the spec ${spec.name}`);
+	const snapRail = source.snapRail;
+	const declaredClient = snapRail?.client !== void 0;
+	if (declaredClient !== (spec.clientFace !== void 0)) throw new Error(`pack: ${spec.name} declares snapRail.client ${declaredClient ? "with" : "without"} a clientFace directory`);
+	const clientOnly = snapRail?.clientOnly === true;
+	if (spec.hostFace === void 0 && !clientOnly) throw new Error(`pack: ${spec.name} has no host face and does not declare snapRail.clientOnly`);
+	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";
+	const main = spec.hostFace ?? clientEntry;
+	const files = {};
+	if (spec.hostDir !== void 0) {
+		Object.assign(files, await collectDir(join(spec.dir, spec.hostDir), spec.dir));
+		for (const path of Object.keys(files)) if (path === `${spec.hostDir}/types` || path.startsWith(`${spec.hostDir}/types/`)) delete files[path];
+	}
+	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;
+	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})`);
+	return files;
+}
+/** The zip file name a package's release takes under dist-plugins/. */
+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 { catalogEntryFromZip, releaseFiles, releaseManifest, zipFileName };

package/lib/recipe.js

@@ -0,0 +1,51 @@
+import { z } from "zod";
+/** One combo row: exactly the user-layer row shape, strict. */
+const recipeRowSchema = z.object({
+	name: z.string().regex(/^(@[a-z0-9-]+\/[a-z0-9-]+|[a-z0-9-]+)(\/[a-z0-9-]+)*$/),
+	enabled: z.boolean().optional(),
+	config: z.unknown().optional()
+}).strict();
+/** A combo package's document: identity + the rows the preset carries. */
+const recipeDocumentSchema = z.object({
+	/** Stable id; also the preset file name (`recipe-<id>.yml`). */
+	id: z.string().regex(/^[a-z0-9-]+$/),
+	version: z.string().min(1),
+	title: z.string().min(1),
+	kind: z.enum(["base", "scenario"]),
+	description: z.string().optional(),
+	plugins: z.array(recipeRowSchema).min(1)
+}).strict();
+/**
+* The real package names a combo references, deduplicated in document order.
+* A subpath row (`@snap-rail/equipment/rpc`) addresses the package
+* `@snap-rail/equipment`; the combo archive carries one zip per package.
+*
+* @param document - the parsed combo document.
+* @returns unique package names in first-reference order.
+*/
+function recipePackageNames(document) {
+	const names = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const row of document.plugins) {
+		const name = packageNameOf(row.name);
+		if (seen.has(name)) continue;
+		seen.add(name);
+		names.push(name);
+	}
+	return names;
+}
+/**
+* The npm package a row belongs to (`@scope/pkg/sub` → `@scope/pkg`).
+*
+* @param name - a package name or subpath entry.
+* @returns the package name.
+*/
+function packageNameOf(name) {
+	if (!name.startsWith("@")) return name.split("/")[0];
+	const slash = name.indexOf("/");
+	if (slash < 0) return name;
+	const second = name.indexOf("/", slash + 1);
+	return second < 0 ? name : name.slice(0, second);
+}
+//#endregion
+export { packageNameOf, recipeDocumentSchema, recipePackageNames, recipeRowSchema };

package/lib/seeds.js

@@ -0,0 +1,117 @@
+//#region lib/types/seeds.js
+/**
+* The renderer's shared-module vocabulary, in two tiers.
+*
+* `SEED_MODULES` is the **base tier**: the ids the shell itself seeds (by
+* importing them statically into the app bundle) and parity-checks at boot.
+* Everything a client bundle `require`s beyond this list must either be
+* bundled in or contributed (below). Cross-plugin value imports are
+* forbidden (collaboration goes through cordis services and slots); spine
+* contract faces (`./contract` — zod + types only) and pure utility faces
+* qualify; package host entries never do — the node side (store, drizzle,
+* node:sqlite) must stay out of the client graph. Adding a base id is a
+* spine decision.
+*
+* `CONTRIBUTED_SEED_MODULES` is the **installed tier**: ids that arrive with
+* an installed plugin's client face (the framework's primitives, an
+* extension pack's components). The provider's client entry default-exports
+* a `seeds` map (`{ seeds: { ui: namespace, … } }`); the shell requires the
+* face once and seeds every `<package>/<key>` id from that map, so every
+* consumer shares the provider's single instances. The shell never seeds
+* these itself — an absent provider simply leaves the ids unseeded and
+* dependent faces skip with a load error instead of mounting half a UI.
+*
+* `CLIENT_EXTERNALS` (the union) is the external surface client bundles
+* build against: the plugin-kit's client preset externalizes exactly these
+* ids.
+*
+* @module @snap-rail/plugin-kit/seeds
+*/
+/** Module ids the shell seeds and every client bundle may require. */
+const SEED_MODULES = [
+	"react",
+	"react/jsx-runtime",
+	"react-dom",
+	"react-dom/client",
+	"@snap-rail/cordis",
+	"@snap-rail/cordis-plugin-timer",
+	"@snap-rail/client-kernel",
+	"@snap-rail/client-modules",
+	"@snap-rail/connection",
+	"@snap-rail/protocol",
+	"@snap-rail/station-rpc/contract",
+	"@snap-rail/app-boot/contract",
+	"@snap-rail/equipment/contract",
+	"@snap-rail/util",
+	"zod"
+];
+/**
+* Module ids installed plugins contribute through their client face's
+* `seeds` map — the framework tier: every face of an installed UI framework
+* (primitives, slot registry, runtime, fallback) serves as a shared
+* instance for the components bound to it. The equipment wire contract
+* rides the base tier instead — it is the station platform's API surface,
+* not an installed framework's; a scenario's own contract stays inside its
+* suite package. A third-party framework contributes its own ids; this
+* list covers the in-repo builds.
+*/
+const CONTRIBUTED_SEED_MODULES = [
+	"@snap-rail/framework-shadcn/ui",
+	"@snap-rail/framework-shadcn/slots",
+	"@snap-rail/framework-shadcn/semantic",
+	"@snap-rail/framework-shadcn/settings-pages",
+	"@snap-rail/framework-shadcn/session",
+	"@snap-rail/framework-shadcn/workflows",
+	"@snap-rail/framework-shadcn/variables",
+	"@snap-rail/framework-shadcn/runtime",
+	"@snap-rail/framework-shadcn/fallback"
+];
+/** The full external surface for in-repo client-bundle builds. */
+const CLIENT_EXTERNALS = [...SEED_MODULES, ...CONTRIBUTED_SEED_MODULES];
+/**
+* The seed contract's ABI revision. Bump when the contract between the
+* shell's seed table and client bundles changes shape — interop semantics,
+* a seed id's export shape. Packs stamp every client face with the revision
+* it was built against (`snapRail.client.seedAbi`); the shell refuses a
+* face stamped with a foreign revision instead of letting it crash the
+* renderer (r1 exists because a seed default-import compiled to a namespace
+* where the author meant a class — the shape must be checkable).
+*/
+const SEED_ABI_REVISION = 1;
+/**
+* Compare a client face's stamped seed ABI against the live table. Only the
+* ids present in BOTH maps are compared (a stamp covers exactly what its
+* build could resolve): the revision must match exactly, every shared
+* version must agree on the major. An absent declaration passes — zips
+* predating the stamping stay installable, marked for the caller to log.
+*/
+function checkSeedAbi(declared, host) {
+	if (declared === void 0) return {
+		ok: true,
+		undeclared: true
+	};
+	if (declared.revision !== host.revision) return {
+		ok: false,
+		undeclared: false,
+		reason: `插件构建于种子 ABI r${declared.revision}，宿主为 r${host.revision} —— 请更新插件包或桌面应用`
+	};
+	for (const [id, version] of Object.entries(declared.versions)) {
+		const live = host.versions[id];
+		if (live === void 0) continue;
+		if (majorOf(version) !== majorOf(live)) return {
+			ok: false,
+			undeclared: false,
+			reason: `插件构建于 ${id}@${version}，宿主提供 ${live}（主版本不一致）`
+		};
+	}
+	return {
+		ok: true,
+		undeclared: false
+	};
+}
+/** The npm major of a version string; unparsable → NaN, which never equals. */
+function majorOf(version) {
+	return Number.parseInt(version.split(".")[0] ?? "", 10);
+}
+//#endregion
+export { CLIENT_EXTERNALS, CONTRIBUTED_SEED_MODULES, SEED_ABI_REVISION, SEED_MODULES, checkSeedAbi };

package/lib/sign.js

@@ -0,0 +1,107 @@
+import { createHash, sign, verify } from "node:crypto";
+//#region lib/types/sign.js
+/**
+* Release metadata and Ed25519 signatures for installable plugins.
+*
+* The signature covers a canonical release manifest. The manifest contains a
+* digest for every payload file, so the verifier authenticates both the
+* publisher and the bytes that will be installed without signing the zip
+* container itself.
+*
+* @module @snap-rail/plugin-kit/sign
+*/
+/** The metadata file embedded in a release archive. */
+const RELEASE_METADATA_PATH = "META-INF/release.json";
+/** The signature envelope embedded in a release archive. */
+const RELEASE_SIGNATURE_PATH = "META-INF/signature.json";
+/** Stable JSON serialization used as the Ed25519 signing input. */
+function canonicalJson(value) {
+	return `${canonicalValue(value)}\n`;
+}
+function canonicalValue(value) {
+	if (value === null || typeof value === "boolean" || typeof value === "number" || typeof value === "string") {
+		const encoded = JSON.stringify(value);
+		if (encoded === void 0) throw new TypeError("release metadata contains an unsupported primitive");
+		return encoded;
+	}
+	if (Array.isArray(value)) return `[${value.map(canonicalValue).join(",")}]`;
+	if (typeof value !== "object") throw new TypeError("release metadata contains an unsupported value");
+	return `{${Object.entries(value).sort(([a], [b]) => a.localeCompare(b)).map(([key, item]) => `${JSON.stringify(key)}:${canonicalValue(item)}`).join(",")}}`;
+}
+/** SHA-256 digest of one payload file. */
+function sha256(data) {
+	return createHash("sha256").update(data).digest("hex");
+}
+/**
+* Build signed metadata from a release file set. Metadata and signature files
+* are excluded from the digest table so signing never becomes recursive.
+*/
+function releaseMetadata(files, options) {
+	const digests = {};
+	for (const path of Object.keys(files).sort()) {
+		if (path === "META-INF/release.json" || path === "META-INF/signature.json") continue;
+		digests[path] = `sha256:${sha256(files[path])}`;
+	}
+	return {
+		format: 1,
+		name: options.name,
+		version: options.version,
+		...options.publisher === void 0 ? {} : { publisher: options.publisher },
+		createdAt: options.createdAt ?? (/* @__PURE__ */ new Date()).toISOString(),
+		files: digests
+	};
+}
+/** Sign release metadata with an Ed25519 private key. */
+function signReleaseMetadata(metadata, key) {
+	const bytes = Buffer.from(canonicalJson(metadata), "utf8");
+	return {
+		algorithm: "Ed25519",
+		keyId: key.keyId,
+		signedFile: RELEASE_METADATA_PATH,
+		signature: sign(null, bytes, key.privateKey).toString("base64")
+	};
+}
+/** Add signed metadata and signature files to a release file set. */
+function signReleaseFiles(files, options) {
+	const metadata = releaseMetadata(files, options);
+	const signature = signReleaseMetadata(metadata, options);
+	return {
+		...files,
+		[RELEASE_METADATA_PATH]: new TextEncoder().encode(canonicalJson(metadata)),
+		[RELEASE_SIGNATURE_PATH]: new TextEncoder().encode(canonicalJson(signature))
+	};
+}
+/** Verify release metadata, signature and every payload file digest. */
+function verifyReleaseFiles(files, trustedKeys) {
+	const metadataBytes = files[RELEASE_METADATA_PATH];
+	const signatureBytes = files[RELEASE_SIGNATURE_PATH];
+	if (metadataBytes === void 0 || signatureBytes === void 0) throw new Error("release signature metadata is missing");
+	const metadata = parseJson(metadataBytes, "release metadata");
+	const signature = parseJson(signatureBytes, "release signature");
+	if (metadata.format !== 1 || signature.algorithm !== "Ed25519" || signature.signedFile !== "META-INF/release.json") throw new Error("unsupported release signature format");
+	if (Object.prototype.hasOwnProperty.call(metadata.files, "META-INF/release.json") || Object.prototype.hasOwnProperty.call(metadata.files, "META-INF/signature.json")) throw new Error("release digest table must not include signature metadata");
+	const key = trustedKeys.find((candidate) => candidate.keyId === signature.keyId);
+	if (key === void 0) throw new Error(`untrusted release key ${signature.keyId}`);
+	if (key.publisher !== void 0 && metadata.publisher !== key.publisher) throw new Error("release publisher does not match the trusted key");
+	if (!verify(null, Buffer.from(canonicalJson(metadata), "utf8"), key.publicKey, Buffer.from(signature.signature, "base64"))) throw new Error("release signature is invalid");
+	const expected = new Set(Object.keys(metadata.files));
+	for (const path of Object.keys(files)) {
+		if (path === "META-INF/release.json" || path === "META-INF/signature.json") continue;
+		if (!expected.has(path)) throw new Error(`release contains an unsigned file ${path}`);
+	}
+	for (const [path, digest] of Object.entries(metadata.files)) {
+		const data = files[path];
+		if (data === void 0) throw new Error(`release is missing signed file ${path}`);
+		if (digest !== `sha256:${sha256(data)}`) throw new Error(`release file digest mismatch for ${path}`);
+	}
+	return metadata;
+}
+function parseJson(bytes, label) {
+	try {
+		return JSON.parse(new TextDecoder().decode(bytes));
+	} catch (cause) {
+		throw new Error(`${label} is not valid JSON`, { cause });
+	}
+}
+//#endregion
+export { RELEASE_METADATA_PATH, RELEASE_SIGNATURE_PATH, canonicalJson, releaseMetadata, sha256, signReleaseFiles, signReleaseMetadata, verifyReleaseFiles };

package/lib/types/build.d.ts

@@ -0,0 +1,72 @@
+/**
+ * tsdown config factories for plugin packages — the two faces a plugin
+ * ships. The host face is a plain ESM node bundle; the client face is the
+ ** CJS factory bundle** the renderer's module loader consumes: the whole
+ * output wrapped in `window.__ModuleLoader__.load({ id, factory })`, with
+ * the seed table externalized (shared instances, zero duplication).
+ *
+ * Usage (a plugin package's `tsdown.config.ts`):
+ *
+ * ```ts
+ * import { clientBundle, hostBundle } from '@snap-rail/plugin-kit/build'
+ * export default [
+ *   hostBundle('packages/host/src/index.ts'),
+ *   clientBundle('@scope/my-suite', 'packages/client/src/index.tsx'),
+ * ]
+ * ```
+ *
+ * @module @snap-rail/plugin-kit/build
+ */
+import { defineConfig } from 'tsdown';
+import type { Plugin } from 'rolldown';
+/**
+ * The seed interop guard: a client face must consume seed modules through
+ * **named or star imports only**. A default import compiles — under
+ * rolldown's CJS node-mode interop (`__toESM(require(id), 1)`) — into
+ * `.default` = the required namespace itself, never the module's own
+ * default export. A class-shaped seed (the timer service) then arrives as
+ * a plain object and cordis refuses it at mount: on the user's terminal,
+ * as a dead renderer, instead of here at build time. Star and named
+ * imports survive both interop modes; `import type` erases and is fine.
+ *
+ * Source-level scan (emit-independent), plugin sources only — inlined
+ * third-party dependencies keep their own import style.
+ */
+export declare function seedImportGuard(): Plugin;
+/**
+ * The host face: an ESM node bundle. The spine stays external by default
+ * (tsdown externalizes package.json dependencies); anything else the plugin
+ * needs ships inside.
+ *
+ * @param entry - the host entry source file.
+ */
+export declare function hostBundle(entry: string): ReturnType<typeof defineConfig>;
+/** Options for {@link clientBundle}. */
+export interface ClientBundleOptions {
+    /**
+     * Stylesheet files to inject into the bundle beyond the `.css` imports the
+     * sources make (e.g. a precompiled tailwind output produced by an earlier
+     * build step). Each becomes an idempotent style-injection module imported
+     * by the entry, so the bundle carries its own styling.
+     */
+    css?: readonly string[] | undefined;
+}
+/**
+ * The client face: a CJS browser bundle welded into the module-loader
+ * factory wrapper. Only the seed vocabulary ({@link CLIENT_EXTERNALS} —
+ * base plus contributed ids) stays external; everything else (icons,
+ * protocol libraries, bitmaps) inlines — bitmaps and SVGs excepted: they
+ * emit beside the bundle as `snap-plugin://`-addressed assets instead of
+ * base64 bulk, and `.css` imports become style-injection modules.
+ *
+ * A provider of contributed seeds (a framework, a contract owner) builds
+ * the same way: its entry default-exports `{ seeds: { … } }` mapping each
+ * 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).
+ * @param entry - the renderer entry source file.
+ * @param options - see {@link ClientBundleOptions}.
+ */
+export declare function clientBundle(packageName: string, entry: string, options?: ClientBundleOptions): ReturnType<typeof defineConfig>;
+//# sourceMappingURL=build.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The plugin author's kit: manifest vocabulary, the renderer seed whitelist,
+ * the tsdown presets producing installable host + client faces, and the
+ * final-format packer assembling the installable zip. A new plugin starts by
+ * copying `driver-modbus` (host-only) or a suite package and swapping these
+ * presets in.
+ *
+ * @module @snap-rail/plugin-kit
+ */
+export { PLUGIN_KINDS, clientFaceSchema, seedAbiSchema, snapRailManifestSchema, type SnapRailManifest, type SnapRailManifestInput, } from './manifest.ts';
+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 { 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

@@ -0,0 +1,72 @@
+/**
+ * The plugin author's manifest vocabulary: the `snapRail` field of a plugin
+ * package's `package.json`. One source of truth for the shape — the
+ * installer validates against it, the pool scan records it, and authors
+ * import the types.
+ *
+ * @module @snap-rail/plugin-kit/manifest
+ */
+import { z } from 'zod';
+import { PLUGIN_LAYERS } from '@snap-rail/util/manifest';
+/** Plugin package kinds. `suite` and `framework` packages are single-active. */
+export declare const PLUGIN_KINDS: readonly ["suite", "driver", "framework", "plugin"];
+/** The layer taxonomy — single source in `@snap-rail/util/manifest`. */
+export { PLUGIN_LAYERS };
+/** The seed-ABI stamp a pack writes into a client face's manifest (shape of
+ * `snapRail.client.seedAbi`). Computed by the packer from the built bundle
+ * and the build tree's resolved seed versions — authors never hand-write it. */
+export declare const seedAbiSchema: z.ZodObject<{
+    revision: z.ZodNumber;
+    versions: z.ZodRecord<z.ZodString, z.ZodString>;
+}, z.core.$strict>;
+/** The renderer face declaration: where the client bundle lives. */
+export declare const clientFaceSchema: z.ZodObject<{
+    entry: z.ZodDefault<z.ZodString>;
+    seeds: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    externalSeeds: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    seedAbi: z.ZodOptional<z.ZodObject<{
+        revision: z.ZodNumber;
+        versions: z.ZodRecord<z.ZodString, z.ZodString>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+/** The `snapRail` manifest field's schema. */
+export declare const snapRailManifestSchema: z.ZodObject<{
+    kind: z.ZodOptional<z.ZodEnum<{
+        suite: "suite";
+        driver: "driver";
+        framework: "framework";
+        plugin: "plugin";
+    }>>;
+    layer: z.ZodOptional<z.ZodEnum<{
+        suite: "suite";
+        base: "base";
+        store: "store";
+        equipment: "equipment";
+        ui: "ui";
+        tool: "tool";
+    }>>;
+    title: z.ZodOptional<z.ZodString>;
+    category: z.ZodOptional<z.ZodString>;
+    exclusive: z.ZodOptional<z.ZodString>;
+    requires: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    clientOnly: z.ZodOptional<z.ZodBoolean>;
+    client: z.ZodOptional<z.ZodObject<{
+        entry: z.ZodDefault<z.ZodString>;
+        seeds: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        externalSeeds: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        seedAbi: z.ZodOptional<z.ZodObject<{
+            revision: z.ZodNumber;
+            versions: z.ZodRecord<z.ZodString, z.ZodString>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+    permissions: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    engines: z.ZodOptional<z.ZodObject<{
+        snapRail: z.ZodOptional<z.ZodString>;
+        hostProtocol: z.ZodOptional<z.ZodString>;
+        renderer: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+}, z.core.$strip>;
+/** The validated manifest field. */
+export type SnapRailManifestInput = z.input<typeof snapRailManifestSchema>;
+export type SnapRailManifest = z.output<typeof snapRailManifestSchema>;
+//# sourceMappingURL=manifest.d.ts.map