@animus-ui/extract 0.1.1 → 0.1.3

package/README.md

@@ -14,20 +14,21 @@ Pre-built binaries for:
 
 ## API
 
+v2 is the only engine (v1 was retired — openspec: `retire-extract-v1`); the
+package root entry is the engine.
+
 ```tsx
-import { analyzeProject } from '@animus-ui/extract';
+import { ExtractEngine, loadSystemModule } from '@animus-ui/extract';
 
-const manifest = analyzeProject(
-  fileEntriesJson,
-  scalesJson,
+const engine = new ExtractEngine({
+  configJson,
+  groupRegistryJson,
+  themeJson,
   variableMapJson,
-  contextualVarsJson,
-  propConfig,
-  groupRegistry,
-  packageResolutionJson,
-  devMode,
-  prefix
-);
+  devMode: false,
+});
+const manifest = engine.analyze(fileEntriesJson);
+const { code, hasComponents } = JSON.parse(engine.transformFile(path));
 ```
 
 ## License

package/crates/extract-v2/index.d.ts

@@ -57,6 +57,12 @@ export interface EngineOptions {
   groupRegistryJson?: string
   /** Selector aliases JSON (v1 `selector_aliases_json`). */
   selectorAliasesJson?: string
+  /**
+   * Condition aliases JSON (inc 03 — `conditionAliases` manifest field):
+   * `{ "_motionReduce": { "value": "@media …", "order": 500, "kind":
+   * "media" } }`. Absent = no registrations.
+   */
+  conditionAliasesJson?: string
   /** Global style blocks JSON (v1 `global_style_blocks_json`). */
   globalStyleBlocksJson?: string
   /**
@@ -68,6 +74,11 @@ export interface EngineOptions {
   packageResolutionJson?: string
   /** Path aliases JSON (`{aliases: [...]}` wrapper, v1 shape). */
   pathAliasesJson?: string
+  /**
+   * Forced-emission declarations (spec: static-emission-overrides) —
+   * the serialized `staticCss` plugin option.
+   */
+  staticCssJson?: string
   /** v1 `dev_mode`: retain all components (skip reconciliation pruning). */
   devMode?: boolean
 }
@@ -99,6 +110,17 @@ export interface NapiSystemConfig {
   contextualVarsJson: string
   selectorAliases?: string
   selectorOrder?: string
+  /**
+   * Condition alias map JSON (inc 03 — `conditionAliases`): alias →
+   * `{ value, order, kind }`. Absent when the system registers none.
+   */
+  conditionAliases?: string
   globalStyleBlocks?: string
   keyframesBlocks?: string
+  /**
+   * Canonical absolute paths of every module evaluated for the system
+   * (sorted; entry included, runtime stubs excluded). The plugins use this
+   * as the geological-reset membership set.
+   */
+  dependencies: Array<string>
 }

package/dist/analyze-project-args.d.ts

@@ -0,0 +1,50 @@
+/**
+ * The positional argument tuple for the NAPI `analyzeProject` call.
+ *
+ * This is the single authoritative copy of the 14-slot contract consumed by
+ * both extraction plugins (vite-plugin and next-plugin). The slot order is
+ * mirrored by the Rust NAPI surface — changing it requires a coordinated
+ * Rust-side update.
+ */
+/** @internal */
+export type AnalyzeProjectArgs = [
+    filesJson: string,
+    scalesJson: string,
+    variableMapJson: string,
+    contextualVarsJson: string | null,
+    propConfigJson: string,
+    groupRegistryJson: string,
+    packageResolutionJson: string,
+    devMode: boolean,
+    emitterConfigJson: string | null,
+    selectorAliasesJson: string | null,
+    selectorOrderJson: null,
+    globalStyleBlocksJson: string | null,
+    pathAliasesJson: string | null,
+    keyframesJson: string | null,
+    staticCssJson: string | null,
+    conditionAliasesJson: string | null
+];
+/** @internal */
+export interface AnalyzeProjectInputs {
+    filesJson: string;
+    scalesJson: string;
+    variableMapJson: string;
+    contextualVarsJson: string | null;
+    propConfigJson: string;
+    groupRegistryJson: string;
+    packageResolutionJson: string;
+    devMode: boolean;
+    emitterConfigJson: string | null;
+    selectorAliasesJson: string | null;
+    globalStyleBlocksJson: string | null;
+    pathAliasesJson: string | null;
+    keyframesJson: string | null;
+    /** Forced-emission declarations (spec: static-emission-overrides). */
+    staticCssJson: string | null;
+    /** Condition alias map JSON (modern-css-surface inc 03), or null. */
+    conditionAliasesJson: string | null;
+}
+/** @internal */
+export declare function buildAnalyzeProjectArgs(inputs: AnalyzeProjectInputs): AnalyzeProjectArgs;
+//# sourceMappingURL=analyze-project-args.d.ts.map

package/dist/analyze-project-args.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analyze-project-args.d.ts","sourceRoot":"","sources":["../pipeline/analyze-project-args.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,gBAAgB;AAChB,MAAM,MAAM,kBAAkB,GAAG;IAC/B,SAAS,EAAE,MAAM;IACjB,UAAU,EAAE,MAAM;IAClB,eAAe,EAAE,MAAM;IACvB,kBAAkB,EAAE,MAAM,GAAG,IAAI;IACjC,cAAc,EAAE,MAAM;IACtB,iBAAiB,EAAE,MAAM;IACzB,qBAAqB,EAAE,MAAM;IAC7B,OAAO,EAAE,OAAO;IAChB,iBAAiB,EAAE,MAAM,GAAG,IAAI;IAChC,mBAAmB,EAAE,MAAM,GAAG,IAAI;IAClC,iBAAiB,EAAE,IAAI;IACvB,qBAAqB,EAAE,MAAM,GAAG,IAAI;IACpC,eAAe,EAAE,MAAM,GAAG,IAAI;IAC9B,aAAa,EAAE,MAAM,GAAG,IAAI;IAC5B,aAAa,EAAE,MAAM,GAAG,IAAI;IAG5B,oBAAoB,EAAE,MAAM,GAAG,IAAI;CACpC,CAAC;AAEF,gBAAgB;AAChB,MAAM,WAAW,oBAAoB;IACnC,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,EAAE,MAAM,CAAC;IACxB,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,cAAc,EAAE,MAAM,CAAC;IACvB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,qBAAqB,EAAE,MAAM,CAAC;IAC9B,OAAO,EAAE,OAAO,CAAC;IACjB,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,mBAAmB,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,qBAAqB,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,sEAAsE;IACtE,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,qEAAqE;IACrE,oBAAoB,EAAE,MAAM,GAAG,IAAI,CAAC;CACrC;AAED,gBAAgB;AAChB,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,oBAAoB,GAC3B,kBAAkB,CAmBpB"}

package/dist/content-hash.d.ts

@@ -0,0 +1,7 @@
+/**
+ * MD5 content hash used for file-change detection (HMR diffing) by both
+ * extraction plugins. The algorithm/encoding is a cross-plugin contract:
+ * cache keys written by one build path must compare equal in the next.
+ */
+export declare function contentHash(source: string): string;
+//# sourceMappingURL=content-hash.d.ts.map

package/dist/content-hash.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"content-hash.d.ts","sourceRoot":"","sources":["../pipeline/content-hash.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAElD"}

package/dist/discover-files.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Recursively discover source files under `dir`, skipping any path that
+ * contains one of `excludePatterns` (matched as substrings of both the full
+ * and root-relative path) and keeping files whose extension is in
+ * `extensionsSet`.
+ *
+ * Single authoritative copy for both extraction plugins.
+ */
+export declare function discoverFiles(dir: string, rootDir: string, excludePatterns: string[], extensionsSet: ReadonlySet<string>): string[];
+//# sourceMappingURL=discover-files.d.ts.map

package/dist/discover-files.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"discover-files.d.ts","sourceRoot":"","sources":["../pipeline/discover-files.ts"],"names":[],"mappings":"AAGA;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAC3B,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,MAAM,EACf,eAAe,EAAE,MAAM,EAAE,EACzB,aAAa,EAAE,WAAW,CAAC,MAAM,CAAC,GACjC,MAAM,EAAE,CAoCV"}

package/dist/discover-packages.d.ts

@@ -1,3 +1,92 @@
+/**
+ * Walk up from a resolved package entry file to the nearest directory
+ * containing a package.json (the package root). Stops at the filesystem
+ * root and returns it if no package.json is found on the way up.
+ */
+export declare function findPackageRoot(absEntryPath: string): string;
+/**
+ * Exclusion fragments for discovery inside an external package's src/,
+ * matched against paths RELATIVE TO the src dir. Per spec
+ * external-package-file-discovery, the filters apply "within the package" —
+ * an npm-installed package whose own location is under node_modules (or a
+ * repo path containing 'dist') must still have its sources discovered.
+ */
+export declare const PACKAGE_SRC_EXCLUDES: string[];
+/**
+ * What one declared include specifier produced, so callers can tell a package
+ * that contributed sources apart from one that silently contributed nothing.
+ * Collection itself never warns — reporting is the caller's policy.
+ */
+export interface ExternalPackageOutcome {
+    /** The declared specifier, exactly as it appeared in the system file. */
+    specifier: string;
+    /**
+     * - `resolved` — resolved to a package and accounted for at least one source
+     * - `unresolvable` — specifier could not be resolved (skipped, per spec)
+     * - `empty` — resolved to a package root but accounted for no sources
+     */
+    outcome: 'resolved' | 'unresolvable' | 'empty';
+    /**
+     * Source files this specifier accounted for in the analysis set: files it
+     * contributed, plus files a previous specifier or the caller's own file set
+     * already supplied (those are in the set, just not attributable to this
+     * collection pass). Files skipped by `preprocessFile` or unreadable ones are
+     * NOT counted — they never reach the analysis set.
+     */
+    fileCount: number;
+}
+export interface CollectedExternalPackages {
+    /** New file entries (rootDir-relative, preprocessed) for the analysis set. */
+    entries: Array<{
+        path: string;
+        source: string;
+    }>;
+    /** specifier → rootDir-relative module-resolution entry (src/index.ts when present). */
+    packageMap: Record<string, string>;
+    /** specifier → absolute src/index.ts path, only for packages with one. */
+    sourceEntries: Map<string, string>;
+    /** Absolute directories for bundler loader allowlisting (src/ or dist entry dir). */
+    packageDirs: string[];
+    /** One record per declared specifier, in declaration order. */
+    outcomes: ExternalPackageOutcome[];
+}
+/**
+ * Shared external-package source collection (spec:
+ * external-package-file-discovery), consumed by both extraction plugins.
+ * For each specifier: resolve to an absolute entry (null/throw → silently
+ * skip; an absolute-path specifier falls back to a filesystem probe), walk up
+ * to the package root, then either discover sources under src/ (redirecting
+ * module resolution to src/index.ts when present) or fall back to ingesting
+ * the resolved entry file itself.
+ *
+ * The only bundler-specific seams are callbacks: specifier resolution,
+ * dedup against already-ingested files, per-file preprocessing (MDX), and
+ * the unreadable-file warning. Hashing and caching stay in the plugins —
+ * their cache policies legitimately differ.
+ *
+ * Alongside the aggregates, one `ExternalPackageOutcome` per declared
+ * specifier records what that specifier produced. Collection never reports on
+ * them — any warning or gate is the caller's policy.
+ */
+export declare function collectExternalPackageSources(opts: {
+    specifiers: string[];
+    /** Resolve a specifier to an absolute entry path; null (or a throw) skips it. */
+    resolveSpecifier: (specifier: string) => string | null | Promise<string | null>;
+    rootDir: string;
+    extensionsSet: ReadonlySet<string>;
+    /** Does the caller's file set already contain this rootDir-relative path? */
+    hasEntry: (relPath: string) => boolean;
+    /**
+     * Preprocess a discovered source (e.g. MDX→tsx with a path rewrite).
+     * Return null to skip the file; return the input unchanged to pass through.
+     */
+    preprocessFile: (source: string, relPath: string, absPath: string) => Promise<{
+        source: string;
+        relPath: string;
+    } | null>;
+    /** Called when a discovered file cannot be read; the file is skipped. */
+    onUnreadable: (relPath: string, error: unknown) => void;
+}): Promise<CollectedExternalPackages>;
 /**
  * Extract external DS package names from `includes` declarations in the system file.
  *
@@ -6,10 +95,20 @@
  *   - Legacy:          `.includes([identifier, ...])` chain method (RC migration fallback)
  *
  * For each identifier found, traces back to its import declaration and returns
- * the import specifier. Only packages explicitly declared via `includes` are treated
- * as external DS dependencies.
+ * the import specifier: a bare specifier normalized to its package name, a
+ * relative specifier resolved against the system file's directory into an
+ * absolute path (so a sibling package referenced by path contributes discovery
+ * too). Only packages explicitly declared via `includes` are treated as
+ * external DS dependencies.
  *
  * Falls back to empty array if no `includes` declaration is found.
  */
+/**
+ * The message for the strict/warn gate over unresolvable includes, or null
+ * when every declared specifier resolved (external-package-file-discovery:
+ * silence is never an outcome — non-strict consumers warn with this line,
+ * strict consumers throw it).
+ */
+export declare function unresolvableIncludesMessage(outcomes: ExternalPackageOutcome[]): string | null;
 export declare function extractSystemFilePackages(systemFilePath: string): string[];
 //# sourceMappingURL=discover-packages.d.ts.map

package/dist/discover-packages.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"discover-packages.d.ts","sourceRoot":"","sources":["../pipeline/discover-packages.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;GAYG;AACH,wBAAgB,yBAAyB,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM,EAAE,CAmF1E"}
+{"version":3,"file":"discover-packages.d.ts","sourceRoot":"","sources":["../pipeline/discover-packages.ts"],"names":[],"mappings":"AAKA;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAS5D;AAED;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,UAKhC,CAAC;AAEF;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACrC,yEAAyE;IACzE,SAAS,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,OAAO,EAAE,UAAU,GAAG,cAAc,GAAG,OAAO,CAAC;IAC/C;;;;;;OAMG;IACH,SAAS,EAAE,MAAM,CAAC;CACnB;AA6BD,MAAM,WAAW,yBAAyB;IACxC,8EAA8E;IAC9E,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACjD,wFAAwF;IACxF,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACnC,0EAA0E;IAC1E,aAAa,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACnC,qFAAqF;IACrF,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,+DAA+D;IAC/D,QAAQ,EAAE,sBAAsB,EAAE,CAAC;CACpC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,6BAA6B,CAAC,IAAI,EAAE;IACxD,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,iFAAiF;IACjF,gBAAgB,EAAE,CAChB,SAAS,EAAE,MAAM,KACd,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC5C,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACnC,6EAA6E;IAC7E,QAAQ,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC;IACvC;;;OAGG;IACH,cAAc,EAAE,CACd,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,KACZ,OAAO,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC,CAAC;IACzD,yEAAyE;IACzE,YAAY,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CACzD,GAAG,OAAO,CAAC,yBAAyB,CAAC,CAuHrC;AAED;;;;;;;;;;;;;;;GAeG;AACH;;;;;GAKG;AACH,wBAAgB,2BAA2B,CACzC,QAAQ,EAAE,sBAAsB,EAAE,GACjC,MAAM,GAAG,IAAI,CAMf;AAED,wBAAgB,yBAAyB,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM,EAAE,CA2F1E"}

package/dist/dynamic-prop-config.d.ts

@@ -0,0 +1,23 @@
+/**
+ * snake_case → camelCase mapping for the manifest's `dynamic_props` block.
+ *
+ * Single authoritative copy for both extraction plugins: the emitted
+ * `dynamicPropConfig` object in each plugin's system-props module is
+ * `JSON.stringify(buildDynamicPropConfig(...))`, so field order and the
+ * omission rules (no `transformName` when absent, no `scaleValues` when
+ * empty) are part of the emitted-bundle contract.
+ */
+export interface DynamicPropMeta {
+    var_name: string;
+    slot_class: string;
+    transform_name?: string | null;
+    scale_values?: Record<string, string> | null;
+}
+export interface DynamicPropConfigEntry {
+    varName: string;
+    slotClass: string;
+    transformName?: string;
+    scaleValues?: Record<string, string>;
+}
+export declare function buildDynamicPropConfig(dynamicProps: Record<string, DynamicPropMeta>): Record<string, DynamicPropConfigEntry>;
+//# sourceMappingURL=dynamic-prop-config.d.ts.map

package/dist/dynamic-prop-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dynamic-prop-config.d.ts","sourceRoot":"","sources":["../pipeline/dynamic-prop-config.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAAC;CAC9C;AAED,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACtC;AAED,wBAAgB,sBAAsB,CACpC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,GAC5C,MAAM,CAAC,MAAM,EAAE,sBAAsB,CAAC,CAaxC"}

package/dist/engine-adapter.d.ts

@@ -0,0 +1,95 @@
+/**
+ * The v2 `ExtractEngine` adapter, hoisted to one authoritative copy.
+ *
+ * Both extraction plugins (next-plugin, vite-plugin) drive the stateful v2
+ * `ExtractEngine` through the engine-agnostic surface the v1 native module
+ * already exposes (loadSystemModule / analyzeProject / transformFile /
+ * clearAnalysisCache). This factory builds that surface once; the plugins
+ * differ only in (a) how the engine option is resolved, (b) how the native
+ * module is loaded, and (c) where the per-run state lives — so those are the
+ * injected dependencies.
+ *
+ * State storage is the pivotal difference: next-plugin must survive the
+ * ESM/CJS double-load (the plugin loads as ESM via next.config, the webpack
+ * loader via CJS require), so it backs the store with globalThis; vite-plugin
+ * keeps per-plugin-instance state in closure variables. The one-shot drift
+ * flag lives in the store too, so next's warning stays one-shot across the
+ * double-load.
+ *
+ * Loading semantics (lazy CJS require, fail-loud, no silent fallback to the
+ * other engine) live at the call site via `loadNativeEngine`; this module
+ * never imports the native binding, and never imports from either plugin,
+ * webpack, or vite (dependency direction: plugins -> extract).
+ */
+/** The stateful v2 engine handle produced by `new native.ExtractEngine(...)`. */
+export interface V2ExtractEngine {
+    analyze(filesJson: string): string;
+    transformFile(path: string): string;
+    clearCache(): void;
+}
+/** Per-file transform result, as both plugins consume it. */
+export interface TransformFileResult {
+    code: string;
+    hasComponents: boolean;
+}
+/**
+ * The engine-agnostic API surface. The v1 leg is the raw native module (which
+ * already exposes these methods); the v2 leg is the adapter this factory
+ * builds. The positional `analyzeProject` tuple mirrors the NAPI contract in
+ * `analyze-project-args.ts`.
+ */
+export interface EngineApi {
+    loadSystemModule: (...args: unknown[]) => any;
+    analyzeProject: (filesJson: string, scalesJson: string, variableMapJson: string, contextualVarsJson: string | null, propConfigJson: string, groupRegistryJson: string, packageResolutionJson: string, devMode: boolean, emitterConfigJson: string | null, selectorAliasesJson: string | null, selectorOrderJson: string | null, globalStyleBlocksJson: string | null, pathAliasesJson: string | null, keyframesJson: string | null, staticCssJson: string | null, conditionAliasesJson: string | null) => string;
+    transformFile: (source: string, path: string, manifest: string) => TransformFileResult;
+    clearAnalysisCache: () => void;
+}
+/**
+ * Storage for the per-run engine instance, the analyze-time sources (drift
+ * detection), and the one-shot drift flag. next backs this with globalThis;
+ * vite with closure variables.
+ */
+export interface V2EngineStateStore {
+    getEngine(): V2ExtractEngine | null;
+    setEngine(engine: V2ExtractEngine | null): void;
+    getSentSources(): Map<string, string> | null;
+    setSentSources(sources: Map<string, string> | null): void;
+    getDriftWarned(): boolean;
+    setDriftWarned(value: boolean): void;
+}
+/** The native engine module. Its own generated `.d.ts` is authoritative. */
+type NativeEngineModule = any;
+export interface V2EngineAdapterDeps {
+    /** Log label for the drift warning and the fail-loud transform error
+     *  (e.g. 'animus-next', 'animus-extract'). */
+    label: string;
+    /** Whether v2 is selected. When false, `engineApi()` returns the raw native
+     *  module unchanged (the v1 leg). next reads the shared engine choice from
+     *  globalThis; vite the per-plugin resolved option. */
+    isV2(): boolean;
+    /** Require the native engine module. Loading semantics — lazy CJS require,
+     *  fail-loud, no silent fallback — live here. */
+    loadNativeEngine(): NativeEngineModule;
+    /** Per-run state storage (globalThis for next, closure for vite). */
+    store: V2EngineStateStore;
+    /** When true, `transformFile` passes paths absent from the last `analyze()`
+     *  set through unchanged (v1 parity: the webpack loader hands the adapter
+     *  files outside the analysis universe — generated `.animus/*` modules,
+     *  workspace-resolved library dist; vite pre-filters them, so it leaves this
+     *  off). */
+    passThroughUnknownPaths?: boolean;
+    /** Optional pre-analyze re-hydration of empty sources. vite's HMR sends
+     *  empty sources for unchanged files and v2 has no Rust-side cache, so vite
+     *  refills them from its own file cache before analyze; next always sends
+     *  full sources. Identity when omitted. */
+    rehydrateFilesJson?(filesJsonRaw: string): string;
+}
+/**
+ * Build the engine-agnostic `engineApi()` both plugins call. Returns a function
+ * (invoked per call site) so `isV2()` and `loadNativeEngine()` re-evaluate each
+ * time — next reads its engine choice and native module dynamically from
+ * globalThis.
+ */
+export declare function createV2EngineApi(deps: V2EngineAdapterDeps): () => EngineApi;
+export {};
+//# sourceMappingURL=engine-adapter.d.ts.map

package/dist/engine-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine-adapter.d.ts","sourceRoot":"","sources":["../pipeline/engine-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,iFAAiF;AACjF,MAAM,WAAW,eAAe;IAC9B,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC;IACnC,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IACpC,UAAU,IAAI,IAAI,CAAC;CACpB;AAED,6DAA6D;AAC7D,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,EAAE,OAAO,CAAC;CACxB;AAED;;;;;GAKG;AACH,MAAM,WAAW,SAAS;IAIxB,gBAAgB,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,GAAG,CAAC;IAC9C,cAAc,EAAE,CACd,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,eAAe,EAAE,MAAM,EACvB,kBAAkB,EAAE,MAAM,GAAG,IAAI,EACjC,cAAc,EAAE,MAAM,EACtB,iBAAiB,EAAE,MAAM,EACzB,qBAAqB,EAAE,MAAM,EAC7B,OAAO,EAAE,OAAO,EAChB,iBAAiB,EAAE,MAAM,GAAG,IAAI,EAChC,mBAAmB,EAAE,MAAM,GAAG,IAAI,EAClC,iBAAiB,EAAE,MAAM,GAAG,IAAI,EAChC,qBAAqB,EAAE,MAAM,GAAG,IAAI,EACpC,eAAe,EAAE,MAAM,GAAG,IAAI,EAC9B,aAAa,EAAE,MAAM,GAAG,IAAI,EAC5B,aAAa,EAAE,MAAM,GAAG,IAAI,EAC5B,oBAAoB,EAAE,MAAM,GAAG,IAAI,KAChC,MAAM,CAAC;IACZ,aAAa,EAAE,CACb,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,KACb,mBAAmB,CAAC;IACzB,kBAAkB,EAAE,MAAM,IAAI,CAAC;CAChC;AAED;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,SAAS,IAAI,eAAe,GAAG,IAAI,CAAC;IACpC,SAAS,CAAC,MAAM,EAAE,eAAe,GAAG,IAAI,GAAG,IAAI,CAAC;IAChD,cAAc,IAAI,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAAC;IAC7C,cAAc,CAAC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,GAAG,IAAI,CAAC;IAC1D,cAAc,IAAI,OAAO,CAAC;IAC1B,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;CACtC;AAED,4EAA4E;AAE5E,KAAK,kBAAkB,GAAG,GAAG,CAAC;AA0B9B,MAAM,WAAW,mBAAmB;IAClC;kDAC8C;IAC9C,KAAK,EAAE,MAAM,CAAC;IACd;;2DAEuD;IACvD,IAAI,IAAI,OAAO,CAAC;IAChB;qDACiD;IACjD,gBAAgB,IAAI,kBAAkB,CAAC;IACvC,qEAAqE;IACrE,KAAK,EAAE,kBAAkB,CAAC;IAC1B;;;;gBAIY;IACZ,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAClC;;;+CAG2C;IAC3C,kBAAkB,CAAC,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAAC;CACnD;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,mBAAmB,GAAG,MAAM,SAAS,CAgH5E"}

package/dist/engine-retirement.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Loud rejection of the retired v1 extraction engine (openspec:
+ * retire-extract-v1).
+ *
+ * v2 is the only engine. Selecting v1 — via a plugin `engine: 'v1'` option or
+ * the `ANIMUS_ENGINE=v1` fixture env override — is a build-stopping error, never
+ * a silent upgrade to v2 (design D1: a silent flip would let a pinned consumer's
+ * build change engines without notice). Both extraction plugins call this before
+ * any engine selection so the rejection is uniform and the message is defined
+ * once.
+ */
+/** The one canonical retirement message, shared verbatim by both plugins and
+ *  the env path (tasks.md cross-cutting: define once, reuse). */
+export declare const RETIRED_ENGINE_MESSAGE: string;
+/**
+ * Throw the canonical retirement error when v1 is selected through either
+ * surface. Accepts the raw engine option as a string because the option type no
+ * longer admits `'v1'` — callers cast it so a stale `'v1'` config still fails
+ * loud at runtime instead of being silently coerced.
+ */
+export declare function assertNoRetiredEngineSelection(engineOption: string | undefined): void;
+//# sourceMappingURL=engine-retirement.d.ts.map

package/dist/engine-retirement.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine-retirement.d.ts","sourceRoot":"","sources":["../pipeline/engine-retirement.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH;iEACiE;AACjE,eAAO,MAAM,sBAAsB,QAEyC,CAAC;AAE7E;;;;;GAKG;AACH,wBAAgB,8BAA8B,CAC5C,YAAY,EAAE,MAAM,GAAG,SAAS,GAC/B,IAAI,CAIN"}