@ethisyscore/vite-plugin 1.16.0 → 1.18.0

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { Plugin } from 'vite';
+import { Plugin, InlineConfig } from 'vite';
 
 /**
  * Reference from the plugin manifest to an SDUI resource JSON file.
@@ -352,6 +352,169 @@ interface ParsePlatformReactPagesOptions {
  */
 declare function parsePlatformReactPages(manifestPath: string, options?: ParsePlatformReactPagesOptions): ResolvedPlatformReactPage[];
 
+/**
+ * Specifiers the host realm provides at runtime — never bundled into a page.
+ * A `components/ui/*` abstraction that re-exports `@mui/material` therefore
+ * costs zero bundle weight and shares the host's MUI singleton + theme.
+ */
+declare const PLATFORM_REACT_EXTERNALS: readonly string[];
+/**
+ * Bundled deps that MUST resolve to a single copy. When a bundled dep (e.g.
+ * `@tanstack/react-query`) is imported by BOTH the plugin's own hooks and the
+ * SDK foundation (aliased cross-repo to a sibling `dist`), the bundler otherwise
+ * resolves two copies — one per repo's `node_modules`. Two module instances =
+ * two React contexts, so a provider in one is invisible to a consumer in the
+ * other (the classic "No QueryClient set"). Pin them to one copy.
+ */
+declare const PLATFORM_REACT_DEDUPE: readonly string[];
+/** A `resolve.alias` entry (string or regex find), as Vite accepts. */
+interface PlatformReactAlias {
+    find: string | RegExp;
+    replacement: string;
+}
+/**
+ * One surface declared in `feature.manifest.json` (`ui.platformReactPages[]`).
+ * `views` is the page's `useView` manifest slice — the adapter-view modules it
+ * renders by name (`{ DayView: "src/adapter/<feature>/DayView.tsx" }`). It rides
+ * along as an open extra field the SDK's manifest readers ignore.
+ */
+interface PlatformReactPageInput {
+    id: string;
+    moduleSpecifier: string;
+    exportName?: string;
+    title?: string | null;
+    views?: Record<string, string>;
+}
+/** The fully-resolved per-page build context handed to the (injectable) builder. */
+interface PlatformReactBuildContext {
+    pageId: string;
+    /** Virtual entry module id (`\0virtual:surface/<id>`). */
+    entryId: string;
+    /** Rollup plugin that resolves + loads the synthesised virtual entry. */
+    surfacePlugin: Plugin;
+    root: string;
+    outDir: string;
+    outputPrefix: string;
+    external: readonly string[];
+    dedupe: readonly string[];
+    alias: PlatformReactAlias[];
+    plugins: Plugin[];
+    target: string;
+    minify: boolean;
+    sourcemap: boolean;
+}
+/** Low-level Vite `build` function. Defaults to a dynamic `import("vite")`. */
+type ViteBuildFn = (config: InlineConfig) => Promise<unknown>;
+/** Injectable per-page builder. Defaults to a real Vite library build. */
+type PlatformReactViteBuild = (ctx: PlatformReactBuildContext) => Promise<void>;
+interface BuildPlatformReactPagesOptions {
+    /** Root the manifest + `src/…` paths resolve against. Default `process.cwd()`. */
+    root?: string;
+    /** Manifest path (relative to `root`). Default `feature.manifest.json`. */
+    manifestPath?: string;
+    /** Inline manifest object (test injection). When omitted, read from disk. */
+    manifest?: unknown;
+    /** Output directory the bundles + companion JSON land in. Default `dist`. */
+    outDir?: string;
+    /** Sub-directory + summary/digest key prefix. Default `platform-react`. */
+    outputPrefix?: string;
+    /** Plugin-specific `resolve.alias` entries (contracts, router shim, `@/`, …). */
+    alias?: PlatformReactAlias[];
+    /** Plugin-specific Vite plugins (e.g. `react()`, `tailwindcss()`). */
+    plugins?: Plugin[];
+    /** Bundled deps to dedupe. Default {@link PLATFORM_REACT_DEDUPE}. */
+    dedupe?: readonly string[];
+    /** Host externals. Default {@link PLATFORM_REACT_EXTERNALS}. */
+    external?: readonly string[];
+    /** Module specifier the generated entry imports `definePluginPage` from. */
+    definePluginPageSpecifier?: string;
+    /** Source dir stripped when rewriting manifest paths to the alias. Default `src`. */
+    srcDir?: string;
+    /** Alias prefix manifest `src/…` paths are rewritten to. Default `@` (→ `@/…`). */
+    aliasPrefix?: string;
+    /** Rollup build target. Default `es2022`. */
+    target?: string;
+    /** Minify output. Default `false` (digest stability + debuggability). */
+    minify?: boolean;
+    /** Emit sourcemaps. Default `true`. */
+    sourcemap?: boolean;
+    /** Wipe `outDir` before building. Default `true`. */
+    clean?: boolean;
+    /** Progress logger. Default `console`. */
+    logger?: Pick<Console, "log" | "warn">;
+    /** Low-level Vite `build` (production override so the CONSUMER's vite is used). */
+    viteBuild?: ViteBuildFn;
+    /** Injectable per-page builder (test injection — skips Vite entirely). */
+    build?: PlatformReactViteBuild;
+    /** Injectable bundle reader for digesting. Default `fs.readFileSync` (utf-8). */
+    readFile?: (path: string) => string;
+    /** Injectable file writer. Default `fs.writeFileSync` (creating dirs). */
+    writeFile?: (path: string, contents: string) => void;
+}
+interface PlatformReactBuildSummary {
+    pages: Array<{
+        id: string;
+        exportName: string;
+        title: string | null;
+        bundlePath: string;
+        source: string;
+    }>;
+    digests: Array<{
+        path: string;
+        sha256: string;
+    }>;
+    summaryPath: string | null;
+    digestMapPath: string | null;
+}
+/**
+ * Rollup output pass: rewrite aliased named imports from host externals into the
+ * namespace-import form the host's PlatformReact loader accepts.
+ *
+ * esbuild emits `import { Dialog as Dialog$1 } from "@mui/material"` to
+ * deconflict a name collision (an adapter view imports MUI `Dialog` directly
+ * while a feature component pulls in the `components/ui/dialog` wrapper of the
+ * same name). The host loader handles `import * as X`, plain `import { Y }`,
+ * default imports, and aliased EXPORTS — but throws "Unexpected identifier 'as'"
+ * on aliased named IMPORTS `{ X as Y }`. In a final `inlineDynamicImports`
+ * bundle every remaining `import { … } from "…"` is an EXTERNAL import, so
+ * rewriting any that contain `as` into `import * as ns from "…"; const local =
+ * ns.imported, …;` is safe and removes the only construct the loader rejects.
+ * Runs in `renderChunk`, before the host-verified digest is computed.
+ */
+declare function rewriteAliasedExternalImports(): Plugin;
+/**
+ * Synthesise one isolated PlatformReact entry per surface straight from its
+ * manifest declaration: `definePluginPage(Page, { …views })`, importing ONLY
+ * that surface's page (`moduleSpecifier`) + adapter views (`views`) so each
+ * bundle stays self-contained. Returned as a Rollup virtual module so there are
+ * no physical per-page entry files — the manifest is the single source of truth.
+ * `src/…` paths are rewritten to the alias the build resolves (e.g. `@/…`).
+ */
+declare function virtualPageEntry(page: PlatformReactPageInput, config: {
+    definePluginPageSpecifier: string;
+    toAlias: (p: string) => string;
+}): {
+    id: string;
+    plugin: Plugin;
+};
+/**
+ * Build every `ui.platformReactPages[]` surface as its own self-contained ESM
+ * bundle and emit the companion `platform-react-pages.json` summary + the
+ * per-asset SHA-256 `platform-react-digest-map.json` the host's verified loader
+ * and the `.ccpkg` packaging step read.
+ *
+ * Each PlatformReact page must be ONE bundle (`inlineDynamicImports: true`), and
+ * Rollup rejects that with more than one input — so this runs one Vite sub-build
+ * per surface, each with a single synthesised virtual entry (see
+ * {@link virtualPageEntry}). The generic seams (host externals, dedupe, the
+ * host-loader aliased-import rewrite, the digest/summary contract) live here;
+ * the plugin supplies only its `alias` entries + `plugins` (and, in production,
+ * its own `viteBuild` so the consumer's Vite is used, not the SDK's).
+ *
+ * No-op (returns empty) when no pages are declared.
+ */
+declare function buildPlatformReactPages(options?: BuildPlatformReactPagesOptions): Promise<PlatformReactBuildSummary>;
+
 /** One emitted artifact from a per-page Vite sub-build. */
 type IframeBuildOutputItem = {
     type: "chunk";
@@ -443,4 +606,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 IframeBuildContext, type IframeBuildOutputItem, type IframeBuildResult, type IframeSandboxBuildSummary, type IframeSandboxPluginOptions, type IframeViteBuild, type ManifestReactiveRuleRef, type ManifestResourceRef, type ParsePlatformReactPagesOptions, type PlatformReactManifest, type PlatformReactPageDeclaration, type PlatformReactPluginOptions, type ResolvedPlatformReactPage, type ValidationFailure, type ValidationResult, buildIframeSandboxPages, ethisysContractAPlugin, ethisysContractBPlugin, ethisysIframeSandboxPlugin, ethisysManifestPlugin, ethisysPlatformReactPlugin, parsePlatformReactPages, validateDeclarativeResource, validateReactiveRule };
+export { type BuildPlatformReactPagesOptions, CONTRACT_B_IMPORT_MAP_ALLOWLIST, CONTRACT_B_RUNTIME_IMPORTS, CONTRACT_B_SEMANTIC_PRIMITIVES, type ContractAManifest, type ContractAPluginOptions, type ContractBManifest, type ContractBPluginOptions, type EthisysPluginOptions, type IframeBuildContext, type IframeBuildOutputItem, type IframeBuildResult, type IframeSandboxBuildSummary, type IframeSandboxPluginOptions, type IframeViteBuild, type ManifestReactiveRuleRef, type ManifestResourceRef, PLATFORM_REACT_DEDUPE, PLATFORM_REACT_EXTERNALS, type ParsePlatformReactPagesOptions, type PlatformReactAlias, type PlatformReactBuildContext, type PlatformReactBuildSummary, type PlatformReactManifest, type PlatformReactPageDeclaration, type PlatformReactPageInput, type PlatformReactPluginOptions, type PlatformReactViteBuild, type ResolvedPlatformReactPage, type ValidationFailure, type ValidationResult, type ViteBuildFn, buildIframeSandboxPages, buildPlatformReactPages, ethisysContractAPlugin, ethisysContractBPlugin, ethisysIframeSandboxPlugin, ethisysManifestPlugin, ethisysPlatformReactPlugin, parsePlatformReactPages, rewriteAliasedExternalImports, validateDeclarativeResource, validateReactiveRule, virtualPageEntry };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { Plugin } from 'vite';
+import { Plugin, InlineConfig } from 'vite';
 
 /**
  * Reference from the plugin manifest to an SDUI resource JSON file.
@@ -352,6 +352,169 @@ interface ParsePlatformReactPagesOptions {
  */
 declare function parsePlatformReactPages(manifestPath: string, options?: ParsePlatformReactPagesOptions): ResolvedPlatformReactPage[];
 
+/**
+ * Specifiers the host realm provides at runtime — never bundled into a page.
+ * A `components/ui/*` abstraction that re-exports `@mui/material` therefore
+ * costs zero bundle weight and shares the host's MUI singleton + theme.
+ */
+declare const PLATFORM_REACT_EXTERNALS: readonly string[];
+/**
+ * Bundled deps that MUST resolve to a single copy. When a bundled dep (e.g.
+ * `@tanstack/react-query`) is imported by BOTH the plugin's own hooks and the
+ * SDK foundation (aliased cross-repo to a sibling `dist`), the bundler otherwise
+ * resolves two copies — one per repo's `node_modules`. Two module instances =
+ * two React contexts, so a provider in one is invisible to a consumer in the
+ * other (the classic "No QueryClient set"). Pin them to one copy.
+ */
+declare const PLATFORM_REACT_DEDUPE: readonly string[];
+/** A `resolve.alias` entry (string or regex find), as Vite accepts. */
+interface PlatformReactAlias {
+    find: string | RegExp;
+    replacement: string;
+}
+/**
+ * One surface declared in `feature.manifest.json` (`ui.platformReactPages[]`).
+ * `views` is the page's `useView` manifest slice — the adapter-view modules it
+ * renders by name (`{ DayView: "src/adapter/<feature>/DayView.tsx" }`). It rides
+ * along as an open extra field the SDK's manifest readers ignore.
+ */
+interface PlatformReactPageInput {
+    id: string;
+    moduleSpecifier: string;
+    exportName?: string;
+    title?: string | null;
+    views?: Record<string, string>;
+}
+/** The fully-resolved per-page build context handed to the (injectable) builder. */
+interface PlatformReactBuildContext {
+    pageId: string;
+    /** Virtual entry module id (`\0virtual:surface/<id>`). */
+    entryId: string;
+    /** Rollup plugin that resolves + loads the synthesised virtual entry. */
+    surfacePlugin: Plugin;
+    root: string;
+    outDir: string;
+    outputPrefix: string;
+    external: readonly string[];
+    dedupe: readonly string[];
+    alias: PlatformReactAlias[];
+    plugins: Plugin[];
+    target: string;
+    minify: boolean;
+    sourcemap: boolean;
+}
+/** Low-level Vite `build` function. Defaults to a dynamic `import("vite")`. */
+type ViteBuildFn = (config: InlineConfig) => Promise<unknown>;
+/** Injectable per-page builder. Defaults to a real Vite library build. */
+type PlatformReactViteBuild = (ctx: PlatformReactBuildContext) => Promise<void>;
+interface BuildPlatformReactPagesOptions {
+    /** Root the manifest + `src/…` paths resolve against. Default `process.cwd()`. */
+    root?: string;
+    /** Manifest path (relative to `root`). Default `feature.manifest.json`. */
+    manifestPath?: string;
+    /** Inline manifest object (test injection). When omitted, read from disk. */
+    manifest?: unknown;
+    /** Output directory the bundles + companion JSON land in. Default `dist`. */
+    outDir?: string;
+    /** Sub-directory + summary/digest key prefix. Default `platform-react`. */
+    outputPrefix?: string;
+    /** Plugin-specific `resolve.alias` entries (contracts, router shim, `@/`, …). */
+    alias?: PlatformReactAlias[];
+    /** Plugin-specific Vite plugins (e.g. `react()`, `tailwindcss()`). */
+    plugins?: Plugin[];
+    /** Bundled deps to dedupe. Default {@link PLATFORM_REACT_DEDUPE}. */
+    dedupe?: readonly string[];
+    /** Host externals. Default {@link PLATFORM_REACT_EXTERNALS}. */
+    external?: readonly string[];
+    /** Module specifier the generated entry imports `definePluginPage` from. */
+    definePluginPageSpecifier?: string;
+    /** Source dir stripped when rewriting manifest paths to the alias. Default `src`. */
+    srcDir?: string;
+    /** Alias prefix manifest `src/…` paths are rewritten to. Default `@` (→ `@/…`). */
+    aliasPrefix?: string;
+    /** Rollup build target. Default `es2022`. */
+    target?: string;
+    /** Minify output. Default `false` (digest stability + debuggability). */
+    minify?: boolean;
+    /** Emit sourcemaps. Default `true`. */
+    sourcemap?: boolean;
+    /** Wipe `outDir` before building. Default `true`. */
+    clean?: boolean;
+    /** Progress logger. Default `console`. */
+    logger?: Pick<Console, "log" | "warn">;
+    /** Low-level Vite `build` (production override so the CONSUMER's vite is used). */
+    viteBuild?: ViteBuildFn;
+    /** Injectable per-page builder (test injection — skips Vite entirely). */
+    build?: PlatformReactViteBuild;
+    /** Injectable bundle reader for digesting. Default `fs.readFileSync` (utf-8). */
+    readFile?: (path: string) => string;
+    /** Injectable file writer. Default `fs.writeFileSync` (creating dirs). */
+    writeFile?: (path: string, contents: string) => void;
+}
+interface PlatformReactBuildSummary {
+    pages: Array<{
+        id: string;
+        exportName: string;
+        title: string | null;
+        bundlePath: string;
+        source: string;
+    }>;
+    digests: Array<{
+        path: string;
+        sha256: string;
+    }>;
+    summaryPath: string | null;
+    digestMapPath: string | null;
+}
+/**
+ * Rollup output pass: rewrite aliased named imports from host externals into the
+ * namespace-import form the host's PlatformReact loader accepts.
+ *
+ * esbuild emits `import { Dialog as Dialog$1 } from "@mui/material"` to
+ * deconflict a name collision (an adapter view imports MUI `Dialog` directly
+ * while a feature component pulls in the `components/ui/dialog` wrapper of the
+ * same name). The host loader handles `import * as X`, plain `import { Y }`,
+ * default imports, and aliased EXPORTS — but throws "Unexpected identifier 'as'"
+ * on aliased named IMPORTS `{ X as Y }`. In a final `inlineDynamicImports`
+ * bundle every remaining `import { … } from "…"` is an EXTERNAL import, so
+ * rewriting any that contain `as` into `import * as ns from "…"; const local =
+ * ns.imported, …;` is safe and removes the only construct the loader rejects.
+ * Runs in `renderChunk`, before the host-verified digest is computed.
+ */
+declare function rewriteAliasedExternalImports(): Plugin;
+/**
+ * Synthesise one isolated PlatformReact entry per surface straight from its
+ * manifest declaration: `definePluginPage(Page, { …views })`, importing ONLY
+ * that surface's page (`moduleSpecifier`) + adapter views (`views`) so each
+ * bundle stays self-contained. Returned as a Rollup virtual module so there are
+ * no physical per-page entry files — the manifest is the single source of truth.
+ * `src/…` paths are rewritten to the alias the build resolves (e.g. `@/…`).
+ */
+declare function virtualPageEntry(page: PlatformReactPageInput, config: {
+    definePluginPageSpecifier: string;
+    toAlias: (p: string) => string;
+}): {
+    id: string;
+    plugin: Plugin;
+};
+/**
+ * Build every `ui.platformReactPages[]` surface as its own self-contained ESM
+ * bundle and emit the companion `platform-react-pages.json` summary + the
+ * per-asset SHA-256 `platform-react-digest-map.json` the host's verified loader
+ * and the `.ccpkg` packaging step read.
+ *
+ * Each PlatformReact page must be ONE bundle (`inlineDynamicImports: true`), and
+ * Rollup rejects that with more than one input — so this runs one Vite sub-build
+ * per surface, each with a single synthesised virtual entry (see
+ * {@link virtualPageEntry}). The generic seams (host externals, dedupe, the
+ * host-loader aliased-import rewrite, the digest/summary contract) live here;
+ * the plugin supplies only its `alias` entries + `plugins` (and, in production,
+ * its own `viteBuild` so the consumer's Vite is used, not the SDK's).
+ *
+ * No-op (returns empty) when no pages are declared.
+ */
+declare function buildPlatformReactPages(options?: BuildPlatformReactPagesOptions): Promise<PlatformReactBuildSummary>;
+
 /** One emitted artifact from a per-page Vite sub-build. */
 type IframeBuildOutputItem = {
     type: "chunk";
@@ -443,4 +606,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 IframeBuildContext, type IframeBuildOutputItem, type IframeBuildResult, type IframeSandboxBuildSummary, type IframeSandboxPluginOptions, type IframeViteBuild, type ManifestReactiveRuleRef, type ManifestResourceRef, type ParsePlatformReactPagesOptions, type PlatformReactManifest, type PlatformReactPageDeclaration, type PlatformReactPluginOptions, type ResolvedPlatformReactPage, type ValidationFailure, type ValidationResult, buildIframeSandboxPages, ethisysContractAPlugin, ethisysContractBPlugin, ethisysIframeSandboxPlugin, ethisysManifestPlugin, ethisysPlatformReactPlugin, parsePlatformReactPages, validateDeclarativeResource, validateReactiveRule };
+export { type BuildPlatformReactPagesOptions, CONTRACT_B_IMPORT_MAP_ALLOWLIST, CONTRACT_B_RUNTIME_IMPORTS, CONTRACT_B_SEMANTIC_PRIMITIVES, type ContractAManifest, type ContractAPluginOptions, type ContractBManifest, type ContractBPluginOptions, type EthisysPluginOptions, type IframeBuildContext, type IframeBuildOutputItem, type IframeBuildResult, type IframeSandboxBuildSummary, type IframeSandboxPluginOptions, type IframeViteBuild, type ManifestReactiveRuleRef, type ManifestResourceRef, PLATFORM_REACT_DEDUPE, PLATFORM_REACT_EXTERNALS, type ParsePlatformReactPagesOptions, type PlatformReactAlias, type PlatformReactBuildContext, type PlatformReactBuildSummary, type PlatformReactManifest, type PlatformReactPageDeclaration, type PlatformReactPageInput, type PlatformReactPluginOptions, type PlatformReactViteBuild, type ResolvedPlatformReactPage, type ValidationFailure, type ValidationResult, type ViteBuildFn, buildIframeSandboxPages, buildPlatformReactPages, ethisysContractAPlugin, ethisysContractBPlugin, ethisysIframeSandboxPlugin, ethisysManifestPlugin, ethisysPlatformReactPlugin, parsePlatformReactPages, rewriteAliasedExternalImports, validateDeclarativeResource, validateReactiveRule, virtualPageEntry };