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

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/lib/build.js

@@ -0,0 +1,216 @@
+import { CLIENT_EXTERNALS } from "./seeds.js";
+import { readFileSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { defineConfig } from "tsdown";
+//#region lib/types/build.js
+/**
+* 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
+*/
+/**
+* Contributed-seed ids this package declares it requires from other plugins
+* (`snapRail.client.externalSeeds`), read from the package.json in the
+* working directory (tsdown runs there). clientBundle externalizes exactly
+* these ids on top of the seed whitelist, so a consumer's bundle resolves a
+* third-party framework's primitives or an extension pack's components from
+* the runtime seed table — single instances — instead of inlining private
+* copies the loader could never resolve.
+*/
+function declaredExternalSeeds() {
+	try {
+		const seeds = JSON.parse(readFileSync(join(process.cwd(), "package.json"), "utf8")).snapRail?.client?.externalSeeds;
+		return Array.isArray(seeds) && seeds.every((seed) => typeof seed === "string" && seed !== "") ? seeds : [];
+	} catch {
+		return [];
+	}
+}
+/** Extensions the client preset ships as emitted assets beside the bundle. */
+const ASSET_EXTENSIONS = /\.(png|jpe?g|webp|gif|svg)$/;
+/**
+* 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.
+*/
+function seedImportGuard() {
+	const seedPattern = CLIENT_EXTERNALS.map((id) => id.replace(/[.*+?^${}()|[\]\\]/g, String.raw`\$&`)).join("|");
+	const pattern = new RegExp(String.raw`import\s+(?![{*])(?!type\b)([\w$]+)\s*(?:,[^;]*?)?\s*from\s*['"](` + seedPattern + String.raw`)['"]`);
+	return {
+		name: "snap-rail-seed-import-guard",
+		transform(code, id) {
+			if (id.includes("node_modules")) return void 0;
+			const match = pattern.exec(code);
+			if (match === null) return void 0;
+			this.error(`种子模块 "${match[2]}" 被默认导入（import ${match[1]} from '${match[2]}'）。种子只允许 named/star 导入：rolldown 的 CJS interop 会把 default 变成整个命名空间对象，运行时挂载即崩。请改为 import { … } from '` + match[2] + "' 或 import * as ns from '" + match[2] + "'。");
+		}
+	};
+}
+/** The pool directory name an installed package occupies (installer rule). */
+function poolDirName(packageName) {
+	return packageName.replaceAll("/", "__");
+}
+/** A cheap stable id for deduplicating injected stylesheet tags. */
+function styleId(source) {
+	let hash = 5381;
+	for (let index = 0; index < source.length; index += 1) hash = (hash << 5) + hash + source.charCodeAt(index) | 0;
+	return `snap-rail-css-${(hash >>> 0).toString(36)}`;
+}
+/**
+* Turn `.css` imports into modules that inject a `<style>` tag on first
+* evaluation. The module loader has no stylesheet story and the pool world
+* has no app-level stylesheet: whoever needs tokens or utilities (the
+* framework, above all) carries them inside the bundle, idempotently. The
+* virtual-id redirect (`\0snap-rail-css:`) keeps rolldown's built-in CSS
+* pipeline — which demands `@tsdown/css` and emits side files we have no
+* loader for — out of the graph entirely.
+*/
+function cssModules() {
+	const VIRTUAL_PREFIX = "\0snap-rail-css:";
+	return {
+		name: "snap-rail-css-modules",
+		resolveId(source, importer) {
+			if (source.startsWith(VIRTUAL_PREFIX) || !source.endsWith(".css")) return void 0;
+			const file = isAbsolute(source) ? source : resolve(dirname(importer ?? process.cwd()), source);
+			return `${VIRTUAL_PREFIX}${file.replaceAll("\\", "/")}.js`;
+		},
+		async load(id) {
+			if (!id.startsWith(VIRTUAL_PREFIX)) return void 0;
+			const file = id.slice(15).replace(/\.js$/, "");
+			const css = await readFile(file, "utf8");
+			const tag = styleId(css);
+			return [
+				`const css = ${JSON.stringify(css)};`,
+				`const id = ${JSON.stringify(tag)};`,
+				"if (typeof document === \"undefined\") throw new Error(\"css module outside the renderer\");",
+				"if (document.getElementById(id) === null) {",
+				"  const style = document.createElement(\"style\");",
+				"  style.id = id;",
+				"  style.textContent = css;",
+				"  document.head.append(style);",
+				"}",
+				"export default {}"
+			].join("\n");
+		}
+	};
+}
+/**
+* Emit imported bitmap/svg assets beside the client bundle and rewrite their
+* import values to absolute `snap-plugin://` URLs. The renderer has no
+* filesystem and the module loader's `require` only knows the seed table, so
+* a relative asset path could never resolve at runtime — the transport URL
+* is the one address that works identically in dev and packaged builds.
+* Emitted file names are stable (no content hash — a zip is immutable);
+* same-named assets in different directories collide, last one wins.
+*/
+function assetUrls(packageName, baseDir) {
+	return {
+		name: "snap-rail-asset-urls",
+		async load(id) {
+			const file = id.replaceAll("\\", "/").split("?")[0].replace(/#.*$/, "");
+			if (!ASSET_EXTENSIONS.test(file)) return void 0;
+			const fileName = `assets/${file.split("/").at(-1)}`;
+			this.emitFile({
+				type: "asset",
+				fileName,
+				source: await readFile(file)
+			});
+			return `export default ${JSON.stringify(`snap-plugin://pool/${poolDirName(packageName)}/${baseDir}/${fileName}`)}`;
+		}
+	};
+}
+/**
+* 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.
+*/
+function hostBundle(entry) {
+	return defineConfig({
+		entry: { host: entry },
+		outDir: "lib-host",
+		format: ["esm"],
+		platform: "node",
+		target: "es2024",
+		dts: false,
+		clean: false
+	});
+}
+/**
+* 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}.
+*/
+function clientBundle(packageName, entry, options = {}) {
+	const entryFile = entry.replaceAll("\\", "/");
+	const entryPath = resolve(process.cwd(), entryFile).replaceAll("\\", "/");
+	const extraCss = (options.css ?? []).map((file) => resolve(process.cwd(), file).replaceAll("\\", "/"));
+	/** Prepend the extra-css imports to the entry so the styles ride the
+	* bundle through the same style-injection modules as source css. */
+	const injectExtraCss = {
+		name: "snap-rail-inject-extra-css",
+		transform(code, id) {
+			if (id.replaceAll("\\", "/").split("?")[0].replace(/#.*$/, "") !== entryPath || extraCss.length === 0) return void 0;
+			return `${extraCss.map((css) => `import ${JSON.stringify(css)};\n`).join("")}${code}`;
+		}
+	};
+	return defineConfig({
+		entry: { client: entry },
+		outDir: "lib-client",
+		format: ["cjs"],
+		platform: "browser",
+		target: "es2024",
+		dts: false,
+		clean: false,
+		outExtensions: () => ({ js: ".js" }),
+		noExternal: [/.*/],
+		external: [...CLIENT_EXTERNALS, ...declaredExternalSeeds()],
+		plugins: [
+			injectExtraCss,
+			cssModules(),
+			assetUrls(packageName, "lib-client"),
+			seedImportGuard()
+		],
+		outputOptions: {
+			banner: `window.__ModuleLoader__.load({ id: ${JSON.stringify(packageName)}, factory: function (require, module, exports) {`,
+			footer: "return module.exports && module.exports.__esModule === true && \"default\" in module.exports ? module.exports.default : module.exports; } });"
+		}
+	});
+}
+//#endregion
+export { clientBundle, hostBundle, seedImportGuard };

package/lib/index.js

@@ -0,0 +1,43 @@
+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 { 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
+/**
+* Authoring helper for UI framework packages: define the package's slot
+* vocabulary in one place and get a runtime membership guard for it. A
+* vocabulary is plain data — a `shell.menu`-style dotted id table plus the
+* reserved `custom:<publisher>.<name>` extension namespace — and every
+* consumer (components, layouts) checks membership through the returned
+* guard instead of hand-rolled string tests. Ids are declared with an
+* `as const` object so consumers get autocomplete and compile-time
+* misspelling errors from the literal-union type (`SlotIdOf`).
+*
+* The shipped framework (@snap-rail/framework-shadcn) implements the same
+* contract inline (`UI_SLOT_IDS`/`isValidUiSlotId`); new frameworks start
+* here.
+*
+* @module @snap-rail/plugin-kit/slot-vocabulary
+*/
+/** Shape every slot id shares: dotted lowercase kebab (`shell.menu`). */
+const SLOT_ID_PATTERN = /^[a-z][a-z0-9-]*(?:\.[a-z][a-z0-9-]+)+$/;
+/** The reserved extension namespace: a custom slot is owned by a publisher. */
+const CUSTOM_SLOT_PATTERN = /^custom:[a-z0-9][a-z0-9-]*\.[a-z0-9][a-z0-9-]*$/;
+/** Define and validate a framework's slot vocabulary. Malformed ids throw at
+* definition time — a vocabulary ships once and is consumed everywhere, so
+* it fails loudly in the framework author's build, never in a component. */
+function defineSlotVocabulary(ids, options) {
+	for (const [key, id] of Object.entries(ids)) if (!SLOT_ID_PATTERN.test(id)) throw new Error(`defineSlotVocabulary: 插槽 id 不合法（需为小写 kebab 点分，如 shell.menu）：${key} = ${JSON.stringify(id)}`);
+	const known = new Set(Object.values(ids));
+	const customPattern = options?.customPattern ?? CUSTOM_SLOT_PATTERN;
+	return {
+		ids,
+		isSlotId(value) {
+			return known.has(value) || customPattern.test(value);
+		}
+	};
+}
+//#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 };

package/lib/manifest.js

@@ -0,0 +1,122 @@
+import { z } from "zod";
+import { PLUGIN_LAYERS } from "@snap-rail/util/manifest";
+//#region lib/types/manifest.js
+/**
+* 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
+*/
+/** Plugin package kinds. `suite` and `framework` packages are single-active. */
+const PLUGIN_KINDS = [
+	"suite",
+	"driver",
+	"framework",
+	"plugin"
+];
+/** 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. */
+const seedAbiSchema = z.object({
+	/** The seed-contract revision the face was built against. */
+	revision: z.number().int().min(1),
+	/** 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 renderer face declaration: where the client bundle lives. */
+const clientFaceSchema = z.object({
+	/** Path of the CJS factory bundle inside the package (from its root). */
+	entry: z.string().min(1).default("lib/client.js"),
+	/**
+	* 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.
+	*/
+	seeds: z.array(z.string().min(1)).optional(),
+	/**
+	* Contributed seed ids (`<package>/<subpath>`) this client face requires
+	* from other installed plugins (a framework's primitives, an extension
+	* pack's components). Build-time plumbing: `clientBundle` externalizes
+	* exactly these ids so they resolve from the shell's seed table at
+	* runtime instead of being inlined as private copies; the enable precheck
+	* verifies each provider is installed and declares the id. It is not a
+	* compatibility declaration — package/version compatibility rides
+	* `requires`.
+	*/
+	externalSeeds: z.array(z.string().min(1)).optional(),
+	/**
+	* The seed-contract stamp the packer computed at pack time (see
+	* `@snap-rail/plugin-kit/seeds` for the comparison contract). Present in
+	* the release manifest only; the installer and the renderer boot both
+	* check it against the live table, absent declarations pass untouched.
+	*/
+	seedAbi: seedAbiSchema.optional()
+}).strict();
+/**
+* Declared dependencies — the single compatibility declaration a plugin
+* makes, checked before an enable/disable/uninstall lands. Three entry
+* forms:
+*
+* - `name` — a package requirement (`@snap-rail/equipment`): satisfied when
+*   that package is installed and enabled.
+* - `name@range` — the same, with a version range on the resolved versions
+*   (`@snap-rail/framework-shadcn@^0.1`): also requires the installed
+*   version to satisfy the range (`@snap-rail/util/semver` semantics).
+*   A renderer face's ecosystem binding IS this form: requiring the
+*   framework package is what binds a component to it — there is no
+*   separate framework field.
+* - `service:id` — a live cordis service (`service:store`), checked
+*   against the running service table.
+*
+* An unmet requirement refuses the write instead of leaving the next boot
+* to fail.
+*/
+const requiresSchema = z.array(z.string().min(1)).optional();
+/** The `snapRail` manifest field's schema. */
+const snapRailManifestSchema = z.object({
+	/** Role declaration; `suite` and `framework` packages are single-active. */
+	kind: z.enum(PLUGIN_KINDS).optional(),
+	/** The layer this package belongs to; gates the import direction. */
+	layer: z.enum(PLUGIN_LAYERS).optional(),
+	/**
+	* The human-facing display name shown wherever the plugin is listed (the
+	* management page, install confirmations). The package author names it
+	* freely (Chinese included); absent → surfaces fall back to the package
+	* name.
+	*/
+	title: z.string().min(1).max(64).optional(),
+	/**
+	* The classification marker shown in the management UI. Open vocabulary —
+	* the package author names it freely (Chinese included); the app groups
+	* rows by the raw marker and never validates it against an enum. Absent →
+	* the management page files the row under 其他.
+	*/
+	category: z.string().min(1).max(64).optional(),
+	/**
+	* Mutex group: enabling a package of group X deactivates every other
+	* enabled package of group X in the same batched write. Suites default
+	* to `'suite'`, frameworks to `'framework'`.
+	*/
+	exclusive: z.string().min(1).optional(),
+	requires: requiresSchema,
+	/**
+	* True for packages with no host face at all (frameworks, renderer
+	* stations): their rows are config-only — never mounted into the host
+	* tree, served to the renderer through `client-config.list`.
+	*/
+	clientOnly: z.boolean().optional(),
+	/** The renderer face; omit for host-only plugins. */
+	client: clientFaceSchema.optional(),
+	/** Permission declarations — shown at install time, enforced later. */
+	permissions: z.array(z.string()).optional(),
+	/** Host and renderer versions the built faces support. */
+	engines: z.object({
+		snapRail: z.string().min(1).optional(),
+		hostProtocol: z.string().min(1).optional(),
+		renderer: z.string().min(1).optional()
+	}).strict().optional()
+});
+//#endregion
+export { PLUGIN_KINDS, PLUGIN_LAYERS, clientFaceSchema, seedAbiSchema, snapRailManifestSchema };