@ethisyscore/vite-plugin 1.6.2 → 1.7.0

package/dist/index.d.cts

@@ -136,7 +136,7 @@ declare function validateReactiveRule(rule: unknown, filePath: string): Validati
  * mirror the registry exactly; a drift between the two breaks the cross-repo
  * agreement that E4.S4 locks in.
  */
-declare const CONTRACT_B_SEMANTIC_PRIMITIVES: readonly ["Button", "DataTable", "Form", "EntityPicker", "CommandBar", "Drawer", "Modal", "CanvasSurface", "WebGLSurface"];
+declare const CONTRACT_B_SEMANTIC_PRIMITIVES: readonly ["Button", "DataTable", "Form", "EntityPicker", "CommandBar", "Drawer", "Modal", "CanvasSurface", "WebGLSurface", "Card", "Tabs", "Select", "Alert"];
 /**
  * Non-component import-map entries — the runtime libraries the worker is
  * permitted to resolve via bare specifiers. Authoring constraint: the plugin's
@@ -219,6 +219,139 @@ interface ContractBPluginOptions {
  */
 declare function ethisysContractBPlugin(options?: ContractBPluginOptions): Plugin;
 
+/**
+ * A single PlatformReact page declaration extracted from
+ * `ui.platformReactPages[]` in the manifest. Aligns with the typed interface
+ * defined in `ethisyscore-protocol` RFC 0003.
+ *
+ * - `id` is the host-side page identifier and the basename of the emitted
+ *   bundle (e.g. `id: "dashboard"` → `platform-react/dashboard.js`).
+ * - `moduleSpecifier` is a host-origin relative path to the page module — the
+ *   plugin author's source entry that Rollup bundles.
+ * - `exportName` is the named export Rollup keeps live in the bundle. The host
+ *   loader reads `bundle[exportName]` at mount time.
+ * - `title` is an optional display label for the host's surface chrome.
+ */
+interface PlatformReactPageDeclaration {
+    id?: string;
+    moduleSpecifier?: string;
+    exportName?: string;
+    title?: string;
+    [key: string]: unknown;
+}
+/**
+ * The subset of a manifest this pass consumes. Manifests are tolerated as a
+ * superset — extra fields are ignored so newer-schema manifests still load.
+ */
+interface PlatformReactManifest {
+    type?: string;
+    ui?: {
+        platformReactPages?: PlatformReactPageDeclaration[];
+        [key: string]: unknown;
+    };
+    [key: string]: unknown;
+}
+/**
+ * Author-facing options for the PlatformReact Vite pass.
+ */
+interface PlatformReactPluginOptions {
+    /**
+     * Root directory the manifest path is resolved against. When omitted,
+     * Vite's `configResolved` populates it from `config.root`.
+     */
+    root?: string;
+    /**
+     * Manifest path. Relative paths resolve against `root`. Defaults to
+     * `feature.manifest.json`.
+     */
+    manifestPath?: string;
+    /**
+     * Output prefix for emitted page assets and the companion manifest.
+     * Defaults to `platform-react/`.
+     */
+    outputPrefix?: string;
+}
+/**
+ * Build-time Vite/Rollup plugin pass for EthisysCore PlatformReact pages
+ * (RFC 0003: the high-trust, host-extension tier). For each entry under
+ * `ui.platformReactPages[]` in the manifest, registers a Rollup input that
+ * emits an ESM bundle the host loads via `import()` at surface mount time.
+ *
+ * Behaviour:
+ * - For each declared page: registers `{ "platform-react/<id>": <moduleSpecifier> }`
+ *   in Rollup's input table. Output is forced to `format: "es"` and
+ *   `inlineDynamicImports: true` so each page ships as ONE bundled module.
+ * - Emits a `platform-react/platform-react-pages.json` companion asset listing
+ *   the declared pages so the host (and the `.ccpkg` packaging step) can
+ *   inspect what the build produced.
+ * - When `ui.platformReactPages` is absent or empty: the pass is a no-op.
+ *   Composition is expected — the recommended template registers this pass
+ *   alongside Contract A / Contract B so a single Vite config covers every
+ *   render mode.
+ *
+ * Origin enforcement of the bundle URL at runtime is the host's responsibility
+ * (see `PlatformReactSurfaceMount.tsx` in `coreconnect-web`). This pass only
+ * blocks remote/absolute paths at the manifest layer so a malformed manifest
+ * fails fast.
+ */
+declare function ethisysPlatformReactPlugin(options?: PlatformReactPluginOptions): Plugin;
+
+/**
+ * A fully-validated PlatformReact page declaration. All fields are guaranteed
+ * present (no `undefined`), `exportName` is defaulted to `"default"`, and the
+ * `moduleSpecifier` is guaranteed to exist on disk when `verifyOnDisk: true`
+ * was passed to {@link parsePlatformReactPages}.
+ */
+interface ResolvedPlatformReactPage {
+    id: string;
+    moduleSpecifier: string;
+    exportName: string;
+    title: string | null;
+}
+/**
+ * Options for {@link parsePlatformReactPages}.
+ */
+interface ParsePlatformReactPagesOptions {
+    /**
+     * Root directory the manifest path and the page module specifiers are
+     * resolved against. Defaults to `process.cwd()`.
+     */
+    root?: string;
+    /**
+     * When `true`, every declared `moduleSpecifier` must exist on disk (relative
+     * to {@link root}). The default is `false` so the helper can be used to
+     * snapshot-test a manifest without checking-out the page source files.
+     */
+    verifyOnDisk?: boolean;
+}
+/**
+ * Parse + validate `ui.platformReactPages[]` declarations from a manifest
+ * file. Designed for plugin authors writing Vitest tests against their own
+ * manifest — the helper applies the same shape and uniqueness rules the
+ * build-time Vite pass enforces, so a passing unit test gives the same
+ * guarantee a green build would.
+ *
+ * Returns an empty array when the manifest does not exist OR does not
+ * declare `ui.platformReactPages` OR declares it as an empty array.
+ *
+ * Throws on any malformed declaration. The thrown message matches the
+ * build-time error so a failing test reads identically to a failing build.
+ *
+ * @example
+ * ```ts
+ * import { parsePlatformReactPages } from "@ethisyscore/vite-plugin";
+ *
+ * test("manifest declares dashboard and admin pages", () => {
+ *   const pages = parsePlatformReactPages("./feature.manifest.json");
+ *   expect(pages).toEqual([
+ *     { id: "dashboard", moduleSpecifier: "src/pages/Dashboard.tsx", exportName: "default", title: "Dashboard" },
+ *     { id: "admin", moduleSpecifier: "src/pages/Admin.tsx", exportName: "AdminPage", title: null },
+ *   ]);
+ * });
+ * ```
+ */
+declare function parsePlatformReactPages(manifestPath: string, options?: ParsePlatformReactPagesOptions): ResolvedPlatformReactPage[];
+
 interface EthisysPluginOptions {
     /**
      * Path to the manifest file, relative to Vite's root directory.
@@ -242,4 +375,4 @@ interface EthisysPluginOptions {
  */
 declare function ethisysManifestPlugin(options?: EthisysPluginOptions): Plugin;
 
-export { CONTRACT_B_IMPORT_MAP_ALLOWLIST, CONTRACT_B_RUNTIME_IMPORTS, CONTRACT_B_SEMANTIC_PRIMITIVES, type ContractAManifest, type ContractAPluginOptions, type ContractBManifest, type ContractBPluginOptions, type EthisysPluginOptions, type ManifestReactiveRuleRef, type ManifestResourceRef, type ValidationFailure, type ValidationResult, ethisysContractAPlugin, ethisysContractBPlugin, ethisysManifestPlugin, validateDeclarativeResource, validateReactiveRule };
+export { CONTRACT_B_IMPORT_MAP_ALLOWLIST, CONTRACT_B_RUNTIME_IMPORTS, CONTRACT_B_SEMANTIC_PRIMITIVES, type ContractAManifest, type ContractAPluginOptions, type ContractBManifest, type ContractBPluginOptions, type EthisysPluginOptions, type ManifestReactiveRuleRef, type ManifestResourceRef, type ParsePlatformReactPagesOptions, type PlatformReactManifest, type PlatformReactPageDeclaration, type PlatformReactPluginOptions, type ResolvedPlatformReactPage, type ValidationFailure, type ValidationResult, ethisysContractAPlugin, ethisysContractBPlugin, ethisysManifestPlugin, ethisysPlatformReactPlugin, parsePlatformReactPages, validateDeclarativeResource, validateReactiveRule };

package/dist/index.d.ts

@@ -136,7 +136,7 @@ declare function validateReactiveRule(rule: unknown, filePath: string): Validati
  * mirror the registry exactly; a drift between the two breaks the cross-repo
  * agreement that E4.S4 locks in.
  */
-declare const CONTRACT_B_SEMANTIC_PRIMITIVES: readonly ["Button", "DataTable", "Form", "EntityPicker", "CommandBar", "Drawer", "Modal", "CanvasSurface", "WebGLSurface"];
+declare const CONTRACT_B_SEMANTIC_PRIMITIVES: readonly ["Button", "DataTable", "Form", "EntityPicker", "CommandBar", "Drawer", "Modal", "CanvasSurface", "WebGLSurface", "Card", "Tabs", "Select", "Alert"];
 /**
  * Non-component import-map entries — the runtime libraries the worker is
  * permitted to resolve via bare specifiers. Authoring constraint: the plugin's
@@ -219,6 +219,139 @@ interface ContractBPluginOptions {
  */
 declare function ethisysContractBPlugin(options?: ContractBPluginOptions): Plugin;
 
+/**
+ * A single PlatformReact page declaration extracted from
+ * `ui.platformReactPages[]` in the manifest. Aligns with the typed interface
+ * defined in `ethisyscore-protocol` RFC 0003.
+ *
+ * - `id` is the host-side page identifier and the basename of the emitted
+ *   bundle (e.g. `id: "dashboard"` → `platform-react/dashboard.js`).
+ * - `moduleSpecifier` is a host-origin relative path to the page module — the
+ *   plugin author's source entry that Rollup bundles.
+ * - `exportName` is the named export Rollup keeps live in the bundle. The host
+ *   loader reads `bundle[exportName]` at mount time.
+ * - `title` is an optional display label for the host's surface chrome.
+ */
+interface PlatformReactPageDeclaration {
+    id?: string;
+    moduleSpecifier?: string;
+    exportName?: string;
+    title?: string;
+    [key: string]: unknown;
+}
+/**
+ * The subset of a manifest this pass consumes. Manifests are tolerated as a
+ * superset — extra fields are ignored so newer-schema manifests still load.
+ */
+interface PlatformReactManifest {
+    type?: string;
+    ui?: {
+        platformReactPages?: PlatformReactPageDeclaration[];
+        [key: string]: unknown;
+    };
+    [key: string]: unknown;
+}
+/**
+ * Author-facing options for the PlatformReact Vite pass.
+ */
+interface PlatformReactPluginOptions {
+    /**
+     * Root directory the manifest path is resolved against. When omitted,
+     * Vite's `configResolved` populates it from `config.root`.
+     */
+    root?: string;
+    /**
+     * Manifest path. Relative paths resolve against `root`. Defaults to
+     * `feature.manifest.json`.
+     */
+    manifestPath?: string;
+    /**
+     * Output prefix for emitted page assets and the companion manifest.
+     * Defaults to `platform-react/`.
+     */
+    outputPrefix?: string;
+}
+/**
+ * Build-time Vite/Rollup plugin pass for EthisysCore PlatformReact pages
+ * (RFC 0003: the high-trust, host-extension tier). For each entry under
+ * `ui.platformReactPages[]` in the manifest, registers a Rollup input that
+ * emits an ESM bundle the host loads via `import()` at surface mount time.
+ *
+ * Behaviour:
+ * - For each declared page: registers `{ "platform-react/<id>": <moduleSpecifier> }`
+ *   in Rollup's input table. Output is forced to `format: "es"` and
+ *   `inlineDynamicImports: true` so each page ships as ONE bundled module.
+ * - Emits a `platform-react/platform-react-pages.json` companion asset listing
+ *   the declared pages so the host (and the `.ccpkg` packaging step) can
+ *   inspect what the build produced.
+ * - When `ui.platformReactPages` is absent or empty: the pass is a no-op.
+ *   Composition is expected — the recommended template registers this pass
+ *   alongside Contract A / Contract B so a single Vite config covers every
+ *   render mode.
+ *
+ * Origin enforcement of the bundle URL at runtime is the host's responsibility
+ * (see `PlatformReactSurfaceMount.tsx` in `coreconnect-web`). This pass only
+ * blocks remote/absolute paths at the manifest layer so a malformed manifest
+ * fails fast.
+ */
+declare function ethisysPlatformReactPlugin(options?: PlatformReactPluginOptions): Plugin;
+
+/**
+ * A fully-validated PlatformReact page declaration. All fields are guaranteed
+ * present (no `undefined`), `exportName` is defaulted to `"default"`, and the
+ * `moduleSpecifier` is guaranteed to exist on disk when `verifyOnDisk: true`
+ * was passed to {@link parsePlatformReactPages}.
+ */
+interface ResolvedPlatformReactPage {
+    id: string;
+    moduleSpecifier: string;
+    exportName: string;
+    title: string | null;
+}
+/**
+ * Options for {@link parsePlatformReactPages}.
+ */
+interface ParsePlatformReactPagesOptions {
+    /**
+     * Root directory the manifest path and the page module specifiers are
+     * resolved against. Defaults to `process.cwd()`.
+     */
+    root?: string;
+    /**
+     * When `true`, every declared `moduleSpecifier` must exist on disk (relative
+     * to {@link root}). The default is `false` so the helper can be used to
+     * snapshot-test a manifest without checking-out the page source files.
+     */
+    verifyOnDisk?: boolean;
+}
+/**
+ * Parse + validate `ui.platformReactPages[]` declarations from a manifest
+ * file. Designed for plugin authors writing Vitest tests against their own
+ * manifest — the helper applies the same shape and uniqueness rules the
+ * build-time Vite pass enforces, so a passing unit test gives the same
+ * guarantee a green build would.
+ *
+ * Returns an empty array when the manifest does not exist OR does not
+ * declare `ui.platformReactPages` OR declares it as an empty array.
+ *
+ * Throws on any malformed declaration. The thrown message matches the
+ * build-time error so a failing test reads identically to a failing build.
+ *
+ * @example
+ * ```ts
+ * import { parsePlatformReactPages } from "@ethisyscore/vite-plugin";
+ *
+ * test("manifest declares dashboard and admin pages", () => {
+ *   const pages = parsePlatformReactPages("./feature.manifest.json");
+ *   expect(pages).toEqual([
+ *     { id: "dashboard", moduleSpecifier: "src/pages/Dashboard.tsx", exportName: "default", title: "Dashboard" },
+ *     { id: "admin", moduleSpecifier: "src/pages/Admin.tsx", exportName: "AdminPage", title: null },
+ *   ]);
+ * });
+ * ```
+ */
+declare function parsePlatformReactPages(manifestPath: string, options?: ParsePlatformReactPagesOptions): ResolvedPlatformReactPage[];
+
 interface EthisysPluginOptions {
     /**
      * Path to the manifest file, relative to Vite's root directory.
@@ -242,4 +375,4 @@ interface EthisysPluginOptions {
  */
 declare function ethisysManifestPlugin(options?: EthisysPluginOptions): Plugin;
 
-export { CONTRACT_B_IMPORT_MAP_ALLOWLIST, CONTRACT_B_RUNTIME_IMPORTS, CONTRACT_B_SEMANTIC_PRIMITIVES, type ContractAManifest, type ContractAPluginOptions, type ContractBManifest, type ContractBPluginOptions, type EthisysPluginOptions, type ManifestReactiveRuleRef, type ManifestResourceRef, type ValidationFailure, type ValidationResult, ethisysContractAPlugin, ethisysContractBPlugin, ethisysManifestPlugin, validateDeclarativeResource, validateReactiveRule };
+export { CONTRACT_B_IMPORT_MAP_ALLOWLIST, CONTRACT_B_RUNTIME_IMPORTS, CONTRACT_B_SEMANTIC_PRIMITIVES, type ContractAManifest, type ContractAPluginOptions, type ContractBManifest, type ContractBPluginOptions, type EthisysPluginOptions, type ManifestReactiveRuleRef, type ManifestResourceRef, type ParsePlatformReactPagesOptions, type PlatformReactManifest, type PlatformReactPageDeclaration, type PlatformReactPluginOptions, type ResolvedPlatformReactPage, type ValidationFailure, type ValidationResult, ethisysContractAPlugin, ethisysContractBPlugin, ethisysManifestPlugin, ethisysPlatformReactPlugin, parsePlatformReactPages, validateDeclarativeResource, validateReactiveRule };