vite-plugin-nora 0.1.0

package/src/client/sweep/SweepPanel.jsx

@@ -0,0 +1,206 @@
+import { useEffect, useState } from "react";
+import { CheckIcon } from "../toolbar/icons.jsx";
+import { buildReport } from "./report.js";
+import { SWEEP_MIN, SWEEP_MAX } from "./run-sweep.js";
+
+const pct = (w) => ((w - SWEEP_MIN) / (SWEEP_MAX - SWEEP_MIN)) * 100;
+
+/**
+ * Sweep results, as a popover on the bar.
+ *
+ * It lives here rather than in a panel below the canvas for two reasons. The
+ * bar already owns this idiom — the folder browser, the palette and the
+ * viewport menu are all popovers, and a fourth surface type would be one too
+ * many. And a panel docked under the canvas shrinks the canvas, which changes
+ * the Fit width and reflows the very component the results describe.
+ *
+ * The axis is the point: findings are located *at widths*, so they belong on a
+ * ruler. Click anywhere on it to send the frame to that width and look for
+ * yourself — a flagged range you can't inspect is just an accusation.
+ */
+/**
+ * @param {object} props
+ * @param {import("./run-sweep.js").SweepResult} props.result
+ * @param {{ name?: string, file?: string } | null} [props.subject]
+ * @param {number | null} props.currentWidth
+ * @param {(width: number) => void} props.onPickWidth
+ * @param {() => void} props.onRerun
+ * @param {() => void} props.onClose
+ * @param {boolean} props.sweeping
+ */
+export function SweepPanel({
+  result,
+  subject,
+  currentWidth,
+  onPickWidth,
+  onRerun,
+  onClose,
+  sweeping,
+}) {
+  const { breakpoints, overflowRanges } = result;
+  const clean = !breakpoints.length && !overflowRanges.length;
+
+  const [copied, setCopied] = useState(false);
+
+  // The confirmation clears itself. Keyed on `copied` rather than set inside the
+  // click handler so the timer is cancelled if the panel closes first.
+  useEffect(() => {
+    if (!copied) return;
+    const t = setTimeout(() => setCopied(false), 1600);
+    return () => clearTimeout(t);
+  }, [copied]);
+
+  const copy = async () => {
+    try {
+      await navigator.clipboard.writeText(buildReport(result, subject));
+      setCopied(true);
+    } catch {
+      /* clipboard refused — the findings are still on screen to read */
+    }
+  };
+
+  const pick = (event) => {
+    const box = event.currentTarget.getBoundingClientRect();
+    const ratio = (event.clientX - box.left) / box.width;
+    const w = Math.round(SWEEP_MIN + ratio * (SWEEP_MAX - SWEEP_MIN));
+    onPickWidth(Math.max(SWEEP_MIN, Math.min(SWEEP_MAX, w)));
+  };
+
+  return (
+    <div className="nora-panel nora-sweep-panel" role="dialog" aria-label="Sweep Results">
+      <div className="nora-panel-head">
+        <span className="nora-panel-title">
+          Swept {SWEEP_MIN}–{SWEEP_MAX}
+        </span>
+        <span className="nora-sweep-summary">
+          {overflowRanges.length ? (
+            <span className="nora-sweep-bad">
+              {overflowRanges.length} Overflow{overflowRanges.length === 1 ? "" : "s"}
+            </span>
+          ) : null}
+          {breakpoints.length ? (
+            <span className="nora-sweep-neutral">
+              {breakpoints.length} Breakpoint{breakpoints.length === 1 ? "" : "s"}
+            </span>
+          ) : null}
+          {clean ? (
+            <span className="nora-sweep-ok">
+              <CheckIcon size={12} strokeWidth={2.75} />
+              Passed
+            </span>
+          ) : null}
+        </span>
+      </div>
+
+      <div
+        className="nora-sweep-axis"
+        data-clean={clean ? "true" : "false"}
+        data-ticks={breakpoints.length ? "true" : "false"}
+        onClick={pick}
+        role="slider"
+        tabIndex={0}
+        aria-label="Jump to Width"
+        aria-valuemin={SWEEP_MIN}
+        aria-valuemax={SWEEP_MAX}
+        aria-valuenow={currentWidth ?? SWEEP_MIN}
+        // A slider must carry aria-valuenow, but "Fit" is not a width, and
+        // reporting SWEEP_MIN for it would be a confident lie. valuetext is
+        // what a screen reader actually announces, so the truth goes there.
+        aria-valuetext={currentWidth ? `${currentWidth}px` : "No width chosen"}
+        onKeyDown={(e) => {
+          if (e.key === "ArrowLeft") onPickWidth(Math.max(SWEEP_MIN, (currentWidth ?? 800) - 8));
+          if (e.key === "ArrowRight") onPickWidth(Math.min(SWEEP_MAX, (currentWidth ?? 800) + 8));
+        }}
+      >
+        <div className="nora-sweep-track" />
+
+        {overflowRanges.map((r) => (
+          <div
+            key={`o-${r.from}`}
+            className="nora-sweep-band"
+            style={{ left: `${pct(r.from)}%`, width: `${Math.max(0.8, pct(r.to) - pct(r.from))}%` }}
+            title={`Overflows by up to ${r.worst}px between ${r.from} and ${r.to}`}
+          />
+        ))}
+
+        {breakpoints.map((b) => (
+          <div
+            key={`b-${b.width}`}
+            className="nora-sweep-tick"
+            style={{ left: `${pct(b.width)}%` }}
+          >
+            <span className="nora-sweep-tick-label">{b.width}</span>
+          </div>
+        ))}
+
+        {currentWidth ? (
+          <div className="nora-sweep-cursor" style={{ left: `${pct(currentWidth)}%` }} />
+        ) : null}
+      </div>
+
+      <div className="nora-sweep-scale">
+        <span>{SWEEP_MIN}</span>
+        <span>{SWEEP_MAX}</span>
+      </div>
+
+      {clean ? (
+        <div className="nora-sweep-clear">No overflow or layout transitions.</div>
+      ) : (
+        <div className="nora-panel-body">
+          {overflowRanges.map((r) => (
+            <button
+              key={`of-${r.from}`}
+              className="nora-finding is-bad"
+              onClick={() => onPickWidth(r.from)}
+              title={r.offenders?.[0]?.label ?? ""}
+            >
+              <span className="nora-finding-range">
+                {r.from}–{r.to}
+              </span>
+              <span className="nora-finding-text">
+                overflows {r.worst}px
+                {r.offenders?.[0] ? ` · ${r.offenders[0].label}` : ""}
+              </span>
+            </button>
+          ))}
+
+          {breakpoints.map((b) => (
+            <button
+              key={`bp-${b.width}`}
+              className="nora-finding"
+              onClick={() => onPickWidth(b.width)}
+            >
+              <span className="nora-finding-range">{b.width}</span>
+              <span className="nora-finding-text">
+                {b.changes.length
+                  ? b.changes
+                      .slice(0, 2)
+                      .map((c) => `${c.prop} ${c.from} → ${c.to}`)
+                      .join(", ")
+                  : `reflows ${b.rowsBefore} → ${b.rowsAfter} rows`}
+              </span>
+            </button>
+          ))}
+        </div>
+      )}
+
+      <div className="nora-sweep-actions">
+        <button className="nora-sweep-rerun" onClick={onRerun} disabled={sweeping}>
+          {sweeping ? "Sweeping…" : "Sweep"}
+        </button>
+        {clean ? null : (
+          <button
+            className="nora-sweep-copy"
+            onClick={copy}
+            title="Copy the findings as text, ready to paste"
+          >
+            {copied ? "Copied" : "Copy"}
+          </button>
+        )}
+        <button className="nora-panel-close nora-sweep-dismiss" onClick={onClose}>
+          Close
+        </button>
+      </div>
+    </div>
+  );
+}

package/src/client/sweep/measure.js

@@ -0,0 +1,230 @@
+/**
+ * The probe. Runs against the frame document at one width and returns
+ * everything the sweep needs to reason about that width.
+ *
+ * Two jobs, and they are different in kind:
+ *
+ *   1. Detect breakage — overflow, content pushed off-screen. Judgemental, so
+ *      it has to be nearly false-positive free or nobody will trust the panel.
+ *
+ *   2. Fingerprint the layout — so the sweep can find the widths where the
+ *      component genuinely changes shape. Purely descriptive, so it can't be
+ *      "wrong", only interesting.
+ *
+ * The fingerprint is the subtle part. Under a fluid layout, geometry changes at
+ * every single width, so "did the boxes move" is useless — it is always true.
+ * What we track instead are the *discrete* computed values: display,
+ * flex-direction, wrap, grid column count, visibility. Those don't drift as you
+ * resize; they change only when a rule starts or stops applying. A change in
+ * that fingerprint is a real layout transition, which is what a breakpoint is.
+ */
+
+/** Discrete properties: they change by rule, not by pixel. */
+const DISCRETE_PROPS = [
+  "display",
+  "flexDirection",
+  "flexWrap",
+  "position",
+  "visibility",
+  "float",
+  "whiteSpace",
+  "textAlign",
+  "gridAutoFlow",
+];
+
+/** Elements to inspect before giving up — keeps a huge tree from stalling the sweep. */
+const MAX_ELEMENTS = 400;
+
+/** Grid track lists are pixel values under a fluid layout; only the count is discrete. */
+function trackCount(value) {
+  if (!value || value === "none") return 0;
+  return value.trim().split(/\s+/).length;
+}
+
+/** A short, human-readable handle for an element, for use in findings. */
+export function describe(el) {
+  const tag = el.tagName.toLowerCase();
+  const cls =
+    typeof el.className === "string" && el.className.trim()
+      ? "." + el.className.trim().split(/\s+/).slice(0, 2).join(".")
+      : "";
+  const id = el.id ? `#${el.id}` : "";
+  const text = (el.textContent ?? "").trim().replace(/\s+/g, " ").slice(0, 28);
+  const label = `${tag}${id}${cls}`;
+  return text && text.length > 2 ? `${label} — “${text}”` : label;
+}
+
+/** Is this element inside something that scrolls? Then sticking out is intentional. */
+function insideScroller(el, root) {
+  let node = el.parentElement;
+  while (node && node !== root) {
+    const style = getComputedStyle(node);
+    if (/(auto|scroll)/.test(style.overflowX + style.overflow)) return true;
+    node = node.parentElement;
+  }
+  return false;
+}
+
+function fnv1a(str) {
+  let h = 0x811c9dc5;
+  for (let i = 0; i < str.length; i++) {
+    h ^= str.charCodeAt(i);
+    h = Math.imul(h, 0x01000193);
+  }
+  return (h >>> 0).toString(36);
+}
+
+/**
+ * @param {Document} doc  the frame document
+ * @param {number} width  the viewport width it is currently at
+ * @param {boolean} [detailed] keep per-element data so two samples can be diffed
+ */
+export function measure(doc, width, detailed = false) {
+  const root = doc.documentElement;
+  const stage = doc.querySelector(".noraf-stage") ?? doc.body;
+
+  // --- breakage -----------------------------------------------------------
+  // Start from the document: if nothing overflows the page, there is no
+  // overflow bug worth reporting, however far individual boxes stick out of
+  // their own scrollable parents.
+  const docOverflow = root.scrollWidth - root.clientWidth;
+  const overflows = docOverflow > 1;
+
+  const offenders = [];
+  if (overflows) {
+    const all = stage.querySelectorAll("*");
+    const limit = Math.min(all.length, MAX_ELEMENTS);
+    for (let i = 0; i < limit; i++) {
+      const el = all[i];
+      const rect = el.getBoundingClientRect();
+      if (rect.width === 0 || rect.height === 0) continue;
+      const past = rect.right - root.clientWidth;
+      if (past <= 1 && rect.left >= -1) continue;
+      if (insideScroller(el, stage)) continue;
+      offenders.push({
+        label: describe(el),
+        by: Math.round(Math.max(past, -rect.left)),
+      });
+      if (offenders.length >= 3) break;
+    }
+  }
+
+  // --- fingerprint --------------------------------------------------------
+  const all = stage.querySelectorAll("*");
+  const limit = Math.min(all.length, MAX_ELEMENTS);
+  const parts = [];
+  const details = detailed ? [] : null;
+  const wrapRows = [];
+  let visible = 0;
+
+  for (let i = 0; i < limit; i++) {
+    const el = all[i];
+    const style = getComputedStyle(el);
+    const values = DISCRETE_PROPS.map((p) => style[p]);
+    values.push(String(trackCount(style.gridTemplateColumns)));
+
+    if (style.display !== "none" && style.visibility !== "hidden") visible++;
+
+    // Row counting is restricted to containers where "rows" is a layout
+    // concept — a wrapping flex container or a grid. Counting distinct tops
+    // across every element instead would make ordinary text rewrapping look
+    // like a breakpoint, which is exactly the kind of false positive that gets
+    // this panel closed and never reopened.
+    if (style.flexWrap === "wrap" || style.display === "grid" || style.display === "inline-grid") {
+      const tops = new Set();
+      for (const child of el.children) {
+        const rect = child.getBoundingClientRect();
+        if (rect.height > 0) tops.add(Math.round(rect.top));
+      }
+      wrapRows.push(tops.size);
+    }
+
+    parts.push(values.join("|"));
+    if (details) details.push({ label: describe(el), values });
+  }
+
+  const rows = wrapRows.reduce((a, b) => a + b, 0);
+  const signature = `${visible}~${wrapRows.join(",")}~${parts.join(";")}`;
+
+  return {
+    width,
+    overflows,
+    overflowBy: Math.max(0, docOverflow),
+    offenders,
+    rowCount: rows,
+    visibleCount: visible,
+    height: Math.round(stage.getBoundingClientRect().height),
+    hash: fnv1a(signature),
+    details,
+  };
+}
+
+/**
+ * Given two detailed samples, say what actually changed. Turns a bare
+ * "something happened at 771px" into a line a person can act on.
+ */
+/**
+ * Index a sample's details so the same element can be found in both samples.
+ *
+ * The key is the element's label plus how many elements with that label came
+ * before it, because labels repeat: five `li.item` siblings all describe the
+ * same. Insertion order is preserved, so iterating the result walks the
+ * document in order exactly as the old index-based comparison did.
+ */
+function keyed(details) {
+  const seen = new Map();
+  const out = new Map();
+  for (const d of details) {
+    const n = seen.get(d.label) ?? 0;
+    seen.set(d.label, n + 1);
+    out.set(`${d.label}\u0000${n}`, d);
+  }
+  return out;
+}
+
+export function diffSamples(before, after) {
+  if (!before?.details || !after?.details) return [];
+  const changes = [];
+
+  // Matched by identity rather than by position. The two samples are separate
+  // walks of `querySelectorAll("*")`, so a component that renders a different
+  // tree at a different width — `{wide ? <Nav/> : <Drawer/>}`, which is exactly
+  // what a breakpoint often is — shifts every element after the change by one.
+  // Compared by index, that reported a fabricated property change for each of
+  // them and buried the real finding, because the count fallback below only
+  // runs when nothing else was found.
+  const was = keyed(before.details);
+  const now = keyed(after.details);
+
+  for (const [key, a] of was) {
+    const b = now.get(key);
+    if (!b) continue; // absent at this width: a structure change, not a property one
+    const len = Math.min(a.values.length, b.values.length);
+    for (let p = 0; p < len; p++) {
+      if (a.values[p] === b.values[p]) continue;
+      const prop = p < DISCRETE_PROPS.length ? DISCRETE_PROPS[p] : "gridColumns";
+      changes.push({ label: a.label, prop, from: a.values[p], to: b.values[p] });
+      if (changes.length >= 4) return changes;
+    }
+  }
+
+  if (!changes.length) {
+    if (before.visibleCount !== after.visibleCount) {
+      changes.push({
+        label: "element count",
+        prop: "visible elements",
+        from: String(before.visibleCount),
+        to: String(after.visibleCount),
+      });
+    } else if (before.rowCount !== after.rowCount) {
+      changes.push({
+        label: "layout",
+        prop: "rows",
+        from: String(before.rowCount),
+        to: String(after.rowCount),
+      });
+    }
+  }
+
+  return changes;
+}

package/src/client/sweep/report.js

@@ -0,0 +1,54 @@
+/**
+ * Turn a sweep result into text worth pasting somewhere else.
+ *
+ * The panel is built for looking: findings sit on a ruler, and clicking one
+ * sends the frame to that width. None of that survives a copy. What survives is
+ * this: the component, the range it was rendered across, and every finding with
+ * the width it happens at.
+ *
+ * It is written to be read cold, by a person or a model that has none of the
+ * panel's context, so each section says what its numbers mean rather than
+ * assuming the reader knows what "overflow" measures here. Ranges use a plain
+ * hyphen so nothing depends on the reader handling an en dash.
+ *
+ * Pure, and separate from the panel, so the wording can be tested without a DOM.
+ *
+ * @param {Partial<import("./run-sweep.js").SweepResult>} [result] what `runSweep` returned
+ * @param {{ name?: string, file?: string } | null} [subject] the component swept
+ * @returns {string}
+ */
+export function buildReport(result = {}, subject) {
+  const { min, max, breakpoints = [], overflowRanges = [] } = result;
+
+  const who = subject?.name
+    ? subject.file
+      ? `${subject.name} (${subject.file})`
+      : subject.name
+    : "the previewed component";
+
+  const lines = [`nora sweep of ${who}`, `Rendered at every width from ${min}px to ${max}px.`];
+
+  if (overflowRanges.length) {
+    lines.push("", "OVERFLOW (content reaching past the viewport)");
+    for (const r of overflowRanges) {
+      const culprit = r.offenders?.[0]?.label;
+      lines.push(`  ${r.from}-${r.to}px  by up to ${r.worst}px` + (culprit ? `  ${culprit}` : ""));
+    }
+  }
+
+  if (breakpoints.length) {
+    lines.push("", "LAYOUT TRANSITIONS (a width where a CSS rule starts or stops applying)");
+    for (const b of breakpoints) {
+      const what = b.changes?.length
+        ? b.changes.map((c) => `${c.prop}: ${c.from} → ${c.to}`).join(", ")
+        : `reflows ${b.rowsBefore} → ${b.rowsAfter} rows`;
+      lines.push(`  ${b.width}px  ${what}`);
+    }
+  }
+
+  if (!overflowRanges.length && !breakpoints.length) {
+    lines.push("", "No overflow and no layout transitions.");
+  }
+
+  return lines.join("\n");
+}

package/src/client/sweep/run-sweep.js

@@ -0,0 +1,185 @@
+import { measure, diffSamples } from "./measure.js";
+
+export const SWEEP_MIN = 320;
+export const SWEEP_MAX = 1600;
+const COARSE_STEP = 16;
+
+/** Two frames is enough for CSS layout to settle after a width change. */
+function settle() {
+  return new Promise((resolve) => requestAnimationFrame(() => requestAnimationFrame(resolve)));
+}
+
+/**
+ * Measure until two consecutive reads agree.
+ *
+ * CSS settles in a frame, but a component that subscribes to `resize` and calls
+ * setState needs React to re-render first — so a single read can catch the
+ * previous width's DOM and invent a breakpoint that isn't there. Requiring two
+ * matching reads costs one extra frame and removes that whole class of ghost.
+ */
+async function stableMeasure(readDoc, w, detailed, attempts = 3) {
+  let previous = measure(readDoc(), w, detailed);
+  for (let i = 0; i < attempts; i++) {
+    await settle();
+    const next = measure(readDoc(), w, detailed);
+    if (next.hash === previous.hash) return next;
+    previous = next;
+  }
+  return previous;
+}
+
+/**
+ * Sweep the frame across a width range and report what happened.
+ *
+ * Coarse pass first, then bisection. Sampling every pixel from 320 to 1600
+ * would be 1280 layouts for no benefit — layout only changes at a handful of
+ * widths, so the cheap pass finds the 16px bracket a change falls in and the
+ * bisection narrows it to the exact pixel in four more steps.
+ *
+ * @param {object} io
+ * @param {(w:number)=>void} io.setWidth   drive the frame to a width
+ * @param {()=>Document} io.readDoc        read the frame document
+ * @param {(p:number)=>void} [io.onProgress]
+ */
+export async function runSweep({ setWidth, readDoc, onProgress }) {
+  const sample = async (w, detailed = false) => {
+    setWidth(w);
+    await settle();
+    return stableMeasure(readDoc, w, detailed);
+  };
+
+  // Warm up at the starting width before recording anything, so the first
+  // sample isn't a stale read of whatever width the frame was already at.
+  setWidth(SWEEP_MIN);
+  await settle();
+  await stableMeasure(readDoc, SWEEP_MIN, false);
+
+  // --- coarse pass --------------------------------------------------------
+  const coarse = [];
+  const total = Math.floor((SWEEP_MAX - SWEEP_MIN) / COARSE_STEP) + 1;
+
+  for (let i = 0; i < total; i++) {
+    const w = SWEEP_MIN + i * COARSE_STEP;
+    coarse.push(await sample(w));
+    onProgress?.(((i + 1) / total) * 0.8);
+  }
+
+  // --- refine layout transitions -----------------------------------------
+  const breakpoints = [];
+  for (let i = 1; i < coarse.length; i++) {
+    if (coarse[i].hash === coarse[i - 1].hash) continue;
+
+    const exact = await bisect(coarse[i - 1].width, coarse[i].width, coarse[i - 1].hash, sample);
+
+    // Re-measure either side in detail so we can say what changed.
+    const before = await sample(exact - 1, true);
+    const after = await sample(exact, true);
+
+    breakpoints.push({
+      width: exact,
+      changes: diffSamples(before, after),
+      rowsBefore: before.rowCount,
+      rowsAfter: after.rowCount,
+    });
+
+    if (breakpoints.length >= 12) break;
+  }
+
+  onProgress?.(0.9);
+
+  // --- overflow ranges ----------------------------------------------------
+  const ranges = [];
+  let open = null;
+  for (const s of coarse) {
+    if (s.overflows && !open) {
+      open = { from: s.width, to: s.width, worst: s.overflowBy, offenders: s.offenders };
+    } else if (s.overflows && open) {
+      open.to = s.width;
+      if (s.overflowBy > open.worst) {
+        open.worst = s.overflowBy;
+        open.offenders = s.offenders;
+      }
+    } else if (!s.overflows && open) {
+      ranges.push(open);
+      open = null;
+    }
+  }
+  if (open) ranges.push(open);
+
+  // Narrow each range's edges to the exact pixel where overflow starts or ends.
+  for (const range of ranges) {
+    if (range.from > SWEEP_MIN) {
+      range.from = await bisectFlag(
+        range.from - COARSE_STEP,
+        range.from,
+        (s) => s.overflows,
+        sample,
+      );
+    }
+    if (range.to < SWEEP_MAX) {
+      const end = await bisectFlag(range.to, range.to + COARSE_STEP, (s) => !s.overflows, sample);
+      range.to = end - 1;
+    }
+  }
+
+  onProgress?.(1);
+
+  return {
+    min: SWEEP_MIN,
+    max: SWEEP_MAX,
+    breakpoints,
+    overflowRanges: ranges,
+    samples: coarse.map((s) => ({ width: s.width, overflows: s.overflows, height: s.height })),
+  };
+}
+
+/**
+ * A width range where content reached past the viewport.
+ *
+ * @typedef {object} SweepOverflow
+ * @property {number} from
+ * @property {number} to
+ * @property {number} worst  the worst overhang across the range, in px
+ * @property {{ label: string }[]} [offenders] the elements responsible, worst first
+ */
+
+/**
+ * A width at which the layout genuinely changed shape.
+ *
+ * @typedef {object} SweepBreakpoint
+ * @property {number} width
+ * @property {{ prop: string, from: string, to: string }[]} [changes] discrete properties that flipped
+ * @property {number} [rowsBefore] when nothing discrete changed, the row count either side
+ * @property {number} [rowsAfter]
+ */
+
+/**
+ * @typedef {object} SweepResult
+ * @property {number} min
+ * @property {number} max
+ * @property {SweepBreakpoint[]} breakpoints
+ * @property {SweepOverflow[]} overflowRanges
+ * @property {{ width: number, overflows: boolean, height: number }[]} samples
+ */
+
+/** Smallest width in (lo, hi] whose hash differs from loHash. */
+async function bisect(lo, hi, loHash, sample) {
+  while (hi - lo > 1) {
+    const mid = Math.floor((lo + hi) / 2);
+    const s = await sample(mid);
+    if (s.hash === loHash) lo = mid;
+    else hi = mid;
+  }
+  return hi;
+}
+
+/** Smallest width in (lo, hi] where predicate(sample) first holds. */
+async function bisectFlag(lo, hi, predicate, sample) {
+  while (hi - lo > 1) {
+    const mid = Math.floor((lo + hi) / 2);
+    const s = await sample(mid);
+    if (predicate(s)) hi = mid;
+    else lo = mid;
+  }
+  return hi;
+}