waybetter 0.1.1 → 0.7.0

package/dist/runtime/themeDoctor.js

@@ -0,0 +1,112 @@
+// The theme doctor: advice, never a block. A theme may do anything its trust level allows; the doctor
+// points at the lighter mechanism for what the theme does (a token before a component setting, a
+// component setting before CSS, CSS before a script) and at performance, accessibility and contrast
+// costs. Used by the import screen, the Theme Builder's full report and `waybetter store check`.
+// Pure. Every finding says where it is (a token path or the CSS rule), what was found and how to fix
+// it; the words are catalog keys (`wb.doctor.<id>.found` / `.fix`, English below), so a panel shows
+// them in the owner's language and the CLI prints the English.
+import { contrastRatio } from "./themeApi.js";
+import { ensureContrast } from "./themeSpec.js";
+/** The doctor's words in English (the source of `wb.doctor.*` in the catalogs). */
+export const DOCTOR_MESSAGES = {
+    'wb.doctor.css-radius.found': 'This rule sets corner radii in CSS.',
+    'wb.doctor.css-radius.fix': 'Set them with the radius of a part under components, or shape.radius for all of them: no CSS needed, and it keeps working when the site renames its classes.',
+    'wb.doctor.css-bevel.found': 'This rule draws a bevelled edge with stacked inset shadows.',
+    'wb.doctor.css-bevel.fix': 'Use borderStyle "bevel-out" or "bevel-in" on a part under components: it draws the bevel from the theme’s colors.',
+    'wb.doctor.css-hide.found': 'This rule hides something with display: none.',
+    'wb.doctor.css-hide.fix': 'Use visible on a part under components (avatars, counts, names) or a layout variant such as sidebar: hidden; the owner can then switch it back.',
+    'wb.doctor.css-color.found': 'This rule uses a literal color.',
+    'wb.doctor.css-color.fix': 'Name a role (text, muted, accent, surface…) in colors or in a component, so the contrast pass covers it.',
+    'wb.doctor.css-font.found': 'This rule sets a font family.',
+    'wb.doctor.css-font.fix': 'Use font.roles: it sets the post, heading, numbers and mono faces without CSS.',
+    'wb.doctor.css-has.found': 'This rule uses :has(), which is matched again on every change of the page.',
+    'wb.doctor.css-has.fix': 'Keep :has() off rules that repeat down a timeline, or anchor the rule on a part.',
+    'wb.doctor.css-universal.found': 'This rule uses a universal selector (*), matched against every element.',
+    'wb.doctor.css-universal.fix': 'Anchor the rule on a part instead.',
+    'wb.doctor.css-blur.found': 'This rule blurs what is behind it (backdrop-filter), which is costly on parts that repeat.',
+    'wb.doctor.css-blur.fix': 'Use the glass fill of bars and panels: it is the cheaper place for blur.',
+    'wb.doctor.css-outline-none.found': 'This rule removes the focus outline, so keyboard focus is no longer visible.',
+    'wb.doctor.css-outline-none.fix': 'Use decor.focusRing to draw a visible focus ring instead.',
+    'wb.doctor.css-motion.found': 'This rule animates without checking for reduced motion.',
+    'wb.doctor.css-motion.fix': 'Keep motion inside @media (prefers-reduced-motion: no-preference), or let decor.motion do it for you.',
+    'wb.doctor.css-size.found': 'The CSS is more than 20,000 characters long.',
+    'wb.doctor.css-size.fix': 'The site recalculates styles with every rule; tokens and component settings compile to fewer rules.',
+    'wb.doctor.contrast.found': 'The {token} color was adjusted to stay readable ({ratio}:1 on the background).',
+    'wb.doctor.contrast.fix': 'Pick a lighter or darker {token} color; until then the theme is shown with the adjusted one.',
+    'wb.doctor.glass-post.found': 'Glass is set on posts, but it is not drawn: blur on every post of a timeline is too costly.',
+    'wb.doctor.glass-post.fix': 'Use a solid or tinted fill for posts and keep glass for bars and panels.',
+    'wb.doctor.small-post-text.found': 'Post text is {size}px, which is hard to read for many people.',
+    'wb.doctor.small-post-text.fix': 'Use 14px or more for the post text size, or raise the text size of the whole theme.',
+    'wb.doctor.nav-moved.found': 'The navigation is moved to the {position}, which changes where people look for it.',
+    'wb.doctor.nav-moved.fix': 'It only applies on wide panes, and the owner can turn layout changes off. Keep the default position unless the layout needs it.',
+};
+const fill = (text, params) => text.replace(/\{(\w+)\}/g, (_, name) => params[name] ?? '');
+/** What a theme's free-form CSS does that a v2 group does without CSS. */
+const CSS_RULES = [
+    { id: 'css-radius', kind: 'lighter', test: /border-radius\s*:/gi, property: 'border-radius' },
+    { id: 'css-bevel', kind: 'lighter', test: /box-shadow\s*:[^;{}]*inset[^;{}]*inset[^;{}]*inset/gi, property: 'box-shadow' },
+    { id: 'css-hide', kind: 'lighter', test: /display\s*:\s*none/gi, property: 'display' },
+    { id: 'css-color', kind: 'lighter', test: /(?:^|[;{\s])(?:color|background(?:-color)?)\s*:\s*#[0-9a-f]{3,8}/gi, property: 'color' },
+    { id: 'css-font', kind: 'lighter', test: /font-family\s*:/gi, property: 'font-family' },
+    { id: 'css-has', kind: 'performance', test: /:has\(/gi, property: ':has()' },
+    { id: 'css-universal', kind: 'performance', test: /(?:^|[\s,>+~])\*\s*(?:[,{>+~:[]|$)/gm, property: '*' },
+    { id: 'css-blur', kind: 'performance', test: /backdrop-filter\s*:/gi, property: 'backdrop-filter' },
+    { id: 'css-outline-none', kind: 'accessibility', test: /outline\s*:\s*(?:none|0)\b/gi, property: 'outline' },
+    { id: 'css-motion', kind: 'accessibility', test: /(?:animation|transition)\s*:/gi, property: 'transition' },
+];
+const MAX_PER_RULE = 25;
+/** The selector of the rule block a position of `css` is in (the text before its `{`), shortened. */
+function selectorAt(css, index) {
+    const open = css.lastIndexOf('{', index);
+    if (open < 0)
+        return '';
+    const close = Math.max(css.lastIndexOf('}', open - 1), css.lastIndexOf(';', open - 1), css.lastIndexOf('{', open - 1));
+    const selector = css.slice(close + 1, open).replace(/\s+/g, ' ').trim();
+    return selector.length > 80 ? `${selector.slice(0, 79)}…` : selector;
+}
+function advice(id, kind, where, params = {}, key = id) {
+    const words = DOCTOR_MESSAGES;
+    return { kind, id, key, where, params, text: fill(words[`wb.doctor.${key}.found`], params), fix: fill(words[`wb.doctor.${key}.fix`], params) };
+}
+/** Advice for a theme document: every finding, with where it is. Empty when there is nothing to say. */
+export function themeDoctor(theme) {
+    const out = [];
+    const css = theme.css ?? '';
+    if (css.trim()) {
+        for (const rule of CSS_RULES) {
+            const seen = new Set();
+            for (const match of css.matchAll(rule.test)) {
+                const selector = selectorAt(css, match.index ?? 0) || 'css';
+                const where = rule.id === 'css-universal' || rule.id === 'css-has' ? selector : `${selector} { ${rule.property} }`;
+                if (seen.has(where))
+                    continue;
+                seen.add(where);
+                out.push(advice(rule.id, rule.kind, where));
+                if (seen.size >= MAX_PER_RULE)
+                    break;
+            }
+        }
+        if (css.length > 20_000)
+            out.push(advice('css-size', 'performance', 'css'));
+    }
+    if (theme.colors) {
+        const fixed = ensureContrast(theme.colors);
+        for (const role of ['text', 'muted', 'accent']) {
+            if (fixed[role] !== theme.colors[role]) {
+                out.push(advice(`contrast-${role}`, 'contrast', `colors.${role}`, { token: role, ratio: contrastRatio(theme.colors[role], theme.colors.bg).toFixed(2) }, 'contrast'));
+            }
+        }
+    }
+    if (theme.components) {
+        if (theme.components.post?.fill === 'glass')
+            out.push(advice('glass-post', 'performance', 'components.post.fill'));
+        const size = theme.components.postText?.fontSize;
+        if (size !== undefined && size < 14)
+            out.push(advice('small-post-text', 'accessibility', 'components.postText.fontSize', { size: String(size) }));
+    }
+    if (theme.variants?.nav === 'top' || theme.variants?.nav === 'bottom') {
+        out.push(advice('nav-moved', 'accessibility', 'variants.nav', { position: theme.variants.nav }));
+    }
+    return out;
+}
+//# sourceMappingURL=themeDoctor.js.map

package/dist/runtime/themeDoctor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"themeDoctor.js","sourceRoot":"","sources":["../../../runtime/src/themeDoctor.ts"],"names":[],"mappings":"AAAA,sGAAsG;AACtG,iGAAiG;AACjG,oGAAoG;AACpG,iGAAiG;AACjG,qGAAqG;AACrG,oGAAoG;AACpG,+DAA+D;AAE/D,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,EAAE,cAAc,EAAkB,MAAM,gBAAgB,CAAC;AAmBhE,mFAAmF;AACnF,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,4BAA4B,EAAE,qCAAqC;IACnE,0BAA0B,EAAE,8JAA8J;IAC1L,2BAA2B,EAAE,6DAA6D;IAC1F,yBAAyB,EAAE,mHAAmH;IAC9I,0BAA0B,EAAE,+CAA+C;IAC3E,wBAAwB,EAAE,iJAAiJ;IAC3K,2BAA2B,EAAE,iCAAiC;IAC9D,yBAAyB,EAAE,0GAA0G;IACrI,0BAA0B,EAAE,+BAA+B;IAC3D,wBAAwB,EAAE,gFAAgF;IAC1G,yBAAyB,EAAE,4EAA4E;IACvG,uBAAuB,EAAE,kFAAkF;IAC3G,+BAA+B,EAAE,yEAAyE;IAC1G,6BAA6B,EAAE,oCAAoC;IACnE,0BAA0B,EAAE,4FAA4F;IACxH,wBAAwB,EAAE,0EAA0E;IACpG,kCAAkC,EAAE,8EAA8E;IAClH,gCAAgC,EAAE,2DAA2D;IAC7F,4BAA4B,EAAE,yDAAyD;IACvF,0BAA0B,EAAE,uGAAuG;IACnI,0BAA0B,EAAE,8CAA8C;IAC1E,wBAAwB,EAAE,qGAAqG;IAC/H,0BAA0B,EAAE,gFAAgF;IAC5G,wBAAwB,EAAE,8FAA8F;IACxH,4BAA4B,EAAE,6FAA6F;IAC3H,0BAA0B,EAAE,0EAA0E;IACtG,iCAAiC,EAAE,+DAA+D;IAClG,+BAA+B,EAAE,qFAAqF;IACtH,2BAA2B,EAAE,oFAAoF;IACjH,yBAAyB,EAAE,iIAAiI;CACpJ,CAAC;AAEX,MAAM,IAAI,GAAG,CAAC,IAAY,EAAE,MAA8B,EAAE,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC,EAAE,IAAY,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;AAGnI,0EAA0E;AAC1E,MAAM,SAAS,GAAW;IACxB,EAAE,EAAE,EAAE,YAAY,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,qBAAqB,EAAE,QAAQ,EAAE,eAAe,EAAE;IAC7F,EAAE,EAAE,EAAE,WAAW,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,sDAAsD,EAAE,QAAQ,EAAE,YAAY,EAAE;IAC1H,EAAE,EAAE,EAAE,UAAU,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,sBAAsB,EAAE,QAAQ,EAAE,SAAS,EAAE;IACtF,EAAE,EAAE,EAAE,WAAW,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,oEAAoE,EAAE,QAAQ,EAAE,OAAO,EAAE;IACnI,EAAE,EAAE,EAAE,UAAU,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,mBAAmB,EAAE,QAAQ,EAAE,aAAa,EAAE;IACvF,EAAE,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE,UAAU,EAAE,QAAQ,EAAE,QAAQ,EAAE;IAC5E,EAAE,EAAE,EAAE,eAAe,EAAE,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE,sCAAsC,EAAE,QAAQ,EAAE,GAAG,EAAE;IACzG,EAAE,EAAE,EAAE,UAAU,EAAE,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE,uBAAuB,EAAE,QAAQ,EAAE,iBAAiB,EAAE;IACnG,EAAE,EAAE,EAAE,kBAAkB,EAAE,IAAI,EAAE,eAAe,EAAE,IAAI,EAAE,8BAA8B,EAAE,QAAQ,EAAE,SAAS,EAAE;IAC5G,EAAE,EAAE,EAAE,YAAY,EAAE,IAAI,EAAE,eAAe,EAAE,IAAI,EAAE,gCAAgC,EAAE,QAAQ,EAAE,YAAY,EAAE;CAC5G,CAAC;AAEF,MAAM,YAAY,GAAG,EAAE,CAAC;AAExB,qGAAqG;AACrG,SAAS,UAAU,CAAC,GAAW,EAAE,KAAa;IAC5C,MAAM,IAAI,GAAG,GAAG,CAAC,WAAW,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IACzC,IAAI,IAAI,GAAG,CAAC;QAAE,OAAO,EAAE,CAAC;IACxB,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,WAAW,CAAC,GAAG,EAAE,IAAI,GAAG,CAAC,CAAC,EAAE,GAAG,CAAC,WAAW,CAAC,GAAG,EAAE,IAAI,GAAG,CAAC,CAAC,EAAE,GAAG,CAAC,WAAW,CAAC,GAAG,EAAE,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC;IACvH,MAAM,QAAQ,GAAG,GAAG,CAAC,KAAK,CAAC,KAAK,GAAG,CAAC,EAAE,IAAI,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;IACxE,OAAO,QAAQ,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC;AACvE,CAAC;AAED,SAAS,MAAM,CAAC,EAAU,EAAE,IAA0B,EAAE,KAAa,EAAE,SAAiC,EAAE,EAAE,GAAG,GAAG,EAAE;IAClH,MAAM,KAAK,GAAG,eAAyC,CAAC;IACxD,OAAO,EAAE,IAAI,EAAE,EAAE,EAAE,GAAG,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,aAAa,GAAG,QAAQ,CAAE,EAAE,MAAM,CAAC,EAAE,GAAG,EAAE,IAAI,CAAC,KAAK,CAAC,aAAa,GAAG,MAAM,CAAE,EAAE,MAAM,CAAC,EAAE,CAAC;AACnJ,CAAC;AAED,wGAAwG;AACxG,MAAM,UAAU,WAAW,CAAC,KAAgB;IAC1C,MAAM,GAAG,GAAmB,EAAE,CAAC;IAC/B,MAAM,GAAG,GAAG,KAAK,CAAC,GAAG,IAAI,EAAE,CAAC;IAC5B,IAAI,GAAG,CAAC,IAAI,EAAE,EAAE,CAAC;QACf,KAAK,MAAM,IAAI,IAAI,SAAS,EAAE,CAAC;YAC7B,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;YAC/B,KAAK,MAAM,KAAK,IAAI,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;gBAC5C,MAAM,QAAQ,GAAG,UAAU,CAAC,GAAG,EAAE,KAAK,CAAC,KAAK,IAAI,CAAC,CAAC,IAAI,KAAK,CAAC;gBAC5D,MAAM,KAAK,GAAG,IAAI,CAAC,EAAE,KAAK,eAAe,IAAI,IAAI,CAAC,EAAE,KAAK,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,GAAG,QAAQ,MAAM,IAAI,CAAC,QAAQ,IAAI,CAAC;gBACnH,IAAI,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC;oBAAE,SAAS;gBAC9B,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;gBAChB,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,EAAE,IAAI,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC;gBAC5C,IAAI,IAAI,CAAC,IAAI,IAAI,YAAY;oBAAE,MAAM;YACvC,CAAC;QACH,CAAC;QACD,IAAI,GAAG,CAAC,MAAM,GAAG,MAAM;YAAE,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,UAAU,EAAE,aAAa,EAAE,KAAK,CAAC,CAAC,CAAC;IAC9E,CAAC;IACD,IAAI,KAAK,CAAC,MAAM,EAAE,CAAC;QACjB,MAAM,KAAK,GAAG,cAAc,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;QAC3C,KAAK,MAAM,IAAI,IAAI,CAAC,MAAM,EAAE,OAAO,EAAE,QAAQ,CAAU,EAAE,CAAC;YACxD,IAAI,KAAK,CAAC,IAAI,CAAC,KAAK,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC;gBACvC,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,YAAY,IAAI,EAAE,EAAE,UAAU,EAAE,UAAU,IAAI,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,aAAa,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,UAAU,CAAC,CAAC,CAAC;YACxK,CAAC;QACH,CAAC;IACH,CAAC;IACD,IAAI,KAAK,CAAC,UAAU,EAAE,CAAC;QACrB,IAAI,KAAK,CAAC,UAAU,CAAC,IAAI,EAAE,IAAI,KAAK,OAAO;YAAE,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,YAAY,EAAE,aAAa,EAAE,sBAAsB,CAAC,CAAC,CAAC;QACnH,MAAM,IAAI,GAAG,KAAK,CAAC,UAAU,CAAC,QAAQ,EAAE,QAAQ,CAAC;QACjD,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,GAAG,EAAE;YAAE,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,iBAAiB,EAAE,eAAe,EAAE,8BAA8B,EAAE,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC;IACpJ,CAAC;IACD,IAAI,KAAK,CAAC,QAAQ,EAAE,GAAG,KAAK,KAAK,IAAI,KAAK,CAAC,QAAQ,EAAE,GAAG,KAAK,QAAQ,EAAE,CAAC;QACtE,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,eAAe,EAAE,cAAc,EAAE,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;IACnG,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC","sourcesContent":["// The theme doctor: advice, never a block. A theme may do anything its trust level allows; the doctor\n// points at the lighter mechanism for what the theme does (a token before a component setting, a\n// component setting before CSS, CSS before a script) and at performance, accessibility and contrast\n// costs. Used by the import screen, the Theme Builder's full report and `waybetter store check`.\n// Pure. Every finding says where it is (a token path or the CSS rule), what was found and how to fix\n// it; the words are catalog keys (`wb.doctor.<id>.found` / `.fix`, English below), so a panel shows\n// them in the owner's language and the CLI prints the English.\n\nimport { contrastRatio } from './themeApi.ts';\nimport { ensureContrast, type ThemeSpec } from './themeSpec.ts';\n\nexport type DoctorAdvice = {\n  /** `lighter`: a lighter mechanism would do; `performance`, `accessibility`, `contrast`: a cost. */\n  kind: 'lighter' | 'performance' | 'accessibility' | 'contrast';\n  /** Stable id of the finding, for tests (`css-radius`, `contrast-text`). */\n  id: string;\n  /** Its words in the catalog: `wb.doctor.<key>.found` and `wb.doctor.<key>.fix` (`css-radius`, `contrast`). */\n  key: string;\n  /** A token path of the theme (`colors.text`, `components.postText.fontSize`) or the CSS rule (`.card { border-radius }`). */\n  where: string;\n  /** Values for the `{name}` slots of the words. */\n  params: Record<string, string>;\n  /** English: what was found. */\n  text: string;\n  /** English: how to fix it. */\n  fix: string;\n};\n\n/** The doctor's words in English (the source of `wb.doctor.*` in the catalogs). */\nexport const DOCTOR_MESSAGES = {\n  'wb.doctor.css-radius.found': 'This rule sets corner radii in CSS.',\n  'wb.doctor.css-radius.fix': 'Set them with the radius of a part under components, or shape.radius for all of them: no CSS needed, and it keeps working when the site renames its classes.',\n  'wb.doctor.css-bevel.found': 'This rule draws a bevelled edge with stacked inset shadows.',\n  'wb.doctor.css-bevel.fix': 'Use borderStyle \"bevel-out\" or \"bevel-in\" on a part under components: it draws the bevel from the theme’s colors.',\n  'wb.doctor.css-hide.found': 'This rule hides something with display: none.',\n  'wb.doctor.css-hide.fix': 'Use visible on a part under components (avatars, counts, names) or a layout variant such as sidebar: hidden; the owner can then switch it back.',\n  'wb.doctor.css-color.found': 'This rule uses a literal color.',\n  'wb.doctor.css-color.fix': 'Name a role (text, muted, accent, surface…) in colors or in a component, so the contrast pass covers it.',\n  'wb.doctor.css-font.found': 'This rule sets a font family.',\n  'wb.doctor.css-font.fix': 'Use font.roles: it sets the post, heading, numbers and mono faces without CSS.',\n  'wb.doctor.css-has.found': 'This rule uses :has(), which is matched again on every change of the page.',\n  'wb.doctor.css-has.fix': 'Keep :has() off rules that repeat down a timeline, or anchor the rule on a part.',\n  'wb.doctor.css-universal.found': 'This rule uses a universal selector (*), matched against every element.',\n  'wb.doctor.css-universal.fix': 'Anchor the rule on a part instead.',\n  'wb.doctor.css-blur.found': 'This rule blurs what is behind it (backdrop-filter), which is costly on parts that repeat.',\n  'wb.doctor.css-blur.fix': 'Use the glass fill of bars and panels: it is the cheaper place for blur.',\n  'wb.doctor.css-outline-none.found': 'This rule removes the focus outline, so keyboard focus is no longer visible.',\n  'wb.doctor.css-outline-none.fix': 'Use decor.focusRing to draw a visible focus ring instead.',\n  'wb.doctor.css-motion.found': 'This rule animates without checking for reduced motion.',\n  'wb.doctor.css-motion.fix': 'Keep motion inside @media (prefers-reduced-motion: no-preference), or let decor.motion do it for you.',\n  'wb.doctor.css-size.found': 'The CSS is more than 20,000 characters long.',\n  'wb.doctor.css-size.fix': 'The site recalculates styles with every rule; tokens and component settings compile to fewer rules.',\n  'wb.doctor.contrast.found': 'The {token} color was adjusted to stay readable ({ratio}:1 on the background).',\n  'wb.doctor.contrast.fix': 'Pick a lighter or darker {token} color; until then the theme is shown with the adjusted one.',\n  'wb.doctor.glass-post.found': 'Glass is set on posts, but it is not drawn: blur on every post of a timeline is too costly.',\n  'wb.doctor.glass-post.fix': 'Use a solid or tinted fill for posts and keep glass for bars and panels.',\n  'wb.doctor.small-post-text.found': 'Post text is {size}px, which is hard to read for many people.',\n  'wb.doctor.small-post-text.fix': 'Use 14px or more for the post text size, or raise the text size of the whole theme.',\n  'wb.doctor.nav-moved.found': 'The navigation is moved to the {position}, which changes where people look for it.',\n  'wb.doctor.nav-moved.fix': 'It only applies on wide panes, and the owner can turn layout changes off. Keep the default position unless the layout needs it.',\n} as const;\n\nconst fill = (text: string, params: Record<string, string>) => text.replace(/\\{(\\w+)\\}/g, (_, name: string) => params[name] ?? '');\n\ntype Rule = { id: string; kind: DoctorAdvice['kind']; test: RegExp; property: string };\n/** What a theme's free-form CSS does that a v2 group does without CSS. */\nconst CSS_RULES: Rule[] = [\n  { id: 'css-radius', kind: 'lighter', test: /border-radius\\s*:/gi, property: 'border-radius' },\n  { id: 'css-bevel', kind: 'lighter', test: /box-shadow\\s*:[^;{}]*inset[^;{}]*inset[^;{}]*inset/gi, property: 'box-shadow' },\n  { id: 'css-hide', kind: 'lighter', test: /display\\s*:\\s*none/gi, property: 'display' },\n  { id: 'css-color', kind: 'lighter', test: /(?:^|[;{\\s])(?:color|background(?:-color)?)\\s*:\\s*#[0-9a-f]{3,8}/gi, property: 'color' },\n  { id: 'css-font', kind: 'lighter', test: /font-family\\s*:/gi, property: 'font-family' },\n  { id: 'css-has', kind: 'performance', test: /:has\\(/gi, property: ':has()' },\n  { id: 'css-universal', kind: 'performance', test: /(?:^|[\\s,>+~])\\*\\s*(?:[,{>+~:[]|$)/gm, property: '*' },\n  { id: 'css-blur', kind: 'performance', test: /backdrop-filter\\s*:/gi, property: 'backdrop-filter' },\n  { id: 'css-outline-none', kind: 'accessibility', test: /outline\\s*:\\s*(?:none|0)\\b/gi, property: 'outline' },\n  { id: 'css-motion', kind: 'accessibility', test: /(?:animation|transition)\\s*:/gi, property: 'transition' },\n];\n\nconst MAX_PER_RULE = 25;\n\n/** The selector of the rule block a position of `css` is in (the text before its `{`), shortened. */\nfunction selectorAt(css: string, index: number): string {\n  const open = css.lastIndexOf('{', index);\n  if (open < 0) return '';\n  const close = Math.max(css.lastIndexOf('}', open - 1), css.lastIndexOf(';', open - 1), css.lastIndexOf('{', open - 1));\n  const selector = css.slice(close + 1, open).replace(/\\s+/g, ' ').trim();\n  return selector.length > 80 ? `${selector.slice(0, 79)}…` : selector;\n}\n\nfunction advice(id: string, kind: DoctorAdvice['kind'], where: string, params: Record<string, string> = {}, key = id): DoctorAdvice {\n  const words = DOCTOR_MESSAGES as Record<string, string>;\n  return { kind, id, key, where, params, text: fill(words[`wb.doctor.${key}.found`]!, params), fix: fill(words[`wb.doctor.${key}.fix`]!, params) };\n}\n\n/** Advice for a theme document: every finding, with where it is. Empty when there is nothing to say. */\nexport function themeDoctor(theme: ThemeSpec): DoctorAdvice[] {\n  const out: DoctorAdvice[] = [];\n  const css = theme.css ?? '';\n  if (css.trim()) {\n    for (const rule of CSS_RULES) {\n      const seen = new Set<string>();\n      for (const match of css.matchAll(rule.test)) {\n        const selector = selectorAt(css, match.index ?? 0) || 'css';\n        const where = rule.id === 'css-universal' || rule.id === 'css-has' ? selector : `${selector} { ${rule.property} }`;\n        if (seen.has(where)) continue;\n        seen.add(where);\n        out.push(advice(rule.id, rule.kind, where));\n        if (seen.size >= MAX_PER_RULE) break;\n      }\n    }\n    if (css.length > 20_000) out.push(advice('css-size', 'performance', 'css'));\n  }\n  if (theme.colors) {\n    const fixed = ensureContrast(theme.colors);\n    for (const role of ['text', 'muted', 'accent'] as const) {\n      if (fixed[role] !== theme.colors[role]) {\n        out.push(advice(`contrast-${role}`, 'contrast', `colors.${role}`, { token: role, ratio: contrastRatio(theme.colors[role], theme.colors.bg).toFixed(2) }, 'contrast'));\n      }\n    }\n  }\n  if (theme.components) {\n    if (theme.components.post?.fill === 'glass') out.push(advice('glass-post', 'performance', 'components.post.fill'));\n    const size = theme.components.postText?.fontSize;\n    if (size !== undefined && size < 14) out.push(advice('small-post-text', 'accessibility', 'components.postText.fontSize', { size: String(size) }));\n  }\n  if (theme.variants?.nav === 'top' || theme.variants?.nav === 'bottom') {\n    out.push(advice('nav-moved', 'accessibility', 'variants.nav', { position: theme.variants.nav }));\n  }\n  return out;\n}\n"]}

package/dist/runtime/themeGuards.d.ts

@@ -0,0 +1,60 @@
+/** The viewport box popovers must stay in. */
+export type Box = {
+    left: number;
+    top: number;
+    right: number;
+    bottom: number;
+};
+export type Rect = {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+};
+/** Attribute on a shifted layer (a static rule hides its caret, which points at the old anchor). */
+export declare const CLAMPED_ATTR = "data-wb-clamped";
+export declare const CLAMP_X = "--wb-clamp-x";
+export declare const CLAMP_Y = "--wb-clamp-y";
+/**
+ * Pure: the shift that brings `rect` inside `box`. A rect larger than the box keeps its start edge
+ * inside (left/top) and reports `overflowY`, so the caller can cap its height and let it scroll.
+ */
+export declare function clampShift(rect: Rect, box: Box): {
+    dx: number;
+    dy: number;
+    overflowY: boolean;
+};
+/** The box: the viewport less `margin` on every side and the bar insets top and bottom. */
+export declare function viewportBox(width: number, height: number, insets: {
+    top: number;
+    bottom: number;
+}, margin?: number): Box;
+/** The static rules the guard relies on (part of the theme sheet). */
+export declare function layerGuardCss(): string;
+export type LayerGuardOptions = {
+    /** The container the site renders its portals into (X: `#layers`). */
+    root: string;
+    /** Inside a new layer, the element that is positioned and should be shifted (first match wins). */
+    targets: string[];
+    /** Bar insets in px (read from the theme's `--wb-bar-inset-top/bottom` by default). */
+    insets?: () => {
+        top: number;
+        bottom: number;
+    };
+};
+/** Watches the layer root; returns a stop function. Off in safe mode (the host never installs it then). */
+export declare function installLayerGuard(win: Window, options: LayerGuardOptions): () => void;
+export declare const VOID_ATTR = "data-wb-void";
+/** Elements that make a part non-empty when they render. */
+export declare const VISIBLE_INSIDE = "a,button,h2,img,svg,input,video,[role=\"heading\"],[data-testid=\"tweetText\"]";
+/** The static rule the marker relies on. */
+export declare const frameMarkerCss: () => string;
+export type FrameMarkerOptions = {
+    /** Containers to watch (X: the sidebar column). */
+    scopes: string[];
+    /** Framed parts inside them (one selector list). */
+    parts: string;
+};
+/** Pure: whether `part` renders nothing (every candidate inside has no client rect). */
+export declare function isVoid(part: Element): boolean;
+export declare function installFrameMarker(win: Window, options: FrameMarkerOptions): () => void;

package/dist/runtime/themeGuards.js

@@ -0,0 +1,235 @@
+// Theme engine v3, step 8 (.omc/plans/theme-engine-v3.md 3.5, 4.2): the layer guard. A site positions
+// its popovers (menus, hover cards, tooltips) from an anchor; a theme that moves the anchor (a bottom
+// taskbar, a top bar) moves them past the window edge. Static CSS cannot see where a portal lands, so
+// this guard measures each new layer root once and shifts it back inside the viewport minus the bar
+// insets. Bounded: it watches only the layer container's children (no subtree attribute observation
+// of the page), measures in an idle callback, at most a few layers per frame, never timeline cells.
+/** Attribute on a shifted layer (a static rule hides its caret, which points at the old anchor). */
+export const CLAMPED_ATTR = 'data-wb-clamped';
+export const CLAMP_X = '--wb-clamp-x';
+export const CLAMP_Y = '--wb-clamp-y';
+/**
+ * Pure: the shift that brings `rect` inside `box`. A rect larger than the box keeps its start edge
+ * inside (left/top) and reports `overflowY`, so the caller can cap its height and let it scroll.
+ */
+export function clampShift(rect, box) {
+    const shift = (start, size, min, max) => {
+        if (size >= max - min)
+            return min - start;
+        if (start < min)
+            return min - start;
+        if (start + size > max)
+            return max - (start + size);
+        return 0;
+    };
+    return {
+        dx: Math.round(shift(rect.left, rect.width, box.left, box.right)),
+        dy: Math.round(shift(rect.top, rect.height, box.top, box.bottom)),
+        overflowY: rect.height > box.bottom - box.top,
+    };
+}
+/** The box: the viewport less `margin` on every side and the bar insets top and bottom. */
+export function viewportBox(width, height, insets, margin = 8) {
+    return { left: margin, top: margin + insets.top, right: width - margin, bottom: height - margin - insets.bottom };
+}
+/** The static rules the guard relies on (part of the theme sheet). */
+export function layerGuardCss() {
+    return `[${CLAMPED_ATTR}]{translate:var(${CLAMP_X},0px) var(${CLAMP_Y},0px) !important}\n[${CLAMPED_ATTR}="scroll"]{max-height:var(--wb-clamp-h) !important;overflow-y:auto !important}`;
+}
+const px = (value) => { const n = parseFloat(value); return Number.isFinite(n) ? n : 0; };
+/** Watches the layer root; returns a stop function. Off in safe mode (the host never installs it then). */
+export function installLayerGuard(win, options) {
+    const doc = win.document;
+    const insets = options.insets ?? (() => {
+        const style = win.getComputedStyle(doc.documentElement);
+        return { top: px(style.getPropertyValue('--wb-bar-inset-top')), bottom: px(style.getPropertyValue('--wb-bar-inset-bottom')) };
+    });
+    const selector = options.targets.join(',');
+    const pending = new Set();
+    let scheduled = false;
+    const measure = () => {
+        scheduled = false;
+        let budget = 4;
+        for (const layer of [...pending]) {
+            if (budget-- <= 0)
+                break;
+            pending.delete(layer);
+            if (!layer.isConnected)
+                continue;
+            for (const target of layer.matches(selector) ? [layer] : [...layer.querySelectorAll(selector)].slice(0, 2))
+                clamp(target);
+        }
+        if (pending.size)
+            schedule();
+    };
+    // A measured popover is watched for the site moving it again (its inline position): only its own
+    // style attribute, and only position changes count (our own clamp variables change it too).
+    const placed = new WeakMap();
+    const position = (el) => `${el.style.left}|${el.style.top}|${el.style.right}|${el.style.bottom}|${el.style.transform}`;
+    const Observer = win.MutationObserver;
+    const moved = new Observer((records) => {
+        for (const record of records) {
+            const el = record.target;
+            if (el.isConnected && placed.get(el) !== position(el)) {
+                pending.add(el);
+                schedule();
+            }
+        }
+    });
+    // A popover that grows (a theme's font, content loading in) is measured again too.
+    const Resize = win.ResizeObserver;
+    const sized = Resize ? new Resize(entries => { for (const entry of entries) {
+        const el = entry.target;
+        if (el.isConnected) {
+            pending.add(el);
+            schedule();
+        }
+    } }) : null;
+    const clamp = (el) => {
+        if (!placed.has(el)) {
+            moved.observe(el, { attributes: true, attributeFilter: ['style'] });
+            sized?.observe(el);
+        }
+        placed.set(el, position(el));
+        // Measure without our own shift.
+        el.style.removeProperty(CLAMP_X);
+        el.style.removeProperty(CLAMP_Y);
+        const r = el.getBoundingClientRect();
+        if (r.width < 1 || r.height < 1)
+            return;
+        const box = viewportBox(win.innerWidth, win.innerHeight, insets());
+        const { dx, dy, overflowY } = clampShift({ left: r.left, top: r.top, width: r.width, height: r.height }, box);
+        if (!dx && !dy && !overflowY) {
+            el.removeAttribute(CLAMPED_ATTR);
+            return;
+        }
+        el.style.setProperty(CLAMP_X, `${dx}px`);
+        el.style.setProperty(CLAMP_Y, `${dy}px`);
+        if (overflowY)
+            el.style.setProperty('--wb-clamp-h', `${Math.max(80, box.bottom - box.top)}px`);
+        el.setAttribute(CLAMPED_ATTR, overflowY ? 'scroll' : '');
+    };
+    const schedule = () => {
+        if (scheduled)
+            return;
+        scheduled = true;
+        const idle = win.requestIdleCallback;
+        if (idle)
+            idle.call(win, measure, { timeout: 120 });
+        else
+            win.setTimeout(measure, 16);
+    };
+    // Only a node that is or holds a popover is worth a measurement (typing in a dialog inserts nodes too).
+    const queue = (node) => {
+        if (!node || node.nodeType !== 1)
+            return;
+        const el = node;
+        if (!el.matches(selector) && !el.querySelector(selector))
+            return;
+        pending.add(el);
+        schedule();
+        // The site positions a portal after it mounts (a layout effect, a measured anchor): measure again
+        // once it has settled. Two late passes, no observer on the page's style attributes.
+        for (const delay of [120, 450])
+            win.setTimeout(() => { if (el.isConnected) {
+                pending.add(el);
+                schedule();
+            } }, delay);
+    };
+    let observer = null;
+    let layers = null;
+    const attach = () => {
+        const found = doc.querySelector(options.root);
+        if (found === layers)
+            return;
+        observer?.disconnect();
+        layers = found;
+        if (!found)
+            return;
+        // Children of the layer root and their children: a portal mounts its positioned box a level or two down.
+        const next = new Observer((records) => { for (const record of records)
+            for (const node of record.addedNodes)
+                queue(node.nodeType === 1 ? (node.closest(selector) ?? node) : null); });
+        next.observe(found, { childList: true, subtree: true });
+        observer = next;
+        for (const child of found.children)
+            queue(child);
+    };
+    attach();
+    const retry = win.setInterval(attach, 2000);
+    const onResize = () => { if (layers)
+        for (const child of layers.children)
+            queue(child); };
+    win.addEventListener('resize', onResize);
+    return () => { observer?.disconnect(); moved.disconnect(); sized?.disconnect(); win.clearInterval(retry); win.removeEventListener('resize', onResize); };
+}
+// ---------------------------------------------------------------------------------------------
+// Frame marker (theme engine v3 4.3, step 10): a framed part (a card, a panel) whose content is all
+// hidden (a feature switch, a plugin, the site itself) collapses instead of leaving an empty frame.
+// Static CSS cannot see `display:none` inside, so the marker sets `data-wb-void` and a static rule
+// hides the part. Watched by a ResizeObserver per framed part (a hidden module changes the part's size)
+// and a child-list observer on the scopes (new parts), never by a timer.
+export const VOID_ATTR = 'data-wb-void';
+/** Elements that make a part non-empty when they render. */
+export const VISIBLE_INSIDE = 'a,button,h2,img,svg,input,video,[role="heading"],[data-testid="tweetText"]';
+/** The static rule the marker relies on. */
+export const frameMarkerCss = () => `:root:root [${VOID_ATTR}]{display:none !important}`;
+/** Pure: whether `part` renders nothing (every candidate inside has no client rect). */
+export function isVoid(part) {
+    return ![...part.querySelectorAll(VISIBLE_INSIDE)].some(el => el.getClientRects().length > 0);
+}
+export function installFrameMarker(win, options) {
+    const doc = win.document;
+    const Resize = win.ResizeObserver;
+    const Observer = win.MutationObserver;
+    const watched = new WeakSet();
+    let frame = 0;
+    const check = (part) => {
+        // A void part is display:none itself: lift the mark to see whether something came back.
+        const was = part.hasAttribute(VOID_ATTR);
+        if (was)
+            part.removeAttribute(VOID_ATTR);
+        if (isVoid(part))
+            part.setAttribute(VOID_ATTR, '');
+    };
+    const sweep = () => {
+        frame = 0;
+        for (const scope of options.scopes) {
+            const root = doc.querySelector(scope);
+            if (!root)
+                continue;
+            for (const part of root.querySelectorAll(options.parts)) {
+                if (!watched.has(part)) {
+                    watched.add(part);
+                    sized?.observe(part);
+                }
+                check(part);
+            }
+        }
+    };
+    const schedule = () => { if (!frame)
+        frame = win.requestAnimationFrame(sweep); };
+    const sized = Resize ? new Resize(schedule) : null;
+    // Inner modules change while the part keeps its size only when hidden content was already 0 tall:
+    // child-list changes under the scopes cover those, and new parts.
+    const added = new Observer(schedule);
+    const roots = new WeakSet();
+    const attach = () => {
+        for (const scope of options.scopes) {
+            const root = doc.querySelector(scope);
+            if (root && !roots.has(root)) {
+                roots.add(root);
+                added.observe(root, { childList: true, subtree: true, attributes: true, attributeFilter: ['style', 'class', 'hidden'] });
+                schedule();
+            }
+        }
+    };
+    attach();
+    // Scopes mount late and are replaced on navigation: looked up again every 2 s (one querySelector per
+    // scope; the per-part work is all observer-driven).
+    const retry = win.setInterval(attach, 2000);
+    return () => { sized?.disconnect(); added.disconnect(); win.clearInterval(retry); if (frame)
+        win.cancelAnimationFrame(frame); for (const el of doc.querySelectorAll(`[${VOID_ATTR}]`))
+        el.removeAttribute(VOID_ATTR); };
+}
+//# sourceMappingURL=themeGuards.js.map

package/dist/runtime/themeGuards.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"themeGuards.js","sourceRoot":"","sources":["../../../runtime/src/themeGuards.ts"],"names":[],"mappings":"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","sourcesContent":["// Theme engine v3, step 8 (.omc/plans/theme-engine-v3.md 3.5, 4.2): the layer guard. A site positions\n// its popovers (menus, hover cards, tooltips) from an anchor; a theme that moves the anchor (a bottom\n// taskbar, a top bar) moves them past the window edge. Static CSS cannot see where a portal lands, so\n// this guard measures each new layer root once and shifts it back inside the viewport minus the bar\n// insets. Bounded: it watches only the layer container's children (no subtree attribute observation\n// of the page), measures in an idle callback, at most a few layers per frame, never timeline cells.\n\n/** The viewport box popovers must stay in. */\nexport type Box = { left: number; top: number; right: number; bottom: number };\nexport type Rect = { left: number; top: number; width: number; height: number };\n\n/** Attribute on a shifted layer (a static rule hides its caret, which points at the old anchor). */\nexport const CLAMPED_ATTR = 'data-wb-clamped';\nexport const CLAMP_X = '--wb-clamp-x';\nexport const CLAMP_Y = '--wb-clamp-y';\n\n/**\n * Pure: the shift that brings `rect` inside `box`. A rect larger than the box keeps its start edge\n * inside (left/top) and reports `overflowY`, so the caller can cap its height and let it scroll.\n */\nexport function clampShift(rect: Rect, box: Box): { dx: number; dy: number; overflowY: boolean } {\n  const shift = (start: number, size: number, min: number, max: number) => {\n    if (size >= max - min) return min - start;\n    if (start < min) return min - start;\n    if (start + size > max) return max - (start + size);\n    return 0;\n  };\n  return {\n    dx: Math.round(shift(rect.left, rect.width, box.left, box.right)),\n    dy: Math.round(shift(rect.top, rect.height, box.top, box.bottom)),\n    overflowY: rect.height > box.bottom - box.top,\n  };\n}\n\n/** The box: the viewport less `margin` on every side and the bar insets top and bottom. */\nexport function viewportBox(width: number, height: number, insets: { top: number; bottom: number }, margin = 8): Box {\n  return { left: margin, top: margin + insets.top, right: width - margin, bottom: height - margin - insets.bottom };\n}\n\n/** The static rules the guard relies on (part of the theme sheet). */\nexport function layerGuardCss(): string {\n  return `[${CLAMPED_ATTR}]{translate:var(${CLAMP_X},0px) var(${CLAMP_Y},0px) !important}\\n[${CLAMPED_ATTR}=\"scroll\"]{max-height:var(--wb-clamp-h) !important;overflow-y:auto !important}`;\n}\n\nexport type LayerGuardOptions = {\n  /** The container the site renders its portals into (X: `#layers`). */\n  root: string;\n  /** Inside a new layer, the element that is positioned and should be shifted (first match wins). */\n  targets: string[];\n  /** Bar insets in px (read from the theme's `--wb-bar-inset-top/bottom` by default). */\n  insets?: () => { top: number; bottom: number };\n};\n\nconst px = (value: string) => { const n = parseFloat(value); return Number.isFinite(n) ? n : 0; };\n\n/** Watches the layer root; returns a stop function. Off in safe mode (the host never installs it then). */\nexport function installLayerGuard(win: Window, options: LayerGuardOptions): () => void {\n  const doc = win.document;\n  const insets = options.insets ?? (() => {\n    const style = win.getComputedStyle(doc.documentElement);\n    return { top: px(style.getPropertyValue('--wb-bar-inset-top')), bottom: px(style.getPropertyValue('--wb-bar-inset-bottom')) };\n  });\n  const selector = options.targets.join(',');\n  const pending = new Set<Element>();\n  let scheduled = false;\n  const measure = () => {\n    scheduled = false;\n    let budget = 4;\n    for (const layer of [...pending]) {\n      if (budget-- <= 0) break;\n      pending.delete(layer);\n      if (!layer.isConnected) continue;\n      for (const target of layer.matches(selector) ? [layer] : [...layer.querySelectorAll(selector)].slice(0, 2)) clamp(target as HTMLElement);\n    }\n    if (pending.size) schedule();\n  };\n  // A measured popover is watched for the site moving it again (its inline position): only its own\n  // style attribute, and only position changes count (our own clamp variables change it too).\n  const placed = new WeakMap<HTMLElement, string>();\n  const position = (el: HTMLElement) => `${el.style.left}|${el.style.top}|${el.style.right}|${el.style.bottom}|${el.style.transform}`;\n  const Observer = (win as Window & { MutationObserver: typeof MutationObserver }).MutationObserver;\n  const moved = new Observer((records: MutationRecord[]) => {\n    for (const record of records) {\n      const el = record.target as HTMLElement;\n      if (el.isConnected && placed.get(el) !== position(el)) { pending.add(el); schedule(); }\n    }\n  });\n  // A popover that grows (a theme's font, content loading in) is measured again too.\n  const Resize = (win as Window & { ResizeObserver?: typeof ResizeObserver }).ResizeObserver;\n  const sized = Resize ? new Resize(entries => { for (const entry of entries) { const el = entry.target as HTMLElement; if (el.isConnected) { pending.add(el); schedule(); } } }) : null;\n  const clamp = (el: HTMLElement) => {\n    if (!placed.has(el)) { moved.observe(el, { attributes: true, attributeFilter: ['style'] }); sized?.observe(el); }\n    placed.set(el, position(el));\n    // Measure without our own shift.\n    el.style.removeProperty(CLAMP_X); el.style.removeProperty(CLAMP_Y);\n    const r = el.getBoundingClientRect();\n    if (r.width < 1 || r.height < 1) return;\n    const box = viewportBox(win.innerWidth, win.innerHeight, insets());\n    const { dx, dy, overflowY } = clampShift({ left: r.left, top: r.top, width: r.width, height: r.height }, box);\n    if (!dx && !dy && !overflowY) { el.removeAttribute(CLAMPED_ATTR); return; }\n    el.style.setProperty(CLAMP_X, `${dx}px`); el.style.setProperty(CLAMP_Y, `${dy}px`);\n    if (overflowY) el.style.setProperty('--wb-clamp-h', `${Math.max(80, box.bottom - box.top)}px`);\n    el.setAttribute(CLAMPED_ATTR, overflowY ? 'scroll' : '');\n  };\n  const schedule = () => {\n    if (scheduled) return;\n    scheduled = true;\n    const idle = (win as Window & { requestIdleCallback?: (cb: () => void, o?: { timeout: number }) => number }).requestIdleCallback;\n    if (idle) idle.call(win, measure, { timeout: 120 }); else win.setTimeout(measure, 16);\n  };\n  // Only a node that is or holds a popover is worth a measurement (typing in a dialog inserts nodes too).\n  const queue = (node: Node | null) => {\n    if (!node || node.nodeType !== 1) return;\n    const el = node as Element;\n    if (!el.matches(selector) && !el.querySelector(selector)) return;\n    pending.add(el); schedule();\n    // The site positions a portal after it mounts (a layout effect, a measured anchor): measure again\n    // once it has settled. Two late passes, no observer on the page's style attributes.\n    for (const delay of [120, 450]) win.setTimeout(() => { if (el.isConnected) { pending.add(el); schedule(); } }, delay);\n  };\n  let observer: MutationObserver | null = null;\n  let layers: Element | null = null;\n  const attach = () => {\n    const found = doc.querySelector(options.root);\n    if (found === layers) return;\n    observer?.disconnect();\n    layers = found;\n    if (!found) return;\n    // Children of the layer root and their children: a portal mounts its positioned box a level or two down.\n    const next = new Observer((records: MutationRecord[]) => { for (const record of records) for (const node of record.addedNodes) queue(node.nodeType === 1 ? ((node as Element).closest(selector) ?? node) : null); });\n    next.observe(found, { childList: true, subtree: true });\n    observer = next;\n    for (const child of found.children) queue(child);\n  };\n  attach();\n  const retry = win.setInterval(attach, 2000);\n  const onResize = () => { if (layers) for (const child of layers.children) queue(child); };\n  win.addEventListener('resize', onResize);\n  return () => { observer?.disconnect(); moved.disconnect(); sized?.disconnect(); win.clearInterval(retry); win.removeEventListener('resize', onResize); };\n}\n\n// ---------------------------------------------------------------------------------------------\n// Frame marker (theme engine v3 4.3, step 10): a framed part (a card, a panel) whose content is all\n// hidden (a feature switch, a plugin, the site itself) collapses instead of leaving an empty frame.\n// Static CSS cannot see `display:none` inside, so the marker sets `data-wb-void` and a static rule\n// hides the part. Watched by a ResizeObserver per framed part (a hidden module changes the part's size)\n// and a child-list observer on the scopes (new parts), never by a timer.\n\nexport const VOID_ATTR = 'data-wb-void';\n/** Elements that make a part non-empty when they render. */\nexport const VISIBLE_INSIDE = 'a,button,h2,img,svg,input,video,[role=\"heading\"],[data-testid=\"tweetText\"]';\n\n/** The static rule the marker relies on. */\nexport const frameMarkerCss = () => `:root:root [${VOID_ATTR}]{display:none !important}`;\n\nexport type FrameMarkerOptions = {\n  /** Containers to watch (X: the sidebar column). */\n  scopes: string[];\n  /** Framed parts inside them (one selector list). */\n  parts: string;\n};\n\n/** Pure: whether `part` renders nothing (every candidate inside has no client rect). */\nexport function isVoid(part: Element): boolean {\n  return ![...part.querySelectorAll(VISIBLE_INSIDE)].some(el => el.getClientRects().length > 0);\n}\n\nexport function installFrameMarker(win: Window, options: FrameMarkerOptions): () => void {\n  const doc = win.document;\n  const Resize = (win as Window & { ResizeObserver?: typeof ResizeObserver }).ResizeObserver;\n  const Observer = (win as Window & { MutationObserver: typeof MutationObserver }).MutationObserver;\n  const watched = new WeakSet<Element>();\n  let frame = 0;\n  const check = (part: Element) => {\n    // A void part is display:none itself: lift the mark to see whether something came back.\n    const was = part.hasAttribute(VOID_ATTR);\n    if (was) part.removeAttribute(VOID_ATTR);\n    if (isVoid(part)) part.setAttribute(VOID_ATTR, '');\n  };\n  const sweep = () => {\n    frame = 0;\n    for (const scope of options.scopes) {\n      const root = doc.querySelector(scope);\n      if (!root) continue;\n      for (const part of root.querySelectorAll(options.parts)) {\n        if (!watched.has(part)) { watched.add(part); sized?.observe(part); }\n        check(part);\n      }\n    }\n  };\n  const schedule = () => { if (!frame) frame = win.requestAnimationFrame(sweep); };\n  const sized = Resize ? new Resize(schedule) : null;\n  // Inner modules change while the part keeps its size only when hidden content was already 0 tall:\n  // child-list changes under the scopes cover those, and new parts.\n  const added = new Observer(schedule);\n  const roots = new WeakSet<Element>();\n  const attach = () => {\n    for (const scope of options.scopes) {\n      const root = doc.querySelector(scope);\n      if (root && !roots.has(root)) { roots.add(root); added.observe(root, { childList: true, subtree: true, attributes: true, attributeFilter: ['style', 'class', 'hidden'] }); schedule(); }\n    }\n  };\n  attach();\n  // Scopes mount late and are replaced on navigation: looked up again every 2 s (one querySelector per\n  // scope; the per-part work is all observer-driven).\n  const retry = win.setInterval(attach, 2000);\n  return () => { sized?.disconnect(); added.disconnect(); win.clearInterval(retry); if (frame) win.cancelAnimationFrame(frame); for (const el of doc.querySelectorAll(`[${VOID_ATTR}]`)) el.removeAttribute(VOID_ATTR); };\n}\n"]}

package/dist/runtime/themeIcons.d.ts

@@ -0,0 +1,130 @@
+import { type ColorRole, type RoleColors } from './themeComponents.ts';
+/** Semantic names a pack may draw. `.active` is a selected navigation item, `.on` an action that is set. */
+export declare const ICON_NAMES: readonly ["home", "home.active", "explore", "explore.active", "notifications", "notifications.active", "messages", "messages.active", "grok", "bookmarks", "bookmarks.active", "lists", "communities", "premium", "profile", "profile.active", "more", "compose", "reply", "repost", "repost.on", "like", "like.on", "views", "bookmark", "bookmark.on", "share", "verified", "logo", "caret", "back", "close", "search", "settings", "media", "gif", "poll", "emoji", "schedule", "location", "pinned", "repostContext", "lock", "history", "studio", "articles"];
+export type IconName = typeof ICON_NAMES[number];
+export declare const ICON_GROUPS: readonly ["nav", "actions", "composer", "misc"];
+export type IconGroup = typeof ICON_GROUPS[number];
+/** Limits of a pack (the JSON Schema and the Store check say the same). */
+export declare const ICON_LIMITS: {
+    readonly names: 64;
+    readonly pathChars: 4000;
+    readonly layers: 6;
+    readonly pngChars: 6000;
+    readonly packBytes: 120000;
+    readonly labelChars: 12;
+    readonly overrides: 8;
+};
+/** Path data only: commands, numbers, separators. */
+export declare const PATH_GRAMMAR: RegExp;
+export type IconFill = ColorRole | string | {
+    from: string;
+    to: string;
+};
+export type IconGlyph = {
+    d: string;
+    rule?: 'evenodd';
+    stroke?: boolean;
+} | {
+    layers: Array<{
+        d: string;
+        fill: IconFill;
+        opacity?: number;
+        rule?: 'evenodd';
+    }>;
+} | {
+    png: string;
+    pixel?: boolean;
+};
+export type IconStyle = {
+    stroke: number;
+    cap: 'round' | 'square' | 'butt';
+    join: 'round' | 'miter' | 'bevel';
+    scale: number;
+};
+export declare const BASE_ICON_STYLE: IconStyle;
+export declare const ICON_LABEL_NAMES: readonly ["reply", "repost", "like", "views", "bookmark", "share"];
+export type IconLabels = Partial<Record<typeof ICON_LABEL_NAMES[number], string>>;
+export type IconSymbols = {
+    like?: 'heart' | 'star' | 'custom';
+    separator?: 'dot' | 'bullet' | 'slash' | 'dash' | 'pipe' | 'none';
+};
+export type IconPack = {
+    id: string;
+    name: string;
+    description: string;
+    author: string;
+    /** SPDX id, or `own` for the author's own drawings, or a plain name for artwork under other terms. */
+    license: string;
+    /** Where the drawings come from (a project name or URL as text) and whom to credit. */
+    source: string;
+    credits: string;
+    version: 1;
+    style: IconStyle;
+    glyphs: Partial<Record<IconName, IconGlyph>>;
+    symbols?: IconSymbols;
+    labels?: IconLabels;
+};
+/** What a theme says about icons: a pack by id, plus small adjustments. Never a whole pack. */
+export type ThemeIcons = {
+    pack?: string;
+    style?: Partial<IconStyle>;
+    overrides?: Partial<Record<IconName, IconGlyph>>;
+    symbols?: IconSymbols;
+    labels?: IconLabels;
+};
+/** One glyph from JSON, or null when it is not valid path data, layers or a small PNG. */
+export declare function sanitizeGlyph(value: unknown): IconGlyph | null;
+export declare const sanitizeIconStyle: (value: unknown, base?: IconStyle) => IconStyle;
+/** Any JSON to a valid pack, or null when it has no id, no name or no valid glyph. */
+export declare function sanitizeIconPack(input: unknown): IconPack | null;
+/** Parses an imported `*.icons.json`; errors are human-readable. */
+export declare function parseIconPackJson(json: string): {
+    pack: IconPack;
+    warnings: string[];
+} | {
+    error: string;
+};
+/** The `icons` group of a theme from JSON. Null when it says nothing valid. */
+export declare function sanitizeThemeIcons(value: unknown): ThemeIcons | null;
+/** `theme`: follow the theme's suggestion; `site`: the site's own icons; otherwise a pack id. */
+export type IconChoice = 'theme' | 'site' | string;
+export declare const normalizeIconChoice: (value: unknown) => IconChoice;
+export type IconCatalog = {
+    packs: readonly IconPack[];
+    get(id: string | undefined): IconPack | null;
+    /** The pack that is drawn: the owner's pick, else the theme's suggestion; null for the site's own icons or an unknown pack. */
+    resolve(choice: IconChoice, theme: ThemeIcons | null | undefined): IconPack | null;
+};
+export declare function createIconCatalog(builtins: readonly IconPack[], installed?: readonly IconPack[]): IconCatalog;
+/** The SVG document of a glyph, built from validated data. `colors` resolves role fills of layers; a single path is black (it is used as a mask). */
+export declare function glyphSvg(glyph: IconGlyph, style: IconStyle, colors?: RoleColors | null): string | null;
+/** True for glyphs that carry their own colors (drawn as an image, not as a mask of the current color). */
+export declare const isColored: (glyph: IconGlyph) => boolean;
+/** How a site finds one of its icons: the container that holds it (stable hooks), else the start of its path data. */
+export type IconMatcher = {
+    /** Selector of the icon's `<svg>` by its container (`[data-testid="like"] svg`). */
+    ctx?: string;
+    /** Prefixes of the site's own path data for this icon, for icons without a container hook. */
+    sig?: readonly string[];
+    group: IconGroup;
+    /** Needed for its group to be drawn at all (a rail never shows half ours, half the site's). */
+    core?: boolean;
+};
+export type IconTable = Partial<Record<IconName, IconMatcher>>;
+/** Selectors of the `<svg>` boxes of one icon. */
+export declare function iconSelectors(matcher: IconMatcher): string[];
+export type IconContext = {
+    colors: RoleColors | null;
+    /** Attribute on `<html>` that lists the groups that are on (`data-wb-icons="nav actions"`); absent: every group draws. */
+    gate?: string;
+    /** The owner lets themes and packs change icons (default: yes). */
+    allowed?: boolean;
+};
+/**
+ * CSS that draws `pack` over a site's icons. One rule per glyph the pack has and the site's table
+ * knows, inside guards: forced colors remove backgrounds (a masked icon would vanish) and an engine
+ * without masks would paint solid squares.
+ */
+export declare function compileIcons(pack: IconPack | null, theme: ThemeIcons | null | undefined, table: IconTable, ctx: IconContext): string;
+/** The groups of `table` whose core icons are all on the page (`has(selector)` says whether one matches). Empty table entries count as present. */
+export declare function iconGroupsPresent(table: IconTable, has: (selector: string) => boolean): IconGroup[];