@ethisyscore/vite-plugin 1.5.2 → 1.6.0

package/dist/index.d.ts

@@ -1,5 +1,224 @@
 import { Plugin } from 'vite';
 
+/**
+ * Reference from the plugin manifest to an SDUI resource JSON file.
+ *
+ * Wave 0 convention: the manifest declares each declarative resource with
+ * a stable `uri` plus a `file` path (relative to the manifest's directory)
+ * pointing at the JSON document the host will serve. The static-file
+ * convention lets the Vite plugin validate the tree at build time without
+ * having to execute plugin runtime code.
+ */
+interface ManifestResourceRef {
+    uri: string;
+    /**
+     * Relative path (POSIX or platform-native) to the SDUI JSON document.
+     * Must not be absolute, must not contain `..` traversal segments.
+     */
+    file?: string;
+}
+/**
+ * Top-level manifest reactivity-rule declaration. Each entry pairs an
+ * author-supplied identifier with a {@link import("@ethisyscore/protocol").ReactiveRule}.
+ *
+ * Reactivity declared inline on SDUI nodes (the `bindings` property) is
+ * validated by the SDUI-tree pass; this surface covers the rarer case of
+ * a manifest-level rule that applies cross-resource.
+ */
+interface ManifestReactiveRuleRef {
+    id: string;
+    rule: unknown;
+}
+/**
+ * The subset of the plugin manifest the Contract A Vite plugin pass cares
+ * about. The full manifest is intentionally a superset — the plugin
+ * tolerates additional fields it has not been taught yet so manifests
+ * built against a newer schema still load.
+ */
+interface ContractAManifest {
+    resources?: ManifestResourceRef[];
+    reactiveRules?: ManifestReactiveRuleRef[];
+    [key: string]: unknown;
+}
+/**
+ * Author-facing options for the Contract A Vite plugin pass.
+ *
+ * `root` defaults to Vite's resolved root at `configResolved` time, so the
+ * common case requires no configuration. `manifestPath` defaults to the
+ * `feature.manifest.json` convention emitted by the host-rendered
+ * scaffolding template; pass an absolute or relative path to override.
+ */
+interface ContractAPluginOptions {
+    /**
+     * 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` colocated with the Vite root.
+     */
+    manifestPath?: string;
+    /**
+     * Output prefix for emitted SDUI assets. Defaults to `sdui/`. The plugin
+     * always emits an `${prefix}sdui-manifest.json` index alongside the
+     * validated resource JSON.
+     */
+    outputPrefix?: string;
+}
+/**
+ * Build-time Vite/Rollup plugin pass for EthisysCore Contract A
+ * (`renderMode: host-rendered`) plugins.
+ *
+ * Reads `feature.manifest.json` (or `extension.manifest.json` via
+ * `manifestPath`), validates each declared SDUI resource against the
+ * protocol's `SduiNode` Zod schema, validates each manifest-level
+ * reactivity rule against `ReactiveRule`, and emits the validated JSON
+ * into the Rollup bundle under the configured output prefix. Validation
+ * failures abort the build with a multi-line structured error that names
+ * the offending operator/primitive and the source file path + JSON
+ * pointer so the author can land on the offending node immediately.
+ *
+ * Worker-bundle emission for `renderMode: remote-runtime` is deferred to
+ * Wave 1's E7.S1b — this pass deliberately does nothing for non-Contract-A
+ * manifests.
+ */
+declare function ethisysContractAPlugin(options?: ContractAPluginOptions): Plugin;
+
+/**
+ * A single, structured validation failure surfaced by the Contract A
+ * schema validators. Carries enough context for a build-time error
+ * to be actionable without the plugin author opening the host runtime.
+ */
+interface ValidationFailure {
+    /** Absolute path of the source file whose JSON failed validation. */
+    filePath: string;
+    /**
+     * JSON-pointer (RFC 6901) into the failing JSON document, pointing at
+     * the offending node. Empty string when the offender is the root.
+     */
+    pointer: string;
+    /** The offending operator / primitive / rule-kind name, if extractable. */
+    offender?: string;
+    /** Human-readable message suitable for surfacing at the build CLI. */
+    message: string;
+}
+/**
+ * Result of a validation call. Discriminated on `ok` so callers can branch
+ * narrowly without juggling exception flow for expected outcomes.
+ */
+type ValidationResult = {
+    ok: true;
+} | {
+    ok: false;
+    failures: ValidationFailure[];
+};
+/**
+ * Validate a single declarative SDUI resource against the protocol's
+ * {@link SduiNode} Zod schema. The recursive schema rejects unknown
+ * primitives and unknown JsonLogic operators at any depth of the tree.
+ *
+ * `filePath` is propagated into every emitted failure so the build CLI
+ * can point the author at the exact file on disk.
+ */
+declare function validateDeclarativeResource(doc: unknown, uri: string, filePath: string): ValidationResult;
+/**
+ * Validate a single {@link ReactiveRule} against the protocol's curated
+ * JsonLogic operator subset. Used for top-level reactivity declarations
+ * declared on the manifest itself (i.e. not embedded under a `bindings`
+ * key on a SDUI node — those are covered by {@link validateDeclarativeResource}).
+ */
+declare function validateReactiveRule(rule: unknown, filePath: string): ValidationResult;
+
+/**
+ * Contract B semantic primitive vocabulary (the closed v1 set authored in
+ * `sdk/extension-runtime/src/host/worker/component-registry.ts`). The names
+ * 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"];
+/**
+ * Non-component import-map entries — the runtime libraries the worker is
+ * permitted to resolve via bare specifiers. Authoring constraint: the plugin's
+ * single ESM bundle (Contract B emits exactly one — see `worker-bundle.ts`)
+ * can `import x from "react"` or `import { ... } from "@ethisyscore/extension-runtime"`
+ * and nothing else off-bundle.
+ */
+declare const CONTRACT_B_RUNTIME_IMPORTS: readonly ["react", "@ethisyscore/extension-runtime"];
+/**
+ * Full allowlist of bare specifiers a Contract B plugin bundle may import.
+ * Frozen at module load so plugins can't mutate it via a transitive dep.
+ */
+declare const CONTRACT_B_IMPORT_MAP_ALLOWLIST: readonly string[];
+/**
+ * The subset of a Contract B (`renderMode: remote-runtime`) plugin manifest
+ * that this Vite pass consumes. Manifests are tolerated as a superset — extra
+ * fields are ignored so newer-schema manifests still load.
+ */
+interface ContractBManifest {
+    renderMode?: string;
+    /**
+     * Worker bundle declaration. Required when `renderMode === "remote-runtime"`.
+     * The `entry` is a relative path (POSIX or platform-native) from the
+     * manifest's directory to the plugin's TypeScript/JavaScript entrypoint.
+     *
+     * Absolute paths, path-traversal, and non-host-origin URLs are rejected at
+     * build time — Contract B requires the worker bundle to be a host-origin
+     * asset (the import-map enforcement in E4.S4 builds on this guarantee).
+     */
+    worker?: {
+        entry?: string;
+    };
+    [key: string]: unknown;
+}
+/**
+ * Author-facing options for the Contract B Vite pass.
+ */
+interface ContractBPluginOptions {
+    /**
+     * 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 worker assets and the worker-bundle manifest.
+     * Defaults to `worker/`.
+     */
+    outputPrefix?: string;
+}
+/**
+ * Build-time Vite/Rollup plugin pass for EthisysCore Contract B
+ * (`renderMode: remote-runtime`) plugins.
+ *
+ * Behaviour:
+ * - For `renderMode: "remote-runtime"`: declares a single ESM worker entry as
+ *   the Rollup input table. The output is forced to `format: "es"` and
+ *   `inlineDynamicImports: true` so a Contract B plugin always ships as ONE
+ *   bundled module — no chunk splitting, no shared chunks, no async imports
+ *   spread across multiple files. This is the precondition for E4.S4's
+ *   frozen import map.
+ * - For any other `renderMode` (including `host-rendered` and `undefined`):
+ *   the pass is a no-op. The Wave 0 Contract A path (`ethisysContractAPlugin`)
+ *   continues to apply without interference. Composition is expected — the
+ *   recommended template registers both plugins so a manifest can switch
+ *   render modes without changing its Vite config.
+ *
+ * The pass also emits a `worker/worker-bundle.json` companion asset listing
+ * the bundled entry so the host (or downstream packaging) can inspect what
+ * the build produced without re-parsing the bundle.
+ *
+ * Origin enforcement on the import map (path-pinned host origin, no `data:` /
+ * `blob:` imports) is the responsibility of E4.S4 (worker bootstrap) — this
+ * pass only blocks remote/absolute paths at the manifest layer so a malformed
+ * manifest fails fast.
+ */
+declare function ethisysContractBPlugin(options?: ContractBPluginOptions): Plugin;
+
 interface EthisysPluginOptions {
     /**
      * Path to the manifest file, relative to Vite's root directory.
@@ -23,4 +242,4 @@ interface EthisysPluginOptions {
  */
 declare function ethisysManifestPlugin(options?: EthisysPluginOptions): Plugin;
 
-export { type EthisysPluginOptions, ethisysManifestPlugin };
+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 };