@bezda/rhp-mcp 0.1.5 → 0.1.7

package/skill/references/download.md

@@ -5,7 +5,11 @@ Copy the following block before `</body>`, after the chart's module script.
 Keep it outside the poster so the saved PNG includes the whole poster, its headline and source note, without the download control or gallery navigation.
 The button joins `.recipe-navigation` when the gallery supplies one, inheriting the gallery link's color.
 Otherwise it creates its own row above each poster, sized to the poster on desktop and phones.
-The exporter loads only when clicked, waits for fonts, and saves the current poster at twice its displayed resolution.
+The adjacent fit-to-screen icon toggles between full size and a proportional view at up to 95% of the viewport height.
+Its icon changes to show the available action, and fitting preserves the poster's layout and selection.
+The fitted view uses the stable small viewport height, so browser controls appearing or disappearing during scrolling do not change its scale.
+The exporter loads only when clicked, waits for fonts, and saves the current poster at twice its full-size resolution, including when the view is fitted.
+It preserves authored margins and absolute-position rules, including adopted chart stylesheets, because Safari's computed offsets can be wrong inside subgrids.
 Activating the download control preserves the poster's selection, including keyboard focus transitions, and does not bubble into outside-click handlers.
 Like the chart's CDN import, the first download needs a connection.
 For an embedded chart inside an existing app, follow the app's export controls instead of adding page navigation.
@@ -13,24 +17,84 @@ For an embedded chart inside an existing app, follow the app's export controls i
 ```html
 <style id="poster-download-styles">
   .poster-download-tools { display: flex; justify-content: flex-end; align-items: center; margin: 0 auto 12px; max-width: 100%; }
-  .poster-download { display: inline-flex; align-items: center; justify-content: center; flex: 0 0 auto; width: 44px; height: 44px; padding: 10px; border: 0; border-radius: 4px; background: transparent; color: inherit; cursor: pointer; }
-  .poster-download svg { display: block; width: 20px; height: 20px; }
-  .poster-download:hover { background: color-mix(in srgb, currentColor 8%, transparent); }
-  .poster-download:focus-visible { outline: 2px solid currentColor; outline-offset: 2px; }
-  .poster-download[aria-disabled="true"] { cursor: progress; opacity: .5; }
+  .poster-actions { display: flex; align-items: center; margin-left: auto; }
+  .poster-download, .poster-fit-toggle { display: inline-flex; align-items: center; justify-content: center; flex: 0 0 auto; width: 44px; height: 44px; padding: 10px; border: 0; border-radius: 4px; background: transparent; color: inherit; cursor: pointer; }
+  .poster-actions svg { display: block; width: 20px; height: 20px; }
+  .poster-actions button:hover { background: color-mix(in srgb, currentColor 8%, transparent); }
+  .poster-actions button:focus-visible { outline: 2px solid currentColor; outline-offset: 2px; }
+  .poster-actions button[aria-disabled="true"] { cursor: progress; opacity: .5; }
+  .poster-fit-frame, .poster-fit-content { display: contents; }
+  .poster-fit-frame { max-height: 95svh; }
+  .poster-fit-frame.is-fitted { display: block; margin: 0 auto; overflow: clip; }
+  .poster-fit-frame.is-fitted > .poster-fit-content { display: block; transform-origin: top left; }
   .poster-download-error { margin: 8px auto; font: 14px/1.4 system-ui, sans-serif; color: inherit; }
-  @media print { .poster-download-tools, .poster-download, .poster-download-error { display: none !important; } }
+  @media print { .poster-download-tools, .poster-actions, .poster-download-error { display: none !important; } }
 </style>
 <script type="module" id="poster-download-script">
+function addPosterFit(poster, button, changed) {
+  const frame = document.createElement('div'), content = document.createElement('div');
+  frame.className = 'poster-fit-frame'; content.className = 'poster-fit-content';
+  poster.before(frame); frame.append(content); content.append(poster);
+  const properties = ['width', 'max-width', 'margin', 'box-sizing'];
+  const original = properties.map(name => [name, poster.style.getPropertyValue(name), poster.style.getPropertyPriority(name)]);
+  let fitted = false, scale = 1, request = 0, layout = null;
+  const availableHeight = () => parseFloat(getComputedStyle(frame).maxHeight) || innerHeight * .95;
+  const layoutKey = () => {
+    const css = getComputedStyle(poster);
+    return [innerWidth, availableHeight(), css.width, css.height].join('/');
+  };
+  const restore = () => original.forEach(([name, value, priority]) => {
+    if (value) poster.style.setProperty(name, value, priority);
+    else poster.style.removeProperty(name);
+  });
+  function update() {
+    request = 0;
+    if (fitted && layout === layoutKey()) return;
+    frame.classList.remove('is-fitted'); frame.style.width = ''; frame.style.height = '';
+    content.style.width = ''; content.style.transform = ''; restore(); scale = 1;
+    if (fitted) {
+      const box = poster.getBoundingClientRect();
+      scale = Math.min(1, availableHeight() / box.height);
+      poster.style.setProperty('box-sizing', 'border-box');
+      poster.style.setProperty('width', `${box.width}px`);
+      poster.style.setProperty('max-width', 'none');
+      poster.style.setProperty('margin', '0');
+      content.style.width = `${box.width}px`;
+      content.style.transform = `scale(${scale})`;
+      frame.style.width = `${box.width * scale}px`; frame.style.height = `${box.height * scale}px`;
+      frame.classList.add('is-fitted');
+    }
+    layout = layoutKey();
+    const label = fitted ? 'Restore poster size' : 'Fit poster to screen';
+    button.setAttribute('aria-label', label); button.title = label;
+    button.setAttribute('aria-pressed', String(fitted));
+    button.innerHTML = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.7" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="${fitted ? 'M15 3h6v6m0-6-7 7M9 21H3v-6m0 6 7-7' : 'M4 4l6 6m0-6v6H4m16 10-6-6m0 6v-6h6'}"/></svg>`;
+    changed();
+    poster.dispatchEvent(new Event('poster-view-change'));
+  }
+  const schedule = () => { if (fitted && !request && layout !== layoutKey()) request = requestAnimationFrame(update); };
+  new ResizeObserver(schedule).observe(poster);
+  addEventListener('resize', schedule);
+  document.fonts.ready.then(schedule);
+  update();
+  return {
+    toggle() { fitted = !fitted; layout = null; cancelAnimationFrame(request); update(); },
+    dimensions() {
+      if (!fitted) { const box = poster.getBoundingClientRect(); return {width:box.width,height:box.height}; }
+      const css = getComputedStyle(poster);
+      return {width:parseFloat(css.width),height:parseFloat(css.height)};
+    },
+  };
+}
 function addPosterDownloads() {
   document.querySelectorAll('.poster').forEach((poster, index) => {
     const navigation = index === 0 && document.querySelector('.recipe-navigation');
     const tools = navigation || document.createElement('div');
     if (tools.querySelector('.poster-download')) return;
+    const align = () => { if (!navigation) tools.style.width = `${poster.getBoundingClientRect().width}px`; };
     if (!navigation) {
       tools.className = 'poster-download-tools';
       poster.before(tools);
-      const align = () => { tools.style.width = `${poster.getBoundingClientRect().width}px`; };
       new ResizeObserver(align).observe(poster);
       align();
       const rgb = getComputedStyle(document.body).backgroundColor.match(/[\d.]+/g);
@@ -48,27 +112,43 @@ function addPosterDownloads() {
     button.setAttribute('aria-label', 'Download poster as PNG');
     button.title = 'Download poster as PNG';
     button.innerHTML = '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.7" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M12 3v12m-5-5 5 5 5-5M5 16v4h14v-4"/></svg>';
+    const actions = document.createElement('div'), fitButton = document.createElement('button');
+    actions.className = 'poster-actions'; fitButton.className = 'poster-fit-toggle'; fitButton.type = 'button';
+    if (!poster.id) {
+      let id = `rhp-poster-${index + 1}`;
+      while (document.getElementById(id)) id += '-view';
+      poster.id = id;
+    }
+    fitButton.setAttribute('aria-controls', poster.id);
+    fitButton.setAttribute('data-poster-view-toggle', '');
+    const fit = addPosterFit(poster, fitButton, align);
+    fitButton.addEventListener('click', event => { event.stopPropagation(); if (!busy) fit.toggle(); });
+    actions.append(fitButton, button);
     const error = document.createElement('p');
     error.className = 'poster-download-error';
     error.setAttribute('role', 'alert');
     error.hidden = true;
     tools.after(error);
     // Download is part of the poster interaction, even though its control sits outside the image.
-    button.addEventListener('pointerdown', event => {
+    actions.addEventListener('pointerdown', event => {
       event.stopPropagation();
     });
-    button.addEventListener('mousedown', event => {
+    actions.addEventListener('mousedown', event => {
       // Pointer activation downloads without taking focus from the selected chart item.
       event.preventDefault();
       event.stopPropagation();
     });
     poster.addEventListener('focusout', event => {
-      if (button.contains(event.relatedTarget) || button.matches(':active')) event.stopImmediatePropagation();
+      if (actions.contains(event.relatedTarget) || actions.querySelector(':active')) event.stopImmediatePropagation();
     }, true);
     poster.addEventListener('pointerleave', event => {
-      if (button.contains(event.relatedTarget) || document.activeElement === button) event.stopImmediatePropagation();
+      if (actions.contains(event.relatedTarget) || actions.contains(document.activeElement)) event.stopImmediatePropagation();
+    }, true);
+    poster.addEventListener('pointermove', event => {
+      // Safari can move the pointer over the title while a keyboard-triggered download is being prepared.
+      if (actions.contains(document.activeElement) && !event.target.closest('.rhp-chart')) event.stopImmediatePropagation();
     }, true);
-    for (const type of ['keydown', 'keyup']) button.addEventListener(type, event => {
+    for (const type of ['keydown', 'keyup']) actions.addEventListener(type, event => {
       if (event.key === 'Enter' || event.key === ' ') event.stopPropagation();
     });
     let exporter, retries = 0, busy = false;
@@ -78,6 +158,7 @@ function addPosterDownloads() {
       busy = true;
       button.setAttribute('aria-disabled', 'true');
       button.setAttribute('aria-busy', 'true');
+      fitButton.setAttribute('aria-disabled', 'true');
       button.setAttribute('aria-label', 'Preparing poster PNG');
       error.hidden = true;
       let url;
@@ -85,35 +166,53 @@ function addPosterDownloads() {
         exporter ||= import('https://cdn.jsdelivr.net/npm/modern-screenshot@4.7.0/+esm' + (retries ? `?retry=${retries}` : ''));
         const { domToBlob } = await exporter;
         await document.fonts.ready;
-        // Grid auto margins resolve to zero in getComputedStyle, so keep their author rules.
-        const autoMargins = new Set();
-        const marginRules = rules => [...rules].map(rule => {
+        // Preserve author layout rules where computed styles lose the grid's used geometry.
+        // Safari misreports percentage insets in subgrids, and grid auto margins resolve to zero.
+        const autoMargins = new Set(), positioned = new Set();
+        const isMargin = name => name === 'margin' || name.startsWith('margin-');
+        const isInset = name => name === 'inset' || name.startsWith('inset-') || ['top', 'right', 'bottom', 'left'].includes(name);
+        const layoutRules = rules => [...rules].map(rule => {
           if (rule.selectorText && rule.style) {
-            const margins = [...rule.style].filter(name => name === 'margin' || name.startsWith('margin-'));
+            const margins = [...rule.style].filter(isMargin);
             if (margins.some(name => /\bauto\b/.test(rule.style.getPropertyValue(name)))) autoMargins.add(rule.selectorText);
-            return margins.length ? `${rule.selectorText} { ${margins.map(name => `${name}: ${rule.style.getPropertyValue(name)}${rule.style.getPropertyPriority(name) ? ' !important' : ''};`).join(' ')} }` : '';
+            const insets = [...rule.style].filter(isInset);
+            if (insets.length) positioned.add(rule.selectorText);
+            const layout = [...margins, ...insets];
+            return layout.length ? `${rule.selectorText} { ${layout.map(name => `${name}: ${rule.style.getPropertyValue(name)}${rule.style.getPropertyPriority(name) ? ' !important' : ''};`).join(' ')} }` : '';
           }
-          if (!rule.cssRules) return '';
-          if (rule instanceof CSSMediaRule) return matchMedia(rule.conditionText).matches ? marginRules(rule.cssRules) : '';
-          if (rule instanceof CSSSupportsRule) return CSS.supports(rule.conditionText) ? marginRules(rule.cssRules) : '';
-          return rule.cssText.slice(0, rule.cssText.indexOf('{') + 1) + marginRules(rule.cssRules) + '}';
+          if (!rule.cssRules) return /^@layer\b/.test(rule.cssText) ? rule.cssText : '';
+          if (rule instanceof CSSMediaRule) return matchMedia(rule.conditionText).matches ? layoutRules(rule.cssRules) : '';
+          if (rule instanceof CSSSupportsRule) return CSS.supports(rule.conditionText) ? layoutRules(rule.cssRules) : '';
+          return rule.cssText.slice(0, rule.cssText.indexOf('{') + 1) + layoutRules(rule.cssRules) + '}';
         }).join('\n');
-        const margins = [...document.styleSheets].map(sheet => {
-          try { return marginRules(sheet.cssRules); } catch (cause) { return ''; }
+        const sheets = [...document.styleSheets, ...document.adoptedStyleSheets];
+        const layout = sheets.map(sheet => {
+          try { return layoutRules(sheet.cssRules); } catch (cause) { return ''; }
         }).join('\n');
         // Omit display-none HTML subtrees, such as collapsed chart rows, from the image and its SVG payload.
         const includeNode = node => !(node instanceof HTMLElement) || getComputedStyle(node).display !== 'none';
-        const restoreMargins = (source, clone) => {
-          if (clone.style && source !== poster && [...autoMargins].some(selector => source.matches(selector))) {
-            [...clone.style].filter(name => name === 'margin' || name.startsWith('margin-')).forEach(name => clone.style.removeProperty(name));
-            [...source.style].filter(name => name === 'margin' || name.startsWith('margin-')).forEach(name => clone.style.setProperty(name, source.style.getPropertyValue(name), source.style.getPropertyPriority(name)));
+        const restoreLayout = (source, clone) => {
+          if (clone.style && source !== poster) {
+            const margins = [...autoMargins].some(selector => source.matches(selector));
+            const computed = getComputedStyle(source);
+            const insets = computed.position === 'absolute' && [...positioned].some(selector => source.matches(selector));
+            const restore = name => (margins && isMargin(name)) || (insets && isInset(name));
+            [...clone.style].filter(restore).forEach(name => clone.style.removeProperty(name));
+            [...source.style].filter(restore).forEach(name => clone.style.setProperty(name, source.style.getPropertyValue(name), source.style.getPropertyPriority(name)));
+            if (insets) {
+              // Only the scaled axis needs its percentage rule. Freeze the other axis in pixels:
+              // Firefox does not reevaluate container queries reliably inside an SVG foreignObject.
+              const axis = source.getAttribute('data-rhp-o');
+              const fixed = axis === 'h' ? ['top', 'bottom'] : axis === 'v' ? ['left', 'right'] : ['top', 'right', 'bottom', 'left'];
+              fixed.forEach(name => clone.style.setProperty(name, computed.getPropertyValue(name), 'important'));
+            }
           }
           const children = [...source.children].filter(node => !['STYLE', 'SCRIPT'].includes(node.tagName) && includeNode(node));
-          [...clone.children].forEach((child, i) => { if (children[i]) restoreMargins(children[i], child); });
+          [...clone.children].forEach((child, i) => { if (children[i]) restoreLayout(children[i], child); });
         };
         // Cross-origin font stylesheets are readable through fetch, but not through cssRules.
         const fontFiles = new Map();
-        const fontRules = await Promise.all([...document.styleSheets].map(async sheet => {
+        const fontRules = await Promise.all(sheets.map(async sheet => {
           let css;
           try { css = [...sheet.cssRules].map(rule => rule.cssText).join('\n'); }
           catch (cause) {
@@ -164,12 +263,12 @@ function addPosterDownloads() {
           node.style.backgroundImage = background;
         };
         const blob = await domToBlob(poster, {
-          scale: 2, style: { margin: '0' }, filter: includeNode,
+          ...fit.dimensions(), scale: 2, style: { margin: '0' }, filter: includeNode,
           font: { cssText: fontRules.join('\n') }, onCloneEachNode: embedTexture,
           onCloneNode: clone => {
-            restoreMargins(poster, clone);
+            restoreLayout(poster, clone);
             const style = document.createElement('style');
-            style.textContent = margins;
+            style.textContent = layout;
             clone.prepend(style);
           },
           // CSS content's alternative text follows a slash and must not be painted.
@@ -197,10 +296,11 @@ function addPosterDownloads() {
         busy = false;
         button.removeAttribute('aria-disabled');
         button.removeAttribute('aria-busy');
+        fitButton.removeAttribute('aria-disabled');
         button.setAttribute('aria-label', 'Download poster as PNG');
       }
     });
-    tools.append(button);
+    tools.append(actions);
   });
 }
 // A chart module may await fonts or data after DOMContentLoaded has already fired.
@@ -217,6 +317,6 @@ else {
 ```
 
 The block above is the maintained source for the recipe controls.
-After changing it, run `node scripts/sync-poster-download.mjs` from the rhp repository to update every recipe.
+After changing it, run `node scripts/sync-poster-download.mjs` from the rhp repository to update every recipe and existing example poster.
 Test an actual PNG download on a desktop and a phone, including a poster taller than the viewport, and verify that the image includes the bottom note and excludes the controls.
 The implementation uses [modern-screenshot](https://github.com/qq15725/modern-screenshot) to preserve computed styles, pseudo-elements, images and embedded fonts.

package/skill/references/forms.md

@@ -30,7 +30,7 @@ rhp draws all of these; the recipe named has the technique, not the design.
 | a route or a sequence in space (stops, stages, a course, a river) | one line with its stations in order | `stacked-100` (its key is a metro line), `gantt`, `slope` |
 | a document the reader knows (a receipt, a ledger, a timetable, a scoreboard, a league table, a menu) | the chart laid out as that document, its lines the slats | `lollipop`, `waterfall`, `sparklines`, `live` |
 | a place (states, districts, seats in a hall, a pitch, a shelf) | a grid of tiles that echoes the place | `heatmap`'s composition (a Plot of rows, each a Plot of Cells) |
-| an instrument that measures it (a thermometer, a gauge, a ruler, a clock, a scale) | the instrument's own scale and pointer | a `Scale` drawn your own way, a Tick as the pointer, `radial-bars` |
+| an instrument that measures it (a thermometer, a gauge, a ruler, a clock, a scale) | the instrument's own scale and pointer | a `Scale` drawn your own way, a Tick as the pointer, `radial-bars`, `tape` (a ruler's rules and numerals along a whole cut into lengths) |
 
 - The native form is the hero, and the numbers still have to be read: print each value on or beside its mark, since a ring, an outline or a tile is read less exactly than a bar on a shared baseline.
 - When an exact comparison is the whole point, keep bars from one baseline and let the subject show in how the marks are drawn (design.md section 2).
@@ -76,7 +76,7 @@ The headline will be its answer.
 | see a value over two categories | a grid of values (day by hour) | heatmap | `heatmap` |
 | see two groups across ordered bands | two values per band | pyramid | `pyramid` |
 | see things known by their shape at their size | one value per item, each item with an outline | silhouettes to scale | `silhouettes` |
-| see how a day or another cycle splits | parts that add up to the cycle | a dial | `dial` |
+| see how a day or another cycle splits | parts that add up to the cycle | a dial, or a tape cut into lengths | `dial`, `tape` |
 | follow one part of a total over periods, and count it | parts per period that add up | unit stacks with the part at the foot | `unit-stack` |
 | see a schedule and its progress | tasks with start, end, progress | gantt | `gantt` |
 | follow prices with their range | open, high, low, close per day | candlestick | `candlestick` |
@@ -150,6 +150,7 @@ The interaction listed is the recipe's; interaction.md has the others.
 | `pyramid` | two sides of a population by age | 2 | an age picked lights everyone that age or older |
 | `silhouettes` | ten towers to scale, each in its own outline, on one street | 1, vertical, `shape()` per row | readout of the tower picked, its level carried to the tallest |
 | `dial` | the parts of a day around a 24-hour dial | 10 + 9 | a hand that turns to the part picked, a readout in the hub |
+| `tape` | the parts of a day laid end to end along a tape measure cut into three 8-hour lengths | 2 (an `overlap` Plot of Bars from each part's start to its end), a Chart per length + 9 | readout of the part picked, its key lines picking too |
 | `log-line` | ten years of a price on a log scale with a line at each doubling, its falls shaded | 5 (the falls as one filled Line) + 8 + 9, log scale | a crosshair readout by pointer, tap, drag or keys |
 | `unit-stack` | monthly spending as piles of coins, one part at the foot of every pile | 2 (the picked part and the rest), units by a mask | a picker of parts |
 | `gantt` | tasks over weeks, progress, today | 2 + 8 + 9 | readout of a task and its dependencies |

package/skill/references/interaction.md

@@ -1,6 +1,6 @@
 # Interaction
 
-How to pick the one interaction that serves a chart's story when the user names none, and how to build any interaction a user asks for.
+How to choose interaction behavior and presentation for the reader's task, and how to build an interaction a user asks for.
 rhp keeps no interaction state: the app holds it in a signal, passes it to the Plot as data, and the slat shows it.
 
 Contents:
@@ -71,10 +71,14 @@ The page's CSS styles what sits around the chart (the poster, the readout, butto
 
 ## 1. Pick the interaction from the story
 
-When the user names an interaction, build exactly that, from the section that matches it.
-When they name none, find the chart's story here and add that one interaction.
+When the user names an interaction, preserve the behavior they requested and use the sections below for the techniques it needs.
+When they name none, decide what the reader should be able to inspect, compare or change, and what visible response helps them do it.
+The table offers working examples, not fixed pairings between stories, chart types and controls.
+Reuse reliable state and event handling, while choosing the controls, feedback, placement and transitions for this chart.
+The same selection state can drive an inline annotation, a comparison or a detail reveal; a separate readout band is only one way to present it.
+Keep a familiar pattern when it fits the task and design; difference alone is not a reason to change it.
 
-| The story | The interaction | Section | Recipes that have it |
+| The reader's task | Example interaction | Section | Recipes demonstrating the technique |
 |---|---|---|---|
 | compare items: which is bigger, by how much | readout of the slat under the pointer, finger or focus, with the fields the bars do not show | 2 | bar, column, pyramid, donut |
 | a ranking whose order depends on the measure | sort toggle | 3 | grouped-bars, bullet, dumbbell |

package/skill/references/pitfalls.md

@@ -95,7 +95,7 @@ Start from a recipe, never from what another library does.
 6. **Numbers show long decimals while they move** [26]: in the JS version (`animate`) values are fractional mid-way; round what you print.
 7. **Bars vanish, or a slat jumps to the first place, after the data changes** [4]: a `style` given as a string that changed (or turned to nothing) replaced the variables rhp keeps in the element's style.
    Give a slat root's changing style as an object: `style=${() => ({ "--n": d.n })}`.
-   Blocks need the same workaround on published rhp 2.0.2; current source fixes Block style replacements for the upcoming 2.0.3 release.
+   Blocks need the same workaround only on rhp 2.0.2; 2.0.3 fixed Block style replacements.
 8. **`animate` is on, but a value still jumps**: the JS version never moves a group given as a function of the row (`v=${(d) => ...}`). Give the changing numbers as a list (`v=${() => values()}`), a single value or a field of `rows`.
 9. **A race stops at each step, or a live feed's marks stop between readings**: to play back data you have, never step through it with a timer; move a playhead on every frame, give the Plot the values interpolated between the steps around it, and keep the JS version's default 150 ms, so the marks glide and Pause leaves them between steps (interaction.md section 10). For a live feed, whose next value is not known yet, ease linear into each new reading over a little more than one interval (`ease: "linear"`, 1.5 intervals); with ease-out or a shorter duration the marks rest between readings.
 10. **Marks trail behind data that changes rapidly or continuously** (a live feed, a slider or drag that drives the data, a play button, a bar chart race): in the default CSS version every new value restarts a CSS transition from wherever the mark is, so under steady change the marks always lag, and Safari can stall transitions that input events retarget. Give the Plot `animate` for the data groups that change (`animate=${["value"]}`, or `animate=${true}`), or the Chart when the scale moves with the data: rhp's JS clock carries each move into the next value. Measured with a slider changing the data every frame: the CSS version trailed the data by 10 points of 100, the JS version by 6.
@@ -116,12 +116,13 @@ Start from a recipe, never from what another library does.
 
 ## The layout jumps when the reader interacts
 
-The checker warns (`layout-jump`) when a control or the chart moves after one of its interactions; these are the usual causes. It tries only some controls, so try every one yourself and compare.
+The checker warns (`layout-jump`) when a control or the chart moves after one of its interactions, (`text-shift`) when a text that still says the same thing moves, and (`jitter`) when a text moves as the pointer goes along a chart that follows it (a line read day by day); these are the usual causes. It tries only some controls, so try every one yourself and compare.
 
 1. **Text that changes with a switch moves the controls below it** (a headline or a dek per question): stack every version in one grid cell (a wrapper with `display: grid`, each version at `grid-area: 1 / 1`, `visibility: hidden` except the current one), so the cell is always as tall as the longest version.
    Align the versions to the cell's end (`align-self: end`) when the chart is below them, so a short version leaves no empty line above the chart.
 2. **A readout that wraps on a phone pushes the chart down**: give it a `min-height` for its longest text at 320px (`min-height: 2lh`, or `3lh`), counting the longest numbers and dates that gain a year ("Jan 4, 2027").
 3. **Numbers that change width shift what follows them**: use `font-variant-numeric: tabular-nums`, and give a column of numbers a fixed room; in an "auto" end room, align them across slats with `justify-self: stretch` and `justify-content: flex-end` on the label.
+   In a readout, tabular figures alone are not enough when the number of digits changes ("$654" to "$84,176") or a date's month names differ in width: start each part where nothing before it changes width (a grid with a column per part, or each part on its own line), or give the value a box with a `min-width` in `ch` for the longest value it can show, right-aligned. A label or a unit after a value on the same line ("8,101 tons in 2026") slides at every step of a pointer moving along the chart.
 4. **Every bar slides when a slat is lit**: the lit name turns bold in a `room.start` of "auto", which measures the widest name again and moves the plot.
    Change only the lit name's color, or keep its bold width at rest: room in px, or the bold text drawn hidden under the name (`.name::after { content: attr(data-name); display: block; height: 0; overflow: hidden; visibility: hidden; font-weight: 700; }`, with `data-name=${() => d.name}` on the Label; measured: the bars held still at 1280px, where a plain bold name moved them 10.8px).
 5. **A button whose text changes (Play, Pause) moves its neighbors**: stack both texts in one grid cell, the hidden one `visibility: hidden`, so the button is always as wide as the longer one.

package/skill/scripts/add-download.mjs

@@ -0,0 +1,33 @@
+// Adds the poster's fit-to-screen and PNG download block to a standalone HTML page, before </body>.
+// The block is the same in every recipe; this copies it from one, so the agent never reads it.
+// Usage: node scripts/add-download.mjs <page.html>
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const page = process.argv[2];
+if (!page || !fs.existsSync(page)) {
+  console.error("Usage: node scripts/add-download.mjs <page.html> (the page must exist)");
+  process.exit(1);
+}
+
+const html = fs.readFileSync(page, "utf8");
+if (html.includes('id="poster-download-script"')) {
+  console.log(`${page} already has the download block.`);
+  process.exit(0);
+}
+if (!/<\/body>/i.test(html)) {
+  console.error(`${page} has no </body>: add the block by hand, from <style id="poster-download-styles"> to </body> of any recipe.`);
+  process.exit(1);
+}
+
+const recipe = fs.readFileSync(path.join(here, "../recipes/bar.html"), "utf8");
+const start = recipe.indexOf('<style id="poster-download-styles">');
+const end = recipe.lastIndexOf("</body>");
+const block = recipe.slice(start, end);
+
+// We insert before the last </body>, so a </body> inside a script or a comment is left alone.
+const at = html.toLowerCase().lastIndexOf("</body>");
+fs.writeFileSync(page, html.slice(0, at) + block + html.slice(at));
+console.log(`Added the fit-to-screen and download block to ${page} (${block.length} characters). The poster needs the class "poster" for the block to find it.`);

package/src/check/README.md

@@ -19,14 +19,26 @@ The CLI (`rhp-mcp check`) and the MCP tool (`rhp_check`) print the same report.
    It runs at each width checked, and on a page of its own at each of the page's own breakpoints between that width and the next narrower one (both sides of each `min-width` or `max-width` of its media queries, up to six per width), where a layout made only for the widths checked jumps: a readout that takes another line for one slat, just past the width where the poster's padding changes.
    With reduced motion a pick shows at once, so two frames after each are enough: the sweep takes a few seconds per width.
    Widths between those (a jump only from 322 to 338px) are not swept; a readout that keeps its height by design (one line, or the same number of lines whatever it says) has none.
+   While the sweep picks, the texts around the charts that a pick rewrites are noted: that is the readout.
+   When the main chart draws a Line or an Area, a layer over the plot takes the pointer (the main Plot's first slat cannot be pointed at) or the main Plot has one or two slats (a line per series), the reader moves along the chart, and the sweep first **scrubs** it (`scrub()` in index.js): the mouse goes through 41 points across the plot's middle, along the scale of the plot that draws the line or the area (or of a Plot of one or two slats) and across the main Plot's slats otherwise, at every width (a finger dragging along a phone's plot shows the same readout).
+   After each point the layout is measured as for a pick, and so is every line of text around the charts, each text node on its own (its first line box, in the box it floats in), against the page with the pointer away: a text that still says the same thing and moved jitters, and so does one whose words changed and that kept none of its edges (its start, its end or, on one line, its middle) where it was.
+   When the page's text changes at three steps in four or more, the readout follows the pointer along the chart (a line read day by day), and a whole sentence that slides counts, though a pick lets one slide. When it changes less often, it changes once per mark crossed (bubbles that a layer covers), and a slide along the line counts as for a pick: only for a text that still says the same thing, and not for a sentence. A text that moves up or down (a readout's name centered beside a description that takes another line) counts either way.
+   The report says when no slat could be picked, rather than that nothing moved.
+   Then, when the main chart is taller than three quarters of the window (664px at a phone's width), the page is scrolled so that the chart's middle is in the middle of the window, and the controls of the chart's section (not its fit and download icons) and the readout are noted when all of them are out of view.
+   At the first width, with a mouse, the **glide** (`glide()` in index.js) then moves the pointer from a slat to its neighbor in twelve steps, for the first two slats, two in the middle and the last two, and reads after each step the page's visible text and how the slats are drawn (two hashes).
+   When both slats show something of their own and a step between them shows the text, or the slats, as they are with the pointer away, the readout or the lit slat flickers in the gap.
 6. **Interact** (interact.js), on a fresh page with motion on, as a reader gets it.
    At the first width: point at a mark of the first, middle and last slat of the largest chart (in its first Plot that takes the pointer), and of the slat whose edge Label is widest when it is wider than theirs (lit, a name that gets bolder can make room "auto" wider); click each button and toggle, change each range and select, press an arrow key on a slider (`role=slider` first, else a range), and press Tab and the arrow keys when slats take focus.
    Then Tab through the page (up to 8 stops), and compare a screenshot of each stop's box (with 12px around it for an outline) focused and blurred: under 20 pixels that change (by more than 24 in all three channels) is focus that shows nothing.
    At a phone's width, in a window 664px tall (what Safari shows of a page on a 390 by 844 iPhone): tap a mark of the first and the last slat, and note when the tap changed text the reader can see (wrote it, or showed it) but all of that text lies outside the window while the tapped slat is in it; a style the tap changed in view (the tapped bar lit) does not tell the reader what the text says.
    A point on a mark is one that reaches its slat: on its marks, inside an SVG shape in it (`isPointInFill`, for a donut's wedge that fills a small part of its box), or at a Label's center. When none does and the slat takes the pointer, something covers it, and the step says "could not reach slat N" and what covers it instead of pointing at a corner of a box.
-   After each step the guard reads again what the slats read once (stale values, static charts), and the pass notes what moved on the page (the layout jumps).
+   After each step the guard reads again what the slats read once (stale values, static charts), and the pass notes what moved on the page (the layout jumps, and the texts that moved).
+   A step that is not a pick (a button, a range, a select, a key on a slider) is also read five times as it runs, every 200ms, so a text that jitters while Play runs the years counts even when it is back in place at the end.
+   A text is measured in the box it floats in when it floats (fixed, sticky or absolute: a readout pinned to the window, a tooltip that follows the pointer), else on the page, and only when its own text (its text nodes, not its children's) is the same as before: a value that changed may change its size, but the label beside it stays put.
+   A text that moves by as much as something that jumped is reported with that jump, not again.
    Controls go by their accessible name, slats by their Labels' text as the reader sees it (not hidden text, nor screen-reader text).
 7. **Report** (findings.js turns probe results into findings, report.js writes the text): errors first, then warnings, then notes, what passed, the interactions (with one line for the sweep: how many slats, and every width it picked them at) and the screenshots.
+   A finding whose fix the skill's references explain names that section on a line of its own (`See: pitfalls.md, "The layout jumps when the reader interacts"`, from `SEE` in findings.js), so an agent whose fix did not hold reads that section, not the whole file; the headings it names must stay as they are.
    When pointing at slats (and tapping them) changes nothing but buttons or a slider change the chart, the report says so in one line.
    When nothing changes and the page has no controls, it says "no interaction found (fine when none was asked for)" in one line, instead of a line per slat (slats that others cover, in an overlap Plot with no interaction, are left out of it, as long as one slat was reached).
 
@@ -141,8 +153,12 @@ The tests read this table: every code in it must have a chart in `test/broken/`
 | Code | Level | What triggers it | Fix it gives |
 |---|---|---|---|
 | `unnamed-control` | warning | A button, input, select or control with a role (slider, switch, tab...) that has no accessible name: no text, aria-label, aria-labelledby or label, so a screen reader says only what kind of control it is. | Visible text, an aria-label on an icon button, or a `<label>` around an input or a select. |
-| `layout-jump` | warning | An interaction of the pass, or a pick of the sweep, moves a control other than the one it used, or a chart's top, by more than 2px (a readout that takes a second line, a button whose label changes its width); or, while it lights a slat (pointing, a tap, the keyboard), it moves an edge of the plot (a lit name that gets bolder makes room "auto" wider, and every bar slides) or the end of the chart's section (its outermost box in the page: a readout after the chart that takes a second line), by more than 2px. A control in a slat that moves with its slat (rows sorted or removed) is left out, and so are fixed and sticky elements. | A box that keeps its size: a readout on one line with an ellipsis, or a min-height for its longest text; buttons that keep their width; names that keep their weight and size when lit, or room in px. |
+| `layout-jump` | warning | An interaction of the pass, or a pick of the sweep, moves a control other than the one it used, or a chart's top, by more than 2px (a readout that takes a second line, a button whose label changes its width); or, while it lights a slat (pointing, a tap, the keyboard), it moves an edge of the plot (a lit name that gets bolder makes room "auto" wider, and every bar slides) or the end of the chart's section (its outermost box in the page: a readout after the chart that takes a second line), or it changes the size of a box around the charts that has a background, a border or a shadow and holds no chart (a readout's card that shrinks to its text, a legend's panel), by more than 2px. A control in a slat that moves with its slat (rows sorted or removed) is left out, and so are fixed and sticky elements; a box that floats (fixed or absolute: a tooltip) is left out. | A box that keeps its size: a readout on one line with an ellipsis, or a min-height for its longest text; a card or a panel with a fixed width, or a min-width and min-height for its longest content; buttons that keep their width; names that keep their weight and size when lit, or room in px. |
+| `text-shift` | warning | An interaction of the pass, a pick of the sweep, or a moment while a control runs (Play), moves a text around the charts whose own text did not change, by more than 2px, inside the box it floats in or on the page: a label after a value that got wider, a unit after a number in proportional figures, a readout's lines that change order, a legend that reflows, a column that resizes to its widest value. One finding per width, each text at the most it moved; a text that moved with a layout jump is that jump. | Numbers in tabular figures in a column of their own or with a min-width in ch, right-aligned; labels in their own column (a grid), not after a value on one line; lines in a fixed order; a min-height for the readout's longest text. |
+| `jitter` | warning | While the scrub moves the pointer along the chart, a text around the charts moves by more than 2px against the page at rest, inside the box it floats in or on the page: a label or a unit after a value that changed width ("8,101 tons in 2026", where " in 2026" slides), a phrase after a date whose month names differ in width, a sentence whose values change, a line that wraps on some days and not others. One finding per width, each text at the most it moved, named with the line it is part of; a text that moved with a layout jump is that jump, and a text found here is left out of the width's text-shift. | Start each part of the readout where nothing before it changes width: a grid with a column per part, or each part on a line of its own. Values in tabular figures with a min-width in ch for the longest value they can show, right-aligned when they end a column; the readout on its lines whatever it says (nowrap, or a min-height). |
+| `flicker` | warning | With a mouse, between two neighboring slats that each show something of their own, a step of the glide shows the page's text, or the slats, as they are with the pointer away: the pick clears in the gap between two bars and comes back, so the readout or the lit slat blinks as the reader moves along the chart. | Keep the pick while the pointer is between slats: change it only on another slat, clear it only when the pointer leaves the chart or the poster. |
 | `out-of-view` | warning | At a phone's width, in a window 664px tall, a tap on a slat that is in the window changes text the reader can see, and all of it lies outside the window (above, below or beside it), even when the tap lights the slat in view: a readout above a tall chart, when the last slat is tapped. | A readout next to the slat (in the slat, or in a Label of it), or one kept in view (`position: sticky`, with a z-index over the plot's 1). |
+| `scrolls-away` | info | The main chart is taller than three quarters of the window (664px at a phone's width), and with its middle in the middle of the window, all of its section's controls (not its fit and download icons), or all of its readout (the texts a pick rewrites), are out of view: the reader has to scroll back to change the year or to read the values. A note: keeping them in view is usually better, not always. | Consider `position: sticky; top: env(safe-area-inset-top, 0px)` on the row that holds them, with a background and a z-index over the plot's 1, compact on a phone, and `scroll-margin-top` on the slats so a picked slat is never under it. |
 | `focus-invisible` | warning | Tab reaches a slat or a control, and a screenshot of its box (with 12px around it) focused and blurred differ in under 20 pixels: `outline: none` with nothing in its place. | Keep the focus ring, or a `:focus-visible` style that shows in its place (on a slat, in the slat type's css). |
 
 ### Conditional selection repair
@@ -150,17 +166,25 @@ The tests read this table: every code in it must have a chart in `test/broken/`
 The shared checker runs this audit after creation, through both `rhp_check` and the CLI (`npx -y @bezda/rhp-mcp check <file>`).
 It does not require either click selection or hover, and these checks do not choose an interaction for the chart.
 On an isolated page, it first verifies that a click persists after the pointer leaves the poster, another slat's hover overrides it, and leaving the poster restores the clicked selection.
-Only that observed combination qualifies.
+That observed combination qualifies for the click-selection checks.
 It then checks a pointer move and a click on noninteractive text or margin inside the same poster, outside every chart and control.
 The initial appearance is the reset reference, preserving an existing default without guessing which subject should be selected.
+If the poster also has a visible range, number input, select, or external slider, the audit first checks whether two of its values reproduce two different chart hover states.
+Only a control proven to select the same data changes the reset policy; an unrelated filter does not qualify.
+For a proven selection control, the audit checks that leaving the chart restores its committed value and chosen view, and moving focus or clicking noninteractive poster space preserves that choice.
+The visible control may follow the hovered point during preview, provided it returns to the committed choice when preview ends.
+Native thumbs and focus rings are excluded from the image comparison, while the chart and its readout remain in the comparison.
+The initial-state reset recommendation is omitted for these persistent control selections.
 Moving pages, unreachable marks and sequences that scroll are inconclusive rather than findings.
-The audit samples up to three reachable slats of the main Plot at the first checked width.
+The audit samples up to three reachable slats of the main Plot at the first checked width, or both ends and the middle of a single continuous hit surface.
+Controls outside the viewport or without two observable matching selection states are inconclusive.
 It never changes the source; its conditional fix is returned to the authoring agent through the skill's existing check-and-fix step, with explicit user interaction instructions taking precedence.
 
 | Code | Level | What triggers it | Fix it gives |
 |---|---|---|---|
+| `selection-control-reset` | warning | A control demonstrably selects the same data as chart hover, but leaving the chart, moving focus, or clicking noninteractive poster space loses its committed value or chosen view. | Keep the committed input selection separate from hover; allow a synchronized preview while preserving the choice through pointer and focus changes, and share it with chart click, tap, and keyboard selection. |
 | `selection-hover-stays` | warning | Verified click selection with a temporary hover override: moving off the chart but staying in the poster does not restore the clicked selection, although leaving the poster does. | Clear only the hover preview on leaving the chart area; preserve the clicked selection, unless the user explicitly asked for different behavior. |
-| `selection-reset` | warning | The same verified pattern: clicking noninteractive poster space outside the chart fails to restore the initial appearance. | Clear the selection if no default existed, or restore the chart's meaningful default; preserve explicitly requested behavior and other controls. |
+| `selection-reset` | warning | The same verified pattern, without a proven external selection control: clicking noninteractive poster space outside the chart fails to restore the initial appearance. | Clear the selection if no default existed, or restore the chart's meaningful default; preserve explicitly requested behavior and other controls. |
 
 ### Colors (read from screenshots)
 

package/src/check/build.js

@@ -10,6 +10,7 @@ import path from "path";
 import crypto from "crypto";
 import { fileURLToPath } from "url";
 import * as esbuild from "esbuild";
+import { moduleSpecifiers } from "./source.js";
 
 const here = path.dirname(fileURLToPath(import.meta.url));
 const GUARD = path.join(here, "../guard");
@@ -423,12 +424,12 @@ export async function htmlProblems(file, text) {
     }
 
     if (module) {
-      for (const [, spec] of body.matchAll(/(?:from|import)\s*\(?\s*["']([^"'./][^"']*)["']/g)) {
-        if (/^(https?:|data:|blob:)/.test(spec) || spec in mapped || Object.keys(mapped).some((k) => k.endsWith("/") && spec.startsWith(k))) continue;
+      for (const { source: spec, line } of moduleSpecifiers(body, file)) {
+        if (/^(https?:|data:|blob:|\.|\/)/.test(spec) || spec in mapped || Object.keys(mapped).some((k) => k.endsWith("/") && spec.startsWith(k))) continue;
         problems.push({
           level: "error",
           code: "missing-import-map",
-          message: `${path.basename(file)}:${start}: the module script imports "${spec}", but no import map says where it comes from.`,
+          message: `${path.basename(file)}:${start + line - 1}: the module script imports "${spec}", but no import map says where it comes from.`,
           fix: spec.startsWith("@bezda/rhp") ? 'Add <script type="importmap">{ "imports": { "@bezda/rhp/standalone": "https://cdn.jsdelivr.net/npm/@bezda/rhp@2/dist/standalone.js" } }</script> before the module script.' : `Add "${spec}" to the page's import map, or import it by URL.`,
         });
       }

package/src/check/colors.js

@@ -164,11 +164,13 @@ export function colorBlind(items, hidden, k) {
   }
 
   for (const marks of charts.values()) {
-    // one entry per color, colors that look the same merged
+    // One authored paint is still one series over a photograph, even when transparent marks
+    // blend with different parts of it. Also merge colors that already look the same.
     const colors = [];
     for (const m of marks) {
       const rgb = m.rgb;
-      let c = colors.find((x) => difference(x.rgb, rgb) < 2);
+      const samePaint = (other) => other.opacity === m.opacity && other.color.every((v, i) => v === m.color[i]);
+      let c = colors.find((x) => x.marks.some(samePaint) || difference(x.rgb, rgb) < 2);
       if (!c) colors.push((c = { rgb, names: new Set(), marks: [] }));
       c.marks.push(m);
       for (const n of m.names) {