@fasl-work/caos-app-shell 0.13.1 → 0.14.1

package/gate/areas.mjs

@@ -629,3 +629,70 @@ export function docFloorFailures({ route, lang, states, expectedTopics }) {
   }
   return { failures, waivers, topics: topics.size };
 }
+
+// ------------------------------------------------------------------------------------------ flip cards and animation
+// Shell 0.14.0 (CAOS_MANAGE plans/app-shell/0-14-0-plan.md decisions 3 and 4).
+
+/** The limits of a small card, in the interface language; a copy of FLIP_LIMITS of src/content/FlipCard.tsx (test/flipCard.test.tsx keeps them equal). */
+export const FLIP_LIMITS = { title: { en: 8, es: 10 }, back: { en: 40, es: 50 } };
+
+/** The longest an illustration may play: one play, or one cycle of a loop, with its delay, in seconds. */
+export const ANIMATION_MAX_SECONDS = 10;
+
+const seconds = (v) => {
+  const m = /^\s*(\d*\.?\d+)\s*(ms|s)?\s*$/i.exec(String(v ?? ''));
+  return m ? Number(m[1]) / (m[2]?.toLowerCase() === 'ms' ? 1000 : 1) : 0;
+};
+
+/**
+ * What an SVG file says about its animation: `css` (keyframes or an `animation` declaration), `smil` (animate, animateTransform,
+ * animateMotion, set), whether it carries a `@media (prefers-reduced-motion: reduce)` block, whether that block stops the CSS
+ * animation (`animation: none` or `animation-name: none`), and the longest cycle with its longest delay, in seconds (a loop counts one
+ * cycle; an indefinite or absent duration counts as zero).
+ */
+export function analyseSvgAnimation(text) {
+  const src = String(text ?? '');
+  const styles = [...src.matchAll(/<style[^>]*>([\s\S]*?)<\/style>/gi)].map((m) => m[1]).concat([...src.matchAll(/\sstyle="([^"]*)"/gi)].map((m) => m[1]));
+  const css = styles.join('\n');
+  const smilEls = [...src.matchAll(/<(animate|animateTransform|animateMotion|set)\b([^>]*)>/gi)];
+  const hasKeyframes = /@keyframes/i.test(css);
+  const hasAnimationDecl = /(^|[;{\s])animation(-name)?\s*:\s*(?!none\b)[^;}]+/i.test(css.replace(/@media[^{]*\(prefers-reduced-motion:\s*reduce\)\s*\{[\s\S]*?\}\s*\}/gi, ''));
+  const cssAnimated = hasKeyframes || hasAnimationDecl;
+  const smil = smilEls.length > 0;
+  const block = /@media\s*\(\s*prefers-reduced-motion\s*:\s*reduce\s*\)\s*\{([\s\S]*?\}\s*)\}/i.exec(css);
+  const reducedBlock = Boolean(block);
+  const neutralises = Boolean(block && /animation(-name)?\s*:\s*none/i.test(block[1]));
+  let maxDur = 0;
+  let maxDelay = 0;
+  let maxCount = 1;
+  const outsideReduced = css.replace(/@media[^{]*\(prefers-reduced-motion:\s*reduce\)\s*\{[\s\S]*?\}\s*\}/gi, '');
+  // the shorthand `animation: name 8s 3s infinite`: the first time is the duration, the second the delay
+  for (const m of outsideReduced.matchAll(/(?:^|[;{\s])animation\s*:\s*([^;}]+)/gi)) {
+    const times = [...m[1].matchAll(/(\d*\.?\d+)(ms|s)\b/gi)].map((t) => seconds(t[0]));
+    maxDur = Math.max(maxDur, times[0] ?? 0);
+    maxDelay = Math.max(maxDelay, times[1] ?? 0);
+    // a finite count of cycles plays that many times (infinite counts one)
+    if (!/infinite/i.test(m[1])) maxCount = Math.max(maxCount, Number((/(?:^|\s)(\d*\.?\d+)(?=\s|$)/.exec(m[1].replace(/(\d*\.?\d+)(ms|s)/gi, ' ')) ?? [])[1] ?? 1));
+  }
+  for (const m of outsideReduced.matchAll(/(?:^|[;{\s])animation-iteration-count\s*:\s*([^;}]+)/gi)) if (!/infinite/i.test(m[1])) maxCount = Math.max(maxCount, Number(m[1].split(',')[0]) || 1);
+  for (const m of outsideReduced.matchAll(/(?:^|[;{\s])animation-duration\s*:\s*([^;}]+)/gi)) maxDur = Math.max(maxDur, seconds(m[1].split(',')[0]));
+  for (const m of outsideReduced.matchAll(/(?:^|[;{\s])animation-delay\s*:\s*([^;}]+)/gi)) maxDelay = Math.max(maxDelay, seconds(m[1].split(',')[0]));
+  // the longest duration with the longest delay: a safe bound (the rules of the file are not matched to their elements)
+  let longest = maxDur * maxCount + maxDelay;
+  for (const m of smilEls) {
+    const attr = (n) => new RegExp(`\\s${n}="([^"]*)"`, 'i').exec(m[2])?.[1];
+    const reps = Number(attr('repeatCount')) || 1;
+    longest = Math.max(longest, seconds(attr('dur')) * reps + seconds(attr('begin')));
+  }
+  return { animated: cssAnimated || smil, css: cssAnimated, smil, reducedBlock, neutralises, seconds: Math.round(longest * 1000) / 1000 };
+}
+
+/** The problems of one illustration's animation (empty for a still); `name` is how the page calls it. */
+export function animationFailures(a, name) {
+  if (!a || !a.animated) return [];
+  const out = [];
+  if (!a.reducedBlock) out.push(`illustration "${name}" is animated and has no @media (prefers-reduced-motion: reduce) block that shows its static final frame`);
+  else if (a.css && !a.neutralises) out.push(`illustration "${name}" is animated and its reduced-motion block does not stop its CSS animation (animation: none)`);
+  if (a.seconds > ANIMATION_MAX_SECONDS) out.push(`illustration "${name}" plays for ${Math.round(a.seconds)} s; the limit is ${ANIMATION_MAX_SECONDS} s`);
+  return out;
+}

package/gate/inpage.mjs

@@ -622,6 +622,20 @@ export function installLib() {
     const executive = (() => {
       if (!execRoots.length) return { count: 0 };
       const root = execRoots[0];
+      // A card the carousel's window hides (`hidden` on its item) is out of sight by design: G16 walks the carousel and fails one it
+      // cannot reach. Any other card that is not seen is not shown, as before 0.14.0.
+      const hiddenByDeck = (el) => {
+        const li = el.closest('[data-deck-card]');
+        return Boolean(li) && li.hidden && Boolean(li.closest('[data-deck-mode="carousel"]'));
+      };
+      // The back of a flip card is content the reader gets by turning the card: read every field with the cards turned too (the
+      // same `seen` and `innerText` as for any text), and call a field readable when it is seen in either face.
+      const turned = new Map();
+      withFlipsTurned(() => {
+        for (const e of root.querySelectorAll('[data-exec-field], [data-exec-cdef]')) turned.set(e, { text: textOf(e), seen: seen(e) });
+      });
+      const fullText = (e) => textOf(e) || (turned.get(e) ? turned.get(e).text : '');
+      const isSeen = (e) => seen(e) || Boolean(turned.get(e) && turned.get(e).seen);
       const isTok = (v) => {
         const x = String(v || '').trim().toLowerCase();
         return !x || ['none', 'currentcolor', 'transparent', 'inherit', 'initial', 'unset', 'context-fill', 'context-stroke'].includes(x) || x.startsWith('var(--') || x.startsWith('url(');
@@ -674,7 +688,8 @@ export function installLib() {
       });
       // the rows each part of the view shows in this state (the floors), counted once per kind
       const items = {};
-      for (const el of root.querySelectorAll('[data-exec-item]')) if (seen(el)) items[el.getAttribute('data-exec-item')] = (items[el.getAttribute('data-exec-item')] ?? 0) + 1;
+      // a card of a carousel counts although the window hides it (G16 proves every card can be reached); a flip card counts whole
+      for (const el of root.querySelectorAll('[data-exec-item]')) if (seen(el) || hiddenByDeck(el)) items[el.getAttribute('data-exec-item')] = (items[el.getAttribute('data-exec-item')] ?? 0) + 1;
       const landingEl = root.querySelector('[data-exec-landing]');
       const landing = {
         present: Boolean(landingEl && seen(landingEl)),
@@ -683,8 +698,8 @@ export function installLib() {
       };
       // the 4 C's a reader sees in the proposal: the name, the definition and what each means for the proposal
       const cs = [...root.querySelectorAll('[data-exec-c]')]
-        .filter(seen)
-        .map((li) => ({ name: textOf(li.querySelector('[data-exec-cname]') || li), def: textOf(li.querySelector('[data-exec-cdef]') || li), applies: textOf(li.querySelector('[data-exec-field$=".applies"]') || li.querySelector('span') || li) }));
+        .filter((li) => seen(li) || hiddenByDeck(li))
+        .map((li) => ({ name: textOf(li.querySelector('[data-exec-cname]') || li), def: fullText(li.querySelector('[data-exec-cdef]') || li), applies: fullText(li.querySelector('[data-exec-field$=".applies"]') || li.querySelector('span') || li) }));
       const links = [...root.querySelectorAll('[data-exec-links] a')].map((a) => ({ kind: a.getAttribute('data-exec-link'), text: textOf(a), href: a.getAttribute('href') }));
       // the sub-tabs of the view: their labels (all of them, shown or not), and the one selected
       const tabEls = [...root.querySelectorAll('[data-exec-tabs] [role="tab"]')];
@@ -712,7 +727,7 @@ export function installLib() {
         items,
         cs,
         links,
-        fields: [...root.querySelectorAll('[data-exec-field]')].map((e) => ({ path: e.getAttribute('data-exec-field'), text: textOf(e), readable: seen(e) })),
+        fields: [...root.querySelectorAll('[data-exec-field]')].map((e) => ({ path: e.getAttribute('data-exec-field'), text: fullText(e), readable: isSeen(e) || hiddenByDeck(e) })),
         // the blocks of this state narrower than the document column (an illustration may stay centred inside its figure)
         narrow: [...root.querySelectorAll('.subtabs, .caos-exec-notes-wrap, [data-exec-section], [data-exec-section] > *')]
           .filter((e) => visible(e))
@@ -721,7 +736,7 @@ export function installLib() {
           .map(([name, w]) => `${name} ${w}px`),
         column: columnWidth,
         // everything the view prints in this state, for the check that no rubric label or question is on the page
-        text: textOf(root),
+        text: `${textOf(root)} ${[...turned.entries()].filter(([e]) => e.closest('[data-flip-back]')).map(([, v]) => v.text).join(' ')}`,
         tabs: tabEls.map(tabLabel),
         activeTab: tabEls.findIndex((t) => t.getAttribute('aria-selected') === 'true'),
         // each source note: the link it holds (its target and its text) and the text beside the link
@@ -909,6 +924,137 @@ export function installLib() {
     return { checked, unreachable: out.slice(0, 8), unreachableCount: out.length };
   };
 
+  /**
+   * Runs `fn` with every closed flip card turned (and no transition, so the faces are settled), then turns them back. The gate
+   * reads a back with the same measures it uses for any text; a back the card can never show stays unreadable.
+   */
+  const withFlipsTurned = (fn) => {
+    const cards = [...document.querySelectorAll('[data-flip-card][data-flip-open="false"]')];
+    if (cards.length === 0) return fn();
+    const st = document.createElement('style');
+    st.textContent = '.caos-flip, .caos-flip * { transition: none !important; }';
+    document.head.append(st);
+    for (const c of cards) c.setAttribute('data-flip-open', 'true');
+    try {
+      return fn();
+    } finally {
+      for (const c of cards) c.setAttribute('data-flip-open', 'false');
+      st.remove();
+    }
+  };
+  // ---- G16: flip cards and card decks (shell 0.14.0)
+  const inTree = (el) => {
+    // reachable by assistive technology and by the keyboard: rendered, and no ancestor hides it or makes it inert
+    if (!el.checkVisibility({ checkVisibilityCSS: true })) return false;
+    for (let e = el; e; e = e.parentElement) if (e.getAttribute('aria-hidden') === 'true' || e.hasAttribute('inert') || e.hidden) return false;
+    return true;
+  };
+  /** A control a keyboard or a pointer can reach: rendered, no `inert` ancestor. `aria-hidden` does not take a control out of the tab order. */
+  const reachable = (el) => {
+    if (!el.checkVisibility({ checkVisibilityCSS: true })) return false;
+    for (let e = el; e; e = e.parentElement) if (e.hasAttribute('inert')) return false;
+    return true;
+  };
+  const countWords = (t) => String(t || '').split(/\s+/).filter((w) => /[\p{L}\p{N}]/u.test(w)).length;
+  /** What the flip cards and the card decks of this state are: their words, their buttons, what the hidden face exposes, where a deck ends. */
+  G.cards = () => {
+    const squash = (e) => (e ? (e.textContent || '').replace(/\s+/g, ' ').trim() : '');
+    const vw = window.innerWidth;
+    const cards = [...document.querySelectorAll('[data-flip-card]')].map((card, index) => {
+      const open = card.getAttribute('data-flip-open') === 'true';
+      const front = card.querySelector('.caos-flip-front');
+      const back = card.querySelector('[data-flip-back]');
+      const hiddenFace = open ? front : back;
+      const toggles = [...card.querySelectorAll('[data-flip-toggle]')];
+      const owned = toggles.length > 0 && toggles.every((t) => { const id = t.getAttribute('aria-controls'); return id && document.getElementById(id) && t.hasAttribute('aria-expanded'); });
+      const exposed = hiddenFace ? hiddenFace.querySelectorAll('button, a[href], input, select, textarea, [tabindex]:not([tabindex="-1"])') : [];
+      return {
+        index,
+        label: squash(card.querySelector('[data-flip-title]')).slice(0, 40) || `card ${index + 1}`,
+        titleWords: countWords(squash(card.querySelector('[data-flip-title]'))),
+        backWords: countWords(squash(card.querySelector('[data-flip-content]'))),
+        open,
+        shown: inTree(card) || card.getClientRects().length > 0,
+        buttons: toggles.length > 0 && toggles.every((t) => t.tagName === 'BUTTON'),
+        wired: owned,
+        hiddenInTree: Boolean(hiddenFace) && inTree(hiddenFace),
+        hiddenFocusable: [...exposed].some(reachable),
+        contentShown: (() => { const c = card.querySelector('[data-flip-content]'); if (!c || !c.checkVisibility({ checkVisibilityCSS: true })) return false; const r = c.getBoundingClientRect(); return r.height > 0 && r.width > 0; })(),
+        deck: Array.from(document.querySelectorAll('[data-card-deck]')).findIndex((d) => d.contains(card)),
+      };
+    });
+    const decks = [...document.querySelectorAll('[data-card-deck]')].map((deck, index) => {
+      const track = deck.querySelector('[data-deck-track]');
+      const box = deck.getBoundingClientRect();
+      const lis = [...deck.querySelectorAll('[data-deck-card]')];
+      const shownCards = lis.filter((li) => li.checkVisibility({ checkVisibilityCSS: true }));
+      const outside = shownCards.filter((li) => { const r = li.getBoundingClientRect(); return r.right > box.right + 1 || r.left < box.left - 1; });
+      const next = deck.querySelector('[data-deck-next]');
+      const prev = deck.querySelector('[data-deck-prev]');
+      return {
+        index,
+        label: deck.getAttribute('aria-label') || (track && track.getAttribute('aria-label')) || `deck ${index + 1}`,
+        mode: deck.getAttribute('data-deck-mode'),
+        total: lis.length,
+        visible: lis.map((li, i) => (li.checkVisibility({ checkVisibilityCSS: true }) ? i : -1)).filter((i) => i >= 0),
+        flip: deck.hasAttribute('data-deck-flip'),
+        controls: Boolean(next && prev) && next.checkVisibility({ checkVisibilityCSS: true }) && prev.checkVisibility({ checkVisibilityCSS: true }),
+        atEnd: next ? next.getAttribute('aria-disabled') === 'true' : true,
+        atStart: prev ? prev.getAttribute('aria-disabled') === 'true' : true,
+        sideways: Math.max(deck.scrollWidth - deck.clientWidth, track ? track.scrollWidth - track.clientWidth : 0) > 1 || box.right > vw + 1 || outside.length > 0 || (track ? track.getBoundingClientRect().right > box.right + 1 : false),
+        outside: outside.length,
+        docW: document.documentElement.scrollWidth,
+        vw,
+      };
+    });
+    return { lang: (document.documentElement.lang || 'en').slice(0, 2) === 'es' ? 'es' : 'en', cards, decks };
+  };
+
+  // ---- G17: animated illustrations (shell 0.14.0)
+  /** The SVG drawings of the page (the executive illustrations and the figures): their markup, and what still moves in them. */
+  G.animations = () => {
+    const items = [...document.querySelectorAll('figure svg, [data-exec-illustration] svg')].filter((v, i, a) => a.indexOf(v) === i).map((svg, i) => {
+      const fig = svg.closest('[data-exec-illustration]');
+      const smil = svg.querySelector('animate, animateTransform, animateMotion, set');
+      const css = document.getAnimations().filter((a) => a.effect && a.effect.target && svg.contains(a.effect.target) && a.playState === 'running').length;
+      return { name: fig ? fig.getAttribute('data-exec-illustration') : `figure ${i + 1}`, svg: svg.outerHTML, runningCss: css, runningSmil: smil ? !svg.animationsPaused() : false, smil: Boolean(smil) };
+    });
+    return { items };
+  };
+
+  /** The documentation figures drawn by an `img` of an SVG file: their sources (the runner fetches and analyses them). */
+  G.figureImages = () => [...document.querySelectorAll('figure img')].filter((i) => /\.svg(\?|#|$)/i.test(i.getAttribute('src') || '')).map((i, k) => ({ name: `figure ${k + 1}`, src: i.currentSrc || i.src }));
+
+  // ---- G18: Focus mode for the App (shell 0.14.0)
+  /** The App or Focus mode as the reader meets it: which one, the case and the group, the URL, the page and the rail. */
+  G.focusFacts = () => {
+    const shell = document.querySelector('[data-focus-shell]');
+    const stage = document.querySelector('[data-case-workbench]');
+    const rail = document.querySelector('.caos-focus-rail');
+    const lists = [...document.querySelectorAll('[data-focus-shell] [role="tablist"]')].filter(visible);
+    const rows = lists.map((t) => new Set([...t.querySelectorAll('[role="tab"]')].map((b) => Math.round(b.getBoundingClientRect().top))).size);
+    const panel = stage ? stage.querySelector('[role="tabpanel"]') : null;
+    const st = document.querySelector('.caos-focus-stage');
+    const box = st ? st.getBoundingClientRect() : null;
+    return {
+      focus: Boolean(shell),
+      app: Boolean(document.querySelector('[data-workbench]')),
+      caseId: stage ? stage.getAttribute('data-case') : null,
+      group: shell ? (stage ? stage.getAttribute('data-focus-group') : null) : panel ? panel.getAttribute('data-panel') : null,
+      search: location.search,
+      subview: (() => { const t = document.querySelector('[data-case-workbench] .subtab.active'); return t ? t.getAttribute('data-tab') : null; })(),
+      nestedMain: document.querySelectorAll('main').length > 1 || Boolean(document.querySelector('main main')),
+      vw: window.innerWidth,
+      vh: window.innerHeight,
+      docW: document.documentElement.scrollWidth,
+      docH: document.documentElement.scrollHeight,
+      rail: rail ? { scroll: rail.scrollHeight, client: rail.clientHeight } : null,
+      tabRows: rows,
+      share: box ? (box.width * box.height) / (window.innerWidth * window.innerHeight) : 0,
+      exitInside: (() => { const e = document.querySelector('[data-focus-exit]'); if (!e) return null; const r = e.getBoundingClientRect(); return r.width > 0 && r.right <= window.innerWidth + 1 && r.bottom <= window.innerHeight + 1; })(),
+    };
+  };
+
   /** Animation frames and DOM mutations over a window at rest (G8). */
   G.idle = (ms) =>
     new Promise((done) => {

package/gate/run.mjs

@@ -23,6 +23,11 @@
 //   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; 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
+//   G16 flip cards, decks    a flip card is a small card (title and back within the limits), a real button that turns with Enter and
+//                            Space, its hidden face out of the accessibility tree; a carousel reaches every card, never scrolls sideways
+//   G17 animated drawings    an animated SVG has its reduced-motion block, plays for 10 s at most and is still under reduced motion
+//   G18 Focus mode           the App's Focus control opens the case's open group in the full viewport and returns to the same case and
+//                            group (by the exit control and by Escape); no page scroll, the rail without scroll, one tab row
 // plus the ADR-0071 and ADR-0017 measures (viewport, one-row tabs, rail without scroll, centred prose, captions,
 // references).
 
@@ -31,7 +36,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';
+import { DOC_ROUTES, FLIP_LIMITS, analyseSvgAnimation, animationFailures, docFloorFailures } from './areas.mjs';
 
 export const DEFAULTS = {
   sizes: '390x844,768x1024,1280x800,1600x900,2560x1440',
@@ -49,6 +54,7 @@ export const DEFAULTS = {
   maxShots: 40,
   wideFont: true,
   wideFontSizes: '390x844,1280x800',
+  requireFocus: false,
 };
 
 /** The wide fallback font of the G10 pass: wider than the Windows and macOS sans fonts; DejaVu Sans is what a Linux
@@ -107,6 +113,7 @@ export async function runGate(o) {
   };
 
   const failures = [];
+  const focusReported = new Set(); // G18: an App without a Focus control is reported once per route and mode
   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).
@@ -311,7 +318,7 @@ export async function runGate(o) {
             // 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 });
+            await processState(page, sink, { ...at, trail: '' }, { route, isWorkbench, primary, idle: idleHere, interact: idleHere, first: true, size, w, h, theme, lang, walkState, contrast });
 
             if (primary) {
               // G4: the trailing-slash form a static host serves for a materialised route.
@@ -331,10 +338,10 @@ export async function runGate(o) {
               sink.splice(0);
             }
 
-            const leaves = 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, interact: idleHere, 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 });
+            if (isWorkbench) await walkCases(page, sink, at, { route, isWorkbench, primary, interact: idleHere, size, w, h, theme, lang, walkState, contrast });
 
             if (primary && isWorkbench) {
               const f = await page.evaluate(() => window.__caosGate.facts());
@@ -484,6 +491,9 @@ export async function runGate(o) {
     const reach = await page.evaluate(() => window.__caosGate.reach());
     if (reach.unreachableCount) fail('G5', where, `${reach.unreachableCount} control(s) not reachable by the pointer: ${reach.unreachable.join('; ')}`);
 
+    await cardChecks(page, where, s);
+    if (s.primary) await animationChecks(page, where);
+
     if (s.primary && s.isWorkbench && s.walkState) await reactivity(page, sink, where, s);
     drain(sink, where);
     const failedHere = failures.some((x) => x.route === where.route && x.mode === where.mode && x.trail === where.trail && x.check !== 'G3');
@@ -650,6 +660,7 @@ export async function runGate(o) {
         if (shownCase !== caseId) fail('G9', where, `asked for case ${caseId}; the workbench shows ${shownCase}`);
         await processState(page, sink, where, { ...s, first: false, idle: false });
         if (s.primary) await walkTabs(page, sink, where, [], new Set(), { ...s, idle: false });
+        await focusVisit(page, sink, where, s, caseId, pickedIndex(pick, caseId), total);
       }
       if (s.primary && pick.length) {
         // A deep link selects the case it names (G9).
@@ -667,6 +678,251 @@ export async function runGate(o) {
     if (total === 0 && !opt.singleCase) fail('G9', at, 'the workbench offers no case ([data-control="case"]); declare --single-case if it has one');
   }
 
+  // ---------------------------------------------------------------------------------------------------- G16, G17, G18
+  function pickedIndex(list, id) {
+    return list.indexOf(id);
+  }
+  function idleAnimations(page) {
+    return page.waitForFunction('document.getAnimations().filter((a) => a.transitionProperty === "transform" || a.transitionProperty === "visibility" || a.animationName === "caos-deck-in").length === 0', undefined, { timeout: 3000 }).catch(() => undefined);
+  }
+
+  /** G16: the flip cards and the card decks of the state (facts), and, in the first theme and language, their interactions. */
+  async function cardChecks(page, where, s) {
+    const f = await page.evaluate(() => window.__caosGate.cards());
+    if (f.cards.length === 0 && f.decks.length === 0) return;
+    for (const c of f.cards) {
+      const tl = FLIP_LIMITS.title[f.lang];
+      const bl = FLIP_LIMITS.back[f.lang];
+      if (c.titleWords > tl) fail('G16', where, `flip card "${c.label}": a title of ${c.titleWords} words; the limit is ${tl} (${f.lang}); a flip card is a small card, a long one stays plain`);
+      if (c.backWords > bl) fail('G16', where, `flip card "${c.label}": a back of ${c.backWords} words; the limit is ${bl} (${f.lang}); a flip card is a small card, a long one stays plain`);
+      if (!c.buttons || !c.wired) fail('G16', where, `flip card "${c.label}": its faces are not real buttons with aria-expanded and aria-controls naming the back`);
+      if (c.hiddenInTree) fail('G16', where, `flip card "${c.label}": the hidden ${c.open ? 'face' : 'back'} is in the accessibility tree (aria-hidden, inert or visibility must take it out)`);
+      else if (c.hiddenFocusable) fail('G16', where, `flip card "${c.label}": the hidden ${c.open ? 'face' : 'back'} holds a control the keyboard reaches`);
+    }
+    for (const d of f.decks) {
+      if (d.sideways) fail('G16', where, `card deck "${d.label}": the carousel scrolls sideways (${d.outside} card(s) past its box, the deck or its track wider than the page); it must page, never scroll`);
+      if (d.docW > d.vw + 1) fail('G16', where, `card deck "${d.label}": the page is ${d.docW}px wide in a ${d.vw}px viewport`);
+      if (d.mode === 'carousel' && d.visible.length === 0) fail('G16', where, `card deck "${d.label}": the carousel shows no card`);
+      if (d.mode === 'carousel' && !d.controls) {
+        for (let k = 0; k < d.total; k += 1) if (!d.visible.includes(k)) fail('G16', where, `card deck "${d.label}": card ${k + 1} of ${d.total} cannot be reached: the carousel hides it and shows no previous and next controls`);
+      }
+    }
+    if (!s.interact) return;
+    try {
+      // a carousel pages through every card with its next button
+      for (const d of f.decks) {
+        if (d.mode !== 'carousel' || !d.controls) continue;
+        const deck = page.locator('[data-card-deck]').nth(d.index);
+        const reached = new Set(d.visible);
+        let st = d;
+        let guard = 0;
+        while (!st.atStart && guard < d.total + 2) {
+          await deck.locator('[data-deck-prev]').click({ timeout: 4000 });
+          st = (await page.evaluate(() => window.__caosGate.cards())).decks[d.index];
+          guard += 1;
+        }
+        for (const i of st.visible) reached.add(i);
+        guard = 0;
+        while (!st.atEnd && guard < d.total + 1) {
+          await deck.locator('[data-deck-next]').click({ timeout: 4000 });
+          await idleAnimations(page);
+          st = (await page.evaluate(() => window.__caosGate.cards())).decks[d.index];
+          for (const i of st.visible) reached.add(i);
+          if (st.sideways) fail('G16', where, `card deck "${d.label}": the carousel scrolls sideways after the next button (${st.outside} card(s) past its box)`);
+          guard += 1;
+        }
+        for (let k = 0; k < d.total; k += 1) if (!reached.has(k)) fail('G16', where, `card deck "${d.label}": card ${k + 1} of ${d.total} cannot be reached with the next button`);
+        guard = 0;
+        while (!st.atStart && guard < d.total + 2) {
+          await deck.locator('[data-deck-prev]').click({ timeout: 4000 }).catch(() => undefined);
+          st = (await page.evaluate(() => window.__caosGate.cards())).decks[d.index];
+          guard += 1;
+        }
+      }
+      // one flip card of each deck (and the loose ones): the face takes focus, Enter turns it, focus follows, Space turns it back
+      const f2 = await page.evaluate(() => window.__caosGate.cards());
+      const done = new Set();
+      for (const c of f2.cards) {
+        if (!c.shown || c.open || done.has(c.deck)) continue;
+        done.add(c.deck);
+        const card = page.locator('[data-flip-card]').nth(c.index);
+        const toggle = card.locator('[data-flip-toggle="front"]');
+        const focused = await toggle.evaluate((el) => { el.focus(); return document.activeElement === el; }).catch(() => false);
+        if (!focused) {
+          fail('G16', where, `flip card "${c.label}" does not turn with the keyboard: its face cannot take focus (it is not a button)`);
+          continue;
+        }
+        await page.keyboard.press('Enter');
+        await idleAnimations(page);
+        const after = (await page.evaluate(() => window.__caosGate.cards())).cards[c.index];
+        if (!after || !after.open) {
+          fail('G16', where, `flip card "${c.label}" does not turn with the keyboard: Enter on its face left it closed`);
+          continue;
+        }
+        const active = await page.evaluate(() => { const a = document.activeElement; return { visible: Boolean(a) && a.checkVisibility({ checkVisibilityCSS: true }), inCard: Boolean(a) && Boolean(a.closest('[data-flip-card]')) }; });
+        if (!active.visible || !active.inCard) fail('G16', where, `flip card "${c.label}": after Enter, keyboard focus is not on a control of the face that shows`);
+        if (after.hiddenInTree) fail('G16', where, `flip card "${c.label}": the hidden face is in the accessibility tree while the back shows`);
+        if (!after.contentShown) fail('G16', where, `flip card "${c.label}": the back shows no content after it turns (its content has no visible box)`);
+        if (s.contrast) for (const m of await page.evaluate(() => window.__caosGate.contrast())) fail('G13', where, `${m} (a flip card turned)`);
+        if (!done.has('shot')) {
+          done.add('shot');
+          await saveShot(page, `flipcard_open_${slug(s.route)}_${s.w}x${s.h}_${s.theme}_${s.lang}.png`);
+        }
+        await page.keyboard.press('Space');
+        await idleAnimations(page);
+        const closed = (await page.evaluate(() => window.__caosGate.cards())).cards[c.index];
+        if (!closed || closed.open) fail('G16', where, `flip card "${c.label}" does not turn back with the keyboard: Space on its back left it open`);
+      }
+    } catch (e) {
+      fail('G16', where, `a flip card or a card deck could not be used: ${e.message.split('\n')[0]}`);
+    }
+  }
+
+  /** G17: every animated SVG of the state has its reduced-motion block, plays for ten seconds at most and stands still under reduced motion. */
+  async function animationChecks(page, where) {
+    const a = await page.evaluate(() => window.__caosGate.animations());
+    const animated = [];
+    for (const it of a.items) {
+      const analysis = analyseSvgAnimation(it.svg);
+      for (const m of animationFailures(analysis, it.name)) fail('G17', where, m);
+      if (analysis.animated) animated.push(it.name);
+    }
+    // a figure drawn by an img of an SVG file: the file is analysed (an img takes no page style, so its own block is what counts)
+    const imgs = await page.evaluate(() => window.__caosGate.figureImages());
+    for (const im of imgs) {
+      const text = await page.evaluate(async (u) => { try { return await (await fetch(u)).text(); } catch (e) { return ''; } }, im.src);
+      for (const m of animationFailures(analyseSvgAnimation(text), im.name)) fail('G17', where, m);
+    }
+    if (animated.length === 0) return;
+    await page.emulateMedia({ reducedMotion: 'reduce' });
+    try {
+      await page.waitForTimeout(250);
+      const b = await page.evaluate(() => window.__caosGate.animations());
+      for (const it of b.items) {
+        if (!animated.includes(it.name)) continue;
+        if (it.runningCss > 0 || it.runningSmil) fail('G17', where, `illustration "${it.name}" keeps moving under reduced motion (${it.runningCss} CSS animation(s) running${it.smil ? `, SMIL ${it.runningSmil ? 'playing' : 'paused'}` : ''})`);
+      }
+    } finally {
+      await page.emulateMedia({ reducedMotion: null });
+    }
+  }
+
+  /**
+   * G18: Focus mode of the cases, by clicking. The App is put on its last group, and on the last sub-view of a group that has
+   * sub-views (the first group is where the walk leaves it, so a Focus that fell back to the first would go unseen); Focus must
+   * open on that case, group and sub-view, keep the keyboard inside its frame, hold one landmark and return to the same place.
+   */
+  async function focusVisit(page, sink, where, s, caseId, index, total) {
+    const enter = page.locator('[data-focus-enter]').filter({ visible: true }).first();
+    if ((await enter.count()) === 0) {
+      if (opt.requireFocus && !focusReported.has(`${s.route} ${where.mode}`)) {
+        focusReported.add(`${s.route} ${where.mode}`);
+        fail('G18', { ...where, trail: `case ${caseId} > Focus` }, 'the App offers no Focus control ([data-focus-enter]): ADR-0070 requires a visible control in the App that opens the selected case in focus mode');
+      }
+      return;
+    }
+    const tabs = page.locator('[data-case-workbench] [role="tablist"]').first().locator('[role="tab"]');
+    const n = await tabs.count();
+    const targets = n > 1 ? [n - 1] : [0];
+    if (s.primary && n > 2) {
+      // and the first group that holds sub-views
+      for (let i = 0; i < n - 1; i += 1) {
+        await tabs.nth(i).click({ timeout: 4000 }).catch(() => undefined);
+        await settle(page);
+        if ((await page.locator('[data-case-workbench] .subtablist').count()) > 0) {
+          targets.push(i);
+          break;
+        }
+      }
+    }
+    for (const [k, t] of targets.entries()) {
+      await tabs.nth(t).click({ timeout: 4000 }).catch(() => undefined);
+      await settle(page);
+      const subs = page.locator('[data-case-workbench] .subtablist [role="tab"]');
+      const sn = await subs.count();
+      if (sn > 1) {
+        await subs.nth(sn - 1).click({ timeout: 4000 }).catch(() => undefined);
+        await settle(page);
+      }
+      await focusVisitOne(page, sink, where, s, caseId, index + k, total, enter);
+    }
+    await tabs.nth(0).click({ timeout: 4000 }).catch(() => undefined);
+    await settle(page);
+  }
+
+  async function focusVisitOne(page, sink, where, s, caseId, index, total, enter) {
+    const at = { ...where, trail: `case ${caseId} > Focus` };
+    const facts = () => page.evaluate(() => window.__caosGate.focusFacts());
+    const label = `Focus mode of case ${caseId}`;
+    const before = await facts();
+    try {
+      await enter.evaluate((el) => window.__caosGate.bringEl(el)).catch(() => undefined);
+      await enter.click({ timeout: 5000 });
+    } catch (e) {
+      fail('G18', at, `${label}: the Focus control could not be clicked: ${e.message.split('\n')[0]}`);
+      return;
+    }
+    const why = await settle(page);
+    if (why) fail('G18', at, `${label}: never settled: ${why}`);
+    const f = await facts();
+    if (!f.focus) {
+      fail('G18', at, `${label}: the Focus control did not open Focus mode`);
+      return;
+    }
+    if (f.caseId !== caseId) fail('G18', at, `${label} shows case ${f.caseId}`);
+    if (f.group !== before.group) fail('G18', at, `${label} shows group ${f.group}, the App had ${before.group}`);
+    if (f.subview !== before.subview) fail('G18', at, `${label} shows sub-view ${f.subview}, the App had ${before.subview}`);
+    const q = new URLSearchParams(f.search);
+    if (q.get('focus') !== '1' || (total > 1 && q.get('case') !== caseId)) fail('G18', at, `${label}: the URL (${f.search || 'no query'}) does not hold ?focus=1 and the case`);
+    if (f.docW > f.vw + 1 || f.docH > f.vh + 1) fail('G18', at, `${label}: the page scrolls (the document is ${f.docW}x${f.docH}px in a ${f.vw}x${f.vh}px viewport); Focus mode is the viewport`);
+    if (f.nestedMain) fail('G18', at, `${label}: the page holds a main inside a main (the Focus frame must not be a second landmark inside the App's main)`);
+    // the keyboard stays in the Focus frame: the App behind it is out of the tab order
+    const strayed = [];
+    for (let i = 0; i < 14; i += 1) {
+      await page.keyboard.press('Tab');
+      const where2 = await page.evaluate(() => { const a = document.activeElement; return !a || a === document.body || a.closest('[data-focus-shell]') ? '' : (a.getAttribute('aria-label') || a.textContent || a.tagName).trim().slice(0, 30); });
+      if (where2) strayed.push(where2);
+    }
+    if (strayed.length) fail('G18', at, `${label}: Tab leaves the Focus frame (focus reached ${[...new Set(strayed)].slice(0, 4).map((x) => `"${x}"`).join(', ')} of the App behind it; make the rest of the page inert)`);
+    const big = s.w >= opt.viewportMinWidth;
+    if (big && f.rail && f.rail.scroll > f.rail.client + 1) fail('G18', at, `${label}: the rail scrolls (${f.rail.scroll}px of content in ${f.rail.client}px)`);
+    if (f.tabRows.some((r) => r > 1)) fail('G18', at, `${label}: a tab row wraps onto ${Math.max(...f.tabRows)} rows`);
+    if (big && f.share < opt.instrumentMin) fail('G18', at, `${label}: the stage covers ${(100 * f.share).toFixed(1)}% of the viewport (floor ${(100 * opt.instrumentMin).toFixed(0)}%)`);
+    if (f.exitInside === false) fail('G18', at, `${label}: the exit control is outside the viewport`);
+    for (const m of await page.evaluate(() => window.__caosGate.drawingText())) fail('G10', at, m);
+    if (s.contrast) for (const m of await page.evaluate(() => window.__caosGate.contrast())) fail('G13', at, m);
+    if (index === 0) await saveShot(page, `focus_${slug(s.route)}_${s.w}x${s.h}_${s.theme}_${s.lang}.png`);
+    // leave: the exit control for one case, Escape for the next, so both ways are walked
+    const byButton = index % 2 === 0;
+    let left = true;
+    if (byButton) {
+      try {
+        await page.locator('[data-focus-exit]').first().click({ timeout: 3000 });
+      } catch (e) {
+        fail('G18', at, `${label}: the exit control could not be used: ${e.message.split('\n')[0]}`);
+        left = false;
+      }
+    } else {
+      await page.keyboard.press('Escape');
+    }
+    if (!left) await page.keyboard.press('Escape');
+    const why2 = await settle(page);
+    if (why2) fail('G18', at, `${label}: never settled after leaving: ${why2}`);
+    const g = await facts();
+    if (g.focus) {
+      fail('G18', at, `${label}: ${byButton && left ? 'the exit control' : 'Escape'} does not return to the App`);
+      await page.goto(`${urlFor(s.route)}?case=${encodeURIComponent(caseId)}`, { waitUntil: 'load', timeout: 30000 }).catch(() => undefined);
+      await settle(page);
+    } else {
+      if (!g.app) fail('G18', at, `${label}: back from Focus mode there is no App on the page`);
+      if (g.caseId !== caseId) fail('G18', at, `${label}: back in the App on case ${g.caseId}, it was left on case ${caseId}`);
+      if (g.group !== before.group) fail('G18', at, `${label}: back in the App on group ${g.group}, it was left on group ${before.group}`);
+      if (g.subview !== before.subview) fail('G18', at, `${label}: back in the App on sub-view ${g.subview}, it was left on sub-view ${before.subview}`);
+      if (new URLSearchParams(g.search).has('focus')) fail('G18', at, `${label}: the URL still holds ?focus after the return`);
+    }
+    drain(sink, at);
+  }
+
   async function workbenchKey(page) {
     return page.evaluate(() => document.querySelector('[data-case-workbench]')?.getAttribute('data-state-key') ?? null);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fasl-work/caos-app-shell",
-  "version": "0.13.1",
+  "version": "0.14.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",