slidemind 0.0.27

package/src/builders/lint-slides.mjs

@@ -0,0 +1,796 @@
+// Slide lint pass — enforces the typed authoring contract.
+//
+// Runs over every slide .jsx in a deck before any HTML/PPTX rendering.
+// Errors fail the build with file:line; warnings print but don't fail.
+// All checks together aim to close the gap between author CSS/JSX and
+// PPTX-translatable output, so regressions surface at build time with a
+// clear suggested replacement instead of as silent visual drift.
+//
+// Five sections, in order:
+//   1. Standard-techniques (AST): imports, hooks, event handlers,
+//      dangerouslySetInnerHTML outside <style>, banned HTML elements,
+//      custom-element tags, unknown PascalCase components.
+//   2. Layer 0 deny-list (CSS + JSX): properties the converter cannot
+//      honor; remote img URLs (local svg/raster <img> is fine — the
+//      server render and the HTML preview both inline local assets).
+//   3. Layer 1 token discipline (CSS values): hex/rgb/named colors,
+//      disallowed font-family. Raw px/em/rem are warn-for-now during
+//      rollout; flip to error after a deck cleanup pass.
+//   4. Primitive registry (AST): every PascalCase JSX tag must be in
+//      skills/create-slides/primitives.json.
+//   5. PPTX-fidelity contract (the rules that prevent HTML↔PPTX
+//      divergence — see references/authoring-contract.md): pseudo
+//      elements may not carry layout content; SVG <text> may not carry
+//      multi-word labels; one-line actionTitle must fit Arial's ~55-char
+//      budget. Each rule maps 1:1 to a "Common mistakes to avoid" entry.
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { parse } from "@babel/parser";
+import _traverse from "@babel/traverse";
+const traverse = _traverse.default || _traverse;
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const PACKAGE_ROOT = path.resolve(__dirname, "..", "..");
+// The layout-contract registry now ships alongside the builders (the per-CD
+// design lives in the materialized bundle). Callers in the build pipeline pass
+// the resolved bundle/deck primitives explicitly; this is the fallback.
+const DEFAULT_PRIMITIVES_PATH = path.join(__dirname, "primitives.json");
+
+const _registryCache = new Map();
+
+function loadOnePrimitivesFile(primitivesPath) {
+  if (!primitivesPath || !fs.existsSync(primitivesPath)) {
+    return { layouts: [], primitives: [] };
+  }
+  const json = JSON.parse(fs.readFileSync(primitivesPath, "utf8"));
+  return {
+    layouts: json.layouts || [],
+    primitives: json.primitives || [],
+  };
+}
+
+// Derive the valid layout component names from the materialized bundle's
+// `layouts/*.jsx`. The build binds each layout by its `export default function
+// <Name>` (falling back to the PascalCase of the kebab filename stem), so we
+// mirror that here. This lets the lint recognize the bundle's actual layout
+// components WITHOUT a primitives.json `layouts` list — the materialized bundle
+// doesn't ship one, and the per-CD layout set is whatever the add-in produced.
+function deriveLayoutBindingsFromDirs(dirs) {
+  const names = new Set();
+  for (const dir of dirs || []) {
+    if (!dir || !fs.existsSync(dir)) continue;
+    let files;
+    try {
+      files = fs.readdirSync(dir);
+    } catch {
+      continue;
+    }
+    for (const f of files) {
+      if (!/\.jsx$/i.test(f)) continue;
+      let src;
+      try {
+        src = fs.readFileSync(path.join(dir, f), "utf8");
+      } catch {
+        continue;
+      }
+      const exportName = src.match(
+        /export\s+default\s+function\s+([A-Za-z_$][\w$]*)/,
+      )?.[1];
+      if (exportName) names.add(exportName);
+      const pascal = f
+        .replace(/\.jsx$/i, "")
+        .split(/[-_\s]+/)
+        .filter(Boolean)
+        .map((p) => p.charAt(0).toUpperCase() + p.slice(1))
+        .join("");
+      if (pascal) names.add(pascal);
+    }
+  }
+  return names;
+}
+
+// Load and merge one or more primitives.json files plus the layout component
+// names derived from the materialized layout dirs. The active skill's
+// primitives take precedence over the brand's on name conflict (rare).
+// Pass either a string path or { primitivesPath, brandPrimitivesPath,
+// layoutsDirs } — the cache key covers all inputs so each combination is
+// memoised once.
+function loadRegistry(arg = DEFAULT_PRIMITIVES_PATH) {
+  const paths =
+    typeof arg === "string"
+      ? [arg]
+      : [arg.brandPrimitivesPath, arg.primitivesPath].filter(
+          (p, i, a) => p && a.indexOf(p) === i,
+        );
+  if (paths.length === 0) paths.push(DEFAULT_PRIMITIVES_PATH);
+  const layoutsDirs =
+    typeof arg === "object" && arg && Array.isArray(arg.layoutsDirs)
+      ? arg.layoutsDirs.filter(Boolean)
+      : [];
+  const cacheKey = [...paths, "::layouts::", ...layoutsDirs].join("\n");
+  if (_registryCache.has(cacheKey)) return _registryCache.get(cacheKey);
+  const layouts = new Set();
+  const primitives = new Map();
+  for (const p of paths) {
+    const file = loadOnePrimitivesFile(p);
+    for (const name of file.layouts) layouts.add(name);
+    for (const prim of file.primitives) primitives.set(prim.name, prim);
+  }
+  for (const name of deriveLayoutBindingsFromDirs(layoutsDirs)) {
+    layouts.add(name);
+  }
+  const reg = { layouts, primitives };
+  _registryCache.set(cacheKey, reg);
+  return reg;
+}
+
+const BANNED_HOOKS = new Set([
+  "useState",
+  "useEffect",
+  "useRef",
+  "useContext",
+  "useMemo",
+  "useCallback",
+  "useReducer",
+  "useLayoutEffect",
+  "useImperativeHandle",
+  "useDebugValue",
+  "useTransition",
+  "useDeferredValue",
+  "useId",
+  "useSyncExternalStore",
+]);
+
+const BANNED_HTML_TAGS = new Set([
+  "script",
+  "iframe",
+  "canvas",
+  "object",
+  "embed",
+]);
+
+const BANNED_CSS_PROPERTIES = [
+  "filter",
+  "mask",
+  "mask-image",
+  "backdrop-filter",
+  "mix-blend-mode",
+  "animation",
+  "animation-name",
+  "animation-duration",
+  "transition",
+  "transition-property",
+  "content-visibility",
+];
+
+const HEX_COLOR_RE = /#(?:[0-9a-f]{3}|[0-9a-f]{4}|[0-9a-f]{6}|[0-9a-f]{8})\b/gi;
+const RGB_COLOR_RE = /\b(?:rgb|rgba|hsl|hsla)\(/gi;
+
+// CSS named colors that we want to flag (subset; covers the common ones an
+// agent might reach for). transparent / currentColor / inherit / unset are
+// in ALLOWED_COLOR_KEYWORDS.
+const NAMED_COLORS_RE = /\b(?:black|white|gray|grey|red|green|blue|yellow|orange|purple|pink|brown|silver|gold|cyan|magenta|lime|teal|navy|maroon|olive|aqua|fuchsia)\b/gi;
+
+function camelToKebab(name) {
+  return name.replace(/[A-Z]/g, (c) => "-" + c.toLowerCase());
+}
+
+function isPascalCase(name) {
+  return typeof name === "string" && /^[A-Z]/.test(name);
+}
+
+function jsxNameToString(node) {
+  if (!node) return "";
+  if (node.type === "JSXIdentifier") return node.name;
+  if (node.type === "JSXMemberExpression") {
+    return jsxNameToString(node.object) + "." + jsxNameToString(node.property);
+  }
+  return "";
+}
+
+// Collect issues from one slide and return them. Each issue is
+// { severity: "error"|"warn", line, message }.
+function lintSlideSource(src, fileName, registrySource) {
+  const issues = [];
+  const registry = loadRegistry(registrySource);
+
+  const reportLine = (loc) => (loc && loc.start ? loc.start.line : 0);
+
+  function err(loc, message) {
+    issues.push({ severity: "error", line: reportLine(loc), message });
+  }
+  function warn(loc, message) {
+    issues.push({ severity: "warn", line: reportLine(loc), message });
+  }
+
+  let ast;
+  try {
+    ast = parse(src, {
+      sourceType: "module",
+      plugins: ["jsx"],
+    });
+  } catch (e) {
+    issues.push({
+      severity: "error",
+      line: e.loc ? e.loc.line : 0,
+      message: `parse error: ${e.message}`,
+    });
+    return issues;
+  }
+
+  // Locally-declared PascalCase functions count as registered components
+  // for this file. Slides occasionally define small JSX helpers inline
+  // — at top level OR nested inside the default-exported render function
+  // (e.g. <Spark> inside 13-roi.jsx is declared as a const inside the
+  // slide's render function). Scan the whole AST.
+  const localComponents = new Set();
+  traverse(ast, {
+    FunctionDeclaration(p) {
+      if (p.node.id && isPascalCase(p.node.id.name)) {
+        localComponents.add(p.node.id.name);
+      }
+    },
+    VariableDeclarator(p) {
+      const id = p.node.id;
+      const init = p.node.init;
+      if (
+        id &&
+        id.type === "Identifier" &&
+        isPascalCase(id.name) &&
+        init &&
+        (init.type === "ArrowFunctionExpression" ||
+          init.type === "FunctionExpression")
+      ) {
+        localComponents.add(id.name);
+      }
+    },
+  });
+
+  // Section 3: collect top-level CSS template literals (declared in the
+  // module scope) so we can lint them like style sheets. The convention
+  // is `const SLIDE_CSS = \`...\`;` followed by `<style dangerouslySet...>`.
+  const cssBlocks = []; // { value, loc }
+
+  traverse(ast, {
+    // 1a. Imports / requires at module top level.
+    ImportDeclaration(p) {
+      err(
+        p.node.loc,
+        `import statements are not allowed in slide JSX (slides have no module system at runtime). Compose with the registered primitives instead.`,
+      );
+    },
+    CallExpression(p) {
+      const callee = p.node.callee;
+      if (
+        callee.type === "Identifier" &&
+        (callee.name === "require" || callee.name === "import")
+      ) {
+        err(
+          p.node.loc,
+          `${callee.name}() is not allowed in slide JSX. Slides cannot pull in packages.`,
+        );
+      }
+      // 1c. React hooks.
+      if (callee.type === "Identifier" && BANNED_HOOKS.has(callee.name)) {
+        err(
+          p.node.loc,
+          `${callee.name} is not allowed in slide JSX. Slides are stateless render functions; no React hooks.`,
+        );
+      }
+    },
+    JSXOpeningElement(p) {
+      const tagName = jsxNameToString(p.node.name);
+      const isPascal = isPascalCase(tagName);
+      const isDom = !isPascal && tagName !== "";
+
+      // 1d. Banned HTML tags.
+      if (isDom && BANNED_HTML_TAGS.has(tagName)) {
+        err(
+          p.node.loc,
+          `<${tagName}> is not allowed in slide JSX. Use static markup or a registered primitive.`,
+        );
+      }
+
+      // 1e. Custom-element tag names (contain a hyphen) outside the registry.
+      if (
+        isDom &&
+        tagName.includes("-") &&
+        !registry.layouts.has(tagName) &&
+        !registry.primitives.has(tagName)
+      ) {
+        err(
+          p.node.loc,
+          `<${tagName}> looks like a custom element. Custom elements / web components are not supported by the PPTX exporter.`,
+        );
+      }
+
+      // 4. Primitive registry: every PascalCase tag must be registered
+      //    OR declared locally in this same slide file.
+      if (isPascal) {
+        if (
+          !registry.layouts.has(tagName) &&
+          !registry.primitives.has(tagName) &&
+          !localComponents.has(tagName)
+        ) {
+          err(
+            p.node.loc,
+            `<${tagName}> is not in primitives.json and is not a local function in this file. Add it to the registry or use a registered primitive and a layout component.`,
+          );
+        }
+      }
+
+      // 1b. Event handlers and dangerouslySetInnerHTML.
+      for (const attr of p.node.attributes) {
+        if (attr.type !== "JSXAttribute") continue;
+        const attrName =
+          attr.name && attr.name.type === "JSXIdentifier"
+            ? attr.name.name
+            : attr.name && attr.name.type === "JSXNamespacedName"
+              ? attr.name.namespace.name + ":" + attr.name.name.name
+              : "";
+
+        if (attrName.startsWith("on") && /^on[A-Z]/.test(attrName)) {
+          err(
+            attr.loc,
+            `event handler ${attrName} is not allowed. Slides are static; event handlers don't translate to the .pptx render.`,
+          );
+        }
+
+        if (attrName === "dangerouslySetInnerHTML" && tagName !== "style") {
+          err(
+            attr.loc,
+            `dangerouslySetInnerHTML is only allowed on <style> elements. Compose with JSX children instead.`,
+          );
+        }
+
+        // 2. <img> source checks. Local svg/raster assets are fine — both
+        //    the server render and the HTML preview inline local files. Only
+        //    remote URLs are rejected; PPTX export requires self-contained
+        //    assets. Catch literal strings AND template literals.
+        if (tagName === "img" && attrName === "src") {
+          const literal = attrLiteralValue(attr);
+          const templateText = attrTemplateText(attr);
+          const text = literal != null ? literal : templateText;
+          if (typeof text === "string") {
+            if (/^https?:/i.test(text)) {
+              err(
+                attr.loc,
+                `<img src=remote-url> is not allowed. PPTX export requires local, self-contained assets.`,
+              );
+            }
+          }
+        }
+
+        // Inline style={{...}} props — lint as CSS values.
+        if (attrName === "style" && attr.value && attr.value.type === "JSXExpressionContainer") {
+          lintInlineStyleObject(attr.value.expression, p.node.loc, err, warn);
+        }
+
+        // 5c. One-line actionTitle must fit Arial Bold 40 px in the 1134 px
+        //     slot. The HTML preview's Inter/Helvetica fallback is ~20 %
+        //     narrower than PowerPoint's Arial, so a line that fits one
+        //     line in the preview can wrap to two lines in PPT. Cap at
+        //     ~55 chars when no explicit \n is present. See
+        //     authoring-contract.md → "One-line action titles longer
+        //     than ~55 characters".
+        if (attrName === "actionTitle") {
+          const literal = attrLiteralValue(attr);
+          const templateText = attrTemplateText(attr);
+          const text = literal != null ? literal : templateText;
+          if (typeof text === "string" && !text.includes("\n") && text.length > 55) {
+            warn(
+              attr.loc || p.node.loc,
+              `actionTitle is ${text.length} chars on a single line; may wrap to two lines in PPT (Arial Bold 40 px in the 1134 px slot fits ~55 chars). Tighten the copy, insert \\n at the intended break point, or accept the wrap as design intent.`,
+            );
+          }
+        }
+      }
+
+      // 5b. SVG <text> for multi-word labels — must be HTML over the SVG.
+      //     authoring-contract.md → "SVG <text> for multi-word labels".
+      if (tagName === "text") {
+        // Walk the parent chain to see if this <text> sits inside an <svg>.
+        let cur = p.parentPath;
+        let insideSvg = false;
+        while (cur) {
+          if (cur.node && cur.node.type === "JSXElement") {
+            const parentTag = jsxNameToString(cur.node.openingElement.name);
+            if (parentTag === "svg") {
+              insideSvg = true;
+              break;
+            }
+          }
+          cur = cur.parentPath;
+        }
+        if (insideSvg) {
+          // Pull static text out of children: JSXText nodes + StringLiteral
+          // expression containers. Skip dynamic expressions — we can't
+          // measure their length statically.
+          const jsxEl = p.parentPath && p.parentPath.node && p.parentPath.node.type === "JSXElement"
+            ? p.parentPath.node
+            : null;
+          let textContent = "";
+          if (jsxEl) {
+            for (const child of jsxEl.children || []) {
+              if (child.type === "JSXText") textContent += child.value;
+              else if (
+                child.type === "JSXExpressionContainer" &&
+                child.expression.type === "StringLiteral"
+              ) {
+                textContent += child.expression.value;
+              }
+            }
+          }
+          const trimmed = textContent.trim();
+          if (trimmed.length > 4) {
+            warn(
+              p.node.loc,
+              `<text> inside <svg> carries ${trimmed.length} chars ("${trimmed.slice(0, 30)}${trimmed.length > 30 ? "…" : ""}"). SVG <text> projects through a different coordinate transform than <rect>/<line>/<path>, so multi-word labels decouple from the geometry in PPT. Use an HTML element (<div>/<span>) absolutely positioned over the SVG container instead. SVG <text> is reserved for single-character markers.`,
+            );
+          }
+        }
+      }
+    },
+    // 1f. Capture `<style>{`...`}</style>` template-literal CSS blocks for
+    //     section 3 linting after the AST walk.
+    JSXElement(p) {
+      const opener = p.node.openingElement;
+      if (jsxNameToString(opener.name) !== "style") return;
+      // Look for dangerouslySetInnerHTML={{ __html: `...css...` }} OR a
+      // template-literal child.
+      for (const attr of opener.attributes) {
+        if (
+          attr.type === "JSXAttribute" &&
+          attr.name &&
+          attr.name.name === "dangerouslySetInnerHTML" &&
+          attr.value &&
+          attr.value.type === "JSXExpressionContainer" &&
+          attr.value.expression.type === "ObjectExpression"
+        ) {
+          for (const prop of attr.value.expression.properties) {
+            if (
+              prop.type === "ObjectProperty" &&
+              prop.key &&
+              ((prop.key.name === "__html") || (prop.key.value === "__html")) &&
+              prop.value
+            ) {
+              const css = expressionToString(prop.value);
+              if (css != null) cssBlocks.push({ value: css, loc: prop.value.loc });
+            }
+          }
+        }
+      }
+      for (const child of p.node.children) {
+        if (child.type === "JSXExpressionContainer") {
+          const css = expressionToString(child.expression);
+          if (css != null) cssBlocks.push({ value: css, loc: child.loc });
+        }
+        if (child.type === "JSXText") {
+          // Ignore whitespace-only text.
+        }
+      }
+    },
+    // Default-export must be a function returning JSX. We don't enforce a
+    // single export shape strictly — the existing slide convention is one
+    // default-exported function, and the rest of the build assumes that.
+  });
+
+  // Section 2 + 3 on collected CSS blocks.
+  for (const { value, loc } of cssBlocks) {
+    lintCssBody(value, loc, err, warn);
+  }
+
+  // Module-level `const X = \`...\`` template literals: lint every one as
+  // if it were CSS. The convention is `const SLIDE_CSS = \`...\``, but
+  // authors sometimes use a different name. False-positive risk is low
+  // because the CSS-declaration regex only matches `prop: value;` shapes.
+  ast.program.body.forEach((node) => {
+    if (node.type !== "VariableDeclaration") return;
+    for (const decl of node.declarations) {
+      if (
+        decl.init &&
+        decl.init.type === "TemplateLiteral" &&
+        decl.init.quasis.length >= 1
+      ) {
+        const body = decl.init.quasis.map((q) => q.value.cooked).join("");
+        if (/[a-z-]+\s*:\s*[^;}\n]+/i.test(body)) {
+          lintCssBody(body, decl.init.loc, err, warn);
+        }
+      }
+    }
+  });
+
+  return issues;
+}
+
+// Read an attribute value literal if it's a string literal.
+function attrLiteralValue(attr) {
+  if (!attr.value) return null;
+  if (attr.value.type === "StringLiteral") return attr.value.value;
+  if (
+    attr.value.type === "JSXExpressionContainer" &&
+    attr.value.expression.type === "StringLiteral"
+  ) {
+    return attr.value.expression.value;
+  }
+  return null;
+}
+
+// Read the static text of a template-literal attribute value (the cooked
+// concatenation of all quasis, ignoring expressions). Returns null if the
+// attribute value isn't a template literal.
+function attrTemplateText(attr) {
+  if (
+    !attr.value ||
+    attr.value.type !== "JSXExpressionContainer" ||
+    attr.value.expression.type !== "TemplateLiteral"
+  ) {
+    return null;
+  }
+  return attr.value.expression.quasis.map((q) => q.value.cooked).join("");
+}
+
+// Best-effort string extraction: literal strings and template literals
+// without expressions.
+function expressionToString(node) {
+  if (!node) return null;
+  if (node.type === "StringLiteral") return node.value;
+  if (node.type === "TemplateLiteral") {
+    return node.quasis.map((q) => q.value.cooked).join("");
+  }
+  if (node.type === "Identifier") {
+    // Bare identifier — caller resolves by walking the program if it cares.
+    return null;
+  }
+  return null;
+}
+
+function lintInlineStyleObject(node, loc, err, warn) {
+  if (!node || node.type !== "ObjectExpression") return;
+  for (const prop of node.properties) {
+    if (prop.type !== "ObjectProperty") continue;
+    let key = "";
+    if (prop.key.type === "Identifier") key = camelToKebab(prop.key.name);
+    else if (prop.key.type === "StringLiteral") key = prop.key.value;
+    if (!key) continue;
+
+    if (BANNED_CSS_PROPERTIES.includes(key)) {
+      err(
+        prop.loc || loc,
+        `inline style property "${key}" is on the deny-list. ${denyListSuggestion(key)}`,
+      );
+      continue;
+    }
+
+    const value =
+      prop.value.type === "StringLiteral"
+        ? prop.value.value
+        : prop.value.type === "TemplateLiteral"
+          ? prop.value.quasis.map((q) => q.value.cooked).join("")
+          : prop.value.type === "NumericLiteral"
+            ? String(prop.value.value)
+            : null;
+    if (value == null) continue;
+
+    checkCssValue(key, value, prop.loc || loc, err, warn);
+  }
+}
+
+function lintCssBody(css, loc, err, warn) {
+  // Strip /* comments */ to avoid false positives.
+  const stripped = css.replace(/\/\*[\s\S]*?\*\//g, "");
+
+  // 2a. Banned at-rules.
+  if (/@keyframes\b/i.test(stripped)) {
+    err(loc, `@keyframes is on the deny-list (animations don't translate to PPTX). Remove the animation.`);
+  }
+  if (/@container\b/i.test(stripped)) {
+    err(loc, `@container queries are on the deny-list. Use brand layouts to handle different aspect ratios.`);
+  }
+
+  // 5a. Pseudo-elements may not carry layout-bearing content.
+  //     authoring-contract.md → "::before / ::after used for layout-bearing content".
+  //     Walk every block selector ending in ::before / ::after; flag based
+  //     on the block's content/width/height declarations and the pseudo's
+  //     own position. The browser has no JS API to report the rendered
+  //     bbox of a flex/grid-positioned pseudo, so the PPTX exporter
+  //     cannot place it correctly.
+  const ruleRe = /([^{}]*?)\{([^{}]*)\}/g;
+  let rm;
+  while ((rm = ruleRe.exec(stripped)) !== null) {
+    const selector = rm[1].trim();
+    const block = rm[2];
+    if (!/::(?:before|after)\b/.test(selector)) continue;
+
+    const contentMatch = block.match(/\bcontent\s*:\s*("([^"]*)"|'([^']*)'|none)\s*[;}]?/i);
+    if (!contentMatch) continue; // No content declared → no rendered pseudo, skip.
+    const contentText = contentMatch[2] != null ? contentMatch[2] : contentMatch[3] != null ? contentMatch[3] : "";
+    const hasContent = contentMatch[0] && !/\bnone\b/i.test(contentMatch[0]);
+
+    if (hasContent && contentText.trim().length > 0) {
+      warn(
+        loc,
+        `${selector} declares content: "${contentText}". Pseudo-elements with semantic text content do not export to PPTX — use a real DOM element (e.g. <span aria-hidden="true">${contentText}</span>) instead.`,
+      );
+      continue;
+    }
+
+    // Empty content with a sized box → layout-bearing pseudo (bullet marker,
+    // divider). The browser flex/grid layout places it, but there is no JS
+    // API to read the resolved bbox, so the PPTX exporter collapses it to
+    // the parent's top-left.
+    const hasWidth = /\bwidth\s*:/.test(block) || /\bflex\s*:\s*[^;{}]*\d/.test(block);
+    const hasHeight = /\bheight\s*:/.test(block);
+    const hasPositionAbs = /\bposition\s*:\s*(?:absolute|fixed)\b/.test(block);
+    if ((hasWidth || hasHeight) && !hasPositionAbs) {
+      warn(
+        loc,
+        `${selector} is a sized pseudo-element that participates in flex/grid flow. The PPTX exporter cannot read the flex-resolved position of a pseudo, so the shape will be placed at the parent's top-left and overlap sibling text. Use a real DOM element (e.g. <span className="…__bullet" aria-hidden="true" />) inside the JSX instead, or make the pseudo position: absolute with concrete offsets.`,
+      );
+    }
+  }
+
+  // 2b. Banned properties — scan declarations.
+  const declRe = /(^|[\s;{])([a-zA-Z-]+)\s*:\s*([^;{}]+)(;|$|})/g;
+  let m;
+  while ((m = declRe.exec(stripped)) !== null) {
+    const prop = m[2].toLowerCase();
+    const value = m[3].trim();
+    if (BANNED_CSS_PROPERTIES.includes(prop)) {
+      err(loc, `CSS property "${prop}" is on the deny-list. ${denyListSuggestion(prop)}`);
+      continue;
+    }
+    if (prop === "position" && /\bsticky\b/.test(value)) {
+      err(loc, `position: sticky is on the deny-list. Sticky positioning has no PPTX equivalent.`);
+      continue;
+    }
+    if (prop === "clip-path" && !/^\s*inset\(/i.test(value) && !/^\s*none\s*$/i.test(value)) {
+      err(loc, `clip-path "${value}" is on the deny-list (only inset(...) is supported).`);
+      continue;
+    }
+    checkCssValue(prop, value, loc, err, warn);
+  }
+
+  // 2c. conic-gradient anywhere in any value.
+  if (/conic-gradient\(/i.test(stripped)) {
+    err(loc, `conic-gradient is not supported by the PPTX exporter (use linear-gradient via a brand wash token).`);
+  }
+}
+
+// Properties where a hex/rgb literal is worth flagging as a token-discipline
+// nudge. We deliberately exclude SVG paint properties (fill, stroke, stop-color)
+// — inline SVG content uses raw color values legitimately and isn't part of
+// the surface-color contract.
+const SURFACE_COLOR_PROPS = new Set([
+  "color",
+  "background",
+  "background-color",
+  "border-color",
+  "border-top-color",
+  "border-right-color",
+  "border-bottom-color",
+  "border-left-color",
+  "outline-color",
+]);
+
+function checkCssValue(prop, value, loc, err, warn) {
+  // Layer 0 value checks that depend on the property + value combo.
+  if (prop === "position" && /\bsticky\b/.test(value)) {
+    err(loc, `position: sticky is on the deny-list. Sticky positioning has no PPTX equivalent.`);
+  }
+  if (prop === "clip-path" && !/^\s*inset\(/i.test(value) && !/^\s*none\s*$/i.test(value)) {
+    err(loc, `clip-path "${value}" is on the deny-list (only inset(...) is supported).`);
+  }
+  if (/conic-gradient\(/i.test(value)) {
+    err(loc, `${prop}: conic-gradient is not supported by the PPTX exporter (use linear-gradient via a brand wash token).`);
+  }
+
+  // Token-discipline warnings: only on surface-color properties. Sizes
+  // (font-size, padding, margin, grid tracks, border widths, letter-spacing,
+  // …) are deliberately not enforced — slides need pixel-precise authoring
+  // for grid layouts and micro-typography, and forcing tokens on every
+  // length is more noise than signal.
+  if (!SURFACE_COLOR_PROPS.has(prop)) return;
+
+  // Strip var(--token) expressions before scanning for color literals —
+  // otherwise "blue" inside `var(--sw-tech-blue)` matches the named-colors
+  // regex. Tokens are the right answer; this gives them a free pass.
+  const valueStripped = value.replace(/var\(\s*--[a-z0-9-]+\s*\)/gi, "");
+
+  if (HEX_COLOR_RE.test(valueStripped)) {
+    HEX_COLOR_RE.lastIndex = 0;
+    warn(
+      loc,
+      `${prop}: ${value} contains a hex color literal. Prefer a brand token (var(--sw-*) / var(--fg-*) / var(--bg-*)).`,
+    );
+  } else {
+    HEX_COLOR_RE.lastIndex = 0;
+  }
+  if (RGB_COLOR_RE.test(valueStripped)) {
+    RGB_COLOR_RE.lastIndex = 0;
+    warn(
+      loc,
+      `${prop}: ${value} contains an rgb()/hsl() color literal. Prefer a brand token (var(--sw-*) / var(--fg-*) / var(--bg-*)).`,
+    );
+  } else {
+    RGB_COLOR_RE.lastIndex = 0;
+  }
+  if (NAMED_COLORS_RE.test(valueStripped)) {
+    NAMED_COLORS_RE.lastIndex = 0;
+    warn(
+      loc,
+      `${prop}: ${value} uses a named CSS color. Prefer a brand token (var(--sw-*) / var(--fg-*) / var(--bg-*)).`,
+    );
+  } else {
+    NAMED_COLORS_RE.lastIndex = 0;
+  }
+}
+
+function denyListSuggestion(prop) {
+  switch (prop) {
+    case "filter":
+    case "backdrop-filter":
+      return `Inline an SVG instead of recolouring/blurring with CSS.`;
+    case "mask":
+    case "mask-image":
+      return `mask-image has no OOXML equivalent. Bake the mask into the SVG asset instead.`;
+    case "mix-blend-mode":
+      return `mix-blend-mode has no OOXML equivalent.`;
+    case "animation":
+    case "animation-name":
+    case "animation-duration":
+    case "transition":
+    case "transition-property":
+      return `Slides are static frames — no animation/transition.`;
+    case "content-visibility":
+      return `content-visibility has no PPTX equivalent.`;
+    default:
+      return `Use a registered primitive or a brand token instead.`;
+  }
+}
+
+// Run the linter over a list of slide files. Returns
+// { errors, warnings, ok } where ok = true iff no errors.
+export function lintSlides(slideFiles, opts = {}) {
+  const registrySource = {
+    primitivesPath: opts.primitivesPath,
+    brandPrimitivesPath: opts.brandPrimitivesPath,
+    layoutsDirs: opts.layoutsDirs,
+  };
+  let errors = 0;
+  let warnings = 0;
+  const lines = [];
+  for (const file of slideFiles) {
+    const stem = path.basename(file);
+    const src = fs.readFileSync(file, "utf8");
+    const issues = lintSlideSource(src, stem, registrySource);
+    for (const issue of issues) {
+      if (issue.severity === "error") errors++;
+      else warnings++;
+      lines.push(
+        `  [lint:${issue.severity}] ${stem}:${issue.line} — ${issue.message}`,
+      );
+    }
+  }
+  return { errors, warnings, lines, ok: errors === 0 };
+}
+
+// Convenience: print the lint result to stderr and throw if errors > 0.
+export function lintSlidesOrThrow(slideFiles, opts = {}) {
+  const result = lintSlides(slideFiles, opts);
+  for (const line of result.lines) {
+    process.stderr.write(line + "\n");
+  }
+  if (!result.ok) {
+    throw new Error(
+      `slide lint: ${result.errors} error${result.errors === 1 ? "" : "s"}` +
+        (result.warnings ? `, ${result.warnings} warning${result.warnings === 1 ? "" : "s"}` : "") +
+        ". See [lint:error] lines above.",
+    );
+  }
+  return result;
+}