@csszyx/unplugin 0.16.0 → 0.17.1

package/dist/jest-transform.mjs

@@ -0,0 +1,175 @@
+import { createHash } from 'node:crypto';
+import fs__default from 'node:fs';
+import path__default from 'node:path';
+import { VERSION, transformSource, szFallbackConsequenceOf } from '@csszyx/compiler';
+import { i as injectNextRuntimeImports } from './shared/unplugin.DcXM9sq5.mjs';
+import { n as normalizePathSeparators } from './shared/unplugin.wMeicb6E.mjs';
+
+const SETTLE_MS = 2e3;
+function mtimeOf(dir) {
+  try {
+    return fs__default.statSync(dir).mtimeMs;
+  } catch {
+    return -1;
+  }
+}
+function settled(mtime) {
+  return Date.now() - mtime < SETTLE_MS ? -1 : mtime;
+}
+function writtenAt(entry) {
+  return typeof entry.timestamp === "string" ? entry.timestamp : "";
+}
+class TransformCacheIndex {
+  /** Directories seen, with the modification time they were last read at. */
+  dirs = /* @__PURE__ */ new Map();
+  seen = /* @__PURE__ */ new Set();
+  byFilename = /* @__PURE__ */ new Map();
+  /**
+   * @param root - The transform cache directory.
+   */
+  constructor(root) {
+    this.dirs.set(root, -1);
+  }
+  /**
+   * Read every entry file written since the last refresh.
+   */
+  refresh() {
+    const moved = [];
+    for (const [dir, readAt] of this.dirs) {
+      const mtime = mtimeOf(dir);
+      if (mtime !== readAt) moved.push(dir);
+    }
+    for (const dir of moved) {
+      this.dirs.set(dir, settled(mtimeOf(dir)));
+      this.readDir(dir);
+    }
+  }
+  /**
+   * Parse the entry files in one directory the index has not read yet.
+   *
+   * @param dir - The directory.
+   */
+  readDir(dir) {
+    let names;
+    try {
+      names = fs__default.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of names) {
+      const full = path__default.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (!this.dirs.has(full)) {
+          this.dirs.set(full, settled(mtimeOf(full)));
+          this.readDir(full);
+        }
+        continue;
+      }
+      if (!entry.name.endsWith(".json") || this.seen.has(full)) continue;
+      this.seen.add(full);
+      this.add(full);
+    }
+  }
+  /**
+   * Parse one entry file into the index.
+   *
+   * @param file - The entry file.
+   */
+  add(file) {
+    let entry;
+    try {
+      entry = JSON.parse(fs__default.readFileSync(file, "utf8"));
+    } catch {
+      return;
+    }
+    if (typeof entry.filename !== "string") return;
+    const list = this.byFilename.get(entry.filename) ?? [];
+    list.push(entry);
+    this.byFilename.set(entry.filename, list);
+  }
+  /**
+   * The build output for one file, when the build saw exactly these contents.
+   *
+   * @param filename - Path of the file under test, as the plugin records it.
+   * @param source - Its current contents.
+   * @returns The matching entry's result, or null.
+   */
+  find(filename, source) {
+    const wanted = createHash("sha256").update(source).digest("hex");
+    const hit = this.pick(filename, wanted);
+    if (hit !== null) return hit;
+    this.refresh();
+    return this.pick(filename, wanted);
+  }
+  /**
+   * The best entry among those recorded for one file and hash.
+   *
+   * The plugin keys its cache on more than the source — the compiler that
+   * wrote the entry, whether variables were mangled, the cross-module
+   * registry — so one file and hash can have several entries. A test wants
+   * the output this compiler produces with readable variable names, and of
+   * those the newest.
+   *
+   * @param filename - Path as the plugin records it.
+   * @param sha256 - Hash of the current contents.
+   * @returns The chosen entry's result, or null when none qualifies.
+   */
+  pick(filename, sha256) {
+    let best = null;
+    for (const entry of this.byFilename.get(filename) ?? []) {
+      if (entry.inputSha256 !== sha256) continue;
+      if (entry.compilerVersion !== VERSION || entry.mangleVars === true) continue;
+      if (typeof entry.result?.code !== "string") continue;
+      if (best === null || writtenAt(entry) > writtenAt(best)) {
+        best = entry;
+      }
+    }
+    return best?.result ?? null;
+  }
+}
+function findCachedTransform(cacheRoot, filename, source) {
+  const index = new TransformCacheIndex(cacheRoot);
+  index.refresh();
+  const code = index.find(normalizePathSeparators(filename), source)?.code;
+  return typeof code === "string" ? code : null;
+}
+const DEFAULT_EXTENSIONS = [".tsx", ".jsx", ".ts", ".js", ".mts", ".mjs"];
+function reportDeadClasses(sourcePath, diagnostics) {
+  if (!Array.isArray(diagnostics)) return;
+  for (const message of diagnostics) {
+    if (typeof message !== "string" || szFallbackConsequenceOf(message) === "nudge") continue;
+    console.warn(`[csszyx] ${sourcePath}
+  ${message}`);
+  }
+}
+function finish(code, usage) {
+  return injectNextRuntimeImports(code, usage).code;
+}
+function createTransformer(options = {}) {
+  const extensions = options.extensions ?? DEFAULT_EXTENSIONS;
+  const cacheRoot = options.cacheRoot ?? path__default.resolve(process.cwd(), ".csszyx/cache", "transform");
+  const index = new TransformCacheIndex(cacheRoot);
+  index.refresh();
+  const compiles = (sourcePath) => extensions.some((extension) => sourcePath.endsWith(extension));
+  const cached = (sourceText, sourcePath) => index.find(normalizePathSeparators(sourcePath), sourceText);
+  return {
+    process(sourceText, sourcePath) {
+      if (!compiles(sourcePath)) return { code: sourceText };
+      const built = cached(sourceText, sourcePath);
+      if (built !== null && typeof built.code === "string") {
+        reportDeadClasses(sourcePath, built.diagnostics);
+        return { code: finish(built.code, built) };
+      }
+      const result = transformSource(sourceText, sourcePath);
+      reportDeadClasses(sourcePath, result.diagnostics);
+      return { code: result.transformed ? finish(result.code, result) : sourceText };
+    },
+    getCacheKey(sourceText, sourcePath, cacheKeyOptions) {
+      const built = compiles(sourcePath) ? cached(sourceText, sourcePath) : null;
+      return createHash("sha256").update(sourceText).update("\0").update(sourcePath).update("\0").update(typeof built?.code === "string" ? built.code : "").update("\0").update(cacheKeyOptions?.configString ?? "").update("\0").update(VERSION).digest("hex");
+    }
+  };
+}
+const transformerModule = { createTransformer };
+
+export { createTransformer, transformerModule as default, findCachedTransform };

package/dist/next-prebuild.cjs

@@ -3,10 +3,11 @@
 const node_crypto = require('node:crypto');
 const fs = require('node:fs');
 const path = require('node:path');
-const nextTransformMetadata = require('./shared/unplugin.gksolKh2.cjs');
-const nextWatcherCycle = require('./shared/unplugin.BWnmKv07.cjs');
-const safelistSource = require('./shared/unplugin.DDSWQJYX.cjs');
-const transformCache = require('./shared/unplugin.BzF0V2kw.cjs');
+const nextTransformMetadata = require('./shared/unplugin.DXzIP7lP.cjs');
+const nextWatcherCycle = require('./shared/unplugin.BKID6KXV.cjs');
+const pathNormalization = require('./shared/unplugin.BqKLlo1h.cjs');
+const safelistSource = require('./shared/unplugin.DS6CFjim.cjs');
+const transformCache = require('./shared/unplugin.YcnV3Izb.cjs');
 require('@csszyx/compiler');
 require('@csszyx/types');
 require('node:os');
@@ -103,7 +104,7 @@ function runNextPrebuild(options) {
     lockOptions: {
       root: context.root,
       mode: context.manifestExpectation.mode,
-      command: "csszyx next prebuild"
+      command: options.lockCommand ?? nextWatcherCycle.NEXT_PREBUILD_LOCK_COMMAND
     },
     createdAt: options.createdAt
   });
@@ -153,7 +154,7 @@ function uniqueFiles(files) {
   return result;
 }
 function createShardCacheKey(context, metadata) {
-  return node_crypto.createHash("sha256").update(context.identity.generation).update("\0").update(safelistSource.normalizePathSeparators(path__namespace.relative(context.root, metadata.sourcePath))).digest("hex");
+  return node_crypto.createHash("sha256").update(context.identity.generation).update("\0").update(pathNormalization.normalizePathSeparators(path__namespace.relative(context.root, metadata.sourcePath))).digest("hex");
 }
 
 exports.runNextPrebuild = runNextPrebuild;

package/dist/next-prebuild.d.cts

@@ -1,7 +1,7 @@
 import { TransformSourceCodeOptions } from '@csszyx/compiler';
-import { J as JsonLike, A as AtomicWriteOptions, N as NextStateContext } from './shared/unplugin.BGog1Bib.cjs';
+import { J as JsonLike, A as AtomicWriteOptions, N as NextStateContext } from './shared/unplugin.XdPo6azz.cjs';
 import { N as NextSourceTransformOutput, a as NextSourceParserMode } from './shared/unplugin.B32Exn-K.cjs';
-import { N as NextWatcherCycleResult } from './shared/unplugin.rWOMecQs.cjs';
+import { N as NextWatcherCycleResult } from './shared/unplugin.C_2R8vIk.cjs';
 
 /** Serializable options accepted by the Next Turbopack csszyx prebuild core. */
 interface NextPrebuildOptions {
@@ -35,6 +35,16 @@ interface NextPrebuildOptions {
     allowProductionMangling?: boolean;
     writeOptions?: AtomicWriteOptions;
     createdAt?: string;
+    /**
+     * What this pass records on the state lock; `csszyx next prebuild` by
+     * default.
+     *
+     * The Turbopack loader steps aside only for a watcher's command. `next
+     * watch` passes that command here because its initial cycle follows this
+     * pass and reads every shard the loader wrote meanwhile. A standalone
+     * prebuild keeps the default: nothing after it would pick those shards up.
+     */
+    lockCommand?: string;
 }
 /** Per-file result captured by one prebuild pass. */
 interface NextPrebuildFileResult {

package/dist/next-prebuild.d.mts

@@ -1,7 +1,7 @@
 import { TransformSourceCodeOptions } from '@csszyx/compiler';
-import { J as JsonLike, A as AtomicWriteOptions, N as NextStateContext } from './shared/unplugin.BGog1Bib.mjs';
+import { J as JsonLike, A as AtomicWriteOptions, N as NextStateContext } from './shared/unplugin.XdPo6azz.mjs';
 import { N as NextSourceTransformOutput, a as NextSourceParserMode } from './shared/unplugin.B32Exn-K.mjs';
-import { N as NextWatcherCycleResult } from './shared/unplugin.COlI0dJs.mjs';
+import { N as NextWatcherCycleResult } from './shared/unplugin.CfXjAV63.mjs';
 
 /** Serializable options accepted by the Next Turbopack csszyx prebuild core. */
 interface NextPrebuildOptions {
@@ -35,6 +35,16 @@ interface NextPrebuildOptions {
     allowProductionMangling?: boolean;
     writeOptions?: AtomicWriteOptions;
     createdAt?: string;
+    /**
+     * What this pass records on the state lock; `csszyx next prebuild` by
+     * default.
+     *
+     * The Turbopack loader steps aside only for a watcher's command. `next
+     * watch` passes that command here because its initial cycle follows this
+     * pass and reads every shard the loader wrote meanwhile. A standalone
+     * prebuild keeps the default: nothing after it would pick those shards up.
+     */
+    lockCommand?: string;
 }
 /** Per-file result captured by one prebuild pass. */
 interface NextPrebuildFileResult {

package/dist/next-prebuild.mjs

@@ -1,10 +1,11 @@
 import { createHash } from 'node:crypto';
 import { existsSync, readFileSync } from 'node:fs';
 import * as path from 'node:path';
-import { r as readPackageVersion, c as configWithImportedStaticSz, a as resolveNextCrossModule, t as transformNextSource, w as withCrossModuleStatics, b as collectNextTransformMetadata, d as createNextSafelistShardFromMetadata } from './shared/unplugin.Vn9x8SBP.mjs';
-import { c as createNextStateContext, w as writeNextSafelistShard, r as runNextWatcherCycle } from './shared/unplugin.BLptVbUe.mjs';
-import { f as findPostcssConfigWithoutCsszyx, m as missingPostcssPluginMessage, n as normalizePathSeparators } from './shared/unplugin.DH_ij6cf.mjs';
-import { r as resolveTransformCacheDir } from './shared/unplugin.C-oQU1jl.mjs';
+import { r as readPackageVersion, c as configWithImportedStaticSz, a as resolveNextCrossModule, t as transformNextSource, w as withCrossModuleStatics, b as collectNextTransformMetadata, d as createNextSafelistShardFromMetadata } from './shared/unplugin.C3bgc29e.mjs';
+import { c as createNextStateContext, w as writeNextSafelistShard, r as runNextWatcherCycle, N as NEXT_PREBUILD_LOCK_COMMAND } from './shared/unplugin.eCo7_znv.mjs';
+import { n as normalizePathSeparators } from './shared/unplugin.wMeicb6E.mjs';
+import { f as findPostcssConfigWithoutCsszyx, m as missingPostcssPluginMessage } from './shared/unplugin.Ba3O1r8M.mjs';
+import { r as resolveTransformCacheDir } from './shared/unplugin.2uf-U76p.mjs';
 import '@csszyx/compiler';
 import '@csszyx/types';
 import 'node:os';
@@ -86,7 +87,7 @@ function runNextPrebuild(options) {
     lockOptions: {
       root: context.root,
       mode: context.manifestExpectation.mode,
-      command: "csszyx next prebuild"
+      command: options.lockCommand ?? NEXT_PREBUILD_LOCK_COMMAND
     },
     createdAt: options.createdAt
   });

package/dist/next-turbo-loader.cjs

@@ -4,14 +4,16 @@ Object.defineProperty(exports, '__esModule', { value: true });
 
 const node_crypto = require('node:crypto');
 const path = require('node:path');
-const themeGroupsFile = require('./shared/unplugin.J6ue_lRJ.cjs');
-const nextTransformMetadata = require('./shared/unplugin.gksolKh2.cjs');
-const nextWatcherCycle = require('./shared/unplugin.BWnmKv07.cjs');
-const safelistSource = require('./shared/unplugin.DDSWQJYX.cjs');
-const transformCache = require('./shared/unplugin.BzF0V2kw.cjs');
+const nextRuntimeInjection = require('./shared/unplugin.Defu9wGh.cjs');
+const nextTransformMetadata = require('./shared/unplugin.DXzIP7lP.cjs');
+const nextWatcherCycle = require('./shared/unplugin.BKID6KXV.cjs');
+const pathNormalization = require('./shared/unplugin.BqKLlo1h.cjs');
+const themeGroupsFile = require('./shared/unplugin.D0tMgokL.cjs');
+const transformCache = require('./shared/unplugin.YcnV3Izb.cjs');
 require('node:fs');
 require('@csszyx/compiler');
 require('@csszyx/types');
+require('./shared/unplugin.DS6CFjim.cjs');
 require('node:os');
 require('proper-lockfile');
 
@@ -67,14 +69,14 @@ function runNextTurboLoader(source, loaderContext, explicitOptions = {}) {
     compilerVersion: options.compilerVersion ?? nextTransformMetadata.readPackageVersion("../../compiler/package.json", (typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('next-turbo-loader.cjs', document.baseURI).href))),
     astBudget: options.astBudget
   });
-  const injected = themeGroupsFile.injectNextRuntimeImports(transform.result.code, transform.result);
+  const injected = nextRuntimeInjection.injectNextRuntimeImports(transform.result.code, transform.result);
   const callsSzcn = transform.result.usesSzcn || /\bszcn\s*\(/.test(source);
   const themeGroups = callsSzcn ? themeGroupsFile.ensureThemeGroupsFile(context.root, path__namespace.join(context.root, ".csszyx")) : { file: null, watch: [] };
   for (const stylesheet of themeGroups.watch) loaderContext.addDependency?.(stylesheet);
   for (const provider of nextTransformMetadata.normalizeProviderPaths(crossModule.providers)) {
     loaderContext.addDependency?.(provider);
   }
-  const code = themeGroups.file === null ? injected.code : themeGroupsFile.insertAfterUseDirective(
+  const code = themeGroups.file === null ? injected.code : nextRuntimeInjection.insertAfterUseDirective(
     injected.code,
     `import '${themeGroupsFile.themeGroupsSpecifier(loaderContext.resourcePath, themeGroups.file)}';
 `
@@ -98,7 +100,7 @@ function runNextTurboLoader(source, loaderContext, explicitOptions = {}) {
         lockOptions: {
           root: context.root,
           mode: context.manifestExpectation.mode,
-          command: "csszyx next turbo-loader"
+          command: nextWatcherCycle.NEXT_TURBO_LOADER_LOCK_COMMAND
         }
       });
       materialized = true;
@@ -192,7 +194,7 @@ function hasEnabledMangleVars(config) {
   return config.mangleVars === true;
 }
 function createShardCacheKey(context, metadata) {
-  return node_crypto.createHash("sha256").update(context.identity.generation).update("\0").update(safelistSource.normalizePathSeparators(path__namespace.relative(context.root, metadata.sourcePath))).digest("hex");
+  return node_crypto.createHash("sha256").update(context.identity.generation).update("\0").update(pathNormalization.normalizePathSeparators(path__namespace.relative(context.root, metadata.sourcePath))).digest("hex");
 }
 
 exports.default = nextTurboLoader;

package/dist/next-turbo-loader.d.cts

@@ -1,5 +1,5 @@
 import { TransformSourceCodeOptions } from '@csszyx/compiler';
-import { J as JsonLike, A as AtomicWriteOptions, N as NextStateContext } from './shared/unplugin.BGog1Bib.cjs';
+import { J as JsonLike, A as AtomicWriteOptions, N as NextStateContext } from './shared/unplugin.XdPo6azz.cjs';
 import { a as NextSourceParserMode, N as NextSourceTransformOutput } from './shared/unplugin.B32Exn-K.cjs';
 
 /** Serializable options accepted by the Next Turbopack csszyx loader. */

package/dist/next-turbo-loader.d.mts

@@ -1,5 +1,5 @@
 import { TransformSourceCodeOptions } from '@csszyx/compiler';
-import { J as JsonLike, A as AtomicWriteOptions, N as NextStateContext } from './shared/unplugin.BGog1Bib.mjs';
+import { J as JsonLike, A as AtomicWriteOptions, N as NextStateContext } from './shared/unplugin.XdPo6azz.mjs';
 import { a as NextSourceParserMode, N as NextSourceTransformOutput } from './shared/unplugin.B32Exn-K.mjs';
 
 /** Serializable options accepted by the Next Turbopack csszyx loader. */

package/dist/next-turbo-loader.mjs

@@ -1,13 +1,15 @@
 import { createHash } from 'node:crypto';
 import * as path from 'node:path';
-import { i as injectNextRuntimeImports, e as ensureThemeGroupsFile, b as insertAfterUseDirective, t as themeGroupsSpecifier } from './shared/unplugin.Ceq-N4jI.mjs';
-import { r as readPackageVersion, c as configWithImportedStaticSz, a as resolveNextCrossModule, t as transformNextSource, w as withCrossModuleStatics, n as normalizeProviderPaths, b as collectNextTransformMetadata, d as createNextSafelistShardFromMetadata } from './shared/unplugin.Vn9x8SBP.mjs';
-import { c as createNextStateContext, w as writeNextSafelistShard, r as runNextWatcherCycle, N as NextSafelistStateLockedError, a as NEXT_WATCH_LOCK_COMMAND, v as validateNextGenerationManifest, b as readNextGenerationManifest } from './shared/unplugin.BLptVbUe.mjs';
-import { n as normalizePathSeparators } from './shared/unplugin.DH_ij6cf.mjs';
-import { r as resolveTransformCacheDir } from './shared/unplugin.C-oQU1jl.mjs';
+import { i as injectNextRuntimeImports, a as insertAfterUseDirective } from './shared/unplugin.DcXM9sq5.mjs';
+import { r as readPackageVersion, c as configWithImportedStaticSz, a as resolveNextCrossModule, t as transformNextSource, w as withCrossModuleStatics, n as normalizeProviderPaths, b as collectNextTransformMetadata, d as createNextSafelistShardFromMetadata } from './shared/unplugin.C3bgc29e.mjs';
+import { c as createNextStateContext, w as writeNextSafelistShard, r as runNextWatcherCycle, a as NEXT_TURBO_LOADER_LOCK_COMMAND, b as NextSafelistStateLockedError, d as NEXT_WATCH_LOCK_COMMAND, v as validateNextGenerationManifest, e as readNextGenerationManifest } from './shared/unplugin.eCo7_znv.mjs';
+import { n as normalizePathSeparators } from './shared/unplugin.wMeicb6E.mjs';
+import { e as ensureThemeGroupsFile, t as themeGroupsSpecifier } from './shared/unplugin.CK-DfKTP.mjs';
+import { r as resolveTransformCacheDir } from './shared/unplugin.2uf-U76p.mjs';
 import 'node:fs';
 import '@csszyx/compiler';
 import '@csszyx/types';
+import './shared/unplugin.Ba3O1r8M.mjs';
 import 'node:os';
 import 'proper-lockfile';
 
@@ -79,7 +81,7 @@ function runNextTurboLoader(source, loaderContext, explicitOptions = {}) {
         lockOptions: {
           root: context.root,
           mode: context.manifestExpectation.mode,
-          command: "csszyx next turbo-loader"
+          command: NEXT_TURBO_LOADER_LOCK_COMMAND
         }
       });
       materialized = true;

package/dist/next-watcher.cjs

@@ -1,10 +1,11 @@
 'use strict';
 
 const path = require('node:path');
-const nextWatcherCycle = require('./shared/unplugin.BWnmKv07.cjs');
+const nextWatcherCycle = require('./shared/unplugin.BKID6KXV.cjs');
 require('node:fs');
-require('./shared/unplugin.DDSWQJYX.cjs');
+require('./shared/unplugin.DS6CFjim.cjs');
 require('node:crypto');
+require('./shared/unplugin.BqKLlo1h.cjs');
 require('node:os');
 require('proper-lockfile');
 
@@ -22,6 +23,12 @@ function _interopNamespaceCompat(e) {
 
 const path__namespace = /*#__PURE__*/_interopNamespaceCompat(path);
 
+const LOADER_LOCK_RETRY_MIN_MS = 50;
+const LOADER_LOCK_WARN_AFTER_MS = 1e3;
+const LOADER_LOCK_GIVE_UP_AFTER_MS = 6e4;
+function isHeldByTurbopackLoader(error) {
+  return error instanceof nextWatcherCycle.NextSafelistStateLockedError && error.holder.command === nextWatcherCycle.NEXT_TURBO_LOADER_LOCK_COMMAND;
+}
 class NextWatcherLoop {
   context;
   cycleOptions;
@@ -29,10 +36,15 @@ class NextWatcherLoop {
   runCycle;
   setTimeoutFn;
   clearTimeoutFn;
+  nowFn;
   onError;
+  onWarn;
   timer;
   disposed = false;
   pendingReasons = /* @__PURE__ */ new Set();
+  /** When the current wait on the loader's lock began; unset while not waiting. */
+  loaderWaitStartedAt;
+  loaderWaitWarned = false;
   lastResult;
   lastError;
   /**
@@ -46,7 +58,9 @@ class NextWatcherLoop {
     this.runCycle = options.runCycle ?? nextWatcherCycle.runNextWatcherCycle;
     this.setTimeoutFn = options.setTimeout ?? setTimeout;
     this.clearTimeoutFn = options.clearTimeout ?? clearTimeout;
+    this.nowFn = options.now ?? Date.now;
     this.onError = options.onError;
+    this.onWarn = options.onWarn;
   }
   /**
    *
@@ -69,17 +83,7 @@ class NextWatcherLoop {
       return;
     }
     this.pendingReasons.add(reason);
-    if (this.timer !== void 0) {
-      return;
-    }
-    this.timer = this.setTimeoutFn(() => {
-      try {
-        this.runPendingCycle();
-      } catch (error) {
-        this.lastError = error;
-        this.onError?.(error);
-      }
-    }, this.debounceMs);
+    this.schedule(this.debounceMs);
   }
   /**
    *
@@ -90,6 +94,32 @@ class NextWatcherLoop {
     }
     return this.runPendingCycle();
   }
+  /**
+   * Run the pending cycle now, or queue it when the Turbopack loader holds the
+   * lock.
+   *
+   * `flush` throws on every failure, which is what closing needs. Starting
+   * needs this instead: `next watch` and `next dev` start together, so the
+   * loader's first compile can hold the lock exactly when the initial cycle
+   * runs, and that overlap is not a failure.
+   *
+   * @returns The cycle result, or `undefined` when nothing was pending or the
+   *   cycle is queued behind the loader.
+   */
+  flushOrQueue() {
+    if (this.disposed || this.timer === void 0) {
+      return void 0;
+    }
+    const reasons = [...this.pendingReasons];
+    try {
+      return this.runPendingCycle();
+    } catch (error) {
+      if (this.waitForLoader(error, reasons)) {
+        return void 0;
+      }
+      throw error;
+    }
+  }
   /**
    *
    */
@@ -101,6 +131,75 @@ class NextWatcherLoop {
     this.pendingReasons.clear();
     this.disposed = true;
   }
+  /**
+   * Run the pending cycle after `delayMs`, unless a run is already scheduled.
+   *
+   * @param delayMs - How long to wait before running it.
+   */
+  schedule(delayMs) {
+    if (this.timer !== void 0) {
+      return;
+    }
+    this.timer = this.setTimeoutFn(() => {
+      const reasons = [...this.pendingReasons];
+      try {
+        this.runPendingCycle();
+      } catch (error) {
+        if (this.waitForLoader(error, reasons)) {
+          return;
+        }
+        this.lastError = error;
+        this.onError?.(error);
+      }
+    }, delayMs);
+  }
+  /**
+   * Queue a cycle again when it failed only because the Turbopack loader holds
+   * the lock.
+   *
+   * Retried, not dropped: the loader's pass read the shards as they stood when
+   * it began, and the event that woke this cycle may be newer. The wait is
+   * timed from the first refusal, says so once when it runs long, and ends in
+   * a reported failure when it runs longer than any live loader could explain.
+   *
+   * @param error - What the cycle threw.
+   * @param reasons - The reasons the failed cycle carried, queued again with it.
+   * @returns True when nothing should be reported: the cycle is queued, or the
+   *   loop was disposed meanwhile.
+   */
+  waitForLoader(error, reasons) {
+    if (!isHeldByTurbopackLoader(error)) {
+      return false;
+    }
+    const now = this.nowFn();
+    this.loaderWaitStartedAt ??= now;
+    const waited = now - this.loaderWaitStartedAt;
+    if (waited > LOADER_LOCK_GIVE_UP_AFTER_MS) {
+      this.endLoaderWait();
+      return false;
+    }
+    if (waited >= LOADER_LOCK_WARN_AFTER_MS && !this.loaderWaitWarned) {
+      this.loaderWaitWarned = true;
+      const warn = this.onWarn ?? (() => {
+      });
+      warn(
+        `[csszyx] next watch is waiting for the safelist lock held by the Turbopack loader (process ${error.holder.pid}). Classes added meanwhile get no CSS until it is released; a lock left by a loader that exited is recovered within 30 s.`
+      );
+    }
+    if (this.disposed) {
+      return true;
+    }
+    for (const reason of reasons) {
+      this.pendingReasons.add(reason);
+    }
+    this.schedule(Math.max(this.debounceMs, LOADER_LOCK_RETRY_MIN_MS));
+    return true;
+  }
+  /** Forget the current wait on the loader, once a cycle gets through or gives up. */
+  endLoaderWait() {
+    this.loaderWaitStartedAt = void 0;
+    this.loaderWaitWarned = false;
+  }
   /**
    *
    */
@@ -115,6 +214,7 @@ class NextWatcherLoop {
     const result = this.runCycle(this.context, this.cycleOptions, reasons);
     this.lastResult = result;
     this.lastError = void 0;
+    this.endLoaderWait();
     return result;
   }
 }
@@ -168,6 +268,14 @@ class NextSafelistWatcher {
   }
   /**
    * Materialize existing shards before accepting live filesystem events.
+   *
+   * `next watch` and `next dev` start together in the documented setup, so
+   * the Turbopack loader's first compile can hold the state lock at this
+   * exact moment. The initial cycle is then queued behind it instead of
+   * throwing, the same way a scheduled cycle waits.
+   *
+   * @returns The initial cycle's result, or `undefined` while it is queued
+   *   behind the Turbopack loader.
    */
   start() {
     if (this.closed) {
@@ -178,8 +286,8 @@ class NextSafelistWatcher {
     }
     this.started = true;
     this.loop.notify("initial");
-    const result = this.loop.flush();
-    if (!result) {
+    const result = this.loop.flushOrQueue();
+    if (!result && !this.loop.pending) {
       throw new Error("[csszyx] Next safelist watcher failed to run its initial cycle.");
     }
     return result;
@@ -233,6 +341,7 @@ class NextSafelistWatcher {
   }
 }
 
+exports.NEXT_WATCH_LOCK_COMMAND = nextWatcherCycle.NEXT_WATCH_LOCK_COMMAND;
 exports.NextSafelistWatcher = NextSafelistWatcher;
 exports.isNextAppSourcePath = isNextAppSourcePath;
 exports.isNextSafelistShardPath = isNextSafelistShardPath;

package/dist/next-watcher.d.cts

@@ -1,5 +1,6 @@
-import { N as NextStateContext } from './shared/unplugin.BGog1Bib.cjs';
-import { a as NextWatcherCycleOptions, N as NextWatcherCycleResult } from './shared/unplugin.rWOMecQs.cjs';
+import { N as NextStateContext } from './shared/unplugin.XdPo6azz.cjs';
+export { c as NEXT_WATCH_LOCK_COMMAND } from './shared/unplugin.XdPo6azz.cjs';
+import { a as NextWatcherCycleOptions, N as NextWatcherCycleResult } from './shared/unplugin.C_2R8vIk.cjs';
 
 /**
  *
@@ -11,6 +12,8 @@ type NextWatcherLoopCycleRunner = (context: NextStateContext, options: NextWatch
 interface NextWatcherLoopTimerHooks {
     setTimeout?: (callback: () => void, delayMs: number) => WatcherTimer;
     clearTimeout?: (timer: WatcherTimer) => void;
+    /** Clock that times a wait on the loader's lock; `Date.now` by default. */
+    now?: () => number;
 }
 
 /** Filesystem events that can change the materialized safelist. */
@@ -22,6 +25,8 @@ interface NextSafelistWatcherOptions extends NextWatcherLoopTimerHooks {
     debounceMs?: number;
     runCycle?: NextWatcherLoopCycleRunner;
     onError?: (error: unknown) => void;
+    /** Receives a notice the watcher keeps running through; dropped by default. */
+    onWarn?: (message: string) => void;
 }
 /**
  * Validate one watcher event path against the flat safelist shard directory.
@@ -75,8 +80,16 @@ declare class NextSafelistWatcher {
     get lastError(): unknown;
     /**
      * Materialize existing shards before accepting live filesystem events.
+     *
+     * `next watch` and `next dev` start together in the documented setup, so
+     * the Turbopack loader's first compile can hold the state lock at this
+     * exact moment. The initial cycle is then queued behind it instead of
+     * throwing, the same way a scheduled cycle waits.
+     *
+     * @returns The initial cycle's result, or `undefined` while it is queued
+     *   behind the Turbopack loader.
      */
-    start(): NextWatcherCycleResult;
+    start(): NextWatcherCycleResult | undefined;
     /**
      * Queue a materialization cycle for one relevant shard filesystem event.
      *