@caelo-cms/shared 0.10.61 → 0.10.62

package/src/css-scope-scan.ts

@@ -0,0 +1,263 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * issue #158 — module CSS scoping check (epic #149).
+ *
+ * Every module's CSS lands in ONE page-wide stylesheet, so a selector
+ * that is not tied to the module bleeds into every other module on the
+ * page: an `h1 {}` in the hero restyles the pricing table's heading, a
+ * `.card {}` in one module restyles another module's cards. The
+ * convention (edit_module description, design-quality skill) is to nest
+ * module CSS under the module's own root class; this scanner is the
+ * mechanical write-time check that rides the authoring tool's result,
+ * so the AI fixes the selector in the same turn. A warning, not a gate:
+ * the write already succeeded, and a module may legitimately style
+ * something global on purpose.
+ *
+ * Pure string analysis, no CSS parser dependency: comments and strings
+ * are skipped, rule preludes are read at the top level and inside
+ * grouping at-rules (`@media`, `@supports`, `@layer`, `@container`),
+ * and blocks whose contents are not selectors (`@keyframes`,
+ * `@font-face`, …) are skipped whole.
+ */
+
+/** Grouping at-rules whose blocks contain style rules. */
+const GROUPING_AT_RULES = new Set(["media", "supports", "layer", "container", "document"]);
+
+/** Max offending selectors named per finding. */
+const MAX_SELECTORS_SHOWN = 5;
+
+/** Index just past the string literal starting at `i` (a quote char). */
+function skipString(css: string, i: number): number {
+  const quote = css[i];
+  let j = i + 1;
+  while (j < css.length && css[j] !== quote) {
+    if (css[j] === "\\") j++;
+    j++;
+  }
+  return j + 1;
+}
+
+/** Index of the `}` matching the `{` at `open`, or css.length when unbalanced. */
+function matchingBrace(css: string, open: number): number {
+  let depth = 0;
+  for (let i = open; i < css.length; i++) {
+    const c = css[i];
+    if (c === '"' || c === "'") {
+      i = skipString(css, i) - 1;
+    } else if (c === "{") {
+      depth++;
+    } else if (c === "}") {
+      depth--;
+      if (depth === 0) return i;
+    }
+  }
+  return css.length;
+}
+
+/** Selector preludes of every style rule in `css[start, end)`, recursing into grouping at-rules. */
+function collectPreludes(css: string, start: number, end: number, out: string[]): void {
+  let i = start;
+  while (i < end) {
+    // Read one prelude: up to `{` (a block) or `;` (a statement at-rule).
+    let j = i;
+    while (j < end && css[j] !== "{" && css[j] !== ";" && css[j] !== "}") {
+      if (css[j] === '"' || css[j] === "'") j = skipString(css, j);
+      else j++;
+    }
+    const prelude = css.slice(i, j).trim();
+    if (j >= end) return;
+    if (css[j] !== "{") {
+      i = j + 1;
+      continue;
+    }
+    const close = matchingBrace(css, j);
+    if (prelude.startsWith("@")) {
+      const name = /^@([\w-]+)/.exec(prelude)?.[1]?.toLowerCase() ?? "";
+      if (GROUPING_AT_RULES.has(name)) collectPreludes(css, j + 1, close, out);
+    } else if (prelude.length > 0) {
+      out.push(prelude);
+    }
+    i = close + 1;
+  }
+}
+
+/** Split a selector list on top-level commas (not inside `()` / `[]`). */
+function splitSelectorList(prelude: string): string[] {
+  const out: string[] = [];
+  let depth = 0;
+  let from = 0;
+  for (let i = 0; i < prelude.length; i++) {
+    const c = prelude[i];
+    if (c === "(" || c === "[") depth++;
+    else if (c === ")" || c === "]") depth--;
+    else if (c === "," && depth === 0) {
+      out.push(prelude.slice(from, i));
+      from = i + 1;
+    }
+  }
+  out.push(prelude.slice(from));
+  return out.map((s) => s.trim().replace(/\s+/g, " ")).filter((s) => s.length > 0);
+}
+
+/** The selector with every `(…)` argument removed (`:not(.x)` does not scope `h1:not(.x)`). */
+function withoutArguments(selector: string): string {
+  let out = "";
+  let depth = 0;
+  for (const c of selector) {
+    if (c === "(") depth++;
+    else if (c === ")") depth--;
+    else if (depth === 0) out += c;
+  }
+  return out;
+}
+
+/**
+ * Index of the first character after leading whitespace and `<!-- -->`
+ * comments, or -1 when a comment is never closed. A scan, not a regex:
+ * `(?:<!--[\s\S]*?-->\s*)*` backtracks exponentially on `<!----><!--…`
+ * input (CodeQL js/redos), and module html is operator/AI supplied.
+ */
+function skipLeadingHtmlComments(html: string): number {
+  let i = 0;
+  for (;;) {
+    while (i < html.length && /\s/.test(html.charAt(i))) i++;
+    if (!html.startsWith("<!--", i)) return i;
+    const end = html.indexOf("-->", i + 4);
+    if (end === -1) return -1;
+    i = end + 3;
+  }
+}
+
+/**
+ * The attribute text of the start tag at `at` (`""` for `<div>`), or null
+ * when no element starts there. Parsed by hand: the regex form
+ * `<name(\s[^>]*)?>` is quadratic on `<A\t<A\t…` input without a `>`
+ * (CodeQL js/polynomial-redos).
+ */
+function openTagAttributes(html: string, at: number): string | null {
+  if (html.charAt(at) !== "<" || !/[a-zA-Z]/.test(html.charAt(at + 1))) return null;
+  let nameEnd = at + 2;
+  while (nameEnd < html.length && /[\w-]/.test(html.charAt(nameEnd))) nameEnd++;
+  const close = html.indexOf(">", nameEnd);
+  if (close === -1) return null;
+  const attrs = html.slice(nameEnd, close);
+  return attrs === "" || /^\s/.test(attrs) ? attrs : null;
+}
+
+/** Class and id tokens of the module's first element, or null when the html has no element. */
+export function moduleRootTokens(html: string): { classes: string[]; id: string | null } | null {
+  const start = skipLeadingHtmlComments(html);
+  if (start === -1) return null;
+  const attrs = openTagAttributes(html, start);
+  if (attrs === null) return null;
+  const classAttr = /\sclass\s*=\s*(?:"([^"]*)"|'([^']*)')/.exec(attrs);
+  const classes = (classAttr?.[1] ?? classAttr?.[2] ?? "")
+    .split(/\s+/)
+    .filter((c) => c.length > 0 && !c.includes("{{"));
+  const idAttr = /\sid\s*=\s*(?:"([^"]*)"|'([^']*)')/.exec(attrs);
+  const id = idAttr?.[1] ?? idAttr?.[2] ?? null;
+  return { classes, id: id !== null && !id.includes("{{") ? id : null };
+}
+
+/**
+ * The CSS without its comments. An unterminated `/*` runs to the end of
+ * the input, as in the CSS syntax spec. A scan rather than a lazy regex,
+ * which is quadratic on `/*a/*a/*…` input (CodeQL js/polynomial-redos).
+ */
+function stripCssComments(css: string): string {
+  let out = "";
+  let from = 0;
+  for (;;) {
+    const open = css.indexOf("/*", from);
+    if (open === -1) return out + css.slice(from);
+    out += css.slice(from, open);
+    const close = css.indexOf("*/", open + 2);
+    if (close === -1) return out;
+    from = close + 2;
+  }
+}
+
+/** What the scope check found in one module's CSS. */
+export interface CssScopeFindings {
+  /** Selectors with no class, id or attribute at all (`h1`, `body p`, `*`). */
+  readonly global: string[];
+  /** Selectors that are not tied to the module's root class (needs the html). */
+  readonly unanchored: string[];
+  /** The module's root classes the CSS was checked against. */
+  readonly rootClasses: string[];
+  /** The module has CSS but its root element carries no class to scope under. */
+  readonly rootHasNoClass: boolean;
+}
+
+/**
+ * Check a module's CSS for selectors that bleed into other modules.
+ * Pass the module's `html` when the write carried it: the selectors are
+ * then also checked against the root element's classes. Prefixed class
+ * names count as scoped (`.hero__title`, `.hero-cta` under root `.hero`).
+ */
+export function scanModuleCssScope(input: { css: string; html?: string }): CssScopeFindings {
+  const css = stripCssComments(input.css);
+  const preludes: string[] = [];
+  collectPreludes(css, 0, css.length, preludes);
+  const selectors = preludes.flatMap(splitSelectorList);
+
+  const root = input.html !== undefined ? moduleRootTokens(input.html) : null;
+  const rootClasses = root?.classes ?? [];
+  const anchorable = rootClasses.length > 0 || (root?.id ?? null) !== null;
+
+  const global: string[] = [];
+  const unanchored: string[] = [];
+  for (const selector of selectors) {
+    const bare = withoutArguments(selector);
+    if (!/[.#[]/.test(bare)) {
+      global.push(selector);
+      continue;
+    }
+    if (!anchorable) continue;
+    const classes = [...bare.matchAll(/\.(-?[_a-zA-Z][\w-]*)/g)].map((m) => m[1] ?? "");
+    const anchored =
+      classes.some((c) =>
+        rootClasses.some((r) => c === r || c.startsWith(`${r}-`) || c.startsWith(`${r}_`)),
+      ) ||
+      (root?.id != null && bare.includes(`#${root.id}`));
+    if (!anchored) unanchored.push(selector);
+  }
+  return {
+    global,
+    unanchored,
+    rootClasses,
+    rootHasNoClass: root !== null && !anchorable && selectors.length > 0,
+  };
+}
+
+function listSelectors(selectors: readonly string[]): string {
+  const shown = selectors.slice(0, MAX_SELECTORS_SHOWN).map((s) => `\`${s}\``);
+  const more = selectors.length - shown.length;
+  return more > 0 ? `${shown.join(", ")} (+${more} more)` : shown.join(", ");
+}
+
+/** The findings as one tool-result sentence group, or null when the CSS is scoped. */
+export function formatCssScopeFindings(f: CssScopeFindings): string | null {
+  const scopeHint =
+    f.rootClasses.length > 0
+      ? `nest them under the module root \`.${f.rootClasses[0]}\` (e.g. \`.${f.rootClasses[0]} h2\`)`
+      : "nest them under the module's root class";
+  const parts: string[] = [];
+  if (f.global.length > 0) {
+    parts.push(
+      `module CSS selectors ${listSelectors(f.global)} style EVERY matching element on the page, including other modules' — ${scopeHint}`,
+    );
+  }
+  if (f.unanchored.length > 0) {
+    parts.push(
+      `module CSS selectors ${listSelectors(f.unanchored)} are not scoped to this module and can restyle other modules using the same class — ${scopeHint} or prefix the class with it`,
+    );
+  }
+  if (f.rootHasNoClass) {
+    parts.push(
+      'the module\'s root element has no class to scope its CSS under — give it one (e.g. `<section class="pricing">`) and nest the module CSS under it',
+    );
+  }
+  return parts.length > 0 ? parts.join(". ") : null;
+}

package/src/index.ts

@@ -13,6 +13,7 @@ export * from "./cloud-shell-install.js";
 export * from "./content.js";
 export * from "./context.js";
 export * from "./css-gradient-scan.js";
+export * from "./css-scope-scan.js";
 export * from "./css-var-scan.js";
 export * from "./database-url.js";
 export * from "./design-draft-shell.js";
@@ -68,6 +69,7 @@ export * from "./skills.js";
 export * from "./snapshots.js";
 export * from "./staging-gate.js";
 export * from "./static-cache-policy.js";
+export * from "./static-security-headers.js";
 export * from "./strip-cdata.js";
 export * from "./structured-sets.js";
 export * from "./subagents.js";

package/src/interactions.test.ts

@@ -0,0 +1,61 @@
+// SPDX-License-Identifier: MPL-2.0
+
+import { describe, expect, it } from "bun:test";
+import {
+  findInteractionIds,
+  INTERACTION_MARKUP_CONTRACT,
+  INTERACTIONS,
+  interactionAssets,
+} from "./interactions.js";
+
+describe("findInteractionIds (issue #160)", () => {
+  it("finds kit ids in either quote style and reports unknown ones", () => {
+    const html =
+      "<div data-caelo-ui=\"tabs\"></div><section data-caelo-ui='carousel'></section>" +
+      '<div data-caelo-ui="tabs"></div><div data-caelo-ui="lightbox"></div>';
+    expect(findInteractionIds(html)).toEqual({
+      known: ["tabs", "carousel"],
+      unknown: ["lightbox"],
+    });
+  });
+
+  it("ignores the attribute text when it appears as escaped page content", () => {
+    expect(findInteractionIds("<p>use data-caelo-ui=&quot;tabs&quot;</p>").known).toEqual([]);
+  });
+
+  it("does not treat inherited object keys as kit ids", () => {
+    expect(findInteractionIds('<div data-caelo-ui="toString"></div>')).toEqual({
+      known: [],
+      unknown: ["toString"],
+    });
+  });
+});
+
+describe("interactionAssets (issue #160)", () => {
+  it("emits in registry order regardless of the order asked", () => {
+    const out = interactionAssets(new Set(["carousel", "accordion"] as const));
+    expect(out.js).toEqual([INTERACTIONS.accordion.js, INTERACTIONS.carousel.js]);
+    expect(out.css).toEqual([INTERACTIONS.accordion.css, INTERACTIONS.carousel.css]);
+  });
+});
+
+describe("the kit", () => {
+  it("documents every snippet's markup contract for the AI", () => {
+    for (const id of Object.keys(INTERACTIONS)) {
+      expect(INTERACTION_MARKUP_CONTRACT).toContain(`\`${id}\``);
+    }
+  });
+
+  it("carries no aesthetics: no color literals in any snippet's CSS", () => {
+    for (const { css } of Object.values(INTERACTIONS)) {
+      expect(css).not.toMatch(/#[0-9a-f]{3,8}\b|rgba?\(|hsla?\(|oklch\(/i);
+    }
+  });
+
+  it("binds by delegation so modules inserted after load still work", () => {
+    for (const { js } of Object.values(INTERACTIONS)) {
+      expect(js).toContain("document.addEventListener(");
+      expect(js).not.toContain("querySelectorAll('.caelo-nav-menu')");
+    }
+  });
+});

package/src/interactions.ts

@@ -5,19 +5,35 @@
  *
  * A header without a working mobile menu reads as broken, not minimal
  * — and hand-rolled per-module JS gets focus/aria handling wrong more
- * often than right. This module carries the FUNCTIONAL (non-aesthetic)
- * CSS + JS for the built-in nav renderer: hamburger toggle under the
- * mobile breakpoint, `aria-expanded` bookkeeping, escape-to-close.
- * All colors/spacing stay the module/theme's business — these rules
- * only govern show/hide behaviour, so they don't violate the
- * no-global-look re-scope (#151).
+ * often than right. This module carries a small kit of dependency-free
+ * interactions (mobile nav, accordion, tabs, carousel) the AI composes
+ * from by MARKUP alone: an element carrying `data-caelo-ui="<id>"` pulls
+ * that interaction's CSS + JS into the page. No module column, no
+ * declaration step — the attribute in the HTML is the declaration, so
+ * the AI cannot forget half of it.
  *
- * The composer includes each asset ONCE per page when at least one
- * nav-menu module rendered (natural dedup, same rule as #158).
+ * Every snippet is FUNCTIONAL only: show/hide, scroll-snap, focus and
+ * aria bookkeeping. Colors, spacing and typography stay the module /
+ * theme's business (`currentColor`, `inherit`), so the kit does not
+ * reintroduce a global look (#151 re-scope).
+ *
+ * Every snippet's JS uses event delegation on `document` instead of
+ * binding to elements at load: a module withheld behind a consent gate
+ * (`wrapDeferredModule`) enters the DOM only after its plugin clones it
+ * out of its `<template>`, long after page load, and must still work.
+ *
+ * The composer includes each used snippet ONCE per page, in registry
+ * order (natural dedup, same rule as #158).
  */
 
-/** Functional-only rules: collapse/expand mechanics, zero aesthetics. */
-export const NAV_FUNCTIONAL_CSS =
+/** One vetted interaction: its functional CSS and its behaviour JS. */
+export interface InteractionSnippet {
+  readonly css: string;
+  readonly js: string;
+}
+
+/** Functional-only rules for the built-in nav renderer: collapse/expand, zero aesthetics. */
+const MOBILE_NAV_CSS =
   ".caelo-nav-menu .caelo-nav-toggle{display:none;background:none;border:0;cursor:pointer;padding:0.5rem;color:inherit;font:inherit}" +
   ".caelo-nav-menu .caelo-nav-toggle .caelo-nav-bar{display:block;width:1.25em;height:2px;background:currentColor;margin:0.25em 0}" +
   "@media (max-width: 720px){" +
@@ -26,23 +42,162 @@ export const NAV_FUNCTIONAL_CSS =
   '.caelo-nav-menu[data-nav-open="true"] > ul{display:block}' +
   "}";
 
+/** Toggle on click; Escape closes and returns focus to the toggle. */
+const MOBILE_NAV_JS =
+  "(function(){" +
+  "var S='[data-caelo-ui=\"mobile-nav\"]';" +
+  "function set(nav,open){nav.setAttribute('data-nav-open',String(open));" +
+  "var b=nav.querySelector('.caelo-nav-toggle');if(b)b.setAttribute('aria-expanded',String(open));return b;}" +
+  "document.addEventListener('click',function(e){" +
+  "var t=e.target;if(!(t instanceof Element))return;" +
+  "var b=t.closest('.caelo-nav-toggle');if(!b)return;var nav=b.closest(S);if(!nav)return;" +
+  "set(nav,nav.getAttribute('data-nav-open')!=='true');});" +
+  "document.addEventListener('keydown',function(e){" +
+  "if(e.key!=='Escape')return;var t=e.target;if(!(t instanceof Element))return;" +
+  "var nav=t.closest(S+'[data-nav-open=\"true\"]');if(!nav)return;" +
+  "var b=set(nav,false);if(b)b.focus();});" +
+  "})();";
+
 /**
- * Toggle behaviour. Runs deferred; idempotent per element via the
- * data attribute; closes on Escape and returns focus to the toggle.
+ * Accordion = native `<details>`/`<summary>` (keyboard + screen-reader
+ * support for free). The snippet adds what the platform lacks: a
+ * container with `data-single` keeps one panel open, and a URL hash
+ * pointing into a panel opens it (deep links to an FAQ answer).
  */
-export const NAV_TOGGLE_JS =
+const ACCORDION_CSS = ':where([data-caelo-ui="accordion"] summary){cursor:pointer}';
+
+const ACCORDION_JS =
   "(function(){" +
-  "document.querySelectorAll('.caelo-nav-menu').forEach(function(nav){" +
-  "var btn=nav.querySelector('.caelo-nav-toggle');if(!btn)return;" +
-  "btn.addEventListener('click',function(){" +
-  "var open=nav.getAttribute('data-nav-open')==='true';" +
-  "nav.setAttribute('data-nav-open',String(!open));" +
-  "btn.setAttribute('aria-expanded',String(!open));" +
-  "});" +
-  "nav.addEventListener('keydown',function(e){" +
-  "if(e.key==='Escape'&&nav.getAttribute('data-nav-open')==='true'){" +
-  "nav.setAttribute('data-nav-open','false');" +
-  "btn.setAttribute('aria-expanded','false');btn.focus();" +
-  "}});" +
-  "});" +
+  "var S='[data-caelo-ui=\"accordion\"]';" +
+  "document.addEventListener('toggle',function(e){" +
+  "var d=e.target;if(!(d instanceof HTMLDetailsElement)||!d.open)return;" +
+  "var acc=d.closest(S);if(!acc||!acc.hasAttribute('data-single'))return;" +
+  "acc.querySelectorAll('details[open]').forEach(function(o){if(o!==d&&o.closest(S)===acc)o.open=false;});" +
+  "},true);" +
+  "function openHash(){var id;try{id=decodeURIComponent(location.hash.slice(1));}catch(_){return;}if(!id)return;" +
+  "var el=document.getElementById(id);if(!el)return;var d=el.closest(S+' details');" +
+  "if(d&&!d.open){d.open=true;el.scrollIntoView();}}" +
+  "window.addEventListener('hashchange',openHash);" +
+  "if(document.readyState==='loading')document.addEventListener('DOMContentLoaded',openHash);else openHash();" +
   "})();";
+
+/**
+ * Tabs per the WAI-ARIA tabs pattern: `role="tablist"` of
+ * `role="tab"` buttons, each `aria-controls` its `role="tabpanel"`.
+ * Click or arrow keys / Home / End select (automatic activation) with a
+ * roving tabindex. The CSS keeps `hidden` panels hidden even when module
+ * CSS gives panels a `display`.
+ */
+const TABS_CSS = '[data-caelo-ui="tabs"] [role="tabpanel"][hidden]{display:none}';
+
+const TABS_JS =
+  "(function(){" +
+  "function tabsOf(list){return Array.prototype.filter.call(list.querySelectorAll('[role=\"tab\"]'),function(t){return t.closest('[role=\"tablist\"]')===list;});}" +
+  "function select(tab,focus){var list=tab.closest('[role=\"tablist\"]');if(!list)return;" +
+  "tabsOf(list).forEach(function(t){var on=t===tab;" +
+  "t.setAttribute('aria-selected',String(on));t.setAttribute('tabindex',on?'0':'-1');" +
+  "var p=document.getElementById(t.getAttribute('aria-controls')||'');if(p){if(on)p.removeAttribute('hidden');else p.setAttribute('hidden','');}});" +
+  "if(focus)tab.focus();}" +
+  "function tabAt(e){var t=e.target;if(!(t instanceof Element))return null;" +
+  "var tab=t.closest('[role=\"tab\"]');return tab&&tab.closest('[data-caelo-ui=\"tabs\"]')?tab:null;}" +
+  "document.addEventListener('click',function(e){var tab=tabAt(e);if(tab)select(tab,false);});" +
+  "document.addEventListener('keydown',function(e){var tab=tabAt(e);if(!tab)return;" +
+  "var list=tab.closest('[role=\"tablist\"]');if(!list)return;var all=tabsOf(list);var i=all.indexOf(tab);var n=-1;" +
+  "if(e.key==='ArrowRight'||e.key==='ArrowDown')n=(i+1)%all.length;" +
+  "else if(e.key==='ArrowLeft'||e.key==='ArrowUp')n=(i-1+all.length)%all.length;" +
+  "else if(e.key==='Home')n=0;else if(e.key==='End')n=all.length-1;" +
+  "if(n<0)return;e.preventDefault();select(all[n],true);});" +
+  "})();";
+
+/**
+ * Carousel = a CSS scroll-snap track (swipe, trackpad and keyboard
+ * scrolling work without JS); the snippet only wires the optional
+ * previous / next buttons, honouring `prefers-reduced-motion`. The
+ * layout defaults sit in `:where()` (zero specificity): the snippet CSS
+ * is emitted after module CSS, and a module must still be able to set
+ * its own slide width or track display.
+ */
+const CAROUSEL_CSS =
+  ':where([data-caelo-ui="carousel"] [data-caelo-carousel-track]){display:flex;overflow-x:auto;scroll-snap-type:x mandatory;scroll-behavior:smooth}' +
+  ':where([data-caelo-ui="carousel"] [data-caelo-carousel-track]>*){flex:0 0 100%;scroll-snap-align:start}' +
+  '@media (prefers-reduced-motion: reduce){[data-caelo-ui="carousel"] [data-caelo-carousel-track]{scroll-behavior:auto}}';
+
+const CAROUSEL_JS =
+  "(function(){" +
+  "document.addEventListener('click',function(e){var t=e.target;if(!(t instanceof Element))return;" +
+  "var b=t.closest('[data-caelo-carousel-prev],[data-caelo-carousel-next]');if(!b)return;" +
+  "var c=b.closest('[data-caelo-ui=\"carousel\"]');if(!c)return;" +
+  "var track=c.querySelector('[data-caelo-carousel-track]');if(!track)return;" +
+  "var dir=b.hasAttribute('data-caelo-carousel-next')?1:-1;" +
+  "var reduce=window.matchMedia('(prefers-reduced-motion: reduce)').matches;" +
+  "track.scrollBy({left:dir*track.clientWidth,behavior:reduce?'auto':'smooth'});});" +
+  "})();";
+
+/**
+ * The vetted kit, in emission order. Keys are the values of
+ * `data-caelo-ui`. Adding a snippet: add it here, document its markup
+ * contract in `INTERACTION_MARKUP_CONTRACT`, and add a composer test.
+ */
+export const INTERACTIONS = {
+  "mobile-nav": { css: MOBILE_NAV_CSS, js: MOBILE_NAV_JS },
+  accordion: { css: ACCORDION_CSS, js: ACCORDION_JS },
+  tabs: { css: TABS_CSS, js: TABS_JS },
+  carousel: { css: CAROUSEL_CSS, js: CAROUSEL_JS },
+} as const satisfies Record<string, InteractionSnippet>;
+
+/** A `data-caelo-ui` value the kit implements. */
+export type InteractionId = keyof typeof INTERACTIONS;
+
+const INTERACTION_IDS = Object.keys(INTERACTIONS) as InteractionId[];
+
+function isInteractionId(id: string): id is InteractionId {
+  return Object.hasOwn(INTERACTIONS, id);
+}
+
+// Matches the attribute only inside a tag: text content carrying the
+// same characters is entity-escaped (`&quot;`) by the template engine,
+// so it cannot produce a match.
+const UI_ATTR_RE = /\sdata-caelo-ui\s*=\s*(?:"([^"]*)"|'([^']*)')/g;
+
+/** Every `data-caelo-ui` value in `html`, split into kit ids and unknown ones. */
+export function findInteractionIds(html: string): {
+  known: InteractionId[];
+  unknown: string[];
+} {
+  const known = new Set<InteractionId>();
+  const unknown = new Set<string>();
+  for (const m of html.matchAll(UI_ATTR_RE)) {
+    const id = (m[1] ?? m[2] ?? "").trim();
+    if (isInteractionId(id)) known.add(id);
+    else unknown.add(id);
+  }
+  return { known: [...known], unknown: [...unknown] };
+}
+
+/**
+ * The CSS and JS for the used interactions, each once, in registry order
+ * (stable output regardless of which module asked first).
+ */
+export function interactionAssets(used: ReadonlySet<InteractionId>): {
+  css: string[];
+  js: string[];
+} {
+  const ids = INTERACTION_IDS.filter((id) => used.has(id));
+  return {
+    css: ids.map((id) => INTERACTIONS[id].css),
+    js: ids.map((id) => INTERACTIONS[id].js),
+  };
+}
+
+/**
+ * The markup contract for each kit interaction, as the AI reads it in
+ * tool descriptions and the design-quality skill. One source so the
+ * guidance cannot drift from the snippets above.
+ */
+export const INTERACTION_MARKUP_CONTRACT =
+  '**Vetted interactions - use these instead of writing JS for them.** Add `data-caelo-ui="<id>"` to the markup and Caelo ships accessible, dependency-free behaviour once per page; style it freely in the module CSS. ' +
+  '`accordion` (FAQ, collapsible sections): `<div data-caelo-ui="accordion" data-single>` containing `<details id="..."><summary>Question</summary><div>Answer</div></details>` items - `data-single` keeps one open; a link to `#<details id>` opens it. ' +
+  '`tabs`: `<div data-caelo-ui="tabs"><div role="tablist" aria-label="..."><button type="button" role="tab" id="t1" aria-controls="p1" aria-selected="true">...</button><button type="button" role="tab" id="t2" aria-controls="p2" aria-selected="false" tabindex="-1">...</button></div><div role="tabpanel" id="p1" aria-labelledby="t1">...</div><div role="tabpanel" id="p2" aria-labelledby="t2" hidden>...</div></div>` - ids must be unique on the page. ' +
+  '`carousel` (slider, testimonials): `<section data-caelo-ui="carousel" aria-roledescription="carousel" aria-label="..."><div data-caelo-carousel-track tabindex="0"><div role="group" aria-roledescription="slide" aria-label="1 of 3">...</div>...</div><button type="button" data-caelo-carousel-prev aria-label="Previous slide"><span aria-hidden="true">&lsaquo;</span></button><button type="button" data-caelo-carousel-next aria-label="Next slide"><span aria-hidden="true">&rsaquo;</span></button></section>` (an icon button keeps its visible content aria-hidden; a text button needs no aria-label) - one slide per view by default; set the slides\' `flex-basis` in module CSS to show more. ' +
+  "`mobile-nav` is applied by the built-in nav-menu renderer; never add it by hand. " +
+  "Write module JS only for behaviour the kit does not cover.";