@animus-ui/next-plugin 0.1.1-beta.2 → 0.1.2

package/README.md

@@ -1,6 +1,6 @@
 # @animus-ui/next-plugin
 
-Static CSS extraction for Next.js. Wraps `next.config` to integrate the Animus extraction pipeline via webpack.
+Static CSS extraction for Next.js (15 and 16). Wraps `next.config` to integrate the Animus extraction pipeline — webpack and Turbopack.
 
 ## Install
 
@@ -18,15 +18,94 @@ const nextConfig = {
   // your existing Next.js config
 };
 
-export default withAnimus(nextConfig, {
+export default withAnimus({
   system: './src/ds.ts',
-});
+})(nextConfig);
 ```
 
+## Turbopack
+
+Turbopack support activates automatically whenever the process runs under
+Turbopack (`next dev --turbopack`, or Next 16 where Turbopack is the
+default) — no config change needed. Extraction runs while `next.config`
+resolves, a watcher re-analyzes on source changes in dev, and per-file
+transforms run in a stateless loader fed by generated `.animus/` artifacts.
+tsconfig `paths` aliases are honored.
+
+Control it explicitly with the `turbopack` option:
+
+```tsx
+export default withAnimus({
+  system: './src/ds.ts',
+  turbopack: { mode: 'auto' }, // 'auto' (default) | 'on' | 'off'
+})(nextConfig);
+```
+
+Under webpack (`next dev` / `next build` on 15, or `--webpack` on 16) the
+plugin behaves exactly as before.
+
+## Appearance bootstrap (no-FOUC color mode)
+
+Optional. Restores a persisted color mode before first paint with zero runtime
+— a generated, dependency-free inline snippet whose CSP hash is computed at
+build time from the exact bytes generated.
+
+The plugin deliberately injects nothing: CSP nonces need request-time control
+the bundler does not have, so the **application** places the artifact. Generate
+it in a server-only module and inline it as the first child of `<head>`.
+
+**App Router:**
+
+```tsx
+// appearance-bootstrap.ts — server-only; never import from a client component
+import { createAppearanceBootstrap } from '@animus-ui/system/bootstrap';
+
+import { tokens } from './src/ds';
+
+export const appearanceBootstrap = createAppearanceBootstrap(tokens);
+```
+
+```tsx
+// app/layout.tsx
+import { appearanceBootstrap } from '../appearance-bootstrap';
+
+export default function RootLayout({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  return (
+    <html lang="en" suppressHydrationWarning>
+      <head>
+        <script
+          data-animus-bootstrap=""
+          dangerouslySetInnerHTML={{ __html: appearanceBootstrap.code }}
+        />
+      </head>
+      <body>{children}</body>
+    </html>
+  );
+}
+```
+
+**Pages Router:** same artifact, placed as the first child of `<Head>` in
+`pages/_document.tsx`, with `suppressHydrationWarning` on `<Html>`.
+
+Two rules either way:
+
+- `suppressHydrationWarning` on the root element is required, not cosmetic —
+  the snippet legitimately mutates `data-color-mode` between SSR and hydration.
+- Serve a CSP that authorizes the script from the artifact itself: either
+  `script-src '<artifact.cspHash>'` (single-quoted, derived at build time —
+  never hand-copied; a renamed mode changes the hash) or a per-request nonce
+  you add to the script tag. The full CSP footguns are documented in the
+  [`@animus-ui/vite-plugin` README](https://github.com/codecaaron/animus/tree/main/packages/vite-plugin#content-security-policy).
+
 ## What It Does
 
-- Adds a webpack loader that transforms `@animus-ui/system` builder chains into static CSS
+- Transforms `@animus-ui/system` builder chains into static CSS (webpack loader or Turbopack loader rule)
 - Emits extracted CSS as a separate asset with `@layer` ordering
+- Post-processes the emitted sheet with Lightning CSS — autoprefixed for your `targets` (browserslist query; defaults to the project config), minified in production (`minify` overrides)
 - Works with both App Router and Pages Router
 - Supports RSC — no runtime style injection means server components work out of the box
 

package/dist/chunk-y_GBKt04.mjs

@@ -0,0 +1,5 @@
+import { createRequire } from "node:module";
+//#region \0rolldown/runtime.js
+var __require = /* @__PURE__ */ createRequire(import.meta.url);
+//#endregion
+export { __require as t };

package/dist/extraction-session.d.ts

@@ -0,0 +1,138 @@
+import type { AnimusNextOptions } from './types';
+/**
+ * Module id the Rust emitter injects for the extracted stylesheet — also the
+ * exact resolve.alias key with-animus registers for it, which the adapter's
+ * alias harvesting must skip.
+ */
+export declare const ANIMUS_CSS_MODULE_ID = ".animus/styles.css";
+/** Watch-cycle change sets, as reported by the bundler's watcher. */
+export interface WatchChanges {
+    modifiedFiles?: ReadonlySet<string>;
+    removedFiles?: ReadonlySet<string>;
+}
+/**
+ * Bundler-agnostic extraction pipeline: system loading, source discovery
+ * and ingestion, external-package collection, analysis, stylesheet and
+ * system-props emission, and watch-cycle diffing.
+ *
+ * The webpack adapter (plugin.ts) owns only bundler wiring: hook
+ * registration, alias harvesting from the compiler config, in-memory asset
+ * replacement, and translating watch events into `handleWatchUpdate`
+ * change sets. Keeping this class free of webpack types is deliberate — a
+ * future Turbopack integration must drive the same session from outside
+ * the bundler (Turbopack has no compiler-hook surface), reusing everything
+ * here unchanged.
+ *
+ * Outputs are published through the package singleton (shared CSS,
+ * manifest, system props) and written to `.animus/` on disk.
+ */
+export declare class ExtractionSession {
+    /** Set by the adapter before any pipeline run. */
+    rootDir: string | null;
+    /** Serialized path aliases, harvested by the adapter from bundler config. */
+    pathAliasesJson: string | null;
+    /** When set (Turbopack orchestration), every analysis also persists
+     *  `.animus/analysis-inputs.json` so isolated loader workers can hydrate.
+     *  Webpack mode leaves this off — its loader shares the process. */
+    persistAnalysisInputs: boolean;
+    /** Emitter identity override for the system-props module id. Webpack mode
+     *  (null) injects the absolute `.animus/system-props.js` path, resolved by
+     *  NormalModuleReplacement; Turbopack rejects absolute-path imports, so
+     *  its driver sets the virtual id that `resolveAlias` maps to disk. */
+    systemPropsModuleId: string | null;
+    /** Absolute directory prefixes for external DS packages (loader allowlisting). */
+    externalPackageDirs: string[];
+    /** External package specifier → absolute source entry path. */
+    externalSourceEntries: Map<string, string>;
+    private readonly options;
+    private readonly staticCssJson;
+    private system;
+    /** Full package-resolution map from the last full pipeline — replayed by
+     *  incremental passes (sourceEntries alone omits dist-resolved packages). */
+    private lastPackageMap;
+    private fileCache;
+    private systemDependencyKeys;
+    /** Loader-reported dependency paths for bundler watch registration. */
+    systemDependencyPaths: string[];
+    private systemDependencyHashes;
+    private lastCssHash;
+    private lastSystemPropsHash;
+    private lastManifestHash;
+    private lastAnalysisInputsHash;
+    private lcssTargets;
+    constructor(options: AnimusNextOptions);
+    get verbose(): boolean;
+    private log;
+    private warn;
+    private now;
+    private elapsed;
+    /** Resolve the scan configuration from options — the single source of the
+     *  exclude/extension policy shared by the full and incremental pipelines. */
+    private resolveScanConfig;
+    /**
+     * Incremental watch pass: geological reset when the system file changed,
+     * otherwise content-hash diffing restricted to the watcher's change sets
+     * (falling back to a full discovery walk when no sets are provided).
+     */
+    handleWatchUpdate(changes: WatchChanges): Promise<void>;
+    /**
+     * Preprocess one `.mdx` entry into scanner-consumable tsx. Returns the
+     * rewritten source plus the `relPath + '.tsx'` path on success, or null
+     * when the file must be skipped.
+     *
+     * `warn: false` (incremental watch pass) skips silently — the full
+     * pipeline already surfaced the warning. `warn: true` (full pipeline)
+     * warns ONCE for a missing @mdx-js/mdx dependency via the shared
+     * `missingDepFlag` holder, and every time for a preprocessing error.
+     */
+    private preprocessMdxEntry;
+    runFullPipeline(): Promise<void>;
+    /**
+     * Reset analysis state for HMR geological reset.
+     */
+    resetForHmr(): void;
+    /**
+     * Build file entries from cache: every cached file rides with full source.
+     * The v2 engine has NO Rust-side cache (extract-v2-spine DEF-7: uncached
+     * re-analysis beats a cache-hit path), so it must always receive full sources
+     * (openspec: retire-extract-v1 removed the v1 empty-source cache contract).
+     */
+    private buildFileEntriesFromCache;
+    /**
+     * Run incremental pipeline with cache-aware file entries.
+     * Reuses system config from the last full pipeline run.
+     */
+    private runIncrementalPipeline;
+    /**
+     * Shared analysis + emit core for both pipelines — the single call site
+     * that routes every manifest through the shared `runProjectAnalysis`,
+     * reachable from both runFullPipeline (production) and
+     * runIncrementalPipeline (HMR).
+     *
+     * Owns diagnostic surfacing, CSS assembly + styles.css write guard,
+     * system-props module emit, and the timing log. The `devMode` flag is the
+     * ONLY behavioral fork:
+     *
+     * - `false` (production): computes bt.analysis + logs the extraction
+     *   report, and writes system-props.js UNCONDITIONALLY (no
+     *   lastSystemPropsHash guard).
+     * - `true` (HMR): skips the report log, and guards the system-props.js
+     *   write by lastSystemPropsHash.
+     *
+     * The styles.css write guard (lastCssHash) is identical on both paths.
+     */
+    private analyzeAndEmit;
+    /** Content hash of an existing `.animus/` artifact, or null when absent or
+     *  unreadable. Seeds a null write guard so a FRESH session never rewrites a
+     *  byte-identical artifact (spec: next-turbopack-integration — a rewrite
+     *  changes mtime/inode and needlessly re-keys Turbopack loader-worker
+     *  hydration). */
+    private diskArtifactHash;
+    /** Ensure `.animus/` exists and write one generated artifact into it.
+     *  Write-then-rename so cross-process readers (Turbopack loader workers)
+     *  can never observe a torn half-written file. The tmp name carries the
+     *  pid — Next dev evaluates the config in more than one process, and two
+     *  sessions writing the same artifact must not race on one tmp path. */
+    private writeAnimusFile;
+}
+//# sourceMappingURL=extraction-session.d.ts.map

package/dist/extraction-session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extraction-session.d.ts","sourceRoot":"","sources":["../src/extraction-session.ts"],"names":[],"mappings":"AAuCA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAOjD;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,uBAAuB,CAAC;AAczD,qEAAqE;AACrE,MAAM,WAAW,YAAY;IAC3B,aAAa,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACpC,YAAY,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;CACpC;AAED;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,iBAAiB;IAC5B,kDAAkD;IAClD,OAAO,EAAE,MAAM,GAAG,IAAI,CAAQ;IAC9B,6EAA6E;IAC7E,eAAe,EAAE,MAAM,GAAG,IAAI,CAAQ;IACtC;;wEAEoE;IACpE,qBAAqB,UAAS;IAC9B;;;2EAGuE;IACvE,mBAAmB,EAAE,MAAM,GAAG,IAAI,CAAQ;IAE1C,kFAAkF;IAClF,mBAAmB,EAAE,MAAM,EAAE,CAAM;IACnC,+DAA+D;IAC/D,qBAAqB,sBAA6B;IAElD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAoB;IAC5C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAgB;IAC9C,OAAO,CAAC,MAAM,CAA6B;IAC3C;iFAC6E;IAC7E,OAAO,CAAC,cAAc,CAA8B;IAGpD,OAAO,CAAC,SAAS,CAAuD;IAMxE,OAAO,CAAC,oBAAoB,CAA0B;IAEtD,uEAAuE;IACvE,qBAAqB,EAAE,MAAM,EAAE,CAAM;IAKrC,OAAO,CAAC,sBAAsB,CAAkC;IAChE,OAAO,CAAC,WAAW,CAAuB;IAC1C,OAAO,CAAC,mBAAmB,CAAuB;IAClD,OAAO,CAAC,gBAAgB,CAAuB;IAC/C,OAAO,CAAC,sBAAsB,CAAuB;IAGrD,OAAO,CAAC,WAAW,CAAiC;IAEpD,YAAY,OAAO,EAAE,iBAAiB,EAKrC;IAED,IAAI,OAAO,IAAI,OAAO,CAMrB;IAED,OAAO,CAAC,GAAG;IAMX,OAAO,CAAC,IAAI;IAKZ,OAAO,CAAC,GAAG;IAGX,OAAO,CAAC,OAAO;IAIf;iFAC6E;IAC7E,OAAO,CAAC,iBAAiB;IAezB;;;;OAIG;IACG,iBAAiB,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CA0I5D;IAED;;;;;;;;;OASG;YACW,kBAAkB;IA2B1B,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC,CAmJrC;IAED;;OAEG;IACH,WAAW,IAAI,IAAI,CAOlB;IAED;;;;;OAKG;IACH,OAAO,CAAC,yBAAyB;IAQjC;;;OAGG;YACW,sBAAsB;IAmBpC;;;;;;;;;;;;;;;;;OAiBG;YACW,cAAc;IAmJ5B;;;;sBAIkB;IAClB,OAAO,CAAC,gBAAgB;IAUxB;;;;4EAIwE;IACxE,OAAO,CAAC,eAAe;CASxB"}