poveste 0.5.1 → 0.5.3

package/dist/node/bin.js

@@ -6,6 +6,7 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 const { version } = JSON.parse(fs.readFileSync(resolve(__dirname, '../../package.json'), 'utf8'));
 process.env.NODE_ENV = 'development';
 process.env.HISTOIRE = 'true';
+process.env.POVESTE = 'true';
 const program = sade('poveste');
 program.version(version);
 program.command('dev')

package/dist/node/builtin-plugins/pinceau-tokens.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pinceau-tokens.d.ts","sourceRoot":"","sources":["../../../src/node/builtin-plugins/pinceau-tokens.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAiB,MAAM,iBAAiB,CAAA;AAI5D,MAAM,WAAW,oBAAoB;IACnC,aAAa,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAA;IACjC,cAAc,CAAC,EAAE,MAAM,CAAA;CACxB;AAED,wBAAgB,aAAa,CAAC,QAAQ,GAAE,oBAAyB,GAAG,MAAM,CA2DzE"}
+{"version":3,"file":"pinceau-tokens.d.ts","sourceRoot":"","sources":["../../../src/node/builtin-plugins/pinceau-tokens.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAiB,MAAM,iBAAiB,CAAA;AAI5D,MAAM,WAAW,oBAAoB;IACnC,aAAa,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAA;IACjC,cAAc,CAAC,EAAE,MAAM,CAAA;CACxB;AAED,wBAAgB,aAAa,CAAC,QAAQ,GAAE,oBAAyB,GAAG,MAAM,CA6DzE"}

package/dist/node/builtin-plugins/pinceau-tokens.js

@@ -41,7 +41,8 @@ export function pinceauTokens(_options = {}) {
                 });
             }
         },
-        onDev(api, onCleanup) {
+        async onDev(api, onCleanup) {
+            await generate(api);
             const watcher = api.watcher.watch(themePath)
                 .on('change', () => generate(api))
                 .on('add', () => generate(api));

package/dist/node/builtin-plugins/tailwind-tokens.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tailwind-tokens.d.ts","sourceRoot":"","sources":["../../../src/node/builtin-plugins/tailwind-tokens.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAiB,MAAM,iBAAiB,CAAA;AAI5D,MAAM,WAAW,qBAAqB;IACpC;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAqBD,wBAAgB,cAAc,CAAC,OAAO,GAAE,qBAA0B,GAAG,MAAM,CAgE1E"}
+{"version":3,"file":"tailwind-tokens.d.ts","sourceRoot":"","sources":["../../../src/node/builtin-plugins/tailwind-tokens.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAiB,MAAM,iBAAiB,CAAA;AAI5D,MAAM,WAAW,qBAAqB;IACpC;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAqBD,wBAAgB,cAAc,CAAC,OAAO,GAAE,qBAA0B,GAAG,MAAM,CAkE1E"}

package/dist/node/builtin-plugins/tailwind-tokens.js

@@ -61,8 +61,9 @@ export function tailwindTokens(options = {}) {
                 }
             }
         },
-        onDev(api, onCleanup) {
+        async onDev(api, onCleanup) {
             if (tailwindCssFile) {
+                await generate(api);
                 const watcher = api.watcher.watch(tailwindCssFile)
                     .on('change', () => generate(api))
                     .on('add', () => generate(api));

package/dist/node/collect/worker.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"worker.d.ts","sourceRoot":"","sources":["../../../src/node/collect/worker.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAoB,WAAW,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAA;AACrF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAA;AAatD,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,WAAW,CAAA;IACjB,SAAS,EAAE,eAAe,CAAA;CAC3B;AAED,MAAM,WAAW,UAAU;IACzB,SAAS,EAAE,WAAW,EAAE,CAAA;CACzB;kCAgB8B,OAAO,KAAG,OAAO,CAAC,UAAU,CAAC;AAA5D,wBAyDC"}
+{"version":3,"file":"worker.d.ts","sourceRoot":"","sources":["../../../src/node/collect/worker.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAoB,WAAW,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAA;AACrF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAA;AAatD,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,WAAW,CAAA;IACjB,SAAS,EAAE,eAAe,CAAA;CAC3B;AAED,MAAM,WAAW,UAAU;IACzB,SAAS,EAAE,WAAW,EAAE,CAAA;CACzB;kCAmB8B,OAAO,KAAG,OAAO,CAAC,UAAU,CAAC;AAA5D,wBA4DC"}

package/dist/node/collect/worker.js

@@ -5,10 +5,13 @@ import { createBirpc } from 'birpc';
 import { dirname, resolve } from 'pathe';
 import pc from 'picocolors';
 import { ModuleCacheMap, ViteNodeRunner } from 'vite-node/client';
-import { createDomEnv } from '../dom/env.js';
+import { createDomEnv, resetDomEnv } from '../dom/env.js';
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const _moduleCache = new ModuleCacheMap();
 let _runner;
+// Worker-lifetime: externalised runtimes cache the DOM they first saw, so one
+// per story broke re-collection.
+let _domEnv;
 let _rpc;
 // Cleanup module cache
 parentPort.on('message', (message) => {
@@ -34,7 +37,12 @@ export default async (payload) => {
             return _rpc.resolveId(id, importer);
         },
     }));
-    const { destroy: destroyDomEnv } = createDomEnv();
+    if (_domEnv) {
+        resetDomEnv(_domEnv);
+    }
+    else {
+        _domEnv = createDomEnv();
+    }
     const el = window.document.createElement('div');
     const beforeExecuteTime = performance.now();
     // Mount app to collect stories/variants
@@ -55,7 +63,6 @@ export default async (payload) => {
             s.docsText = text;
         });
     }
-    destroyDomEnv();
     const endTime = performance.now();
     console.log(pc.dim(`${payload.storyFile.relativePath} ${Math.round(endTime - startTime)}ms (setup:${Math.round(beforeExecuteTime - startTime)}ms, execute:${Math.round(afterExecuteTime - beforeExecuteTime)}ms, run:${Math.round(afterRunTime - afterExecuteTime)}ms)`));
     return {

package/dist/node/commands/dev.d.ts

@@ -1,5 +1,5 @@
 export interface DevOptions {
-    port: number;
+    port?: number | string;
     open?: boolean;
     host?: string | boolean;
     config?: string;

package/dist/node/commands/dev.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dev.d.ts","sourceRoot":"","sources":["../../../src/node/commands/dev.ts"],"names":[],"mappings":"AAOA,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;IACvB,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED,wBAAsB,UAAU,CAAC,OAAO,EAAE,UAAU,iBAoDnD"}
+{"version":3,"file":"dev.d.ts","sourceRoot":"","sources":["../../../src/node/commands/dev.ts"],"names":[],"mappings":"AAQA,MAAM,WAAW,UAAU;IACzB,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;IACtB,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;IACvB,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED,wBAAsB,UAAU,CAAC,OAAO,EAAE,UAAU,iBAsDnD"}

package/dist/node/commands/dev.js

@@ -3,7 +3,9 @@ import pc from 'picocolors';
 import { resolveConfigFile } from '../config.js';
 import { createContext } from '../context.js';
 import { createServer } from '../server.js';
+import { resolvePort } from './port.js';
 export async function devCommand(options) {
+    const port = resolvePort(options.port, 'dev');
     let stop;
     async function start() {
         const ctx = await createContext({
@@ -11,7 +13,7 @@ export async function devCommand(options) {
             mode: 'dev',
         });
         const { server, viteConfigFile, close } = await createServer(ctx, {
-            port: options.port,
+            port,
             open: options.open,
             host: options.host,
         });

package/dist/node/commands/port.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Reads a `--port` value off the parsed CLI options.
+ *
+ * sade declares the flag as taking a value but does not enforce one, so
+ * `poveste preview --port` arrives as the boolean `true` and reaches node's
+ * listen validation, which rejects it with `ERR_INVALID_ARG_VALUE` and names
+ * neither the flag nor the mistake. A non-numeric value fails the same way.
+ */
+export declare function resolvePort(value: unknown, command: string): number | undefined;
+//# sourceMappingURL=port.d.ts.map

package/dist/node/commands/port.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"port.d.ts","sourceRoot":"","sources":["../../../src/node/commands/port.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAoB/E"}

package/dist/node/commands/port.js

@@ -0,0 +1,24 @@
+/**
+ * Reads a `--port` value off the parsed CLI options.
+ *
+ * sade declares the flag as taking a value but does not enforce one, so
+ * `poveste preview --port` arrives as the boolean `true` and reaches node's
+ * listen validation, which rejects it with `ERR_INVALID_ARG_VALUE` and names
+ * neither the flag nor the mistake. A non-numeric value fails the same way.
+ */
+export function resolvePort(value, command) {
+    if (value === undefined || value === null) {
+        return undefined;
+    }
+    // Checked by type, not by coercion: a valueless flag arrives as `true`, and
+    // `Number(true)` is 1, a valid port that would bind to a privileged one.
+    const port = typeof value === 'number'
+        ? value
+        : typeof value === 'string' && value.trim() !== ''
+            ? Number(value)
+            : Number.NaN;
+    if (!Number.isInteger(port) || port < 0 || port > 65535) {
+        throw new TypeError(`--port needs a number between 0 and 65535, got ${JSON.stringify(value)}. Try \`poveste ${command} --port 6006\`.`);
+    }
+    return port;
+}

package/dist/node/commands/preview.d.ts

@@ -1,5 +1,5 @@
 export interface PreviewOptions {
-    port?: number;
+    port?: number | string;
     host?: string | boolean;
     open?: boolean;
 }

package/dist/node/commands/preview.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"preview.d.ts","sourceRoot":"","sources":["../../../src/node/commands/preview.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,cAAc;IAC7B,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;IACvB,IAAI,CAAC,EAAE,OAAO,CAAA;CACf;AAED,wBAAsB,cAAc,CAAC,OAAO,EAAE,cAAc,iBAiB3D"}
+{"version":3,"file":"preview.d.ts","sourceRoot":"","sources":["../../../src/node/commands/preview.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,cAAc;IAC7B,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;IACtB,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;IACvB,IAAI,CAAC,EAAE,OAAO,CAAA;CACf;AAED,wBAAsB,cAAc,CAAC,OAAO,EAAE,cAAc,iBAmB3D"}

package/dist/node/commands/preview.js

@@ -1,6 +1,8 @@
 import { createContext } from '../context.js';
 import { startPreview } from '../preview.js';
+import { resolvePort } from './port.js';
 export async function previewCommand(options) {
+    const port = resolvePort(options.port, 'preview');
     const ctx = await createContext({
         mode: 'build',
     });
@@ -10,7 +12,7 @@ export async function previewCommand(options) {
         }
     }
     const { printUrls } = await startPreview({
-        port: options.port,
+        port,
         host: options.host,
         open: options.open,
     }, ctx);

package/dist/node/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/node/config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,UAAU,EAEV,aAAa,EAEd,MAAM,iBAAiB,CAAA;AACxB,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAkB3C,wBAAgB,gBAAgB,IAAI,aAAa,CA4HhD;AAED,eAAO,MAAM,eAAe,UAU3B,CAAA;AAED,wBAAgB,iBAAiB,CAAC,GAAG,GAAE,MAAsB,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,CAQ1F;AAED,wBAAsB,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC,CAexF;AAED,eAAO,MAAM,gBAAgB,uBAK3B,CAAA;AAEF,eAAO,MAAM,WAAW,uBA8DtB,CAAA;AAEF,wBAAsB,aAAa,CAAC,GAAG,EAAE,MAAsB,EAAE,IAAI,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAgB7H;AA2BD,wBAAsB,aAAa,CAAC,GAAG,EAAE,OAAO,iBAoE/C;AAED,wBAAgB,YAAY,CAAC,MAAM,EAAE,OAAO,CAAC,aAAa,CAAC,0BAE1D;AAED,OAAO,QAAQ,MAAM,CAAC;IACpB,UAAU,UAAU;QAClB;;WAEG;QACH,OAAO,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,CAAA;QAChC;;WAEG;QACH,QAAQ,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,CAAA;KAClC;CACF"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/node/config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,UAAU,EAEV,aAAa,EAEd,MAAM,iBAAiB,CAAA;AACxB,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAkB3C,wBAAgB,gBAAgB,IAAI,aAAa,CA2HhD;AAED,eAAO,MAAM,eAAe,UAU3B,CAAA;AAED,wBAAgB,iBAAiB,CAAC,GAAG,GAAE,MAAsB,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,CAQ1F;AAED,wBAAsB,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC,CAexF;AAED,eAAO,MAAM,gBAAgB,uBAK3B,CAAA;AAEF,eAAO,MAAM,WAAW,uBA8DtB,CAAA;AAEF,wBAAsB,aAAa,CAAC,GAAG,EAAE,MAAsB,EAAE,IAAI,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAgB7H;AA2BD,wBAAsB,aAAa,CAAC,GAAG,EAAE,OAAO,iBAoE/C;AAED,wBAAgB,YAAY,CAAC,MAAM,EAAE,OAAO,CAAC,aAAa,CAAC,0BAE1D;AAED,OAAO,QAAQ,MAAM,CAAC;IACpB,UAAU,UAAU;QAClB;;WAEG;QACH,OAAO,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,CAAA;QAChC;;WAEG;QACH,QAAQ,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,CAAA;KAClC;CACF"}

package/dist/node/config.js

@@ -110,7 +110,6 @@ export function getDefaultConfig() {
                 contrastColor: '#eee',
             },
         ],
-        sandboxDarkClass: 'dark',
         routerMode: 'history',
         build: {
             excludeFromVendorsChunk: [],

package/dist/node/dom/env.d.ts

@@ -1,5 +1,8 @@
 export declare function createDomEnv(): {
     window: Window & typeof globalThis;
     destroy: () => void;
+    pristineKeys: Set<string>;
 };
+/** Returns a reused environment to the state a fresh one would have been in. */
+export declare function resetDomEnv(env: Pick<ReturnType<typeof createDomEnv>, 'window' | 'pristineKeys'>): void;
 //# sourceMappingURL=env.d.ts.map

package/dist/node/dom/env.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../../../src/node/dom/env.ts"],"names":[],"mappings":"AAmCA,wBAAgB,YAAY;;;EAqD3B"}
+{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../../../src/node/dom/env.ts"],"names":[],"mappings":"AAmCA,wBAAgB,YAAY;;;;EAwD3B;AAED,gFAAgF;AAChF,wBAAgB,WAAW,CAAC,GAAG,EAAE,IAAI,CAAC,UAAU,CAAC,OAAO,YAAY,CAAC,EAAE,QAAQ,GAAG,cAAc,CAAC,QA4BhG"}

package/dist/node/dom/env.js

@@ -72,5 +72,36 @@ export function createDomEnv() {
     return {
         window,
         destroy,
+        // `populateGlobal` does `global.window = global`, so `window` here is
+        // `globalThis` — one surface, not two.
+        pristineKeys: new Set(Object.keys(globalThis)),
     };
 }
+/** Returns a reused environment to the state a fresh one would have been in. */
+export function resetDomEnv(env) {
+    const doc = env.window.document;
+    for (const el of [doc.documentElement, doc.head, doc.body]) {
+        if (!el)
+            continue;
+        for (const name of [...el.getAttributeNames()]) {
+            el.removeAttribute(name);
+        }
+    }
+    doc.head?.replaceChildren();
+    doc.body?.replaceChildren();
+    try {
+        // Only present when the key was proxied onto the global, which varies by
+        // node version.
+        env.window.localStorage?.clear();
+        env.window.sessionStorage?.clear();
+    }
+    catch {
+        // Unavailable for some jsdom urls.
+    }
+    // Additions only: the modules that installed the rest are cached, not re-run.
+    for (const key of Object.keys(globalThis)) {
+        if (!env.pristineKeys.has(key)) {
+            delete globalThis[key];
+        }
+    }
+}

package/dist/node/preview.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"preview.d.ts","sourceRoot":"","sources":["../../src/node/preview.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAG3C,MAAM,WAAW,mBAAmB;IAClC,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;IACvB,IAAI,CAAC,EAAE,OAAO,CAAA;CACf;AAED,UAAU,aAAa;IACrB,OAAO,EAAE,MAAM,CAAA;IACf,SAAS,EAAE,MAAM,IAAI,CAAA;IACrB,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CAC3B;AAED,wBAAsB,YAAY,CAAC,OAAO,EAAE,mBAAmB,EAAE,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,aAAa,CAAC,CAwBrG"}
+{"version":3,"file":"preview.d.ts","sourceRoot":"","sources":["../../src/node/preview.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAG3C,MAAM,WAAW,mBAAmB;IAClC,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;IACvB,IAAI,CAAC,EAAE,OAAO,CAAA;CACf;AAED,UAAU,aAAa;IACrB,OAAO,EAAE,MAAM,CAAA;IACf,SAAS,EAAE,MAAM,IAAI,CAAA;IACrB,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CAC3B;AAED,wBAAsB,YAAY,CAAC,OAAO,EAAE,mBAAmB,EAAE,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,aAAa,CAAC,CA6BrG"}

package/dist/node/preview.js

@@ -12,7 +12,12 @@ export async function startPreview(options, ctx) {
             port,
             host: options.host,
             open: options.open,
-            strictPort: false,
+            // A port asked for by name has to be that port or nothing. Moving to the
+            // next free one serves the book where nobody is looking, and lands it on
+            // whatever example owns that number, whose suite then adopts it (#175).
+            // Without an explicit port there is no such expectation, and `build`'s
+            // internal preview reads the port back off the server.
+            strictPort: options.port != null,
         },
     });
     const baseUrl = server.resolvedUrls?.local[0] ?? `http://localhost:${port}${ctx.resolvedViteConfig.base}`;

package/dist/node/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/node/server.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAa3C,MAAM,WAAW,mBAAmB;IAClC,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;CACxB;AAED,wBAAsB,YAAY,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,GAAE,mBAAwB;;;;GAsNjF"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/node/server.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAa3C,MAAM,WAAW,mBAAmB;IAClC,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;CACxB;AAED,wBAAsB,YAAY,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,GAAE,mBAAwB;;;;GA6NjF"}

package/dist/node/server.js

@@ -19,6 +19,12 @@ export async function createServer(ctx, options = {}) {
             if (options.host) {
                 viteConfig.server.host = options.host;
             }
+            // Same rule as `preview`: a port asked for by name is that port or
+            // nothing. Floating to the next free one hands back a server nobody asked
+            // for, and whoever opens the port they typed reads a different book.
+            if (options.port != null) {
+                viteConfig.server.strictPort = true;
+            }
         }
         const server = await createViteServer(mergeViteConfig(viteConfig, {
             optimizeDeps: { include: viteConfig.optimizeDeps?.include ?? [], noDiscovery: collecting },

package/dist/node/style-isolation/entry-css-merger.js

@@ -1,4 +1,4 @@
-import { STORY_SCOPE_ROOT } from './selectors.js';
+import { CONTROLS_SLOT, STORY_SCOPE_ROOT } from './selectors.js';
 import { wrapUserCss } from './transforms.js';
 import { USER_CSS_MARK_END, USER_CSS_MARK_START } from './vite-plugin.js';
 export function entryCssMergerPlugin(opts = { isolateStyles: false }) {
@@ -121,7 +121,7 @@ export function wrapMarkedUserCss(css, scopeRoot) {
         }
         const inner = css.slice(start + USER_CSS_MARK_START.length, end).trim();
         if (inner.length > 0) {
-            out += `${wrapUserCss(inner, { scopeRoot })}\n`;
+            out += `${wrapUserCss(inner, { scopeRoot, excludeRootClass: CONTROLS_SLOT.slice(1) })}\n`;
         }
         cursor = end + USER_CSS_MARK_END.length;
     }

package/dist/node/style-isolation/selectors.d.ts

@@ -1,6 +1,7 @@
 export declare const APP_SCOPE_ROOT = ".poveste-app-root";
 export declare const STORY_SCOPE_ROOT = ".__poveste-render-story";
 export declare const STORY_SCOPE_BOUNDARY = ".__poveste-render-story:not(.__poveste-render-custom-controls)";
+export declare const CONTROLS_SLOT = ".__poveste-controls-slot";
 export declare const DEFAULTS_LAYER = "poveste-defaults";
 export declare const USER_GLOBALS_LAYER = "poveste-user-globals";
 export declare const GLOBAL_LAYER_QUERY = "poveste-global-layer";

package/dist/node/style-isolation/selectors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"selectors.d.ts","sourceRoot":"","sources":["../../../src/node/style-isolation/selectors.ts"],"names":[],"mappings":"AAKA,eAAO,MAAM,cAAc,sBAAsB,CAAA;AACjD,eAAO,MAAM,gBAAgB,4BAA4B,CAAA;AAIzD,eAAO,MAAM,oBAAoB,mEAAmE,CAAA;AACpG,eAAO,MAAM,cAAc,qBAAqB,CAAA;AAChD,eAAO,MAAM,kBAAkB,yBAAyB,CAAA;AAGxD,eAAO,MAAM,kBAAkB,yBAAyB,CAAA"}
+{"version":3,"file":"selectors.d.ts","sourceRoot":"","sources":["../../../src/node/style-isolation/selectors.ts"],"names":[],"mappings":"AAKA,eAAO,MAAM,cAAc,sBAAsB,CAAA;AACjD,eAAO,MAAM,gBAAgB,4BAA4B,CAAA;AAIzD,eAAO,MAAM,oBAAoB,mEAAmE,CAAA;AAGpG,eAAO,MAAM,aAAa,6BAA6B,CAAA;AACvD,eAAO,MAAM,cAAc,qBAAqB,CAAA;AAChD,eAAO,MAAM,kBAAkB,yBAAyB,CAAA;AAGxD,eAAO,MAAM,kBAAkB,yBAAyB,CAAA"}

package/dist/node/style-isolation/selectors.js

@@ -8,6 +8,9 @@ export const STORY_SCOPE_ROOT = '.__poveste-render-story';
 // .__poveste-render-custom-controls) but render inside the chrome panel,
 // so the @scope boundary must keep them in chrome scope.
 export const STORY_SCOPE_BOUNDARY = '.__poveste-render-story:not(.__poveste-render-custom-controls)';
+// The panel only — the sandbox body also carries the class above, so excluding
+// that one would stop a `body` rule applying inside the story itself.
+export const CONTROLS_SLOT = '.__poveste-controls-slot';
 export const DEFAULTS_LAYER = 'poveste-defaults';
 export const USER_GLOBALS_LAYER = 'poveste-user-globals';
 // Import query `globalStyles` files carry so the user-CSS plugin leaves them

package/dist/node/style-isolation/transforms.d.ts

@@ -1,5 +1,7 @@
 export interface WrapOptions {
     scopeRoot: string;
+    /** Bare class name rewritten roots must not match — the panel shares the scope-root class (#173). */
+    excludeRootClass?: string;
 }
 export interface WrapWithLowerOptions {
     scopeRoot: string;

package/dist/node/style-isolation/transforms.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"transforms.d.ts","sourceRoot":"","sources":["../../../src/node/style-isolation/transforms.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,WAAW;IAC1B,SAAS,EAAE,MAAM,CAAA;CAClB;AAED,MAAM,WAAW,oBAAoB;IACnC,SAAS,EAAE,MAAM,CAAA;IACjB,UAAU,EAAE,MAAM,CAAA;CACnB;AAED,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,GAAG,MAAM,CAWlE;AAED,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,oBAAoB,GAAG,MAAM,CAc7E;AAED,wBAAgB,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAKlD"}
+{"version":3,"file":"transforms.d.ts","sourceRoot":"","sources":["../../../src/node/style-isolation/transforms.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,WAAW;IAC1B,SAAS,EAAE,MAAM,CAAA;IACjB,qGAAqG;IACrG,gBAAgB,CAAC,EAAE,MAAM,CAAA;CAC1B;AAED,MAAM,WAAW,oBAAoB;IACnC,SAAS,EAAE,MAAM,CAAA;IACjB,UAAU,EAAE,MAAM,CAAA;CACnB;AAED,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,GAAG,MAAM,CAWlE;AAED,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,oBAAoB,GAAG,MAAM,CAc7E;AAED,wBAAgB,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAKlD"}

package/dist/node/style-isolation/transforms.js

@@ -7,7 +7,7 @@ export function wrapUserCss(css, opts) {
     }
     const { hoisted, remainder } = extractHoistableAtRules(css);
     const body = hasRootSelector(remainder)
-        ? rewriteRootToScope(remainder)
+        ? rewriteRootToScope(remainder, opts.excludeRootClass)
         : remainder;
     const hoistedBlock = hoisted.length > 0 ? `${hoisted.join('\n')}\n` : '';
     return `${hoistedBlock}@scope (${opts.scopeRoot}) {\n${body}\n}\n`;
@@ -65,10 +65,21 @@ function isRootTypeSelector(name) {
 // under `of` rather than `selectors`, so it is untouched for free.
 const DESCENDABLE_PSEUDO_CLASSES = new Set(['is', 'where']);
 const SCOPE_PART = { type: 'pseudo-class', kind: 'scope' };
-function rewriteSelector(selector) {
-    return selector.map((part, index) => {
+// Rewritten roots only, so an author's own classes still apply in the panel.
+function scopeParts(excludeClass) {
+    if (!excludeClass) {
+        return [SCOPE_PART];
+    }
+    return [SCOPE_PART, {
+            type: 'pseudo-class',
+            kind: 'not',
+            selectors: [[{ type: 'class', name: excludeClass }]],
+        }];
+}
+function rewriteSelector(selector, excludeClass) {
+    return selector.flatMap((part, index) => {
         if (part.type === 'pseudo-class' && part.kind === 'root') {
-            return SCOPE_PART;
+            return scopeParts(excludeClass);
         }
         // A namespace is its own part, immediately before the type selector it
         // qualifies. Rewriting past it emits `*|:scope`, which is invalid — a
@@ -76,21 +87,21 @@ function rewriteSelector(selector) {
         // `svg|body` also means a body in the SVG namespace, which is not the
         // document root, so leaving these alone is right on both counts.
         if (part.type === 'type' && isRootTypeSelector(part.name ?? '')) {
-            return selector[index - 1]?.type === 'namespace' ? part : SCOPE_PART;
+            return selector[index - 1]?.type === 'namespace' ? [part] : scopeParts(excludeClass);
         }
         if (part.type === 'pseudo-class' && DESCENDABLE_PSEUDO_CLASSES.has(part.kind ?? '') && part.selectors) {
-            return { ...part, selectors: part.selectors.map(rewriteSelector) };
+            return [{ ...part, selectors: part.selectors.map(s => rewriteSelector(s, excludeClass)) }];
         }
-        return part;
+        return [part];
     });
 }
-function rewriteRootToScope(css) {
+function rewriteRootToScope(css, excludeClass) {
     const processed = lightningcssTransform({
         filename: 'user.css',
         code: Buffer.from(css, 'utf8'),
         minify: false,
         visitor: {
-            Selector: selector => rewriteSelector(selector),
+            Selector: selector => rewriteSelector(selector, excludeClass),
         },
     });
     return Buffer.from(processed.code).toString('utf8');

package/dist/node/style-isolation/vite-plugin.js

@@ -1,4 +1,4 @@
-import { GLOBAL_LAYER_QUERY, STORY_SCOPE_ROOT } from './selectors.js';
+import { CONTROLS_SLOT, GLOBAL_LAYER_QUERY, STORY_SCOPE_ROOT } from './selectors.js';
 import { wrapUserCss } from './transforms.js';
 export const USER_CSS_MARK_START = '/*__PVT_USER_CSS_START__*/';
 export const USER_CSS_MARK_END = '/*__PVT_USER_CSS_END__*/';
@@ -20,7 +20,7 @@ export function userCssScopePlugin(opts) {
             if (hasGlobalQuery(query))
                 return null;
             if (mode === 'wrap') {
-                return { code: wrapUserCss(code, { scopeRoot: STORY_SCOPE_ROOT }), map: null };
+                return { code: wrapUserCss(code, { scopeRoot: STORY_SCOPE_ROOT, excludeRootClass: CONTROLS_SLOT.slice(1) }), map: null };
             }
             return {
                 code: `${USER_CSS_MARK_START}\n${code}\n${USER_CSS_MARK_END}\n`,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "poveste",
   "type": "module",
-  "version": "0.5.1",
+  "version": "0.5.3",
   "description": "A fast story book powered by Vite",
   "author": {
     "name": "Sorin Gitlan"
@@ -68,10 +68,10 @@
     "sirv": "^3.0.0",
     "unhead": "^3.1.0",
     "vite-node": "^6.0.0",
-    "@poveste/app": "^0.5.1",
-    "@poveste/shared": "^0.5.1",
-    "@poveste/controls": "^0.5.1",
-    "@poveste/vendors": "^0.5.1"
+    "@poveste/app": "^0.5.3",
+    "@poveste/shared": "^0.5.3",
+    "@poveste/controls": "^0.5.3",
+    "@poveste/vendors": "^0.5.3"
   },
   "devDependencies": {
     "@types/fs-extra": "^11.0.4",

package/src/node/__tests__/dom-env.spec.ts

@@ -1,5 +1,5 @@
 import { afterEach, describe, expect, it, vi } from 'vitest'
-import { createDomEnv } from '../dom/env.js'
+import { createDomEnv, resetDomEnv } from '../dom/env.js'
 
 describe('createDomEnv', () => {
   let env: ReturnType<typeof createDomEnv>
@@ -54,3 +54,44 @@ describe('createDomEnv', () => {
     })
   })
 })
+
+describe('resetDomEnv', () => {
+  let env: ReturnType<typeof createDomEnv>
+
+  afterEach(() => {
+    env?.destroy()
+  })
+
+  it('returns a dirtied environment to its pristine state', () => {
+    env = createDomEnv()
+    const doc = env.window.document
+
+    doc.body.classList.add('theme-dark')
+    doc.documentElement.setAttribute('lang', 'fr')
+    doc.body.append(doc.createElement('div'))
+    doc.head.append(doc.createElement('style'))
+    // Proxied onto the global only on some node versions.
+    env.window.localStorage?.setItem('seen', '1')
+    ;(env.window as any).__setupInstalled = true
+
+    resetDomEnv(env)
+
+    expect(doc.body.getAttributeNames()).toEqual([])
+    expect(doc.documentElement.getAttributeNames()).toEqual([])
+    expect(doc.body.children).toHaveLength(0)
+    expect(doc.head.children).toHaveLength(0)
+    expect(env.window.localStorage?.getItem('seen') ?? null).toBeNull()
+    // A setup marking itself installed would skip later stories in the worker.
+    expect((env.window as any).__setupInstalled).toBeUndefined()
+  })
+
+  it('leaves the globals the environment itself installed', () => {
+    env = createDomEnv()
+
+    resetDomEnv(env)
+
+    expect(typeof env.window.ResizeObserver).toBe('function')
+    expect(typeof env.window.matchMedia).toBe('function')
+    expect(env.window.document.body).toBeTruthy()
+  })
+})

package/src/node/__tests__/port.spec.ts

@@ -0,0 +1,33 @@
+import { describe, expect, it } from 'vitest'
+import { resolvePort } from '../commands/port.js'
+
+describe('resolvePort', () => {
+  it('returns undefined when the flag was not passed', () => {
+    expect(resolvePort(undefined, 'preview')).toBeUndefined()
+  })
+
+  it('parses the number sade hands over as a string', () => {
+    expect(resolvePort('4569', 'preview')).toBe(4569)
+  })
+
+  it('passes a number through', () => {
+    expect(resolvePort(6006, 'dev')).toBe(6006)
+  })
+
+  // sade declares `--port <port>` but does not enforce the value, so a bare
+  // `--port` arrives as `true`. `Number(true)` is 1 — a valid port that binds
+  // to a privileged one — so this has to be rejected by type.
+  it.each([
+    ['a valueless flag', true],
+    ['a non-numeric value', 'abc'],
+    ['an empty value', ''],
+    ['a port above the range', '99999'],
+    ['a fractional port', '80.5'],
+  ])('rejects %s', (_name, value) => {
+    expect(() => resolvePort(value, 'preview')).toThrow(/--port needs a number/)
+  })
+
+  it('names the command in the message, so the hint is runnable', () => {
+    expect(() => resolvePort(true, 'dev')).toThrow(/poveste dev --port 6006/)
+  })
+})

package/src/node/bin.ts

@@ -9,6 +9,7 @@ const { version } = JSON.parse(fs.readFileSync(resolve(__dirname, '../../package
 
 process.env.NODE_ENV = 'development'
 process.env.HISTOIRE = 'true'
+process.env.POVESTE = 'true'
 
 const program = sade('poveste')
 program.version(version)

package/src/node/builtin-plugins/pinceau-tokens.ts

@@ -52,7 +52,9 @@ export function pinceauTokens(_options: PinceauTokensOptions = {}): Plugin {
       }
     },
 
-    onDev(api, onCleanup) {
+    async onDev(api, onCleanup) {
+      await generate(api)
+
       const watcher = api.watcher.watch(themePath)
         .on('change', () => generate(api))
         .on('add', () => generate(api))

package/src/node/builtin-plugins/tailwind-tokens.ts

@@ -77,8 +77,10 @@ export function tailwindTokens(options: TailwindTokensOptions = {}): Plugin {
       }
     },
 
-    onDev(api, onCleanup) {
+    async onDev(api, onCleanup) {
       if (tailwindCssFile) {
+        await generate(api)
+
         const watcher = api.watcher.watch(tailwindCssFile)
           .on('change', () => generate(api))
           .on('add', () => generate(api))

package/src/node/collect/worker.ts

@@ -8,7 +8,7 @@ import { createBirpc } from 'birpc'
 import { dirname, resolve } from 'pathe'
 import pc from 'picocolors'
 import { ModuleCacheMap, ViteNodeRunner } from 'vite-node/client'
-import { createDomEnv } from '../dom/env.js'
+import { createDomEnv, resetDomEnv } from '../dom/env.js'
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
 
@@ -25,6 +25,9 @@ export interface ReturnData {
 
 const _moduleCache = new ModuleCacheMap()
 let _runner: ViteNodeRunner
+// Worker-lifetime: externalised runtimes cache the DOM they first saw, so one
+// per story broke re-collection.
+let _domEnv: ReturnType<typeof createDomEnv> | undefined
 let _rpc: ReturnType<typeof createBirpc<{
   fetchModule: FetchFunction
   resolveId: ResolveIdFunction
@@ -61,7 +64,12 @@ export default async (payload: Payload): Promise<ReturnData> => {
     },
   }))
 
-  const { destroy: destroyDomEnv } = createDomEnv()
+  if (_domEnv) {
+    resetDomEnv(_domEnv)
+  }
+  else {
+    _domEnv = createDomEnv()
+  }
 
   const el = window.document.createElement('div')
 
@@ -86,8 +94,6 @@ export default async (payload: Payload): Promise<ReturnData> => {
     })
   }
 
-  destroyDomEnv()
-
   const endTime = performance.now()
   console.log(pc.dim(`${payload.storyFile.relativePath} ${Math.round(endTime - startTime)}ms (setup:${Math.round(beforeExecuteTime - startTime)}ms, execute:${Math.round(afterExecuteTime - beforeExecuteTime)}ms, run:${Math.round(afterRunTime - afterExecuteTime)}ms)`))
 

package/src/node/commands/dev.ts

@@ -4,15 +4,18 @@ import pc from 'picocolors'
 import { resolveConfigFile } from '../config.js'
 import { createContext } from '../context.js'
 import { createServer } from '../server.js'
+import { resolvePort } from './port.js'
 
 export interface DevOptions {
-  port: number
+  port?: number | string
   open?: boolean
   host?: string | boolean
   config?: string
 }
 
 export async function devCommand(options: DevOptions) {
+  const port = resolvePort(options.port, 'dev')
+
   let stop: () => Promise<void>
 
   async function start() {
@@ -21,7 +24,7 @@ export async function devCommand(options: DevOptions) {
       mode: 'dev',
     })
     const { server, viteConfigFile, close } = await createServer(ctx, {
-      port: options.port,
+      port,
       open: options.open,
       host: options.host,
     })

package/src/node/commands/port.ts

@@ -0,0 +1,29 @@
+/**
+ * Reads a `--port` value off the parsed CLI options.
+ *
+ * sade declares the flag as taking a value but does not enforce one, so
+ * `poveste preview --port` arrives as the boolean `true` and reaches node's
+ * listen validation, which rejects it with `ERR_INVALID_ARG_VALUE` and names
+ * neither the flag nor the mistake. A non-numeric value fails the same way.
+ */
+export function resolvePort(value: unknown, command: string): number | undefined {
+  if (value === undefined || value === null) {
+    return undefined
+  }
+
+  // Checked by type, not by coercion: a valueless flag arrives as `true`, and
+  // `Number(true)` is 1, a valid port that would bind to a privileged one.
+  const port = typeof value === 'number'
+    ? value
+    : typeof value === 'string' && value.trim() !== ''
+      ? Number(value)
+      : Number.NaN
+
+  if (!Number.isInteger(port) || port < 0 || port > 65535) {
+    throw new TypeError(
+      `--port needs a number between 0 and 65535, got ${JSON.stringify(value)}. Try \`poveste ${command} --port 6006\`.`,
+    )
+  }
+
+  return port
+}

package/src/node/commands/preview.ts

@@ -1,13 +1,16 @@
 import { createContext } from '../context.js'
 import { startPreview } from '../preview.js'
+import { resolvePort } from './port.js'
 
 export interface PreviewOptions {
-  port?: number
+  port?: number | string
   host?: string | boolean
   open?: boolean
 }
 
 export async function previewCommand(options: PreviewOptions) {
+  const port = resolvePort(options.port, 'preview')
+
   const ctx = await createContext({
     mode: 'build',
   })
@@ -19,7 +22,7 @@ export async function previewCommand(options: PreviewOptions) {
   }
 
   const { printUrls } = await startPreview({
-    port: options.port,
+    port,
     host: options.host,
     open: options.open,
   }, ctx)

package/src/node/config.ts

@@ -122,7 +122,6 @@ export function getDefaultConfig(): PovesteConfig {
         contrastColor: '#eee',
       },
     ],
-    sandboxDarkClass: 'dark',
     routerMode: 'history',
     build: {
       excludeFromVendorsChunk: [],

package/src/node/dom/env.ts

@@ -85,5 +85,39 @@ export function createDomEnv() {
   return {
     window,
     destroy,
+    // `populateGlobal` does `global.window = global`, so `window` here is
+    // `globalThis` — one surface, not two.
+    pristineKeys: new Set(Object.keys(globalThis)),
+  }
+}
+
+/** Returns a reused environment to the state a fresh one would have been in. */
+export function resetDomEnv(env: Pick<ReturnType<typeof createDomEnv>, 'window' | 'pristineKeys'>) {
+  const doc = env.window.document
+
+  for (const el of [doc.documentElement, doc.head, doc.body]) {
+    if (!el) continue
+    for (const name of [...el.getAttributeNames()]) {
+      el.removeAttribute(name)
+    }
+  }
+  doc.head?.replaceChildren()
+  doc.body?.replaceChildren()
+
+  try {
+    // Only present when the key was proxied onto the global, which varies by
+    // node version.
+    env.window.localStorage?.clear()
+    env.window.sessionStorage?.clear()
+  }
+  catch {
+    // Unavailable for some jsdom urls.
+  }
+
+  // Additions only: the modules that installed the rest are cached, not re-run.
+  for (const key of Object.keys(globalThis)) {
+    if (!env.pristineKeys.has(key)) {
+      delete (globalThis as Record<string, unknown>)[key]
+    }
   }
 }

package/src/node/preview.ts

@@ -26,7 +26,12 @@ export async function startPreview(options: StartPreviewOptions, ctx: Context):
       port,
       host: options.host,
       open: options.open,
-      strictPort: false,
+      // A port asked for by name has to be that port or nothing. Moving to the
+      // next free one serves the book where nobody is looking, and lands it on
+      // whatever example owns that number, whose suite then adopts it (#175).
+      // Without an explicit port there is no such expectation, and `build`'s
+      // internal preview reads the port back off the server.
+      strictPort: options.port != null,
     },
   })
 

package/src/node/server.ts

@@ -30,6 +30,13 @@ export async function createServer(ctx: Context, options: CreateServerOptions =
       if (options.host) {
         viteConfig.server.host = options.host
       }
+
+      // Same rule as `preview`: a port asked for by name is that port or
+      // nothing. Floating to the next free one hands back a server nobody asked
+      // for, and whoever opens the port they typed reads a different book.
+      if (options.port != null) {
+        viteConfig.server.strictPort = true
+      }
     }
 
     const server = await createViteServer(

package/src/node/style-isolation/__tests__/transforms.spec.ts

@@ -98,6 +98,43 @@ describe('wrapUserCss', () => {
     const occurrences = (out.match(/@scope/g) ?? []).length
     expect(occurrences).toBe(1)
   })
+
+  // #173. Page-level rules stop at the controls slot, which carries the same
+  // scope-root class as the story body; author-written rules still reach it.
+  describe('with excludeRootClass', () => {
+    const opts = {
+      scopeRoot: '.__poveste-render-story',
+      excludeRootClass: '__poveste-controls-slot',
+    }
+
+    it.each([
+      [':root', ':root { background: deeppink }', ':scope:not(.__poveste-controls-slot)'],
+      ['html', 'html { background: deeppink }', ':scope:not(.__poveste-controls-slot)'],
+      ['body', 'body { background: deeppink }', ':scope:not(.__poveste-controls-slot)'],
+      ['body .card', 'body .card { color: red }', ':scope:not(.__poveste-controls-slot) .card'],
+    ])('keeps a page-level %s rule out of the controls slot', (_name, css, expected) => {
+      expect(selectorsIn(wrapUserCss(css, opts))).toEqual([expected])
+    })
+
+    it.each([
+      ['.user-card { background: deeppink }', '.user-card'],
+      ['.body-copy { color: red }', '.body-copy'],
+    ])('leaves the author-written %s alone', (css, expected) => {
+      expect(selectorsIn(wrapUserCss(css, opts))).toEqual([expected])
+    })
+
+    it('carries the exclusion into roots nested in :is()', () => {
+      const out = wrapUserCss(':is(html, body) { color: red }', opts)
+
+      expect(selectorsIn(out)).toEqual([
+        ':is(:scope:not(.__poveste-controls-slot), :scope:not(.__poveste-controls-slot))',
+      ])
+    })
+
+    it('is opt-in, so the chrome pass is unaffected', () => {
+      expect(selectorsIn(wrapUserCss('body { color: red }', { scopeRoot: '.x' }))).toEqual([':scope'])
+    })
+  })
 })
 
 describe('wrapChromeCss', () => {

package/src/node/style-isolation/entry-css-merger.ts

@@ -1,5 +1,5 @@
 import type { Plugin as VitePlugin } from 'vite'
-import { STORY_SCOPE_ROOT } from './selectors.js'
+import { CONTROLS_SLOT, STORY_SCOPE_ROOT } from './selectors.js'
 import { wrapUserCss } from './transforms.js'
 import { USER_CSS_MARK_END, USER_CSS_MARK_START } from './vite-plugin.js'
 
@@ -126,7 +126,7 @@ export function wrapMarkedUserCss(css: string, scopeRoot: string): string {
     }
     const inner = css.slice(start + USER_CSS_MARK_START.length, end).trim()
     if (inner.length > 0) {
-      out += `${wrapUserCss(inner, { scopeRoot })}\n`
+      out += `${wrapUserCss(inner, { scopeRoot, excludeRootClass: CONTROLS_SLOT.slice(1) })}\n`
     }
     cursor = end + USER_CSS_MARK_END.length
   }

package/src/node/style-isolation/selectors.ts

@@ -9,6 +9,9 @@ export const STORY_SCOPE_ROOT = '.__poveste-render-story'
 // .__poveste-render-custom-controls) but render inside the chrome panel,
 // so the @scope boundary must keep them in chrome scope.
 export const STORY_SCOPE_BOUNDARY = '.__poveste-render-story:not(.__poveste-render-custom-controls)'
+// The panel only — the sandbox body also carries the class above, so excluding
+// that one would stop a `body` rule applying inside the story itself.
+export const CONTROLS_SLOT = '.__poveste-controls-slot'
 export const DEFAULTS_LAYER = 'poveste-defaults'
 export const USER_GLOBALS_LAYER = 'poveste-user-globals'
 // Import query `globalStyles` files carry so the user-CSS plugin leaves them

package/src/node/style-isolation/transforms.ts

@@ -3,6 +3,8 @@ import { transform as lightningcssTransform } from 'lightningcss'
 
 export interface WrapOptions {
   scopeRoot: string
+  /** Bare class name rewritten roots must not match — the panel shares the scope-root class (#173). */
+  excludeRootClass?: string
 }
 
 export interface WrapWithLowerOptions {
@@ -17,7 +19,7 @@ export function wrapUserCss(css: string, opts: WrapOptions): string {
   }
   const { hoisted, remainder } = extractHoistableAtRules(css)
   const body = hasRootSelector(remainder)
-    ? rewriteRootToScope(remainder)
+    ? rewriteRootToScope(remainder, opts.excludeRootClass)
     : remainder
   const hoistedBlock = hoisted.length > 0 ? `${hoisted.join('\n')}\n` : ''
   return `${hoistedBlock}@scope (${opts.scopeRoot}) {\n${body}\n}\n`
@@ -92,10 +94,22 @@ interface SelectorPart {
   selectors?: SelectorPart[][]
 }
 
-function rewriteSelector(selector: SelectorPart[]): SelectorPart[] {
-  return selector.map((part, index) => {
+// Rewritten roots only, so an author's own classes still apply in the panel.
+function scopeParts(excludeClass?: string): SelectorPart[] {
+  if (!excludeClass) {
+    return [SCOPE_PART]
+  }
+  return [SCOPE_PART, {
+    type: 'pseudo-class',
+    kind: 'not',
+    selectors: [[{ type: 'class', name: excludeClass }]],
+  }]
+}
+
+function rewriteSelector(selector: SelectorPart[], excludeClass?: string): SelectorPart[] {
+  return selector.flatMap((part, index) => {
     if (part.type === 'pseudo-class' && part.kind === 'root') {
-      return SCOPE_PART
+      return scopeParts(excludeClass)
     }
     // A namespace is its own part, immediately before the type selector it
     // qualifies. Rewriting past it emits `*|:scope`, which is invalid — a
@@ -103,22 +117,22 @@ function rewriteSelector(selector: SelectorPart[]): SelectorPart[] {
     // `svg|body` also means a body in the SVG namespace, which is not the
     // document root, so leaving these alone is right on both counts.
     if (part.type === 'type' && isRootTypeSelector(part.name ?? '')) {
-      return selector[index - 1]?.type === 'namespace' ? part : SCOPE_PART
+      return selector[index - 1]?.type === 'namespace' ? [part] : scopeParts(excludeClass)
     }
     if (part.type === 'pseudo-class' && DESCENDABLE_PSEUDO_CLASSES.has(part.kind ?? '') && part.selectors) {
-      return { ...part, selectors: part.selectors.map(rewriteSelector) }
+      return [{ ...part, selectors: part.selectors.map(s => rewriteSelector(s, excludeClass)) }]
     }
-    return part
+    return [part]
   })
 }
 
-function rewriteRootToScope(css: string): string {
+function rewriteRootToScope(css: string, excludeClass?: string): string {
   const processed = lightningcssTransform({
     filename: 'user.css',
     code: Buffer.from(css, 'utf8'),
     minify: false,
     visitor: {
-      Selector: selector => rewriteSelector(selector as SelectorPart[]) as typeof selector,
+      Selector: selector => rewriteSelector(selector as SelectorPart[], excludeClass) as typeof selector,
     },
   })
   return Buffer.from(processed.code).toString('utf8')

package/src/node/style-isolation/vite-plugin.ts

@@ -1,5 +1,5 @@
 import type { Plugin as VitePlugin } from 'vite'
-import { GLOBAL_LAYER_QUERY, STORY_SCOPE_ROOT } from './selectors.js'
+import { CONTROLS_SLOT, GLOBAL_LAYER_QUERY, STORY_SCOPE_ROOT } from './selectors.js'
 import { wrapUserCss } from './transforms.js'
 
 export const USER_CSS_MARK_START = '/*__PVT_USER_CSS_START__*/'
@@ -29,7 +29,7 @@ export function userCssScopePlugin(opts: UserCssScopePluginOptions): VitePlugin
       if (!isCssPath(path, query)) return null
       if (hasGlobalQuery(query)) return null
       if (mode === 'wrap') {
-        return { code: wrapUserCss(code, { scopeRoot: STORY_SCOPE_ROOT }), map: null }
+        return { code: wrapUserCss(code, { scopeRoot: STORY_SCOPE_ROOT, excludeRootClass: CONTROLS_SLOT.slice(1) }), map: null }
       }
       return {
         code: `${USER_CSS_MARK_START}\n${code}\n${USER_CSS_MARK_END}\n`,