@vmz/plugin 0.3.6 → 0.3.8

package/README.md

@@ -1,57 +1,57 @@
-# @vmz/plugin
-
-## Build extensions without dissolving the application boundary
-
-`@vmz/plugin` is the foundation for authors who want to extend VMZ with a domain capability: a renderer, a content
-processor, a language integration, an editor, a design-oriented utility, or another contribution that belongs in a
-full-stack application workflow.
-
-## The promise to plugin authors
-
-VMZ should be hospitable to npm and JavaScript ecosystem packages. You should be able to package, version, distribute,
-and compose useful functionality with normal Node tooling. A plugin can contribute declared capabilities and source
-assets without forcing every project to adopt a bespoke compiler fork.
-
-## The promise to application authors
-
-Extensions stay transparent to the application model. A VMZ plugin is a versioned contribution surface — not an
-unrestricted `transform(code)` escape hatch or an in-place rewrite of the program graph. Declared contributions keep
-ownership, execution placement, SSR, resume, testing, diagnostics, and deployment explainable.
-
-This is the tradeoff: plugin authors gain a stable way to participate in VMZ, while users retain a coherent application
-model after installing the plugin. If an integration requires arbitrary runtime injection or hidden semantic rewrites,
-it belongs outside the core VMZ plugin contract.
-
-| A plugin contributes...                            | So that VMZ can still...                           |
-|----------------------------------------------------|----------------------------------------------------|
-| A declared capability with known inputs and output | Keep one application runtime and Program Graph     |
-| Versioned integration behavior                     | Explain ownership, placement, and diagnostics      |
-| Assets or adapters VMZ can place and test          | Honor server, lifecycle, and deployment boundaries |
-
-## Who should use it
-
-Use this package when you are creating a native VMZ integration, not when you simply need a conventional JavaScript
-library in application code. The latter should remain a normal dependency unless it needs to participate in VMZ's
-compiler-visible boundaries.
-
-## What a strong plugin can unlock 🚀
-
-- A content engine can contribute deterministic rendered output and diagnostics.
-- An editor can declare browser-only delivery while preserving an SSR-readable host.
-- A design tool can expose compile-time tokens without becoming a global runtime store.
-- A deployment adapter can contribute a target without rewriting application semantics.
-- A testing integration can add evidence while preserving VMZ's test model.
-
-## Why contribution beats mutation
-
-Mutation is convenient for the first plugin and expensive for the fiftieth. If every plugin can rewrite any source,
-graph node, or generated artifact, composition order becomes application semantics and no tool can explain the final
-result.
-
-A contribution says what capability is being added, which versioned schema it follows, what it reads, what it emits, and
-where it may execute. That extra structure is what allows npm extensibility and strong compilation to coexist.
-
-## The litmus test
-
-If installing the plugin makes `vmz check`, SSR, resume, tests, or deployment less able to explain the application, the
-integration is using the wrong boundary. A native plugin should leave VMZ more capable, not less coherent.
+# @vmz/plugin
+
+## Build extensions without dissolving the application boundary
+
+`@vmz/plugin` is the foundation for authors who want to extend VMZ with a domain capability: a renderer, a content
+processor, a language integration, an editor, a design-oriented utility, or another contribution that belongs in a
+full-stack application workflow.
+
+## The promise to plugin authors
+
+VMZ should be hospitable to npm and JavaScript ecosystem packages. You should be able to package, version, distribute,
+and compose useful functionality with normal Node tooling. A plugin can contribute declared capabilities and source
+assets without forcing every project to adopt a bespoke compiler fork.
+
+## The promise to application authors
+
+Extensions stay transparent to the application model. A VMZ plugin is a versioned contribution surface — not an
+unrestricted `transform(code)` escape hatch or an in-place rewrite of the program graph. Declared contributions keep
+ownership, execution placement, SSR, resume, testing, diagnostics, and deployment explainable.
+
+This is the tradeoff: plugin authors gain a stable way to participate in VMZ, while users retain a coherent application
+model after installing the plugin. If an integration requires arbitrary runtime injection or hidden semantic rewrites,
+it belongs outside the core VMZ plugin contract.
+
+| A plugin contributes...                            | So that VMZ can still...                           |
+|----------------------------------------------------|----------------------------------------------------|
+| A declared capability with known inputs and output | Keep one application runtime and Program Graph     |
+| Versioned integration behavior                     | Explain ownership, placement, and diagnostics      |
+| Assets or adapters VMZ can place and test          | Honor server, lifecycle, and deployment boundaries |
+
+## Who should use it
+
+Use this package when you are creating a native VMZ integration, not when you simply need a conventional JavaScript
+library in application code. The latter should remain a normal dependency unless it needs to participate in VMZ's
+compiler-visible boundaries.
+
+## What a strong plugin can unlock 🚀
+
+- A content engine can contribute deterministic rendered output and diagnostics.
+- An editor can declare browser-only delivery while preserving an SSR-readable host.
+- A design tool can expose compile-time tokens without becoming a global runtime store.
+- A deployment adapter can contribute a target without rewriting application semantics.
+- A testing integration can add evidence while preserving VMZ's test model.
+
+## Why contribution beats mutation
+
+Mutation is convenient for the first plugin and expensive for the fiftieth. If every plugin can rewrite any source,
+graph node, or generated artifact, composition order becomes application semantics and no tool can explain the final
+result.
+
+A contribution says what capability is being added, which versioned schema it follows, what it reads, what it emits, and
+where it may execute. That extra structure is what allows npm extensibility and strong compilation to coexist.
+
+## The litmus test
+
+If installing the plugin makes `vmz check`, SSR, resume, tests, or deployment less able to explain the application, the
+integration is using the wrong boundary. A native plugin should leave VMZ more capable, not less coherent.

package/index.d.ts

@@ -1,216 +1,216 @@
-/** VMZ plugin protocol helpers — types + identity `define*` (no N-API). */
-
-export { PLUGIN_PROTOCOL } from '@vmz/protocol';
-
-export function contentHash(content: string | Buffer): string;
-
-/** Resolve a path next to the calling module (`import.meta.url`). */
-export function pluginFileUrl(importMetaUrl: string, relativePath: string): string;
-
-/**
- * Load a real source file shipped with the plugin (typically `components/*.vmz`).
- * Do not embed `.vmz` SFC text inside `vmz.plugin.ts`.
- */
-export function loadPluginSource(
-    importMetaUrl: string,
-    relativePath: string,
-): {
-    content: string;
-    contentHash: string;
-    absPath: string;
-};
-
-export type PluginStage = 'workspace_resolve' | 'source_adapter' | 'analyzer' | 'target';
-
-export interface PluginManifest {
-    name: string;
-    version: string;
-    protocol?: string;
-    stages: PluginStage[];
-    deterministic?: boolean;
-}
-
-export interface ResolvedPackage {
-    name: string;
-    root: string;
-    version?: string;
-}
-
-export interface PluginContext {
-    project: string;
-    outDir: string;
-    stage: PluginStage | string;
-    protocol: string;
-    packages: ResolvedPackage[];
-    /** Default engines from `vmz.config`. */
-    engines?: VmzEngines;
-}
-
-export interface ContributionItem {
-    id: string;
-    kind: string;
-    path?: string;
-    content?: string;
-    contentHash?: string;
-    content_hash?: string;
-    materialize?: boolean;
-    severity?: string;
-    message?: string;
-    code?: string;
-    targetId?: string;
-    target_id?: string;
-    targetKind?: string;
-    target_kind?: string;
-    type?: string;
-    manifest?: unknown;
-    manifestJson?: string;
-    manifest_json?: string;
-    detail?: string;
-    /** Engine registration (host-recognized analyzer/source sidecar). */
-    engine?: string;
-    engineKind?: 'code' | 'math' | 'markdown' | string;
-}
-
-export interface ContributionBatchInput {
-    stage: PluginStage | string;
-    cacheKey?: string;
-    deterministic?: boolean;
-    items: ContributionItem[];
-}
-
-export interface VmzPlugin {
-    manifest: PluginManifest;
-    contribute?: (
-        ctx: PluginContext,
-    ) => Promise<ContributionBatchInput[] | ContributionBatchInput> | ContributionBatchInput[] | ContributionBatchInput;
-}
-
-export interface VmzEngines {
-    /** Default for `<Code>` when `engine` prop omitted. */
-    code?: string;
-    /** Default for `<Math>` when `engine` prop omitted. */
-    math?: string;
-    /** Default for `<Markdown>` when `engine` prop omitted; also used by `vmz document`. */
-    markdown?: string;
-}
-
-/** Workspace format options (`vmz format` reads `vmz.config` `format`). */
-export interface VmzFormatConfig {
-    /** Include globs under the project root. */
-    includes?: string[];
-    /** Skip paths under these globs after includes expand. */
-    excludes?: string[];
-    /** Run `cargo fmt` when a Cargo workspace is present. */
-    rust?: boolean;
-    /** Run the Oak CST formatter on JS/TS targets. */
-    javascript?: boolean;
-    /** Format `.vmz` author files via `vmz-formatter`. */
-    vmz?: boolean;
-    /** Biome-style formatter config (default: `biome.json` at project root). */
-    style?: string;
-}
-
-export interface VmzUserConfig {
-    plugins?: Array<string | VmzPlugin | Promise<VmzPlugin>>;
-    engines?: VmzEngines;
-    /** Workspace format targets and engines (`vmz format`). */
-    format?: VmzFormatConfig;
-    /** Application identity (optional authoring). */
-    application?: { id?: string; [key: string]: unknown };
-    /**
-     * Delivery: named profiles (`default` + `profiles`) or legacy site sugar.
-     * Pure data only; never a parallel `vmz.site.ts` entry.
-     */
-    delivery?: DeliveryAuthoring;
-}
-
-/** Site resource sources (embedded | filesystem | remote) — orthogonal to assembly. */
-export interface SiteDeliveryAuthoring {
-    artifact: string;
-    siteId?: string;
-    sources: Array<{
-        id: string;
-        kind: 'embedded' | 'filesystem' | 'remote';
-        directory?: string;
-        baseUrl?: string;
-        artifact?: string;
-        trust?: string;
-        timeoutMs?: number;
-        priority?: number;
-        integrity?: unknown;
-        signaturePolicy?: string;
-    }>;
-    resolution?: {
-        mode?: 'release';
-        fallback?: string[];
-    };
-    activation?: 'atomic';
-    expectedCompatibility?: unknown;
-    failure?: unknown;
-    failurePolicy?: unknown;
-    update?: unknown;
-    updatePolicy?: unknown;
-    rollback?: unknown;
-    rollbackPolicy?: unknown;
-    security?: unknown;
-    securityPolicy?: unknown;
-}
-
-export type DeliveryAssembly = 'local-static' | 'web-static' | 'server-host' | 'cdn+server' | 'rust-embedded';
-
-export type DeliveryServerRuntime = 'node' | 'worker' | 'deno' | 'bun' | 'rust-host';
-
-export interface DeliveryProfileAuthoring {
-    host?: 'browser';
-    assembly: DeliveryAssembly;
-    /**
-     * Artifact directory under CLI `--out-dir` (default = profile id).
-     * Example: profile `static` + `name: 'cdn'` → `dist/cdn`.
-     */
-    name?: string;
-    serverRuntime?: DeliveryServerRuntime;
-    /** Inline site sources or `defineSite({...})`. */
-    sources?: SiteDeliveryAuthoring | SiteDeliveryAuthoring['sources'];
-    artifact?: string;
-    resolution?: SiteDeliveryAuthoring['resolution'];
-    activation?: SiteDeliveryAuthoring['activation'];
-}
-
-/** WeChat DevTools project identity. Pure data; not WeChat JSON / wx.* APIs. */
-export interface WechatPackagingAuthoring {
-    /** Registered AppID. Omit for WeChat tourist mode (`touristappid`). */
-    appId?: string;
-    projectName?: string;
-    /** `app.json` `window.navigationBarTitleText`. */
-    title?: string;
-}
-
-/** Vendor packaging identity under `defineConfig({ delivery })`. */
-export interface DeliveryPackagingAuthoring {
-    wechat?: WechatPackagingAuthoring;
-}
-
-/** Named profiles (preferred) or legacy site-only sugar. */
-export type DeliveryAuthoring =
-    | {
-          default?: string;
-          profiles: Record<string, DeliveryProfileAuthoring>;
-          packaging?: DeliveryPackagingAuthoring;
-      }
-    | (SiteDeliveryAuthoring & {
-          default?: string;
-          assembly?: DeliveryAssembly;
-          host?: 'browser';
-          serverRuntime?: DeliveryServerRuntime;
-          packaging?: DeliveryPackagingAuthoring;
-      });
-
-export type DefinePluginInput = PluginManifest & {
-    contribute?: VmzPlugin['contribute'];
-};
-
-/** Identity helper for IDE inference. */
-export function definePlugin(def: DefinePluginInput): VmzPlugin;
-
-/** Identity helper for `vmz.config.ts` inference. */
-export function defineConfig(config: VmzUserConfig): VmzUserConfig;
+/** VMZ plugin protocol helpers — types + identity `define*` (no N-API). */
+
+export { PLUGIN_PROTOCOL } from '@vmz/protocol';
+
+export function contentHash(content: string | Buffer): string;
+
+/** Resolve a path next to the calling module (`import.meta.url`). */
+export function pluginFileUrl(importMetaUrl: string, relativePath: string): string;
+
+/**
+ * Load a real source file shipped with the plugin (typically `components/*.vmz`).
+ * Do not embed `.vmz` SFC text inside `vmz.plugin.ts`.
+ */
+export function loadPluginSource(
+    importMetaUrl: string,
+    relativePath: string,
+): {
+    content: string;
+    contentHash: string;
+    absPath: string;
+};
+
+export type PluginStage = 'workspace_resolve' | 'source_adapter' | 'analyzer' | 'target';
+
+export interface PluginManifest {
+    name: string;
+    version: string;
+    protocol?: string;
+    stages: PluginStage[];
+    deterministic?: boolean;
+}
+
+export interface ResolvedPackage {
+    name: string;
+    root: string;
+    version?: string;
+}
+
+export interface PluginContext {
+    project: string;
+    outDir: string;
+    stage: PluginStage | string;
+    protocol: string;
+    packages: ResolvedPackage[];
+    /** Default engines from `vmz.config`. */
+    engines?: VmzEngines;
+}
+
+export interface ContributionItem {
+    id: string;
+    kind: string;
+    path?: string;
+    content?: string;
+    contentHash?: string;
+    content_hash?: string;
+    materialize?: boolean;
+    severity?: string;
+    message?: string;
+    code?: string;
+    targetId?: string;
+    target_id?: string;
+    targetKind?: string;
+    target_kind?: string;
+    type?: string;
+    manifest?: unknown;
+    manifestJson?: string;
+    manifest_json?: string;
+    detail?: string;
+    /** Engine registration (host-recognized analyzer/source sidecar). */
+    engine?: string;
+    engineKind?: 'code' | 'math' | 'markdown' | string;
+}
+
+export interface ContributionBatchInput {
+    stage: PluginStage | string;
+    cacheKey?: string;
+    deterministic?: boolean;
+    items: ContributionItem[];
+}
+
+export interface VmzPlugin {
+    manifest: PluginManifest;
+    contribute?: (
+        ctx: PluginContext,
+    ) => Promise<ContributionBatchInput[] | ContributionBatchInput> | ContributionBatchInput[] | ContributionBatchInput;
+}
+
+export interface VmzEngines {
+    /** Default for `<Code>` when `engine` prop omitted. */
+    code?: string;
+    /** Default for `<Math>` when `engine` prop omitted. */
+    math?: string;
+    /** Default for `<Markdown>` when `engine` prop omitted; also used by `vmz document`. */
+    markdown?: string;
+}
+
+/** Workspace format options (`vmz format` reads `vmz.config` `format`). */
+export interface VmzFormatConfig {
+    /** Include globs under the project root. */
+    includes?: string[];
+    /** Skip paths under these globs after includes expand. */
+    excludes?: string[];
+    /** Run `cargo fmt` when a Cargo workspace is present. */
+    rust?: boolean;
+    /** Run the Oak CST formatter on JS/TS targets. */
+    javascript?: boolean;
+    /** Format `.vmz` author files via `vmz-formatter`. */
+    vmz?: boolean;
+    /** Biome-style formatter config (default: `biome.json` at project root). */
+    style?: string;
+}
+
+export interface VmzUserConfig {
+    plugins?: Array<string | VmzPlugin | Promise<VmzPlugin>>;
+    engines?: VmzEngines;
+    /** Workspace format targets and engines (`vmz format`). */
+    format?: VmzFormatConfig;
+    /** Application identity (optional authoring). */
+    application?: { id?: string; [key: string]: unknown };
+    /**
+     * Delivery: named profiles (`default` + `profiles`) or legacy site sugar.
+     * Pure data only; never a parallel `vmz.site.ts` entry.
+     */
+    delivery?: DeliveryAuthoring;
+}
+
+/** Site resource sources (embedded | filesystem | remote) — orthogonal to assembly. */
+export interface SiteDeliveryAuthoring {
+    artifact: string;
+    siteId?: string;
+    sources: Array<{
+        id: string;
+        kind: 'embedded' | 'filesystem' | 'remote';
+        directory?: string;
+        baseUrl?: string;
+        artifact?: string;
+        trust?: string;
+        timeoutMs?: number;
+        priority?: number;
+        integrity?: unknown;
+        signaturePolicy?: string;
+    }>;
+    resolution?: {
+        mode?: 'release';
+        fallback?: string[];
+    };
+    activation?: 'atomic';
+    expectedCompatibility?: unknown;
+    failure?: unknown;
+    failurePolicy?: unknown;
+    update?: unknown;
+    updatePolicy?: unknown;
+    rollback?: unknown;
+    rollbackPolicy?: unknown;
+    security?: unknown;
+    securityPolicy?: unknown;
+}
+
+export type DeliveryAssembly = 'local-static' | 'web-static' | 'server-host' | 'cdn+server' | 'rust-embedded';
+
+export type DeliveryServerRuntime = 'node' | 'worker' | 'deno' | 'bun' | 'rust-host';
+
+export interface DeliveryProfileAuthoring {
+    host?: 'browser';
+    assembly: DeliveryAssembly;
+    /**
+     * Artifact directory under CLI `--out-dir` (default = profile id).
+     * Example: profile `static` + `name: 'cdn'` → `dist/cdn`.
+     */
+    name?: string;
+    serverRuntime?: DeliveryServerRuntime;
+    /** Inline site sources or `defineSite({...})`. */
+    sources?: SiteDeliveryAuthoring | SiteDeliveryAuthoring['sources'];
+    artifact?: string;
+    resolution?: SiteDeliveryAuthoring['resolution'];
+    activation?: SiteDeliveryAuthoring['activation'];
+}
+
+/** WeChat DevTools project identity. Pure data; not WeChat JSON / wx.* APIs. */
+export interface WechatPackagingAuthoring {
+    /** Registered AppID. Omit for WeChat tourist mode (`touristappid`). */
+    appId?: string;
+    projectName?: string;
+    /** `app.json` `window.navigationBarTitleText`. */
+    title?: string;
+}
+
+/** Vendor packaging identity under `defineConfig({ delivery })`. */
+export interface DeliveryPackagingAuthoring {
+    wechat?: WechatPackagingAuthoring;
+}
+
+/** Named profiles (preferred) or legacy site-only sugar. */
+export type DeliveryAuthoring =
+    | {
+          default?: string;
+          profiles: Record<string, DeliveryProfileAuthoring>;
+          packaging?: DeliveryPackagingAuthoring;
+      }
+    | (SiteDeliveryAuthoring & {
+          default?: string;
+          assembly?: DeliveryAssembly;
+          host?: 'browser';
+          serverRuntime?: DeliveryServerRuntime;
+          packaging?: DeliveryPackagingAuthoring;
+      });
+
+export type DefinePluginInput = PluginManifest & {
+    contribute?: VmzPlugin['contribute'];
+};
+
+/** Identity helper for IDE inference. */
+export function definePlugin(def: DefinePluginInput): VmzPlugin;
+
+/** Identity helper for `vmz.config.ts` inference. */
+export function defineConfig(config: VmzUserConfig): VmzUserConfig;

package/package.json

@@ -1,6 +1,6 @@
 {
   "dependencies": {
-    "@vmz/protocol": "0.3.6"
+    "@vmz/protocol": "0.3.8"
   },
   "description": "VMZ plugin protocol types and definePlugin / defineConfig helpers (no N-API)",
   "exports": {
@@ -31,5 +31,5 @@
   },
   "type": "module",
   "types": "./index.d.ts",
-  "version": "0.3.6"
+  "version": "0.3.8"
 }