@12ui/design 0.2.51 → 0.2.53

package/prototype-kit/polish/rules/section-breathing.mjs

@@ -1,291 +1,515 @@
-// section-breathing: add deliberate air at declared page and internal section boundaries while preserving the
-// boundary's proven solid ground. The rule remains page-atomic and the driver verifies its paint with real pixels.
+// section-breathing: open only model-declared semantic boundaries.
 //
-// Declared facts, not page names, drive the r3 widening:
-//   - adjacent `section[id^=viewport-]` blocks remain the page-seam source;
-//   - a direct child `footer`, `*-faq` / `*-questions`, or full-width `*-partners` block is an internal semantic seam;
-//   - only explicit `.decoration` leaves whose bounds touch/cross a page seam travel with the section below it;
-//   - an explicit `dashboard` block stays silent (dense surfaces keep their deliberate compression).
+// The model names the exact before/after elements, exact ground owner, and
+// whether that owner may continue. This rule validates and executes that fact;
+// no tag, id-pattern, size, pixel sample, or nearest-ground search may mint it.
 //
-// Solid page-seam paint uses an integer-offset shadow. Internal seams grow the section and its full-section solid
-// owner, then move the semantic block and later direct children. Gradient/image/texture grounds still abstain.
+// A semantic seam's AMOUNT is the page's own rhythm, not a constant. The page
+// scale T = min(largest structural gap, 2 x median structural gap) is derived
+// from the vertical air the page already contains, and a seam is opened to T
+// and never past it. The gap it is opened FROM is the page's real air line —
+// the bottom of the lowest peer that ends above the seam — not the pairwise
+// distance between the two declared elements, which reads air that is not there
+// when a floating card or intro column sits inside the seam.
 export const name = 'section-breathing';
 export const maxShift = 192;
 export const phase = 'post';
 export const verifyPaint = true;
 export const recordsCensus = true;
 export const params = {
-  FLOOR: 32,
-  CAP: 64,
-  MIN_TARGET: 48,
-  MAX_TARGET: 192,
-  COVER: 0.8,
-  TIGHT_GAP: 32,
-  SEMANTIC_MAX_GAP: 32,
-  SEMANTIC_WIDTH: 0.8,
-  PREVIOUS_BLOCK_WIDTH: 0.5,
+  FLOOR: 32, CAP: 64, MIN_TARGET: 48, MAX_TARGET: 192,
+  TIGHT_GAP: 32, SEMANTIC_MAX_GAP: 32,
+  // Page-rhythm model (semantic seams only; viewport seams keep FLOOR/MIN_TARGET/MAX_TARGET).
+  PERCEPTIBILITY_FLOOR: 8,
+  SCOPE_WIDTH_FRACTION: 0.4,
+  STRUCTURAL_MIN_INK: 2,
+  // A group whose stacked children share no common edge and vary wildly in width is a
+  // drawing (a metro map, a scatter), not a stack. Air inserted into it pulls the drawing apart.
+  DIAGRAM_MIN_CHILDREN: 4,
+  DIAGRAM_MAX_ALIGN_FRACTION: 0.5,
+  DIAGRAM_MIN_WIDTH_CV: 0.6,
+  DIAGRAM_EDGE_TOLERANCE: 4,
 };
+export const SECTION_BOUNDARY_DECLARATION_REVISION = 'section-boundary-v1';
 
 export function browserFn() {
   return ({ params }) => {
+    const RULE = 'section-breathing';
+    const REVISION = 'section-boundary-v1';
     const P = Object.assign({
-      FLOOR: 32, CAP: 64, MIN_TARGET: 48, MAX_TARGET: 192, COVER: 0.8,
-      TIGHT_GAP: 32, SEMANTIC_MAX_GAP: 32, SEMANTIC_WIDTH: 0.8, PREVIOUS_BLOCK_WIDTH: 0.5,
+      FLOOR: 32, CAP: 64, MIN_TARGET: 48, MAX_TARGET: 192,
+      TIGHT_GAP: 32, SEMANTIC_MAX_GAP: 32,
+      PERCEPTIBILITY_FLOOR: 8,
+      SCOPE_WIDTH_FRACTION: 0.4,
+      STRUCTURAL_MIN_INK: 2,
+      DIAGRAM_MIN_CHILDREN: 4,
+      DIAGRAM_MAX_ALIGN_FRACTION: 0.5,
+      DIAGRAM_MIN_WIDTH_CV: 0.6,
+      DIAGRAM_EDGE_TOLERANCE: 4,
     }, params || {});
     const out = [];
     const visible = (el) => {
-      const s = getComputedStyle(el);
-      if (s.display === 'none' || s.visibility === 'hidden' || parseFloat(s.opacity) === 0) return false;
-      const r = el.getBoundingClientRect();
-      return r.width > 0 && r.height > 0;
+      if (!el) return false;
+      const style = getComputedStyle(el); const rect = el.getBoundingClientRect();
+      return style.display !== 'none' && style.visibility !== 'hidden'
+        && Number.parseFloat(style.opacity) !== 0 && rect.width > 0 && rect.height > 0;
     };
     const alphaOf = (color) => {
-      const m = color && color.match(/^rgba?\(([^)]+)\)$/);
-      if (!m) return color === 'transparent' ? 0 : 1;
-      const p = m[1].split(/[, /]+/).filter(Boolean).map(Number);
-      return p.length > 3 ? p[3] : 1;
+      const match = color && color.match(/^rgba?\(([^)]+)\)$/);
+      if (!match) return color === 'transparent' ? 0 : 1;
+      const parts = match[1].split(/[, /]+/).filter(Boolean).map(Number);
+      return parts.length > 3 ? parts[3] : 1;
     };
-    const groundClass = (style, el) => {
-      if (['IMG', 'PICTURE', 'VIDEO'].includes(el.tagName)) return 'image';
-      const img = style.backgroundImage;
-      if (/repeating-(?:linear|radial|conic)-gradient\(/.test(img)) return 'texture';
-      if (/(?:linear|radial|conic)-gradient\(/.test(img)) return 'gradient';
-      if (img !== 'none') return style.backgroundRepeat === 'no-repeat' ? 'image' : 'texture';
-      return alphaOf(style.backgroundColor) > 0.01 ? 'solid' : 'transparent';
-    };
-    const INK = '.text, .paragraph, h1, h2, h3, h4, h5, h6, .icon, img, .image, button, .button';
-    const median = (v) => {
-      const s = [...v].sort((a, b) => a - b); const m = Math.floor(s.length / 2);
-      return s.length % 2 ? s[m] : (s[m - 1] + s[m]) / 2;
-    };
-    const ceil8 = (v) => Math.ceil(v / 8) * 8;
     const sections = [...document.querySelectorAll('section[id^="viewport-"]')]
-      .filter((s) => /^viewport-\d+-[A-Za-z0-9]+$/.test(s.id) && visible(s))
-      .sort((a, b) => a.getBoundingClientRect().top - b.getBoundingClientRect().top);
-    if (!sections.length) return out;
-
-    const validSolidOwner = (o, section, edge = null) => {
-      if (!o) return { ok: false, reason: 'ground-owner-unproven' };
-      const sr = section.getBoundingClientRect();
-      if (o.gc !== 'solid') return { ok: false, reason: `${o.gc}-ground (experimental class, abstain)` };
-      if (Math.abs(o.rect.left - sr.left) > 0.75 || Math.abs(o.rect.right - sr.right) > 0.75) {
-        return { ok: false, reason: 'ground-does-not-own-full-seam' };
-      }
-      if (edge && (edge === 'bottom' ? Math.abs(o.rect.bottom - sr.bottom) : Math.abs(o.rect.top - sr.top)) > 0.75) {
-        return { ok: false, reason: 'ground-does-not-touch-edge' };
-      }
-      const cs = o.cs;
-      if (cs.boxShadow !== 'none' || cs.clipPath !== 'none' || cs.maskImage !== 'none') {
-        return { ok: false, reason: 'owner-has-shadow-clip-or-mask' };
-      }
-      if (/var\(/.test(cs.backgroundColor) || alphaOf(cs.backgroundColor) < 0.999) {
-        return { ok: false, reason: 'transparent-or-unresolved-solid' };
-      }
-      if (!o.el.id) return { ok: false, reason: 'owner-has-no-id' };
-      return { ok: true, owner: o.el, color: cs.backgroundColor };
+      .filter((section) => /^viewport-\d+-[A-Za-z0-9]+$/.test(section.id) && visible(section))
+      .sort((left, right) => left.getBoundingClientRect().top - right.getBoundingClientRect().top);
+    const sectionIndex = new Map(sections.map((section, index) => [section, index]));
+    const declarations = [...document.querySelectorAll('[data-ly-section-boundary="before"]')].filter(visible);
+    const INK_SELECTOR = '.text,.paragraph,h1,h2,h3,h4,h5,h6,.icon,img,.image,button,.button';
+    const solidGround = (element) => {
+      const style = getComputedStyle(element);
+      return style.backgroundImage === 'none'
+        && alphaOf(style.backgroundColor) >= 0.999
+        && !/var\(/.test(style.backgroundColor)
+        && style.clipPath === 'none' && style.maskImage === 'none';
     };
-    const ownerAt = (section, edge) => {
-      const sr = section.getBoundingClientRect(); const y = edge === 'bottom' ? sr.bottom - 1 : sr.top + 1;
-      const cands = [section, ...section.querySelectorAll('*')].flatMap((el) => {
-        if (!visible(el)) return [];
-        const r = el.getBoundingClientRect();
-        if (!(r.top <= y && r.bottom >= y) || r.width < sr.width * P.COVER) return [];
-        const cs = getComputedStyle(el); const gc = groundClass(cs, el);
-        if (gc === 'transparent') return [];
-        const cls = typeof el.className === 'string' ? el.className : '';
-        if (['IMG', 'PICTURE', 'VIDEO'].includes(el.tagName) && /(?:^|\s)(?:decoration|icon|logo|badge|photo|image)(?:\s|$)/.test(cls)) return [];
-        return [{ el, rect: r, area: r.width * r.height, gc, cs }];
-      }).sort((a, b) => a.area - b.area || String(a.el.id).localeCompare(String(b.el.id)));
-      return cands[0] || null;
+    // Leaf ink: an ink element that contains no ink of its own. Counting leaves rather than
+    // nodes is what keeps label-to-title line leading inside a card from reading as page air.
+    const leafInk = (element) => [...element.querySelectorAll(INK_SELECTOR)].filter(visible)
+      .filter((node) => ![...node.querySelectorAll(INK_SELECTOR)].some(visible)).length
+      || (element.matches(INK_SELECTOR) ? 1 : 0);
+    const stackedChildren = (element) => [...element.children]
+      .filter((child) => visible(child) && child.id)
+      .sort((left, right) => left.getBoundingClientRect().top - right.getBoundingClientRect().top);
+    // Consecutive vertical air inside one container. Children that overlap vertically are one
+    // run (side-by-side columns), so a gap is page air rather than a column edge.
+    const airRuns = (element) => {
+      const children = stackedChildren(element);
+      const runs = [];
+      let bottom = null; let previous = null;
+      for (const child of children) {
+        const rect = child.getBoundingClientRect();
+        if (bottom === null) { bottom = rect.bottom; previous = child; }
+        else {
+          const gap = rect.top - bottom;
+          if (gap > -0.5) { runs.push({ before: previous, after: child, gap, y: bottom }); previous = child; }
+          bottom = Math.max(bottom, rect.bottom);
+        }
+      }
+      return runs;
     };
-    const fullSectionOwner = (section) => {
-      const sr = section.getBoundingClientRect();
-      const cands = [section, ...section.querySelectorAll('*')].flatMap((el) => {
-        if (!visible(el)) return [];
-        const r = el.getBoundingClientRect();
-        if (r.left > sr.left + 0.75 || r.right < sr.right - 0.75 || r.top > sr.top + 0.75 || r.bottom < sr.bottom - 0.75) return [];
-        const cs = getComputedStyle(el); const gc = groundClass(cs, el);
-        if (gc === 'transparent') return [];
-        return [{ el, rect: r, area: r.width * r.height, gc, cs }];
-      }).sort((a, b) => a.area - b.area || String(a.el.id).localeCompare(String(b.el.id)));
-      return validSolidOwner(cands[0] || null, section);
+    // The page's own spacing scale, from every structural gap at every nesting depth.
+    // Structural = the container spans a real share of the page AND both sides carry ink.
+    const pageScaleTarget = () => {
+      const pageWidth = Math.max(0, ...sections.map((section) => section.getBoundingClientRect().width));
+      const gaps = [];
+      const walk = (element, depth) => {
+        if (depth > 6) return;
+        const rect = element.getBoundingClientRect();
+        if (rect.width >= P.SCOPE_WIDTH_FRACTION * pageWidth) {
+          for (const run of airRuns(element)) {
+            if (leafInk(run.before) >= P.STRUCTURAL_MIN_INK && leafInk(run.after) >= P.STRUCTURAL_MIN_INK) {
+              gaps.push(run.gap);
+            }
+          }
+        }
+        for (const child of stackedChildren(element)) walk(child, depth + 1);
+      };
+      for (const section of sections) walk(section, 1);
+      if (!gaps.length) return { target: null, gaps: 0, median: null, largest: null };
+      const sorted = [...gaps].sort((left, right) => left - right);
+      const median = sorted.length % 2
+        ? sorted[(sorted.length - 1) / 2]
+        : (sorted[sorted.length / 2 - 1] + sorted[sorted.length / 2]) / 2;
+      const largest = sorted[sorted.length - 1];
+      return { target: Math.min(largest, 2 * median), gaps: gaps.length, median, largest };
     };
-    const inkEdge = (section, edge) => {
-      const sr = section.getBoundingClientRect();
-      const ink = [...section.querySelectorAll(INK)].filter(visible).map((el) => el.getBoundingClientRect());
-      if (!ink.length) return null;
-      return edge === 'bottom' ? Math.max(...ink.map((r) => r.bottom)) - sr.top : Math.min(...ink.map((r) => r.top)) - sr.top;
+    // The page's real air line at a seam: the bottom of the lowest peer that ends above the cut.
+    // The declared `before` is only one candidate; a floating note card or an intro column that
+    // outlives it is what the eye actually reads the air from.
+    const realAirLine = (group, after) => {
+      const cut = after.getBoundingClientRect().top;
+      const peers = [...group.children].filter((child) => child !== after && visible(child) && child.id)
+        .filter((child) => child.getBoundingClientRect().bottom <= cut + 0.5);
+      if (!peers.length) return null;
+      const anchor = peers.reduce((lowest, child) => (
+        child.getBoundingClientRect().bottom > lowest.getBoundingClientRect().bottom ? child : lowest
+      ));
+      return { anchor, peers, gap: cut - anchor.getBoundingClientRect().bottom };
     };
-    const directChildOf = (section, el) => {
-      let child = el;
-      while (child.parentElement && child.parentElement !== section) child = child.parentElement;
-      return child.parentElement === section ? child : null;
+    // A group whose stacked children share no common left/right/centre edge and whose widths vary
+    // wildly is a drawing, not a stack: its vertical gaps carry meaning and must not be opened.
+    const diagramLike = (element) => {
+      const runs = airRuns(element);
+      if (!runs.length) return false;
+      const stacked = [runs[0].before, ...runs.map((run) => run.after)];
+      if (stacked.length < P.DIAGRAM_MIN_CHILDREN) return false;
+      const boxes = stacked.map((child) => child.getBoundingClientRect());
+      const largestCluster = (values) => {
+        const buckets = new Map();
+        for (const value of values) {
+          const key = Math.round(value / P.DIAGRAM_EDGE_TOLERANCE);
+          buckets.set(key, (buckets.get(key) || 0) + 1);
+        }
+        return Math.max(...buckets.values());
+      };
+      const alignFraction = Math.max(
+        largestCluster(boxes.map((box) => box.left)),
+        largestCluster(boxes.map((box) => box.right)),
+        largestCluster(boxes.map((box) => (box.left + box.right) / 2)),
+      ) / boxes.length;
+      const widths = boxes.map((box) => box.width);
+      const mean = widths.reduce((sum, width) => sum + width, 0) / widths.length;
+      if (!(mean > 0.5)) return false;
+      const widthCv = Math.sqrt(widths.reduce((sum, width) => sum + (width - mean) ** 2, 0) / widths.length) / mean;
+      return alignFraction < P.DIAGRAM_MAX_ALIGN_FRACTION && widthCv >= P.DIAGRAM_MIN_WIDTH_CV;
     };
-    const attachmentsAt = (section, seamY) => {
-      const cands = [...section.querySelectorAll('.decoration[id]')].filter(visible).filter((el) => {
-        const r = el.getBoundingClientRect();
-        return r.top < seamY && r.bottom >= seamY - 0.75 && r.width < section.getBoundingClientRect().width * P.COVER;
-      });
-      return cands.filter((el) => !cands.some((other) => other !== el && el.contains(other))).map((el) => {
-        const r = el.getBoundingClientRect();
-        return { el, topOffset: +(r.top - seamY).toFixed(2), bottomOffset: +(r.bottom - seamY).toFixed(2) };
-      });
+    // Air inserted strictly inside a container is painted by that container's own background, so a
+    // seam below the section's direct children needs no new ownership proof — only a solid enclosing
+    // ground that already spans the group and already continues past the cut.
+    const enclosingPainter = (group, after) => {
+      const groupRect = group.getBoundingClientRect();
+      const cut = after.getBoundingClientRect().top;
+      for (let node = group; node; node = node.parentElement) {
+        if (solidGround(node)) {
+          const rect = node.getBoundingClientRect();
+          if (rect.left <= groupRect.left + 0.75 && rect.right >= groupRect.right - 0.75
+            && rect.top <= cut - 0.75 && rect.bottom >= cut + 0.75) return node;
+        }
+        if (node === group.closest('section[id^="viewport-"]')) break;
+      }
+      return null;
     };
-
-    const viewportSeams = [];
-    for (let i = 1; i < sections.length; i++) {
-      const before = sections[i - 1], after = sections[i];
-      const br = before.getBoundingClientRect(), ar = after.getBoundingClientRect();
-      const lastInk = inkEdge(before, 'bottom'), firstInk = inkEdge(after, 'top');
-      if (lastInk == null || firstInk == null) continue;
-      const gap = (br.height - lastInk) + (ar.top - br.bottom) + firstInk;
-      if (gap < 0) continue;
-      viewportSeams.push({ kind: 'viewport', before, after, section: before, gap });
-    }
-    const target = viewportSeams.length === 1
-      ? viewportSeams[0].gap + P.FLOOR
-      : viewportSeams.length
-        ? Math.max(P.MIN_TARGET, Math.min(P.MAX_TARGET, ceil8(median(viewportSeams.map((s) => s.gap)) + P.FLOOR)))
-        : null;
-    const viewportPlans = viewportSeams.map((s) => {
-      const raw = Math.round(Math.min(P.CAP, Math.max(0, target - s.gap)));
-      const tightScaled = raw > 0 && raw < P.FLOOR && s.gap < P.TIGHT_GAP;
-      const addition = tightScaled ? P.FLOOR : raw;
-      if (addition < P.FLOOR) {
-        return { ...s, addition, declined: addition > 0 ? 'below the 32 px perceptibility floor' : 'already at the page rhythm target' };
+    const scale = pageScaleTarget();
+    const selectorValue = (value) => window.CSS?.escape
+      ? CSS.escape(value) : value.replace(/(["\\])/g, '\\$1');
+    const refusal = (after, reason, extra = {}) => ({
+      kind: after.matches('section[id^="viewport-"]') ? 'viewport' : 'semantic',
+      section: (after.closest('section[id^="viewport-"]') || after).id || null,
+      before: after.dataset.lySectionBefore || null,
+      after: after.id || null,
+      fact: after.dataset.lySectionFact || null,
+      gap: null, addition: 0, declared: true, declined: reason,
+      pageScale: scale.target == null ? null : {
+        target: +scale.target.toFixed(1), median: +scale.median.toFixed(1),
+        largest: +scale.largest.toFixed(1), structuralGaps: scale.gaps,
+      },
+      ground: { reason }, ...extra,
+    });
+    const validate = (after) => {
+      if (after.dataset.lySectionBoundaryRevision !== REVISION) {
+        return { ok: false, census: refusal(after, 'section-boundary-stale') };
       }
-      const tryOwner = (section, edge) => {
-        const valid = validSolidOwner(ownerAt(section, edge), section, edge);
-        return valid.ok ? { ...valid, side: edge === 'bottom' ? 'outgoing' : 'incoming' } : valid;
+      if (!after.id) return { ok: false, census: refusal(after, 'section-boundary-after-unidentified') };
+      const beforeId = after.dataset.lySectionBefore || '';
+      const ownerKey = after.dataset.lySectionOwner || '';
+      const before = beforeId ? document.getElementById(beforeId) : null;
+      const owners = ownerKey
+        ? [...document.querySelectorAll(`[data-ly-section-ground-owner="${selectorValue(ownerKey)}"]`)] : [];
+      if (!before) return { ok: false, census: refusal(after, 'section-boundary-before-missing') };
+      if (owners.length !== 1) return {
+        ok: false,
+        census: refusal(after, owners.length ? 'section-boundary-owner-ambiguous' : 'section-boundary-owner-missing'),
       };
-      const outgoing = tryOwner(s.before, 'bottom'); const ground = outgoing.ok ? outgoing : tryOwner(s.after, 'top');
-      const seamY = s.after.getBoundingClientRect().top;
+      if (after.dataset.lySectionOpenability === 'not-openable') {
+        return { ok: false, census: refusal(after, 'declared-not-openable', { before: before.id }) };
+      }
+      if (after.dataset.lySectionOpenability !== 'openable'
+        || after.dataset.lySectionContinuation !== 'owner-fill') {
+        return { ok: false, census: refusal(after, 'section-boundary-continuation-invalid', { before: before.id }) };
+      }
+      const owner = owners[0];
+      const afterSection = after.matches('section[id^="viewport-"]') ? after : after.closest('section[id^="viewport-"]');
+      const beforeSection = before.matches('section[id^="viewport-"]') ? before : before.closest('section[id^="viewport-"]');
+      const kind = after.matches('section[id^="viewport-"]') ? 'viewport' : 'semantic';
+      if (!afterSection || !beforeSection) return { ok: false, census: refusal(after, 'section-boundary-outside-viewport') };
+      let group = null; let painter = null;
+      if (kind === 'viewport') {
+        if (sectionIndex.get(afterSection) !== sectionIndex.get(beforeSection) + 1) {
+          return { ok: false, census: refusal(after, 'section-boundary-not-adjacent', { before: before.id }) };
+        }
+      } else {
+        // A semantic seam is air between two siblings. The pair may sit at any depth inside the
+        // section, not only among its direct children, provided the group they share is enclosed
+        // by ground that already paints the cut (see enclosingPainter).
+        if (afterSection !== beforeSection || after.parentElement !== before.parentElement) {
+          return { ok: false, census: refusal(after, 'section-boundary-crosses-owner-section', { before: before.id }) };
+        }
+        group = after.parentElement;
+        if (group !== afterSection && !afterSection.contains(group)) {
+          return { ok: false, census: refusal(after, 'section-boundary-outside-viewport', { before: before.id }) };
+        }
+        if (diagramLike(group)) {
+          return { ok: false, census: refusal(after, 'declared-inside-diagram-group', { before: before.id }) };
+        }
+        if (group !== afterSection) {
+          painter = enclosingPainter(group, after);
+          if (!painter) {
+            return { ok: false, census: refusal(after, 'nested-seam-ground-unpainted', { before: before.id }) };
+          }
+          // The painter supplies the paint proof; the declared owner still bounds WHERE the model
+          // authorised air, so the painter must lie inside that ground — by nesting or by covering.
+          const ownerBox = owner.getBoundingClientRect();
+          const painterBox = painter.getBoundingClientRect();
+          const insideOwner = owner === painter || owner.contains(painter)
+            || (ownerBox.left <= painterBox.left + 0.75 && ownerBox.right >= painterBox.right - 0.75
+              && ownerBox.top <= painterBox.top + 0.75 && ownerBox.bottom >= painterBox.bottom - 0.75);
+          if (!insideOwner) {
+            return { ok: false, census: refusal(after, 'nested-seam-ground-outside-owner', { before: before.id }) };
+          }
+        }
+      }
+      if (!(owner.contains(afterSection) || afterSection.contains(owner))) {
+        return { ok: false, census: refusal(after, 'section-boundary-owner-disconnected', { before: before.id }) };
+      }
+      // A nested seam's ground is the enclosing painter, already proven solid and already spanning
+      // the cut, so the section-scale owner geometry below does not apply to it.
+      if (painter) {
+        return {
+          ok: true, kind, section: afterSection, group, painter, before, after, owner, ownerKey,
+          color: getComputedStyle(painter).backgroundColor, fact: after.dataset.lySectionFact || null,
+          execution: 'group-shift', ownerChildren: [],
+        };
+      }
+      const ownerStyle = getComputedStyle(owner);
+      const ownerRect = owner.getBoundingClientRect();
+      const sectionRect = afterSection.getBoundingClientRect();
+      const ownerIsAfter = owner === after;
+      const fullWidth = ownerRect.left <= sectionRect.left + 0.75
+        && ownerRect.right >= sectionRect.right - 0.75;
+      const coversSection = fullWidth && ownerRect.top <= sectionRect.top + 0.75
+        && ownerRect.bottom >= sectionRect.bottom - 0.75;
+      if (!(ownerIsAfter ? fullWidth : coversSection)) {
+        return { ok: false, census: refusal(after, ownerIsAfter
+          ? 'declared-owner-not-full-width' : 'declared-owner-does-not-cover-section', { before: before.id }) };
+      }
+      const alpha = alphaOf(ownerStyle.backgroundColor);
+      const solid = ownerStyle.backgroundImage === 'none'
+        && alpha >= (ownerIsAfter ? 0.01 : 0.999)
+        && !/var\(/.test(ownerStyle.backgroundColor);
+      // owner-fill never stretches raster/image/texture owners. Unsupported
+      // continuation programs refuse this region explicitly.
+      if (!solid) return { ok: false, census: refusal(after, 'declared-owner-fill-unverifiable', { before: before.id }) };
+      if (ownerStyle.clipPath !== 'none' || ownerStyle.maskImage !== 'none') {
+        return { ok: false, census: refusal(after, 'declared-owner-clipped-or-masked', { before: before.id }) };
+      }
+      const ownerChildren = ownerIsAfter ? [...owner.children].filter(visible) : [];
+      if (ownerIsAfter && (!ownerChildren.length || ownerChildren.some((child) => !child.id))) {
+        return { ok: false, census: refusal(after, 'declared-owner-children-unidentified', { before: before.id }) };
+      }
       return {
-        ...s, addition, tightScaled, ground,
-        diagnostics: outgoing.ok ? null : { outgoing: outgoing.reason, incoming: ground.reason },
-        attachments: attachmentsAt(s.before, seamY),
+        ok: true, kind, section: afterSection, group: group || afterSection, painter: null,
+        before, after, owner, ownerKey,
+        color: ownerStyle.backgroundColor, fact: after.dataset.lySectionFact || null,
+        execution: ownerIsAfter ? 'owner-leading-air' : 'section-shift', ownerChildren,
       };
-    });
-
-    const semanticPlans = [];
-    for (const section of sections) {
-      const sr = section.getBoundingClientRect(); const children = [...section.children].filter(visible);
-      const ground = fullSectionOwner(section);
-      const semantic = children.flatMap((el) => {
-        const id = el.id.toLowerCase(); const r = el.getBoundingClientRect();
-        const fact = el.tagName === 'FOOTER' ? 'footer'
-          : /(?:^|[-_])(?:faq|questions)(?:[-_]|$)/.test(id) ? 'questions'
-            : /(?:^|[-_])partners(?:[-_]|$)/.test(id) ? 'partners' : null;
-        return fact && el.id && r.width >= sr.width * P.SEMANTIC_WIDTH ? [{ el, fact, rect: r }] : [];
-      }).sort((a, b) => a.rect.top - b.rect.top);
-      for (const candidate of semantic) {
-        const eligible = children.filter((el) => {
-          if (el === candidate.el || el === ground.owner || !el.id) return false;
-          const r = el.getBoundingClientRect();
-          const fullSection = r.top <= sr.top + 0.75 && r.bottom >= sr.bottom - 0.75;
-          return !fullSection && r.width >= sr.width * P.PREVIOUS_BLOCK_WIDTH && r.bottom <= candidate.rect.top + 0.75;
-        }).sort((a, b) => b.getBoundingClientRect().bottom - a.getBoundingClientRect().bottom);
-        const before = eligible[0]; if (!before) continue;
-        const br = before.getBoundingClientRect(); const gap = candidate.rect.top - br.bottom;
-        if (gap < 0) continue;
-        // Moving a full-width semantic block deliberately changes its vertical relation to every substantial direct
-        // block before it (including unequal-height columns). Declare that exact target relation; unrelated sibling
-        // gaps remain protected by the harm guard.
-        const beforePeers = children.filter((el) => {
-          if (el === candidate.el || el === ground.owner || !el.id) return false;
-          const r = el.getBoundingClientRect();
-          const fullSection = r.top <= sr.top + 0.75 && r.bottom >= sr.bottom - 0.75;
-          return !fullSection && r.bottom <= candidate.rect.top + 0.75;
-        }).map((el) => el.id);
-        const dense = [before.id, candidate.el.id].some((id) => /(?:^|[-_])dashboard(?:[-_]|$)/.test(id.toLowerCase()));
-        const addition = ground.ok && !dense && gap < P.SEMANTIC_MAX_GAP ? P.FLOOR : 0;
-        semanticPlans.push({
-          kind: 'semantic', section, before, beforePeers, after: candidate.el, fact: candidate.fact, gap,
-          addition, ground,
-          declined: !ground.ok ? ground.reason
-            : dense ? 'dense dashboard boundary stays tight'
-            : addition ? null : 'semantic boundary already has at least 32 px',
-        });
+    };
+    const inkEdge = (section, edge) => {
+      const sectionRect = section.getBoundingClientRect();
+      const ink = [...section.querySelectorAll('.text,.paragraph,h1,h2,h3,h4,h5,h6,.icon,img,.image,button,.button')]
+        .filter(visible).map((element) => element.getBoundingClientRect());
+      if (!ink.length) return null;
+      return edge === 'bottom'
+        ? Math.max(...ink.map((rect) => rect.bottom)) - sectionRect.top
+        : Math.min(...ink.map((rect) => rect.top)) - sectionRect.top;
+    };
+    const valid = []; const census = [];
+    for (const after of declarations) {
+      const declaration = validate(after);
+      if (!declaration.ok) { census.push(declaration.census); continue; }
+      let gap;
+      if (declaration.kind === 'viewport') {
+        const beforeRect = declaration.before.getBoundingClientRect();
+        const afterRect = declaration.after.getBoundingClientRect();
+        const lastInk = inkEdge(declaration.before, 'bottom');
+        const firstInk = inkEdge(declaration.after, 'top');
+        if (lastInk == null || firstInk == null) {
+          census.push(refusal(after, 'section-boundary-ink-unmeasurable', { before: declaration.before.id }));
+          continue;
+        }
+        gap = (beforeRect.height - lastInk) + (afterRect.top - beforeRect.bottom) + firstInk;
+      } else {
+        // Measure the air the page actually shows at this seam, not the distance between the two
+        // declared boxes: a floating card or an intro column that outlives `before` is what the
+        // eye reads the air from, and it is what the inserted band will actually sit under.
+        const air = realAirLine(declaration.group, declaration.after);
+        if (!air) {
+          census.push(refusal(after, 'section-boundary-air-unmeasurable', { before: declaration.before.id }));
+          continue;
+        }
+        gap = air.gap;
+        declaration.airAnchor = air.anchor;
+        declaration.airPeers = air.peers;
+      }
+      if (!Number.isFinite(gap) || gap < 0) {
+        census.push(refusal(after, 'section-boundary-gap-invalid', { before: declaration.before.id, gap }));
+        continue;
       }
+      valid.push({ ...declaration, gap });
     }
-
-    const censusRow = (p) => ({
-      kind: p.kind, section: p.section.id, before: p.before.id, after: p.after.id, fact: p.fact || null,
-      gap: +p.gap.toFixed(1), addition: p.addition, declined: p.declined || null,
-      tightScaled: p.tightScaled || false,
-      attachments: (p.attachments || []).map((a) => a.el.id),
-      ground: p.ground ? (p.ground.ok ? { side: p.ground.side || 'internal', color: p.ground.color, owner: p.ground.owner.id } : (p.diagnostics || { reason: p.ground.reason })) : null,
+    const viewport = valid.filter((row) => row.kind === 'viewport');
+    const viewportGaps = viewport.map((row) => row.gap).sort((a, b) => a - b);
+    const medianGap = viewportGaps.length % 2
+      ? viewportGaps[Math.floor(viewportGaps.length / 2)]
+      : viewportGaps.length ? (viewportGaps[viewportGaps.length / 2 - 1] + viewportGaps[viewportGaps.length / 2]) / 2 : null;
+    const viewportTarget = viewport.length === 1 ? viewport[0].gap + P.FLOOR
+      : viewport.length ? Math.max(P.MIN_TARGET, Math.min(P.MAX_TARGET, Math.ceil((medianGap + P.FLOOR) / 8) * 8)) : null;
+    const plans = valid.map((row) => {
+      if (row.kind !== 'viewport') {
+        // Page-rhythm model: bring an under-scale seam up to what this page already does elsewhere,
+        // and never invent an amount the page has not itself used. addition = max(0, T - gap).
+        const floor = P.PERCEPTIBILITY_FLOOR;
+        const addition = scale.target == null ? 0
+          : +Math.min(P.CAP, Math.max(0, scale.target - row.gap)).toFixed(1);
+        const capped = scale.target != null && scale.target - row.gap > P.CAP;
+        const declined = scale.target == null ? 'page has no structural gap to set a scale from'
+          : addition < floor
+            ? (addition > 0 ? `below the ${floor} px perceptibility floor`
+                : 'already at the page rhythm target')
+            : null;
+        census.push({
+          kind: row.kind, section: row.section.id, group: row.group?.id || row.section.id,
+          before: row.before.id, airAnchor: row.airAnchor?.id || null, after: row.after.id,
+          fact: row.fact, gap: +row.gap.toFixed(1), addition, capped, declared: true, declined,
+          pageScale: scale.target == null ? null : {
+            target: +scale.target.toFixed(1), median: +scale.median.toFixed(1),
+            largest: +scale.largest.toFixed(1), structuralGaps: scale.gaps,
+          },
+          ground: { owner: row.ownerKey, color: row.color, continuation: 'owner-fill', execution: row.execution },
+        });
+        return { ...row, addition, capped, declined };
+      }
+      const raw = Math.round(Math.min(P.CAP, Math.max(0, viewportTarget - row.gap)));
+      const tightScaled = raw > 0 && raw < P.FLOOR && row.gap < P.TIGHT_GAP;
+      const addition = tightScaled ? P.FLOOR : raw;
+      const declined = addition < P.FLOOR
+        ? (addition > 0 ? 'below the 32 px perceptibility floor'
+            : 'already at the page rhythm target')
+        : null;
+      census.push({
+        kind: row.kind, section: row.section.id, before: row.before.id, after: row.after.id,
+        fact: row.fact, gap: +row.gap.toFixed(1), addition, tightScaled, declared: true, declined,
+        ground: { owner: row.ownerKey, color: row.color, continuation: 'owner-fill', execution: row.execution },
+      });
+      return { ...row, addition, tightScaled, declined };
     });
-    if (P.census) return [...viewportPlans, ...semanticPlans].map(censusRow);
-
-    const admittedViewport = viewportPlans.filter((p) => !p.declined);
-    const admittedSemantic = semanticPlans.filter((p) => !p.declined);
-    const admitted = [...admittedViewport, ...admittedSemantic];
-    if (!admitted.length || admitted.some((p) => !p.ground?.ok)) return out;
-
-    const sectionShift = new Map(sections.map((s) => [s.id, 0]));
-    const sectionGrowth = new Map(sections.map((s) => [s.id, 0]));
+    if (P.census) return census;
+    const admitted = plans.filter((plan) => !plan.declined);
+    if (!admitted.length) return out;
+    const sectionShift = new Map(sections.map((section) => [section.id, 0]));
+    const sectionGrowth = new Map(sections.map((section) => [section.id, 0]));
+    const ownerGrowth = new Map();
+    const containerGrowth = new Map();
     const childShift = new Map();
-    const sectionIndex = new Map(sections.map((s, i) => [s.id, i]));
-    for (const p of admittedSemantic) {
-      sectionGrowth.set(p.section.id, sectionGrowth.get(p.section.id) + p.addition);
-      const tr = p.after.getBoundingClientRect();
-      for (const child of [...p.section.children].filter(visible)) {
-        if (child.id && child.getBoundingClientRect().top >= tr.top - 0.75) childShift.set(child.id, (childShift.get(child.id) || 0) + p.addition);
+    for (const plan of admitted.filter((row) => row.kind === 'semantic')) {
+      sectionGrowth.set(plan.section.id, sectionGrowth.get(plan.section.id) + plan.addition);
+      if (plan.owner !== plan.section && plan.section.contains(plan.owner) && plan.owner.id) {
+        ownerGrowth.set(plan.owner.id, (ownerGrowth.get(plan.owner.id) || 0) + plan.addition);
+      }
+      if (plan.execution === 'owner-leading-air') {
+        for (const child of plan.ownerChildren) {
+          childShift.set(child.id, (childShift.get(child.id) || 0) + plan.addition);
+        }
+      } else {
+        // Everything at or below the cut inside the seam's own group moves down; every container
+        // between that group and the section grows by the same amount so nothing is clipped.
+        const afterTop = plan.after.getBoundingClientRect().top;
+        for (const child of [...plan.group.children].filter(visible)) {
+          if (child.id && child.getBoundingClientRect().top >= afterTop - 0.75) {
+            childShift.set(child.id, (childShift.get(child.id) || 0) + plan.addition);
+          }
+        }
+        for (let node = plan.group; node && node !== plan.section; node = node.parentElement) {
+          if (node.id) containerGrowth.set(node.id, (containerGrowth.get(node.id) || 0) + plan.addition);
+        }
       }
     }
-    for (const p of admittedViewport) {
-      for (let i = sectionIndex.get(p.after.id); i < sections.length; i++) sectionShift.set(sections[i].id, sectionShift.get(sections[i].id) + p.addition);
-    }
-
-    for (const p of admittedViewport) {
-      const dy = p.ground.side === 'outgoing' ? p.addition : -p.addition;
-      const br = p.before.getBoundingClientRect();
-      const attachments = p.attachments.map((a) => ({ id: a.el.id, topOffset: a.topOffset, bottomOffset: a.bottomOffset }));
+    for (const plan of admitted.filter((row) => row.kind === 'viewport')) {
+      for (let cursor = sectionIndex.get(plan.after); cursor < sections.length; cursor += 1) {
+        sectionShift.set(sections[cursor].id, sectionShift.get(sections[cursor].id) + plan.addition);
+      }
       out.push({
-        id: p.ground.owner.id, rule: 'section-breathing',
-        reason: `viewport seam ${p.before.id}→${p.after.id}: gap ${p.gap.toFixed(0)} + ${p.addition} px, solid ${p.ground.color} extended (${p.ground.side})`,
-        css: { 'box-shadow': `0 ${dy}px 0 0 ${p.ground.color}` },
+        id: plan.before.id, rule: RULE,
+        reason: `declared viewport boundary ${plan.before.id}→${plan.after.id}: +${plan.addition} px`,
+        css: { 'box-shadow': `0 ${plan.addition}px 0 0 ${plan.color}` },
         meta: { seam: {
-          kind: p.kind, before: p.before.id, after: p.after.id, gap: +p.gap.toFixed(1), baseStripHeight: 0,
-          addition: p.addition, color: p.ground.color, side: p.ground.side, owner: p.ground.owner.id,
-          attachments, seamTop: br.bottom + window.scrollY + sectionShift.get(p.before.id) + sectionGrowth.get(p.before.id),
+          kind: 'viewport', before: plan.before.id, after: plan.after.id,
+          gap: +plan.gap.toFixed(1), baseStripHeight: 0, addition: plan.addition,
+          color: plan.color, side: 'outgoing', owner: plan.ownerKey, attachments: [],
+          seamTop: plan.before.getBoundingClientRect().bottom + window.scrollY,
         } },
       });
-      for (const a of p.attachments) {
-        const direct = directChildOf(p.before, a.el); const inherited = direct ? (childShift.get(direct.id) || 0) : 0;
-        const travel = p.addition + sectionGrowth.get(p.before.id) - inherited;
-        if (travel) out.push({ id: a.el.id, rule: 'section-breathing', reason: `declared decoration travels ${travel} px with ${p.after.id}`, dy: travel });
-      }
     }
-    for (const p of admittedSemantic) {
+    for (const plan of admitted.filter((row) => row.kind === 'semantic')) {
+      // The probe strip is anchored to the real air line, so the pixels verified are the pixels the
+      // addition actually inserts — not a band that still contains the peer it was measured past.
+      const airAnchor = plan.airAnchor || plan.before;
+      if (plan.execution === 'owner-leading-air') {
+        const firstChild = [...plan.ownerChildren]
+          .sort((left, right) => left.getBoundingClientRect().top - right.getBoundingClientRect().top)[0];
+        const baseStripHeight = firstChild.getBoundingClientRect().top
+          - airAnchor.getBoundingClientRect().bottom;
+        out.push({
+          id: firstChild.id, rule: RULE,
+          reason: `declared ${plan.fact || 'section'} boundary ${plan.before.id}→${plan.after.id}: +${plan.addition} px inside owner`,
+          dy: plan.addition,
+          meta: { seam: {
+            kind: 'semantic', fact: plan.fact, before: airAnchor.id, after: firstChild.id,
+            declaredBefore: plan.before.id, declaredAfter: plan.after.id, gap: +plan.gap.toFixed(1),
+            baseStripHeight: +baseStripHeight.toFixed(2), addition: plan.addition,
+            color: plan.color, side: 'owner-leading', owner: plan.ownerKey, attachments: [],
+          } },
+        });
+        continue;
+      }
+      const beforePeers = [...plan.group.children].filter((child) => child.id
+        && child !== plan.after && child !== plan.owner
+        && child.getBoundingClientRect().bottom <= plan.after.getBoundingClientRect().top + 0.75)
+        .map((child) => child.id);
       out.push({
-        id: p.after.id, rule: 'section-breathing',
-        reason: `${p.fact} seam ${p.before.id}→${p.after.id}: gap ${p.gap.toFixed(0)} + ${p.addition} px`, dy: p.addition,
+        id: plan.after.id, rule: RULE,
+        reason: `declared ${plan.fact || 'section'} boundary ${plan.before.id}→${plan.after.id}: +${plan.addition} px`,
+        dy: plan.addition,
         meta: { seam: {
-          kind: p.kind, fact: p.fact, before: p.before.id, after: p.after.id, gap: +p.gap.toFixed(1),
-          baseStripHeight: +p.gap.toFixed(2), addition: p.addition, color: p.ground.color, side: 'internal',
-          owner: p.ground.owner.id, attachments: [], beforePeers: p.beforePeers,
+          kind: 'semantic', fact: plan.fact, before: airAnchor.id, after: plan.after.id,
+          declaredBefore: plan.before.id,
+          gap: +plan.gap.toFixed(1), baseStripHeight: +plan.gap.toFixed(2), addition: plan.addition,
+          color: plan.color, side: 'internal', owner: plan.ownerKey, attachments: [], beforePeers,
         } },
       });
     }
     for (const [id, dy] of childShift) {
-      const targetOwnShift = admittedSemantic.filter((p) => p.after.id === id).reduce((n, p) => n + p.addition, 0);
-      const remainder = dy - targetOwnShift;
-      if (remainder) out.push({ id, rule: 'section-breathing', reason: `block follows ${remainder} px of semantic air above it`, dy: remainder });
+      const own = admitted.filter((plan) => plan.kind === 'semantic'
+        && (plan.after.id === id || (plan.execution === 'owner-leading-air'
+          && [...plan.ownerChildren].sort((left, right) => left.getBoundingClientRect().top
+            - right.getBoundingClientRect().top)[0]?.id === id)))
+        .reduce((total, plan) => total + plan.addition, 0);
+      if (dy - own) out.push({ id, rule: RULE, reason: 'block follows declared semantic air', dy: dy - own });
     }
     for (const section of sections) {
-      const growth = sectionGrowth.get(section.id); if (!growth) continue;
-      const sr = section.getBoundingClientRect(); const owner = admittedSemantic.find((p) => p.section === section).ground.owner;
-      const or = owner.getBoundingClientRect();
-      out.push({ id: owner.id, rule: 'section-breathing', reason: `solid section ground grows ${growth} px`, h: or.height + growth });
-      out.push({ id: section.id, rule: 'section-breathing', reason: `section grows ${growth} px for semantic air`, h: sr.height + growth });
+      const growth = sectionGrowth.get(section.id);
+      if (growth) out.push({ id: section.id, rule: RULE, reason: `section grows ${growth} px for declared semantic air`, h: section.getBoundingClientRect().height + growth });
     }
-    for (const [id, dy] of sectionShift) if (dy) out.push({ id, rule: 'section-breathing', reason: `section follows ${dy} px of added air above it`, dy });
-    const total = admitted.reduce((n, p) => n + p.addition, 0);
+    for (const [id, growth] of ownerGrowth) {
+      const owner = document.getElementById(id);
+      if (owner) out.push({ id, rule: RULE, reason: `declared ground owner continues ${growth} px`, h: owner.getBoundingClientRect().height + growth });
+    }
+    for (const [id, growth] of containerGrowth) {
+      if (ownerGrowth.has(id)) continue;
+      const container = document.getElementById(id);
+      if (container) out.push({ id, rule: RULE, reason: `container grows ${growth} px for nested declared air`, h: container.getBoundingClientRect().height + growth });
+    }
+    for (const [id, dy] of sectionShift) if (dy) out.push({ id, rule: RULE, reason: `section follows ${dy} px of declared air`, dy });
+    const total = admitted.reduce((sum, plan) => sum + plan.addition, 0);
     const canvas = document.querySelector('#page-flow') || document.querySelector('.ly-anchor-canvas');
-    const canvasH = canvas ? canvas.getBoundingClientRect().height : document.documentElement.scrollHeight;
-    out.push({ sel: '#page-flow, .ly-anchor-canvas', rule: 'section-breathing', reason: `canvas +${total} px`, css: { height: `${(canvasH + total).toFixed(2)}px` } });
+    const expectedDocumentHeight = Math.max(
+      document.documentElement.scrollHeight,
+      canvas ? canvas.getBoundingClientRect().bottom + window.scrollY + total : 0,
+    );
+    for (const override of out) {
+      if (override.meta?.seam) override.meta.seam.expectedDocumentHeight = expectedDocumentHeight;
+    }
+    if (canvas) out.push({ sel: '#page-flow, .ly-anchor-canvas', rule: RULE, reason: `canvas +${total} px`, css: { height: `${(canvas.getBoundingClientRect().height + total).toFixed(2)}px` } });
     return out;
   };
 }