@fasl-work/caos-app-shell 0.10.0 → 0.11.1

package/gate/inpage.mjs

@@ -31,6 +31,105 @@ export function installLib() {
     return s.visibility !== 'hidden' && s.display !== 'none' && Number(s.opacity) !== 0;
   };
   const shown = (el) => el.getClientRects().length > 0 && (el.checkVisibility ? el.checkVisibility({ checkVisibilityCSS: true }) : true);
+  const FONT_FLOOR = 8; // px: a smaller font is not legible, whatever its line box
+  const fontPx = (el) => Number.parseFloat(getComputedStyle(el).fontSize);
+  /**
+   * The box a `clip-path` leaves of an element's own box `ar`, or null when the gate cannot read the shape: `inset()` is
+   * computed, any other shape (circle, polygon, path, url) is taken as cutting the element away.
+   */
+  const clipPathBox = (cp, ar) => {
+    const m = /^inset\((.*)\)$/.exec(cp.trim());
+    if (!m) return null;
+    const v = m[1].split(/\bround\b/)[0].trim().split(/\s+/).filter(Boolean);
+    if (v.length < 1 || v.length > 4) return null;
+    const [top, right, bottom, left] = [v[0], v[1] ?? v[0], v[2] ?? v[0], v[3] ?? v[1] ?? v[0]];
+    const px = (x, ref) => (x.endsWith('%') ? (Number.parseFloat(x) / 100) * ref : Number.parseFloat(x));
+    const o = { top: px(top, ar.height), right: px(right, ar.width), bottom: px(bottom, ar.height), left: px(left, ar.width) };
+    if (Object.values(o).some((n) => Number.isNaN(n))) return null;
+    return { left: ar.left + o.left, top: ar.top + o.top, right: ar.right - o.right, bottom: ar.bottom - o.bottom };
+  };
+  /**
+   * The part of `rect` a reader can see: inside `within`, inside every ancestor from `el` up (below `within`) that
+   * hides its overflow (`el` itself only when `self`: its overflow cuts its own text, not its own box) and inside every
+   * `clip-path` of `el` and of those ancestors. Null when nothing is left.
+   */
+  const clipRect = (rect, el, within, self) => {
+    const b = within.getBoundingClientRect();
+    let left = Math.max(rect.left, b.left);
+    let top = Math.max(rect.top, b.top);
+    let right = Math.min(rect.right, b.right);
+    let bottom = Math.min(rect.bottom, b.bottom);
+    for (let a = el; a && a !== within && a !== document.body; a = a.parentElement) {
+      const s = getComputedStyle(a);
+      const ar = a.getBoundingClientRect();
+      if (a !== el || self) {
+        if (/hidden|clip/.test(s.overflowX)) {
+          left = Math.max(left, ar.left);
+          right = Math.min(right, ar.right);
+        }
+        if (/hidden|clip/.test(s.overflowY)) {
+          top = Math.max(top, ar.top);
+          bottom = Math.min(bottom, ar.bottom);
+        }
+      }
+      if (s.clipPath && s.clipPath !== 'none') {
+        const c = clipPathBox(s.clipPath, ar);
+        if (!c) return null;
+        left = Math.max(left, c.left);
+        top = Math.max(top, c.top);
+        right = Math.min(right, c.right);
+        bottom = Math.min(bottom, c.bottom);
+      }
+    }
+    return right > left && bottom > top ? { left, top, right, bottom } : null;
+  };
+  const textNodesOf = (el) => {
+    const out = [];
+    const walker = document.createTreeWalker(el, NodeFilter.SHOW_TEXT);
+    for (let n = walker.nextNode(); n; n = walker.nextNode()) {
+      if (!/\S/.test(n.nodeValue || '') || !n.parentElement || n.parentElement.closest('script, style, .katex-mathml')) continue;
+      out.push(n);
+    }
+    return out;
+  };
+  const probe = document.createRange();
+  /** Whether a reader sees the glyphs of a text node: its element is rendered, its font is legible, and a line of it lies inside what is not clipped. */
+  const glyphsSeen = (node, within, minW, minH) => {
+    const p = node.parentElement;
+    if (!p || (p.checkVisibility && !p.checkVisibility({ checkOpacity: true, checkVisibilityCSS: true })) || fontPx(p) < FONT_FLOOR) return false;
+    probe.selectNodeContents(node);
+    for (const rc of probe.getClientRects()) {
+      if (rc.width <= 0 || rc.height <= 0) continue;
+      const c = clipRect(rc, p, within, true);
+      if (c && c.right - c.left >= minW && c.bottom - c.top >= minH) return true;
+    }
+    return false;
+  };
+  /**
+   * What a reader can read (ADR-0080 decision 3, ADR-0017 2.1): the element is rendered (a box, opacity above 0, CSS
+   * visibility), its font is not zero, the part of its box that lies inside `within` (and inside every ancestor that
+   * hides its overflow, and every clip-path) is at least minW by minH px, and the glyphs of its text are painted where
+   * that is so: a text node counts when its font is at least FONT_FLOOR px and a line of it is inside what is not clipped
+   * (text pushed out of its box by `text-indent`, cut by `clip-path` or set in a 1 px font is not read). An element with
+   * no text (a drawing) is judged by its box. `only` judges one text node of the element. A 1 by 1 px screen-reader-only
+   * note, a transparent one, one positioned off-screen or one cut off by a clipping box is not readable. `shown` stays
+   * for `data-state="loading"`, which must catch every pending element, visible or not.
+   */
+  const readable = (el, within, minW = 40, minH = 12, only = null) => {
+    if (!visible(el) || !within) return false;
+    if (fontPx(el) < 1) return false;
+    const box = clipRect(el.getBoundingClientRect(), el, within, false);
+    if (!box || box.right - box.left < minW || box.bottom - box.top < minH) return false;
+    if (!only && el.matches('svg, canvas, img, video')) return true; // a drawing: the box decides, its labels are not the text of a reader
+    const nodes = only ? [only] : textNodesOf(el);
+    if (nodes.length === 0) return true;
+    return nodes.some((n) => glyphsSeen(n, within, Math.min(minW, 2), Math.min(minH, 4)));
+  };
+  /** The words and the letters and digits of the text a reader sees in an element (rendered text: hidden descendants are not in it). */
+  const renderedText = (el) => {
+    const t = el.innerText || '';
+    return { chars: t.replace(/[^\p{L}\p{N}]+/gu, '').length, words: t.split(/\s+/).filter((w) => /[\p{L}\p{N}]/u.test(w)).length };
+  };
   const path = (el) => {
     const parts = [];
     let e = el;
@@ -200,6 +299,8 @@ export function installLib() {
     let instrument = null;
     const surfaces = [];
     let prose = false;
+    let unavailable = null; // data-state="unavailable" declared in the instrument: 'explained' (a reason a reader can read), 'unexplained' (readable, no reason) or 'unseen' (no reader can see it)
+    let drawn = 0; // drawing elements rendered in the instrument, whatever their size or visibility
     if (inst && visible(inst)) {
       const ir = inst.getBoundingClientRect();
       const cx0 = Math.max(0, ir.left);
@@ -209,6 +310,32 @@ export function installLib() {
       instrument = { x: cx0, y: cy0, w: Math.max(0, cx1 - cx0), h: Math.max(0, cy1 - cy0) };
       const ctx = inst.querySelector('.caos-cw-context');
       prose = Boolean(ctx && visible(ctx));
+      // a declaration counts when a reader can see the element (a box of 40 by 12 px at least, inside the instrument,
+      // opaque); its reason is the text rendered, 12 letters or digits in two words at least
+      const declared = [...inst.querySelectorAll('[data-state="unavailable"]')].filter(shown);
+      const seen = declared.filter((el) => readable(el, inst));
+      if (seen.length) {
+        unavailable = seen.some((el) => {
+          const t = renderedText(el);
+          return t.chars >= 12 && t.words >= 2;
+        })
+          ? 'explained'
+          : 'unexplained';
+      } else if (declared.length) unavailable = 'unseen';
+      // a drawing element rendered at all (a collapsed or invisible chart too) cancels the exemption; a card that holds the note is not one
+      drawn = [...inst.querySelectorAll('canvas, img, video, table, svg, [data-plot], [data-drawn]')].filter((el) => {
+        if (el.getClientRects().length === 0) return false;
+        const tag = el.tagName.toLowerCase();
+        if (tag === 'svg') {
+          if (el.parentElement && el.parentElement.closest('svg')) return false;
+          if (el.classList.contains('lucide') || el.closest('button, a, summary, [role="tab"], [role="button"]')) return false;
+          const r = el.getBoundingClientRect();
+          if (el.getAttribute('aria-hidden') === 'true' && r.width > 0 && r.height > 0 && r.width <= 32 && r.height <= 32) return false;
+        }
+        if (tag === 'table' && el.parentElement && el.parentElement.closest('table')) return false;
+        if (el.matches('[data-plot], [data-drawn]') && declared.some((d) => el.contains(d))) return false;
+        return true;
+      }).length;
       for (const el of inst.querySelectorAll('canvas, svg, img, table, video')) {
         const tag = el.tagName.toLowerCase();
         if (tag === 'svg' && el.parentElement && el.parentElement.closest('svg')) continue;
@@ -254,6 +381,18 @@ export function installLib() {
       ? { case: wb.getAttribute('data-case'), key: wb.getAttribute('data-state-key'), replayOnly: wb.getAttribute('data-replay-only') === '1' }
       : null;
 
+    // The references of a page or open tab (ADR-0017 s4): one block, the last thing in its scope (the document page
+    // or the tab panel that holds it).
+    const refScope = (el) => el.closest('[role="tabpanel"], [data-doc-page]');
+    const refBlocks = [...document.querySelectorAll('[data-doc-references]')].filter(visible);
+    const isLastInScope = (block) => {
+      const scope = refScope(block);
+      for (let el = block; el && el !== scope; el = el.parentElement) {
+        for (let n = el.nextElementSibling; n; n = n.nextElementSibling) if (visible(n)) return false;
+      }
+      return true;
+    };
+
     let offCentre = null;
     const proseBody = document.querySelector('.page-body:not(.wide)');
     if (proseBody && visible(proseBody)) {
@@ -278,19 +417,217 @@ export function installLib() {
       instrument,
       surfaces,
       prose,
+      unavailable,
+      drawn,
       workbench,
       offCentre,
       pageText: pageBody ? (pageBody.innerText || '').trim().length : 0,
       referenceLists: [...document.querySelectorAll('.reference-list')].filter(visible).length,
+      // shell 0.11.0: the references of a page or open tab are one block at its end (ADR-0017 s4)
+      referenceBlocks: refBlocks.length,
+      referencesNotLast: refBlocks.filter((b) => !isLastInScope(b)).length,
+      refsDeclaredNoBlock: [...document.querySelectorAll('[data-refs]')].filter((sec) => visible(sec) && !refBlocks.some((b) => refScope(b) === refScope(sec))).length,
       uncaptioned: [...document.querySelectorAll('.equation')].filter((e) => visible(e) && !e.querySelector('.equation-caption')).length,
       // charts whose axis gives a tick the label of the tick before it (UPlotChart declares data-ticks-repeat)
       repeatedTicks: [...document.querySelectorAll('[data-ticks-repeat]')]
         .filter((el) => visible(el) && Number(el.getAttribute('data-ticks-repeat')) > 0)
         .map((el) => ({ label: describe(el.closest('[data-plot]') || el), n: Number(el.getAttribute('data-ticks-repeat')) })),
+      // the drawing a filling card keeps under its note (G6 stage floor): the body of every visible `PlotCard fill`
+      fillStages: [...document.querySelectorAll('.caos-plot.fill')]
+        .filter(visible)
+        .map((card) => ({ label: describe(card), h: (card.querySelector(':scope > .caos-plot-body') || card).getBoundingClientRect().height })),
       sectionsWithoutRefs: [...document.querySelectorAll('[data-no-refs-reason="missing"]')].filter(visible).length,
     };
   };
 
+  // ---- 0.11.0: the required areas of the documentation pages (ADR-0017 section 2.1) ------------------------------
+
+  let docBound = null; // the page being measured: what lies outside it, or is clipped out of it, is not read
+  const wordsOf = (el) => {
+    // the words a reader reads: visible text outside equations; `linkWords` of them inside links
+    let words = 0;
+    let linkWords = 0;
+    const walker = document.createTreeWalker(el, NodeFilter.SHOW_TEXT);
+    for (let n = walker.nextNode(); n; n = walker.nextNode()) {
+      const parent = n.parentElement;
+      if (!parent || parent.closest('.katex, script, style') || !readable(parent, docBound, 4, 4, n)) continue;
+      const k = (n.nodeValue || '').split(/\s+/).filter(Boolean).length;
+      words += k;
+      if (parent.closest('a')) linkWords += k;
+    }
+    return { words, linkWords };
+  };
+  const tabLabel = (t) => (t.textContent || '').trim().replace(/\s+/g, ' ');
+  /** The tabs from the outermost one to the one that opens `panel`: their labels (for messages) and their ids (for rules). */
+  const chainOf = (panel) => {
+    const labels = [];
+    const ids = [];
+    let p = panel;
+    while (p) {
+      const id = p.getAttribute('aria-labelledby');
+      const tab = id ? document.getElementById(id) : null;
+      if (!tab) break;
+      labels.unshift(tabLabel(tab));
+      ids.unshift(tab.getAttribute('data-tab') || tabLabel(tab));
+      const tl = tab.closest('[role="tablist"]');
+      p = tl && tl.parentElement ? tl.parentElement.closest('[role="tabpanel"]') : null;
+    }
+    return { label: labels.join(' > '), key: ids.join('/'), head: ids[0] ?? null };
+  };
+  const textOf = (el) => (el.innerText || '').trim().replace(/\s+/g, ' '); // rendered text: a hidden descendant is not in it
+  const norm = (s) => String(s || '').replace(/\s+/g, ' ').trim().toLowerCase();
+  /** A part of a statement a reader sees: the declared text is in the rendered text, in the readable part (`sel`) when the element has one. */
+  const statPart = (el, want, sel) => {
+    if (!want) return false;
+    const kids = [...el.querySelectorAll(sel)];
+    return kids.length ? kids.some((k) => readable(k, docBound, 4, 4) && norm(k.innerText).includes(want)) : norm(el.innerText).includes(want);
+  };
+  /** A quantified statement: visible, a digit in its value, and the unit and the source it declares readable beside it (the `Stat` component). */
+  const validStat = (el) => {
+    if (!readable(el, docBound, 4, 4)) return false;
+    const value = el.querySelector('.caos-stat-value');
+    return /\d/.test((value ? value.innerText : el.innerText) || '') && statPart(el, norm(el.getAttribute('data-stat-unit')), '.caos-stat-unit') && statPart(el, norm(el.getAttribute('data-stat-source')), '.caos-stat-source');
+  };
+
+  /**
+   * What a documentation page shows in this state: its lede, its waivers, the leaf topics open, the views (the outermost
+   * tabs), every visible section with what it holds, and the figures and captioned equations of the open view. The rules
+   * (gate/areas.mjs) are applied by the runner; this only measures. A hidden element is never counted, a paragraph is
+   * counted once per distinct text, and the words are those of the displayed language.
+   */
+  G.docPage = () => {
+    const page = document.querySelector('[data-doc-page]');
+    if (!page || !visible(page)) return null;
+    docBound = page;
+    const seen = (el) => readable(el, page, 4, 4);
+    const lede = page.querySelector('.lede');
+    const panels = [...page.querySelectorAll('[role="tabpanel"]')].filter(visible);
+    // a tab list inside a section belongs to that section: its panels are not topics, and it does not make its topic a branch
+    const inSection = (el) => Boolean(el.closest('[data-doc-section]'));
+    const leaves = panels.filter((p) => !inSection(p) && ![...p.querySelectorAll('[role="tablist"]')].some((tl) => visible(tl) && !inSection(tl)));
+    const topicPanel = (el) => {
+      let p = el.closest('[role="tabpanel"]');
+      while (p && inSection(p)) p = p.parentElement ? p.parentElement.closest('[role="tabpanel"]') : null;
+      return p;
+    };
+    const topics = leaves.length ? leaves.map((p) => chainOf(p)) : [{ label: '', key: '', head: null }];
+    // the outermost tab list: the views of the page (the Introduction: executive, then technical)
+    const outer = [...page.querySelectorAll('[role="tablist"]')].filter(visible).find((tl) => !tl.closest('[role="tabpanel"]') && !inSection(tl));
+    const outerTabs = outer ? [...outer.querySelectorAll('[role="tab"]')] : [];
+    const outerPanel = outer && outer.parentElement ? [...outer.parentElement.children].find((c) => c.getAttribute('role') === 'tabpanel' && visible(c)) : null;
+    const captioned = (fig) => {
+      const cap = fig.querySelector('figcaption');
+      if (!cap || !textOf(cap)) return null;
+      const svg = fig.querySelector('svg');
+      const img = [...fig.querySelectorAll('img')].find((i) => /\.svg(\?|#|$)/i.test(i.getAttribute('src') || ''));
+      if (!(svg && visible(svg)) && !(img && visible(img))) return null;
+      return textOf(cap);
+    };
+    const equationCaption = (eq) => {
+      const cap = eq.querySelector('.equation-caption');
+      return cap && textOf(cap) ? textOf(cap) : null;
+    };
+    const sections = [...page.querySelectorAll('[data-doc-section]')].filter(visible).map((sec) => {
+      const mine = (el) => el.closest('[data-doc-section]') === sec && seen(el);
+      const dense = new Set();
+      for (const p of sec.querySelectorAll('p')) {
+        if (!mine(p) || p.closest('.callout, figure, .equation, table, [data-glossary], [data-stat]')) continue;
+        const { words, linkWords } = wordsOf(p);
+        if (words >= 40 && linkWords * 2 < words) dense.add(textOf(p).toLowerCase());
+      }
+      const callouts = [...sec.querySelectorAll('.callout')].filter(mine);
+      const variant = (c) => c.getAttribute('data-callout') || (c.classList.contains('callout-honest') ? 'honest' : c.classList.contains('callout-strong') ? 'strong' : 'note');
+      // what is distinct in this state, so the same thing seen in another state (a sub-tab of the section) counts once
+      const keyed = (els, key) => {
+        const seenKey = new Map();
+        return els.map((e) => {
+          const k = key(e);
+          const n = seenKey.get(k) ?? 0;
+          seenKey.set(k, n + 1);
+          return `${k}#${n}`;
+        });
+      };
+      const hasText = (el) => /[\p{L}\p{N}]/u.test(textOf(el));
+      // glossary items a reader sees: a term and a definition, both visible and holding a letter or a digit
+      const glossary = [...sec.querySelectorAll('[data-glossary]')].filter(mine).reduce((a, g) => {
+        const dts = [...g.querySelectorAll('dt')];
+        if (!dts.length) return a + [...g.querySelectorAll(':scope > li')].filter((li) => seen(li) && hasText(li)).length;
+        return a + dts.filter((dt) => {
+          const dd = dt.nextElementSibling;
+          return seen(dt) && hasText(dt) && dd && dd.tagName === 'DD' && seen(dd) && hasText(dd);
+        }).length;
+      }, 0);
+      const plots = [...sec.querySelectorAll('[data-plot]')].filter(mine);
+      const bare = [...sec.querySelectorAll('canvas, svg[data-chart]')].filter((c) => mine(c) && !c.closest('[data-plot]'));
+      const panel = topicPanel(sec);
+      const topic = panel ? chainOf(panel) : { label: '', key: '', head: null };
+      // the first table of the section: its rows of three or more cells, each proved by a quantified statement
+      const table = [...sec.querySelectorAll('table')].find(mine);
+      const tableRows = table ? [...table.querySelectorAll('tbody tr')].filter((r) => seen(r) && r.querySelectorAll('td, th').length >= 3) : [];
+      const list = [...sec.querySelectorAll('ul, ol')].find((l) => mine(l) && !l.closest('[data-glossary]') && !l.parentElement.closest('ul, ol'));
+      const items = list ? [...list.querySelectorAll(':scope > li')].filter(seen) : [];
+      // the rows of the area: those of its first table, or the items of its first list when the list comes first
+      const rowEls = list && (!table || !(table.compareDocumentPosition(list) & Node.DOCUMENT_POSITION_FOLLOWING)) ? items : tableRows;
+      const nonEmpty = (q, sel) => {
+        const e = q.querySelector(sel);
+        return Boolean(e && seen(e) && /[\p{L}\p{N}]/u.test(textOf(e)));
+      };
+      const eqEls = [...sec.querySelectorAll('.equation')].filter((e) => mine(e) && equationCaption(e));
+      const figEls = [...sec.querySelectorAll('figure')].filter((f) => mine(f) && captioned(f));
+      const honestEls = callouts.filter((c) => variant(c) === 'honest');
+      const strongEls = callouts.filter((c) => variant(c) === 'strong');
+      return {
+        title: ((sec.querySelector('h2') || {}).textContent || '').trim().slice(0, 60),
+        area: sec.getAttribute('data-area'),
+        kind: sec.getAttribute('data-method-kind'),
+        topic: topic.label,
+        topicKey: topic.key,
+        view: topic.head,
+        dense: dense.size,
+        denseKeys: [...dense],
+        equations: eqEls.length,
+        equationKeys: keyed(eqEls, (e) => `${equationCaption(e)}|${(e.querySelector('annotation') || {}).textContent || ''}`),
+        figures: figEls.length,
+        figureKeys: keyed(figEls, (f) => captioned(f)),
+        callouts: callouts.length,
+        calloutKeys: keyed(callouts, (c) => `${variant(c)}|${textOf(c)}`),
+        honest: honestEls.length,
+        honestKeys: keyed(honestEls, (c) => `${variant(c)}|${textOf(c)}`),
+        strong: strongEls.length,
+        strongKeys: keyed(strongEls, (c) => `${variant(c)}|${textOf(c)}`),
+        refs: Number(sec.getAttribute('data-refs')) || 0,
+        glossary,
+        steps: Math.max(0, ...[...sec.querySelectorAll('ol')].filter(mine).map((o) => [...o.querySelectorAll(':scope > li')].filter((li) => seen(li) && hasText(li)).length)),
+        tables: [...sec.querySelectorAll('table')].filter((t) => mine(t) && !t.parentElement.closest('table')).length,
+        codes: [...sec.querySelectorAll('pre')].filter(mine).length,
+        charts: plots.length + bare.length,
+        // a control registered with the panel (data-control), not any button or link
+        controls: [...sec.querySelectorAll('[data-control]')].filter(mine).length,
+        stats: [...sec.querySelectorAll('[data-stat]')].filter((e) => mine(e) && validStat(e)).length,
+        rows: rowEls.length,
+        rowsNoStat: rowEls.filter((r) => ![...r.querySelectorAll('[data-stat]')].some(validStat)).length,
+        items: items.length,
+        thinItems: items.filter((li) => wordsOf(li).words < 6).length,
+        qa: [...sec.querySelectorAll('[data-qa]')].filter((q) => mine(q) && nonEmpty(q, '[data-question]') && nonEmpty(q, '[data-answer]')).length,
+      };
+    });
+    const inView = (sel) => (outerPanel ? [...outerPanel.querySelectorAll(sel)] : [...page.querySelectorAll(sel)]).filter(seen);
+    const selected = outerTabs.find((t) => t.getAttribute('aria-selected') === 'true');
+    return {
+      ledeWords: lede && visible(lede) ? wordsOf(lede).words : 0,
+      waiver: page.getAttribute('data-floor-waiver'),
+      topics,
+      views: outerTabs.map((t) => t.getAttribute('data-tab') || tabLabel(t)),
+      view: selected ? selected.getAttribute('data-tab') || tabLabel(selected) : null,
+      // the executive view holds none anywhere on the page, the part outside the two views included
+      viewEquations: [...page.querySelectorAll('.equation')].filter(seen).length,
+      viewGlossaries: [...page.querySelectorAll('[data-glossary]')].filter(seen).length,
+      sections,
+      figures: inView('figure').map(captioned).filter(Boolean),
+      equations: inView('.equation').map(equationCaption).filter(Boolean),
+    };
+  };
+
   /** A tall view must move when scrolled (S1, G5). Restores the positions it changed. */
   G.scrolls = () => {
     const out = [];
@@ -486,6 +823,7 @@ export function installLib() {
           owner,
           name: tl.getAttribute('aria-label') || '',
           source: Boolean(tl.closest('.cs-source-tabs') || tl.classList.contains('cs-source-tabs')),
+          inSection: Boolean(tl.closest('[data-doc-section]')),
           tabs: tabs.map((t) => (t.getAttribute('data-tab') || (t.textContent || '').trim()).slice(0, 40)),
           active: tabs.findIndex((t) => t.getAttribute('aria-selected') === 'true'),
         };

package/gate/run.mjs

@@ -21,7 +21,7 @@
 //                            wide-font pass: Verdana, else DejaVu Sans, the Linux runner's font)
 //   G11 Spanish numbers      a page in Spanish writes no decimal point (canvas text excepted)
 //   G12 sticky lists         a vertical sub-tab list is still in view at the end of a long section
-//   G13 contrast             every visible text at WCAG AA against the colour behind it (primary size, both themes)
+//   G13 contrast             every visible text at WCAG AA against the colour behind it (primary size, both themes; first language, and every language on a documentation route)
 //   G14 captures index       gate-output/index.html shows every capture by route and mode, the failures first
 // plus the ADR-0071 and ADR-0017 measures (viewport, one-row tabs, rail without scroll, centred prose, captions,
 // references).
@@ -31,6 +31,7 @@ import { join } from 'node:path';
 import { decodePng, paintedBox, unionArea } from './png.mjs';
 import { servePages } from './serve.mjs';
 import { installLib } from './inpage.mjs';
+import { DOC_ROUTES, docFloorFailures } from './areas.mjs';
 
 export const DEFAULTS = {
   sizes: '390x844,768x1024,1280x800,1600x900,2560x1440',
@@ -42,6 +43,7 @@ export const DEFAULTS = {
   textFloor: 400,
   instrumentMin: 0.5,
   stageFillMin: 0.3,
+  stageFloor: 140,
   viewportMinWidth: 1280,
   out: 'gate-output',
   maxShots: 40,
@@ -104,6 +106,7 @@ export async function runGate(o) {
   };
 
   const failures = [];
+  const waivers = []; // ADR-0017 2.1: every waiver a documentation page declares, with its verdict
   // The smallest measured values against each floor, so a pass shows its margin (and a CI font change that eats it
   // is visible before it fails).
   const minima = { drawnShare: null, stageFill: null };
@@ -254,12 +257,13 @@ export async function runGate(o) {
           const mode = `${w}x${h} ${theme} ${lang}`;
           const primary = size === primarySize && theme === themes[0] && lang === langs[0];
           const idleHere = theme === themes[0] && lang === langs[0];
-          const contrast = size === primarySize && lang === langs[0];
           const ctx = await openContext(size, theme, lang);
           const { page, sink } = await newPage(ctx);
           for (const route of routes) {
             const isWorkbench = workbenchRoutes.has(route);
             const at = { route, mode };
+            // G13 runs in the first language; the documentation routes (the prose a reader reads) in every language
+            const contrast = size === primarySize && (lang === langs[0] || DOC_ROUTES.includes(route));
             const res = await page.goto(urlFor(route), { waitUntil: 'load', timeout: 30000 }).catch((e) => e);
             const status = res && typeof res.status === 'function' ? res.status() : `error ${res?.message ?? res}`;
             if (status !== 200) {
@@ -279,7 +283,9 @@ export async function runGate(o) {
             if (!String(id.lang ?? '').startsWith(lang)) fail('G2', at, `asked for ${lang} through ${LANG_STORAGE_KEY}; <html lang> is ${id.lang}`);
             if (route !== '/' && id.activeHref && routeOf(id.activeHref) !== route) fail('G4', at, `loaded directly, the page shows route ${routeOf(id.activeHref)}`);
 
-            const walkState = { tested: new Set(), keyedViews: 0, controls: 0, tablists: 0 };
+            // ADR-0017 2.1: the documentation floors are measured once per language, at the primary size and first theme
+            const docFloors = size === primarySize && theme === themes[0] && DOC_ROUTES.includes(route);
+            const walkState = { tested: new Set(), keyedViews: 0, controls: 0, tablists: 0, doc: docFloors ? [] : null };
             await processState(page, sink, { ...at, trail: '' }, { route, isWorkbench, primary, idle: idleHere, first: true, size, w, h, theme, lang, walkState, contrast });
 
             if (primary && route !== '/') {
@@ -300,7 +306,8 @@ export async function runGate(o) {
               sink.splice(0);
             }
 
-            await walkTabs(page, sink, { ...at }, [], new Set(), { route, isWorkbench, primary, idle: primary, size, w, h, theme, lang, walkState, contrast });
+            const leaves = await walkTabs(page, sink, { ...at }, [], new Set(), { route, isWorkbench, primary, idle: primary, size, w, h, theme, lang, walkState, contrast });
+            if (walkState.doc) docResult(at, lang, walkState.doc, Math.max(1, leaves));
 
             if (isWorkbench) await walkCases(page, sink, at, { route, isWorkbench, primary, size, w, h, theme, lang, walkState, contrast });
 
@@ -410,11 +417,19 @@ export async function runGate(o) {
     if (f.truncatedCount) fail('G5', where, `${f.truncatedCount} truncated text(s) without the full text in a title: ${f.truncated.join('; ')}`);
     for (const c of f.clipped) fail('G5', where, c);
     if (f.offCentre !== null && f.offCentre > 2) fail('ADR-0017.1', where, `the prose page is off-centre by ${f.offCentre.toFixed(1)}px`);
-    if (f.referenceLists) fail('ADR-0017.4', where, `${f.referenceLists} bibliography dump(s); references belong at the end of each section`);
+    if (f.referenceLists) fail('ADR-0017.4', where, `${f.referenceLists} bibliography outside the end-of-page references block (a .reference-list); give each DocSection its refs and let the page list them once`);
+    if (f.referencesNotLast) fail('ADR-0017.4', where, `${f.referencesNotLast} references block(s) with content after them; references must be the last block of the page or tab`);
+    if (f.refsDeclaredNoBlock) fail('ADR-0017.4', where, `${f.refsDeclaredNoBlock} section(s) cite references the page never lists (no references block in their page or tab)`);
     if (f.uncaptioned) fail('ADR-0017.2', where, `${f.uncaptioned} equation(s) without a caption`);
+    if (s.walkState?.doc) {
+      const d = await page.evaluate(() => window.__caosGate.docPage());
+      if (d) s.walkState.doc.push(d);
+    }
     for (const r of f.repeatedTicks ?? []) {
       fail('G6', where, `${r.label}: ${r.n} axis tick label(s) repeat the label before them (give the axis fixed decimals)`);
     }
+    // a filling card whose note leaves its drawing under the floor (CAOS_APP_SHELL#95); below 1280 px the document scrolls
+    if (big) for (const c of f.fillStages ?? []) if (c.h < opt.stageFloor) fail('G6', where, `the drawing of ${c.label} keeps ${Math.round(c.h)} px under its note (floor ${opt.stageFloor} px)`);
     for (const m of await page.evaluate(() => window.__caosGate.drawingText())) fail('G10', where, m);
     if (s.lang === 'es') for (const m of await page.evaluate(() => window.__caosGate.decimals())) fail('G11', where, m);
     if (s.w > 760) for (const m of await page.evaluate(() => window.__caosGate.sticky())) fail('G12', where, m);
@@ -452,6 +467,13 @@ export async function runGate(o) {
 
   async function paintedChecks(page, f, where, big) {
     if (f.prose) return; // the context write-up is prose, measured as a document, not as a drawing
+    if (f.surfaces.length === 0 && f.unavailable) {
+      // a declared absence a reader can see and read (ADR-0080 decision 3): nothing to draw, every other check still ran
+      if (f.drawn > 0) fail('G6', where, `a drawing is present but not visible beside a data-state="unavailable" note (${f.drawn} drawing element(s) rendered in the instrument, collapsed, hidden or too small to see): draw it, or remove it`);
+      else if (f.unavailable === 'unexplained') fail('G6', where, 'the instrument declares data-state="unavailable" and draws nothing, but gives no reason (the text a reader sees needs at least 12 letters or digits in two words or more, saying why the data is absent)');
+      else if (f.unavailable === 'unseen') fail('G6', where, 'the instrument declares data-state="unavailable" and draws nothing, but no reader can see the note (it needs a visible box of at least 40 x 12 px inside the instrument, not transparent, not clipped, not off-screen)');
+      return;
+    }
     if (f.surfaces.length === 0) {
       fail('G6', where, 'nothing is drawn in the instrument (no canvas, svg drawing, image or table)');
       return;
@@ -527,7 +549,9 @@ export async function runGate(o) {
     }
   }
 
+  /** Walks every tab of every list owned by `trail`; returns the number of leaf topics found (a tab with no list inside it is one; a list inside a documentation section adds none). */
   async function walkTabs(page, sink, where, trail, handled, s) {
+    let leaves = 0;
     const lists = (await page.evaluate(() => window.__caosGate.tablists())).filter((l) => !handled.has(l.key) && !l.source);
     const parentKey = trail.length ? trail[trail.length - 1].key : null;
     const mine = lists.filter((l) => (parentKey ? l.owner === parentKey : l.owner === null));
@@ -546,13 +570,16 @@ export async function runGate(o) {
             await tab.click({ timeout: 5000 });
           } catch (e) {
             fail('G7', at, `the tab could not be clicked: ${e.message.split('\n')[0]}`);
+            if (!tl.inSection) leaves += 1;
             continue;
           }
           const why = await settle(page);
           if (why) fail('G7', at, `never settled: ${why}`);
           await processState(page, sink, at, { ...s, first: false, idle: s.idle });
         }
-        await walkTabs(page, sink, where, here, new Set(handled), s);
+        const inner = await walkTabs(page, sink, where, here, new Set(handled), s);
+        // the tabs of a list inside a documentation section are visited, but they are parts of that section, not topics
+        if (!tl.inSection) leaves += inner === 0 ? 1 : inner;
       }
       if (tl.active >= 0 && tl.tabs.length > 1) {
         await page.locator(tl.key).locator('[role="tab"]').filter({ visible: true }).nth(tl.active).click({ timeout: 5000 }).catch(() => undefined);
@@ -560,6 +587,14 @@ export async function runGate(o) {
         sink.splice(0);
       }
     }
+    return leaves;
+  }
+
+  /** ADR-0017 2.1: applies the area table (gate/areas.mjs) to what a documentation page showed in one language. */
+  function docResult(at, lang, states, expectedTopics) {
+    const r = docFloorFailures({ route: at.route, lang, states, expectedTopics });
+    for (const f of r.failures) fail('ADR-0017.2', { ...at, trail: f.trail }, f.message);
+    for (const w of r.waivers) waivers.push({ route: at.route, lang, ...w });
   }
 
   async function walkCases(page, sink, at, s) {
@@ -671,6 +706,7 @@ export async function runGate(o) {
       wideFontSizes: opt.wideFont === false ? '' : opt.wideFontSizes,
       states,
       minima,
+      waivers,
       checks,
       captures: captures.length,
       failures,
@@ -708,8 +744,10 @@ export function captureIndex(report, captures) {
     '.grid{display:grid;grid-template-columns:repeat(auto-fill,minmax(320px,1fr));gap:12px}figure{margin:0;background:#fff;border:1px solid #d0d7de;padding:6px}' +
     'img{width:100%;height:auto;display:block}figcaption{font-size:11px;color:#57606a;margin-top:4px}';
   const head = `caos-shell-gate: ${esc(report.expectBrand)} at ${esc(report.base)}: ${report.ok ? 'OK' : `${report.failures.length} failure(s)`} in ${report.states} states, ${captures.length} captures`;
+  const wrows = (report.waivers ?? []).map((w) => `<tr><td>${esc(w.route)}</td><td>${esc(w.lang)}</td><td>${esc(w.floor)}</td><td>${esc(w.reason)}</td><td>${w.valid ? 'accepted' : 'refused'}</td></tr>`).join('');
+  const waiverTable = wrows ? `<h2>Waivers (${report.waivers.length})</h2><table><tr><td>route</td><td>language</td><td>floor</td><td>reason</td><td>verdict</td></tr>${wrows}</table>` : '';
   const table = rows ? `<table><tr><td>check</td><td>route</td><td>mode</td><td>trail</td><td>message</td></tr>${rows}</table>` : '';
-  return `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>${head}</title><style>${style}</style></head><body><h1>${head}</h1>${table}${sections}</body></html>\n`;
+  return `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>${head}</title><style>${style}</style></head><body><h1>${head}</h1>${table}${waiverTable}${sections}</body></html>\n`;
 }
 
 function slug(route) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fasl-work/caos-app-shell",
-  "version": "0.10.0",
+  "version": "0.11.1",
   "description": "Shared web-app shell, workbench primitives, content primitives, design system and measured gate for the CAOS / Faena public apps (ADR-0016, ADR-0017, ADR-0071).",
   "license": "MIT",
   "author": "Felipe Santibáñez-Leal",
@@ -50,7 +50,8 @@
     "prepare": "npm run build",
     "prepublishOnly": "npm run build",
     "prebuild": "node scripts/reserved-classes.mjs",
-    "test:gate": "node --test test/gate-selftest.mjs"
+    "test:gate": "node --test test/gate-selftest.mjs",
+    "check:sdd": "python scripts/check_sdd.py ."
   },
   "peerDependencies": {
     "katex": "^0.16.0",

package/reserved-classes.json

@@ -35,6 +35,8 @@
     "caos-cw-context",
     "caos-cw-panel",
     "caos-cw-panel-head",
+    "caos-doc-reference-list",
+    "caos-doc-references",
     "caos-doc-section",
     "caos-field",
     "caos-focus-actions",
@@ -52,6 +54,8 @@
     "caos-gauge-track",
     "caos-gauge-value",
     "caos-gauge-zone",
+    "caos-glossary",
+    "caos-glossary-item",
     "caos-knob",
     "caos-knob-head",
     "caos-knob-value",
@@ -69,6 +73,9 @@
     "caos-prov-published",
     "caos-prov-real",
     "caos-prov-synthetic",
+    "caos-qa",
+    "caos-qa-answer",
+    "caos-qa-question",
     "caos-readout",
     "caos-readout-head",
     "caos-readout-row",
@@ -79,6 +86,8 @@
     "caos-stale",
     "caos-stale-note",
     "caos-stale-overlay",
+    "caos-stat-source",
+    "caos-stat-value",
     "caos-surface",
     "caos-surface-actions",
     "caos-surface-body",
@@ -268,6 +277,8 @@
     "caos-cw-context",
     "caos-cw-panel",
     "caos-cw-panel-head",
+    "caos-doc-reference-list",
+    "caos-doc-references",
     "caos-doc-section",
     "caos-field",
     "caos-focus-actions",
@@ -285,6 +296,8 @@
     "caos-gauge-track",
     "caos-gauge-value",
     "caos-gauge-zone",
+    "caos-glossary",
+    "caos-glossary-item",
     "caos-knob",
     "caos-knob-head",
     "caos-knob-value",
@@ -302,6 +315,9 @@
     "caos-prov-published",
     "caos-prov-real",
     "caos-prov-synthetic",
+    "caos-qa",
+    "caos-qa-answer",
+    "caos-qa-question",
     "caos-readout",
     "caos-readout-head",
     "caos-readout-row",
@@ -312,6 +328,8 @@
     "caos-stale",
     "caos-stale-note",
     "caos-stale-overlay",
+    "caos-stat-source",
+    "caos-stat-value",
     "caos-surface",
     "caos-surface-actions",
     "caos-surface-body",