@zvndev/darkmown 1.3.0 → 1.5.0

package/src/compiler/loops.js

@@ -15,6 +15,7 @@ import {
   escapeHtml,
   getPath,
   lookupPath,
+  lookupVar,
   resolveStateKey,
   stripQuotes,
   unescapeHtml
@@ -30,15 +31,15 @@ import { compilePredicate, evalPredicate } from "./predicates.js";
 
 // The fixed corrective suggestion shown for any malformed @loop header.
 const LOOP_USAGE =
-  "Use: @loop src into item [where …] [sort by …] [reverse] [offset N] [limit N] [sortable]";
+  "Use: @loop src into item [where …] [sort by …] [reverse] [offset N] [limit N] [paginate N] [sortable]";
 
 /**
  * Parse the optional clause tail of a `@loop` header in FIXED order:
- * `[where P] [sort by key [asc|desc]] [reverse] [offset N] [limit N] [sortable]`.
+ * `[where P] [sort by key [asc|desc]] [reverse] [offset N] [limit N] [paginate N] [sortable]`.
  * @param {string} tail Everything after `@loop src into item`.
  * @param {string} itemName
  * @param {Ctx} ctx
- * @returns {{ where: string|null, sort: import("./context.js").LoopOpts["sort"], reverse: boolean, offset: NumArg|null, limit: NumArg|null, refsState: boolean, sortable: boolean }}
+ * @returns {{ where: string|null, sort: import("./context.js").LoopOpts["sort"], reverse: boolean, offset: NumArg|null, limit: NumArg|null, refsState: boolean, sortable: boolean, paginate: number|null }}
  */
 function parseLoopClauses(tail, itemName, ctx) {
   // Peel clauses off the END in reverse fixed-order (limit, offset, reverse,
@@ -53,6 +54,7 @@ function parseLoopClauses(tail, itemName, ctx) {
   /** @type {NumArg|null} */ let limit = null;
   let refsState = false;
   let sortable = false;
+  /** @type {number|null} */ let paginate = null;
   /** @returns {never} */
   const bad = () => {
     throw new Error(`Malformed @loop clause in ${ctx.file}: "${tail.trim()}". ${LOOP_USAGE}`);
@@ -69,6 +71,20 @@ function parseLoopClauses(tail, itemName, ctx) {
       .trim();
   }
 
+  // `paginate N` slices the listing into static pages. Peel it position-
+  // independently (like `sortable`) so `paginate 2 limit 1` parses and handleLoop
+  // can reject the combination with a precise message rather than failing the
+  // fixed-order parse. The count is a positive integer literal — paginating "by a
+  // state value" makes no sense for a build-time route split.
+  const pm = s.match(/(^|\s)paginate\s+(\d+)(?=\s|$)/);
+  if (pm) {
+    paginate = Number(pm[2]);
+    if (paginate < 1) bad();
+    s = (s.slice(0, pm.index) + s.slice((pm.index ?? 0) + pm[0].length))
+      .replace(/\s+/g, " ")
+      .trim();
+  }
+
   let m = s.match(/(^|\s)limit\s+(\d+|[A-Za-z_$][\w$]*)$/);
   if (m) {
     limit = parseNumArg(m[2], ctx);
@@ -109,7 +125,7 @@ function parseLoopClauses(tail, itemName, ctx) {
     // predicate means a clause was written before `where` finished (wrong order).
     if (/(^|\s)(sort\s+by\s|reverse(\s|$))/.test(where)) bad();
   }
-  return { where, sort, reverse, offset, limit, refsState, sortable };
+  return { where, sort, reverse, offset, limit, refsState, sortable, paginate };
 }
 
 /**
@@ -213,18 +229,32 @@ export function handleLoop(line, bodyLines, emptyLines, ctx) {
         offset: null,
         limit: null,
         refsState: false,
-        sortable: false
+        sortable: false,
+        paginate: null
       };
   const where = clauses.where ? compilePredicate(clauses.where, itemName, ctx) : null;
   // `sortable` reorders the list directly, so it can't combine with a clause that
   // re-derives the visible order (where/sort/reverse) or shows a partial view
-  // (offset/limit) — those would break the 1:1 DOM↔array index mapping.
+  // (offset/limit/paginate) — those would break the 1:1 DOM↔array index mapping.
   if (
     clauses.sortable &&
-    (where || clauses.sort || clauses.reverse || clauses.offset || clauses.limit)
+    (where ||
+      clauses.sort ||
+      clauses.reverse ||
+      clauses.offset ||
+      clauses.limit ||
+      clauses.paginate)
   ) {
     throw new Error(
-      `@loop sortable cannot combine with where/sort/reverse/offset/limit in ${ctx.file}. ${LOOP_USAGE}`
+      `@loop sortable cannot combine with where/sort/reverse/offset/limit/paginate in ${ctx.file}. ${LOOP_USAGE}`
+    );
+  }
+  // `paginate N` OWNS the page slice, so an explicit offset/limit alongside it is
+  // a conflict (which one wins?). Reject it with a clear hint rather than silently
+  // letting one override the other.
+  if (clauses.paginate && (clauses.offset || clauses.limit)) {
+    throw new Error(
+      `@loop paginate cannot combine with offset/limit in ${ctx.file} — paginate already slices each page. ${LOOP_USAGE}`
     );
   }
   /** @type {LoopOpts} */
@@ -236,7 +266,8 @@ export function handleLoop(line, bodyLines, emptyLines, ctx) {
     limit: clauses.limit,
     empty: emptyLines,
     clauseRefsState: clauses.refsState,
-    sortable: clauses.sortable
+    sortable: clauses.sortable,
+    paginate: clauses.paginate
   };
 
   if (
@@ -245,6 +276,7 @@ export function handleLoop(line, bodyLines, emptyLines, ctx) {
     source.startsWith("../") ||
     source.endsWith(".json")
   ) {
+    if (opts.paginate) throw new Error(paginateOnlyCollections(ctx));
     const dataFile = resolveInclude(source, ctx.file, ctx.context, true);
     const rows = JSON.parse(fs.readFileSync(dataFile, "utf8"));
     if (!Array.isArray(rows)) throw new Error(`@loop data must be a JSON array: ${dataFile}`);
@@ -253,6 +285,7 @@ export function handleLoop(line, bodyLines, emptyLines, ctx) {
 
   const resolved = lookupPath(source, ctx);
   if (resolved.found) {
+    if (opts.paginate) throw new Error(paginateOnlyCollections(ctx));
     if (!Array.isArray(resolved.value)) {
       throw new Error(
         `@loop ${source} in ${ctx.file} found an in-scope value, but it is not a list`
@@ -269,9 +302,15 @@ export function handleLoop(line, bodyLines, emptyLines, ctx) {
     }
     const key = resolveStateKey(segs[0], ctx);
     if (key) {
+      if (opts.paginate) throw new Error(paginateOnlyCollections(ctx));
       const fullKey = segs.length > 1 ? `${key}.${segs.slice(1).join(".")}` : key;
       return reactiveLoop(fullKey, itemName, bodyLines, ctx, opts);
     }
+    // A bare name matching a collection (any `site/pages/<name>/` subdir) resolves
+    // to its entry rows at build time and static-unrolls — zero JS. This is checked
+    // after state so a declared `:state` of the same name still wins.
+    const collection = segs.length === 1 ? ctx.comp.collections.get(source) : undefined;
+    if (collection) return loopOverCollection(collection, source, itemName, bodyLines, ctx, opts);
     // Inside a reactive loop, `@loop <outerItem>.<path> into x` loops a field of
     // the enclosing row item — an ITEM-RELATIVE loop the runtime fills per row.
     if (ctx.loopItem && segs[0] === ctx.loopItem && segs.length > 1) {
@@ -280,15 +319,93 @@ export function handleLoop(line, bodyLines, emptyLines, ctx) {
           `@loop sortable is not supported on a nested (item-relative) loop in ${ctx.file}. ${LOOP_USAGE}`
         );
       }
+      if (opts.paginate) throw new Error(paginateOnlyCollections(ctx));
       return itemRelativeLoop(segs.slice(1).join("."), itemName, bodyLines, ctx, opts);
     }
   }
 
-  throw new Error(
-    `@loop source "${source}" in ${ctx.file} was not found. Loop over a JSON file (@loop /data.json into row), an in-scope value, or a :state list.`
+  throw new Error(unresolvedSourceError(source, ctx));
+}
+
+/**
+ * The "source not found" error for an unresolved `@loop` bare name. Lists the
+ * valid collection names (the `site/pages/<name>/` subdirs) so a typo'd
+ * collection reference is immediately actionable.
+ * @param {string} source
+ * @param {Ctx} ctx
+ * @returns {string}
+ */
+function unresolvedSourceError(source, ctx) {
+  const names = [...ctx.comp.collections.keys()].sort();
+  const collectionsHint = names.length ? ` Available collections: ${names.join(", ")}.` : "";
+  return (
+    `@loop source "${source}" in ${ctx.file} was not found. Loop over a collection ` +
+    `(a site/pages/<name>/ subdirectory, by its bare name), a JSON file ` +
+    `(@loop /data.json into row), an in-scope value, or a :state list.${collectionsHint}`
   );
 }
 
+/**
+ * The error for `paginate` on a non-collection source: pagination multiplies
+ * static routes, which only makes sense for a build-time collection listing.
+ * @param {Ctx} ctx
+ * @returns {string}
+ */
+function paginateOnlyCollections(ctx) {
+  return `@loop paginate requires a collection source (a site/pages/<name>/ subdirectory) in ${ctx.file}. ${LOOP_USAGE}`;
+}
+
+/**
+ * Loop over a build-time collection's entry rows. With no `paginate`, this is a
+ * plain static unroll (filter/sort/reverse/offset/limit at build time, zero JS).
+ * With `paginate N`, it records the pagination intent (so the builder multiplies
+ * routes), then renders only the current page's slice using the injected `page`
+ * pager — `offset = (page.current - 1) * N`, `limit = N`.
+ * @param {import("./collections.js").CollectionRow[]} rows
+ * @param {string} name Collection name, for the pagination record.
+ * @param {string} itemName
+ * @param {string[]} bodyLines
+ * @param {Ctx} ctx
+ * @param {LoopOpts} opts
+ * @returns {string}
+ */
+function loopOverCollection(rows, name, itemName, bodyLines, ctx, opts) {
+  if (!opts.paginate) {
+    // No pagination → behave exactly like a JSON-file/in-scope source: a pure
+    // listing static-unrolls (zero JS); a `where` that reads :state turns it into
+    // a reactive baked-rows loop. `loopOverData` makes that call.
+    return loopOverData(rows, itemName, bodyLines, ctx, opts);
+  }
+  // Count rows AFTER where/sort/reverse but BEFORE the page slice, so `total`
+  // reflects what the reader will actually page through. Reuse pipelineRows with
+  // offset/limit stripped for the count.
+  const filtered = pipelineRows(rows, opts.where, { ...opts, offset: null, limit: null }, ctx);
+  const perPage = opts.paginate;
+  const total = Math.max(1, Math.ceil(filtered.length / perPage));
+  ctx.comp.pagination = { perPage, total, collection: name };
+  // `page.current` is the 1-based page the builder is rendering (it seeds the
+  // document scope). Slice this page out of the already-filtered/sorted list.
+  const current = currentPage(ctx);
+  const start = (current - 1) * perPage;
+  return staticUnroll(filtered.slice(start, start + perPage), itemName, bodyLines, ctx, opts.empty);
+}
+
+/**
+ * The 1-based page the builder is currently rendering, read from the injected
+ * `page.current` scope var. Defaults to page 1 (the discovery compile, before the
+ * builder knows the total, runs with `page.current = 1`).
+ * @param {Ctx} ctx
+ * @returns {number}
+ */
+function currentPage(ctx) {
+  const page = lookupVar(ctx.scope, "page");
+  if (page.found && page.value && typeof page.value === "object") {
+    const current = /** @type {Record<string, unknown>} */ (page.value).current;
+    if (typeof current === "number" && current >= 1) return current;
+  }
+  return 1;
+}
+
 // A static source (JSON file / in-scope value). No `where`, or a `where` that
 // only reads the loop item → filter at build time and stay zero-JS. A `where`
 // that reads :state → becomes a reactive filtered loop with the rows baked in.
@@ -440,7 +557,8 @@ function reactiveLoop(key, itemName, bodyLines, ctx, opts = null) {
           : limit,
       empty: null,
       clauseRefsState: false,
-      sortable: false
+      sortable: false,
+      paginate: null
     },
     ctx
   );

package/src/compiler/page.js

@@ -12,7 +12,7 @@ import { htmlHasHighlight } from "../highlight.js";
 import { compileBody } from "./body.js";
 import { createCompilation, createScope } from "./context.js";
 import { parseFrontmatter, warnLikelyFrontmatter } from "./frontmatter.js";
-import { collectColocatedAssets, scanMarkdownHints } from "./includes.js";
+import { collectColocatedAssets, scanMarkdownHints, scopedSkinFor } from "./includes.js";
 import { escapeHtml } from "./interpolation.js";
 import { selectMd } from "./markdown.js";
 
@@ -30,13 +30,16 @@ import { selectMd } from "./markdown.js";
  * Compile a page source file into a full HTML document plus its assets.
  * @param {string} file Absolute path to the source `.md`/`.wd` file.
  * @param {Paths} context Resolved project paths.
- * @param {{ feed?: { href: string, title: string } }} [options] When a site-wide
- *   RSS feed is emitted (the home page set `site_url` and the site has dated
- *   posts), `feed` carries its absolute href + title so every page links it.
+ * @param {{ feed?: { href: string, title: string }, collections?: Map<string, import("./collections.js").CollectionRow[]>, vars?: Record<string, unknown> }} [options]
+ *   When a site-wide RSS feed is emitted (the home page set `site_url` and the
+ *   site has dated posts), `feed` carries its absolute href + title so every page
+ *   links it. `collections` is the build-time collection index a bare-name
+ *   `@loop` resolves against; `vars` seeds the document scope (the pager `page`
+ *   object on a paginated route).
  * @returns {CompiledPage}
  */
 export function compilePage(file, context, options = {}) {
-  const compiled = compileDocument(file, context);
+  const compiled = compileDocument(file, context, [], options.vars, options.collections);
   const title = compiled.meta.title || "Darkmown";
   const description = compiled.meta.description || "";
   // Optional `image:` frontmatter sets the social-share preview (absolute URL).
@@ -132,7 +135,14 @@ export function compilePage(file, context, options = {}) {
     ? `\n  <script type="speculationrules">{"prerender":[{"where":{"and":[{"href_matches":"/*"},{"not":{"selector_matches":".no-prefetch"}},{"not":{"selector_matches":"[rel~=nofollow]"}}]},"eagerness":"moderate"}]}</script>`
     : "";
 
-  const body = enhanceImages(compiled.html, context);
+  // A route whose OWN colocated skin opted into scoping stamps the whole page
+  // body so its scoped selectors match. Pure compile-time string post-pass (like
+  // enhanceImages) — no runtime, no `data-wd-*` marker, so a static page stays
+  // static. Include-scoped skins are stamped earlier, in handleInclude.
+  const scopedSkin = scopedSkinFor(file, context);
+  const stamped =
+    scopedSkin && scopedSkin.scoped ? stampScope(compiled.html, scopedSkin.scopeId) : compiled.html;
+  const body = enhanceImages(stamped, context);
 
   return {
     meta: compiled.meta,
@@ -151,7 +161,8 @@ ${scripts}
 </body>
 </html>`,
     assets: compiled.assets,
-    warnings: compiled.warnings
+    warnings: compiled.warnings,
+    pagination: compiled.pagination
   };
 }
 
@@ -192,6 +203,70 @@ export function enhanceImages(html, paths) {
   });
 }
 
+/**
+ * Raw-text (`script`, `style`) and escapable-raw-text (`textarea`, `title`)
+ * elements per the HTML spec: their CONTENT is not markup, so `<`/`>` inside them
+ * are plain characters and must never be treated as tags. The content runs to the
+ * first matching close tag.
+ * @type {Set<string>}
+ */
+const RAW_TEXT_ELEMENTS = new Set(["script", "style", "textarea", "title"]);
+
+/**
+ * Stamp `data-wd-scope="<id>"` onto every opening tag of a subtree — the HTML
+ * half of compile-time scoped styles, mirroring {@link enhanceImages}: a
+ * compile-time post-pass over assembled HTML, zero runtime JS. Every element
+ * start tag that doesn't already carry a scope attribute gets one, so the scoped
+ * stylesheet (whose selectors end in `[data-wd-scope="<id>"]`) matches inside
+ * this subtree and nowhere else. Void/self-closing tags are stamped too (the
+ * attribute is valid on any element). Closing tags, comments, doctype, and the
+ * `<!`/`<?` families are left alone. A tag that ALREADY has a `data-wd-scope`
+ * (e.g. a nested include with its own scope) keeps its own — first stamp wins.
+ *
+ * Raw-text / escapable-raw-text elements (`script`, `style`, `textarea`,
+ * `title`) are special-cased: their OPENING tag is stamped (valid), but their
+ * BODY is left byte-intact — `<`/`>` inside a `<script>` are JavaScript, not
+ * markup, so stamping there would corrupt the content. A small tokenizer walks
+ * tag-by-tag (quote-aware in attribute lists) and, on entering a raw-text
+ * element, copies through verbatim until the matching close tag.
+ * @param {string} html Subtree HTML to scope.
+ * @param {string} scopeId Scope id (from {@link import("../skin.js").scopeIdFor}).
+ * @returns {string}
+ */
+export function stampScope(html, scopeId) {
+  // Opening tag: name + (quote-aware) attribute list + optional self-close slash.
+  const openTag = /<([a-zA-Z][\w-]*)((?:[^>"']|"[^"]*"|'[^']*')*?)(\/?)>/g;
+  let out = "";
+  let cursor = 0;
+  for (let m = openTag.exec(html); m; m = openTag.exec(html)) {
+    const [tag, name, attrs, slash] = m;
+    out += html.slice(cursor, m.index); // text/markup before this opening tag
+    const stamped = /\bdata-wd-scope\s*=/.test(attrs)
+      ? tag // first stamp wins — a pre-stamped tag keeps its own scope
+      : `<${name}${attrs} data-wd-scope="${scopeId}"${slash ? " /" : ""}>`;
+    out += stamped;
+    cursor = m.index + tag.length;
+
+    // Raw-text element (not self-closed): copy its body through untouched and
+    // resume scanning after the matching close tag, so nothing inside is stamped.
+    if (!slash && RAW_TEXT_ELEMENTS.has(name.toLowerCase())) {
+      const rest = html.slice(cursor);
+      const closeMatch = new RegExp(`</${name}\\s*>`, "i").exec(rest);
+      if (!closeMatch) {
+        out += rest; // unterminated raw-text element — copy the remainder verbatim
+        cursor = html.length;
+        break;
+      }
+      const through = closeMatch.index + closeMatch[0].length; // body + close tag
+      out += rest.slice(0, through); // byte-intact
+      cursor += through;
+      openTag.lastIndex = cursor; // skip the body the scanner would otherwise re-walk
+    }
+  }
+  out += html.slice(cursor); // trailing text after the last opening tag
+  return out;
+}
+
 /**
  * Extract the `src` attribute value from an `<img>` tag, or "" if absent.
  * @param {string} tag
@@ -235,12 +310,21 @@ function measureImage(src, paths) {
  * @param {Paths} context Resolved project paths.
  * @param {string[]} [stack] Include stack for cycle detection.
  * @param {Record<string, unknown>} [vars] Initial static scope variables.
+ * @param {Map<string, import("./collections.js").CollectionRow[]>} [collections]
+ *   Build-time collection index a bare-name `@loop` resolves against.
  * @returns {CompiledDocument}
  */
-export function compileDocument(file, context, stack = [], vars = {}) {
+export function compileDocument(file, context, stack = [], vars = {}, collections = new Map()) {
   const comp = createCompilation();
+  comp.collections = collections;
   const result = compileFile(file, context, stack, createScope(null, vars), comp, [], null);
-  return { meta: result.meta, html: result.html, assets: comp.assets, warnings: comp.warnings };
+  return {
+    meta: result.meta,
+    html: result.html,
+    assets: comp.assets,
+    warnings: comp.warnings,
+    pagination: comp.pagination
+  };
 }
 
 /**

package/src/compiler.js

@@ -22,5 +22,6 @@ export {
   enhanceImages,
   escapeHtml,
   loopKeyOf,
-  parseFrontmatter
+  parseFrontmatter,
+  stampScope
 } from "./compiler/index.js";

package/src/skin.js

@@ -1,3 +1,5 @@
+import crypto from "node:crypto";
+
 const aliases = new Map([
   ["radius", "border-radius"],
   ["shadow", "box-shadow"],
@@ -19,6 +21,29 @@ function resolveProp(prop, rest) {
   return aliases.get(prop) || prop;
 }
 
+/**
+ * Derive a short, deterministic scope id from a skin's PROJECT-RELATIVE PATH.
+ * Path-based (stable across content edits, unique per component file) and short
+ * enough to read in the emitted CSS (`wd-7c21`). The same path always yields the
+ * same id, so the CSS rewrite (builder) and the HTML stamp (page/include) agree
+ * without sharing state — they just hash the same relative path. The path is
+ * normalized to POSIX separators first so a build is identical on Windows.
+ * @param {string} relPath Skin path relative to the project root (cwd).
+ * @returns {string} The scope id, e.g. `wd-7c21`.
+ */
+export function scopeIdFor(relPath) {
+  const posix = relPath.replaceAll("\\", "/");
+  const hash = crypto.createHash("sha256").update(posix).digest("hex");
+  return `wd-${hash.slice(0, 4)}`;
+}
+
+// Selectors that style the whole page, not a component subtree. In a `scoped`
+// skin they are a mistake: scoping appends an attribute to the *subject* element,
+// so `page`/`body`/`html`/`*`/`::selection` would either become a no-op (no
+// element in the subtree carries the attribute on <body>/<html>) or silently
+// fail to do what the author means. We error and point them at a global skin.
+const PAGE_LEVEL_SELECTORS = new Set(["page", "*", "html", "body", "::selection"]);
+
 /**
  * A nesting frame in the indentation stack.
  * @typedef {object} SkinFrame
@@ -29,10 +54,25 @@ function resolveProp(prop, rest) {
 
 /**
  * Compile indentation-based `.skin` source into CSS.
+ *
+ * Scoping (opt-in): when `opts.scope` is set the skin is compiled in scoped
+ * mode — every selector RULE gets `[data-wd-scope="<id>"]` appended to the
+ * subject of each compound selector, so the stylesheet only ever matches inside
+ * the stamped subtree. Design tokens (`tokens` / `tokens dark` / `tokens [attr]`)
+ * stay GLOBAL on `:root` regardless, so `var(--x)` and dark mode keep working
+ * site-wide. A whole-selector `:global(.x)` escapes scoping. Page-level selectors
+ * (`page`/`*`/`html`/`body`/`::selection`) are a compile error in scoped mode.
+ * Without `opts.scope`, output is byte-identical to before this feature existed.
  * @param {string} source
+ * @param {{ scope?: string, subjects?: Set<string> }} [opts] `scope`: the scope
+ *   id enabling scoped mode. `subjects`: an optional set the compiler fills with
+ *   every scoped subject token (`.card`, `h2`, `#id`) for the unused-selector
+ *   warning, so the caller need not re-parse the source.
  * @returns {string}
  */
-export function compileSkin(source) {
+export function compileSkin(source, opts = {}) {
+  const scope = opts.scope;
+  const subjects = opts.subjects;
   const lines = source
     .replace(/\r\n?/g, "\n")
     .replace(/\/\*[\s\S]*?\*\//g, "") // strip /* … */ block comments (any span)
@@ -47,6 +87,19 @@ export function compileSkin(source) {
     })
     .map((raw) => ({ indent: (raw.match(/^\s*/)?.[0] ?? "").length, text: raw.trim() }));
 
+  // The opt-in marker: `scoped` must be the FIRST meaningful line (the filter
+  // above has already dropped comments, blanks, and dividers). Anywhere else it
+  // is an error — a `scoped` mid-file means the author misread the contract.
+  let start = 0;
+  if (scope && lines.length && lines[0].text === "scoped" && lines[0].indent === 0) {
+    start = 1;
+  }
+  for (let i = start; i < lines.length; i++) {
+    if (lines[i].text === "scoped" && lines[i].indent === 0) {
+      throw new Error('"scoped" must be the first line of a .skin file');
+    }
+  }
+
   /** @type {SkinFrame[]} */
   const stack = [];
   /** @type {string[]} */
@@ -65,7 +118,7 @@ export function compileSkin(source) {
   /** @type {Map<string, string[]>} */
   const attrVars = new Map();
 
-  for (let i = 0; i < lines.length; i++) {
+  for (let i = start; i < lines.length; i++) {
     const { indent, text } = lines[i];
     // Structure decides meaning: a line opens a block (selector) exactly when
     // the next line is indented deeper. Everything else is a declaration.
@@ -119,17 +172,28 @@ export function compileSkin(source) {
       if (text.startsWith("@")) {
         stack.push({ indent, selector: parent ?? null, media: text });
       } else {
+        if (scope) guardPageLevel(text, parent);
         stack.push({ indent, selector: normalizeSelector(text, parent) });
       }
       continue;
     }
 
     const current = stack.at(-1)?.selector || ":root";
+    // A leaf with no enclosing selector lands on `:root` — a page-level write. In
+    // a scoped skin that is the same mistake `guardPageLevel` rejects (and the
+    // place a filtered bare `*`/`page` reset would otherwise leak through to), so
+    // it errors with the same hint instead of emitting a never-matching rule.
+    if (scope && current === ":root") {
+      throw new Error(
+        `page-level declaration "${text}" is not allowed in a scoped .skin — page-level styles belong in a global skin, not a scoped one`
+      );
+    }
     const media = stack.find((frame) => frame.media)?.media;
     const [prop, ...rest] = text.split(/\s+/);
     const cssProp = resolveProp(prop, rest);
     const value = rest.join(" ").replace(/\$([a-zA-Z0-9_-]+)/g, "var(--$1)");
-    const rule = `${current} { ${cssProp}: ${value}; }`;
+    const subject = scope ? scopeSelector(current, scope, subjects) : current;
+    const rule = `${subject} { ${cssProp}: ${value}; }`;
     css.push(media ? `${media} { ${rule} }` : rule);
   }
 
@@ -153,6 +217,86 @@ export function compileSkin(source) {
   return css.join("\n");
 }
 
+/**
+ * Reject page-level selectors in a scoped skin. Checks the AUTHORED selector
+ * text (before `page`→`body` rewrite) so `page` is caught by name. Each
+ * comma-separated part is inspected; a bare top-level selector (no parent) that
+ * is one of the page-level set, or a top-level `::selection`, errors with a hint
+ * pointing the author at a global skin.
+ * @param {string} text Raw selector line.
+ * @param {string | null | undefined} parent Enclosing selector, if nested.
+ * @returns {void}
+ */
+function guardPageLevel(text, parent) {
+  // Only TOP-LEVEL selectors are page-level mistakes — `.card *` (a descendant
+  // wildcard inside a component) is fine, so the check applies when there is no
+  // parent selector chain (`:root` is the implicit root, treated as none).
+  if (parent && parent !== ":root") return;
+  for (const part of text.split(",")) {
+    const clean = part.trim();
+    if (PAGE_LEVEL_SELECTORS.has(clean)) {
+      throw new Error(
+        `page-level selector "${clean}" is not allowed in a scoped .skin — page-level styles belong in a global skin, not a scoped one`
+      );
+    }
+  }
+}
+
+/**
+ * Append the scope attribute to a resolved selector list (post `&`-nesting).
+ * Each comma-separated compound selector gets `[data-wd-scope="<id>"]` on its
+ * SUBJECT (rightmost simple selector), inserted BEFORE any trailing
+ * pseudo-class/element so the result stays valid CSS (`.card[…]:hover`, never
+ * `.card:hover[…]`). A whole-selector `:global(.x)` unwraps to a plain `.x` with
+ * NO attribute — the documented escape hatch (whole-selector only this release).
+ * @param {string} selectorList Resolved selector list (may contain commas).
+ * @param {string} scope Scope id.
+ * @param {Set<string>} [subjects] Optional sink for subject tokens (warning).
+ * @returns {string}
+ */
+function scopeSelector(selectorList, scope, subjects) {
+  return selectorList
+    .split(",")
+    .map((part) => {
+      const clean = part.trim();
+      // Whole-selector `:global(.toast)` → `.toast`, unscoped. Descendant
+      // `:global` (`.card :global(.x)`) is intentionally NOT supported yet.
+      const global = clean.match(/^:global\(\s*(.+?)\s*\)$/);
+      if (global) return global[1];
+      // The subject is the last whitespace-delimited compound. Combinators
+      // (`>`, `+`, `~`) stand as their own tokens, so the subject is whatever
+      // follows the final combinator/descendant gap.
+      const tokens = clean.split(/\s+/);
+      const subjectIndex = tokens.length - 1;
+      const lead = tokens.slice(0, subjectIndex);
+      const subject = tokens[subjectIndex];
+      // Split the subject into its base (tag/class/id, plus attribute selectors)
+      // and any trailing pseudo `:hover` / `::before`. The attribute slots in at
+      // the base/pseudo seam: `.card::before` → `.card[scope]::before`.
+      const seam = subject.search(/::?[a-zA-Z-]/);
+      const base = seam === -1 ? subject : subject.slice(0, seam);
+      const pseudo = seam === -1 ? "" : subject.slice(seam);
+      if (subjects) subjects.add(subjectBase(base));
+      const scoped = `${base}[data-wd-scope="${scope}"]${pseudo}`;
+      return [...lead, scoped].join(" ");
+    })
+    .join(", ");
+}
+
+/**
+ * Reduce a scoped subject base to the single token the unused-selector warning
+ * checks against the stamped subtree: the leading `.class`, `#id`, or bare tag,
+ * dropping any chained attribute selectors (`a[href]` → `a`). Returns `""` for a
+ * subject that has no checkable token (a bare attribute selector), which the
+ * caller treats as "always present" (never warns).
+ * @param {string} base
+ * @returns {string}
+ */
+function subjectBase(base) {
+  const m = base.match(/^([.#]?[A-Za-z_][\w-]*)/);
+  return m ? m[1] : "";
+}
+
 /**
  * Normalize a bracketed token modifier into a valid attribute selector,
  * quoting the value so `[data-theme=dark]` becomes `[data-theme="dark"]`.