@ultimat3/ui 22.15.0 → 24.0.0

package/src/components/Tabs.module.scss

@@ -18,11 +18,17 @@
     border-inline-end: 1px solid t.role('line');
   }
 
+  // On the list's inline-END edge, beside its border. A shadow's x offset is physical, so RTL —
+  // where that edge is the left one — gets the mirrored sign, as `Switch.module.scss` does.
   .tab[aria-selected='true'] {
-    box-shadow: inset -2px 0 0 0 t.role('accent');
+    box-shadow: inset calc(-1 * #{t.stroke(thick)}) 0 0 0 t.role('accent');
   }
 }
 
+[dir='rtl'] .orientation-vertical .tab[aria-selected='true'] {
+  box-shadow: inset t.stroke(thick) 0 0 0 t.role('accent');
+}
+
 .list {
   @include t.custom-scrollbar;
   display: flex;
@@ -32,7 +38,7 @@
 }
 
 .tab {
-  @include t.focus-ring(('accent'), 2px, -2px);
+  @include t.focus-ring('accent', t.stroke(thick), calc(-1 * #{t.stroke(thick)}));
   @include t.transition(color, box-shadow, background);
   padding-block: t.space(2);
   padding-inline: t.space(3);
@@ -54,7 +60,7 @@
   &[aria-selected='true'] {
     color: t.role('accent');
     // Inset shadow instead of a border, so the tab does not shift on select.
-    box-shadow: inset 0 -2px 0 0 t.role('accent');
+    box-shadow: inset 0 calc(-1 * #{t.stroke(thick)}) 0 0 t.role('accent');
   }
 }
 
@@ -62,7 +68,7 @@
   min-inline-size: 0;
 
   &:focus-visible {
-    outline: 2px solid t.role('accent');
-    outline-offset: 2px;
+    outline: t.stroke(thick) solid t.role('accent');
+    outline-offset: t.stroke(thick);
   }
 }

package/src/components/Textarea.tsx

@@ -28,11 +28,13 @@ export interface TextareaProps {
 /**
  * `<textarea>` has NO `value` attribute — its value is its text content, and the parser drops the
  * attribute silently, so `value={…}` rendered every admin edit box empty whatever the row held.
- * The leading newline is the serializer's, not the value's: the HTML parser strips exactly one
- * newline after `<textarea>`, so emitting it unconditionally is what makes a value that itself
- * starts with a newline survive the round trip.
+ * On the SERVER the leading newline is the serializer's, not the value's: the HTML parser strips
+ * exactly one newline after `<textarea>`, so emitting it unconditionally is what makes a value that
+ * itself starts with a newline survive the round trip. In a BROWSER no parser runs — an island
+ * builds the element — so the value is the `.value` property, and the newline would be data.
  */
 export function Textarea(props: TextareaProps): JSX.Element {
+  const onServer = typeof document === 'undefined';
   return (
     <textarea
       class={cx(styles['textarea'], props.autoGrow === true && styles['autoGrow'], props.class)}
@@ -49,8 +51,9 @@ export function Textarea(props: TextareaProps): JSX.Element {
       aria-invalid={ariaBool(props['aria-invalid'])}
       onInput={props.onInput}
       onBlur={props.onBlur}
+      value={onServer ? undefined : (props.value ?? '')}
     >
-      {`\n${props.value ?? ''}`}
+      {onServer ? `\n${props.value ?? ''}` : undefined}
     </textarea>
   );
 }

package/src/components/ThemeToggle.module.scss

@@ -18,6 +18,6 @@
 
   &[data-theme-glyph='dark'] {
     background: transparent;
-    box-shadow: inset -0.28rem -0.18rem 0 0 currentcolor;
+    box-shadow: inset t.rem(-4.5px) t.rem(-3px) 0 0 currentcolor;
   }
 }

package/src/components/Toast.module.scss

@@ -38,7 +38,7 @@
   align-items: flex-start;
   gap: t.space(3);
   padding: t.space(4);
-  border-inline-start: 3px solid var(--toast-accent);
+  border-inline-start: t.stroke(heavy) solid var(--toast-accent);
   color: t.role('fg');
   pointer-events: auto;
 
@@ -56,7 +56,7 @@
 
   @starting-style {
     opacity: 0;
-    translate: 0 12px;
+    translate: 0 t.space(3);
   }
 }
 

package/src/components/Tooltip.module.scss

@@ -9,8 +9,13 @@
   @include t.transition(opacity, translate);
   position: absolute;
   z-index: t.z(tooltip);
-  inset-inline-start: 50%;
-  translate: -50% 4px;
+  // Centred over the trigger in either direction: auto margins inside an inset band far wider than
+  // any bubble. A 50% logical inset with a -50% physical translate lands a whole width off-centre
+  // under `dir="rtl"` (`rtl-sheets.test.ts`).
+  inset-inline: -100vw;
+  margin-inline: auto;
+  inline-size: max-content;
+  translate: 0 t.space(1);
   max-inline-size: 18rem;
   padding-block: t.space(1);
   padding-inline: t.space(2);
@@ -36,6 +41,6 @@
 // Hover and keyboard focus both reveal it — a hover-only tooltip is inaccessible.
 .wrap:hover .bubble,
 .wrap:focus-within .bubble {
-  translate: -50% 0;
+  translate: 0 0;
   opacity: 1;
 }

package/src/components/bar-chart-view.ts

@@ -5,6 +5,11 @@ export interface ChartPoint {
   /** The bar's name — a day, a bucket, a label. Read by `<title>` and the axis. */
   readonly key: string;
   readonly value: number;
+  /**
+   * A second series, stacked on `value` — failed on top of done. Absent or 0 draws nothing, so a
+   * one-series chart is exactly the chart it was.
+   */
+  readonly secondary?: number;
 }
 
 export interface BarRect {
@@ -24,11 +29,16 @@ export const BAR_CHART = { width: 600, top: 12, plot: 104, height: 128, gap: 3 }
 /** Quarter lines. Four is what a reader can use to judge a bar's height without a y-axis. */
 export const GRID_STEPS = [0.25, 0.5, 0.75, 1] as const;
 
-/** The busiest point, and never below 1, so an all-zero series still divides. */
+const finite = (value: number | undefined): number =>
+  value !== undefined && Number.isFinite(value) ? Math.max(0, value) : 0;
+
+/** The busiest point — its whole stack — and never below 1, so an all-zero series still divides. */
 export function maxOf(points: readonly ChartPoint[]): number {
   let max = 1;
-  for (const point of points)
-    if (Number.isFinite(point.value) && point.value > max) max = point.value;
+  for (const point of points) {
+    const total = finite(point.value) + finite(point.secondary);
+    if (total > max) max = total;
+  }
   return max;
 }
 
@@ -40,16 +50,36 @@ export function gridY(step: number): number {
 /** One rect per point, oldest first. At least 2px tall so a zero still draws a visible bar. */
 export function barRects(points: readonly ChartPoint[]): readonly BarRect[] {
   const count = Math.max(points.length, 1);
-  const width = (BAR_CHART.width - BAR_CHART.gap * (count - 1)) / count;
+  // The gap gives way before the bars do: at most half of each bar's slot, so past the 201 points
+  // where 3px gaps alone fill the width, every bar is still a positive rect and the row still ends
+  // at the right edge.
+  const gap = Math.min(BAR_CHART.gap, BAR_CHART.width / count / 2);
+  const width = (BAR_CHART.width - gap * (count - 1)) / count;
   const max = maxOf(points);
   return points.map((point, index) => {
     const value = Number.isFinite(point.value) ? Math.max(0, point.value) : 0;
     const height = Math.max(2, (value / max) * BAR_CHART.plot);
     return {
-      x: index * (width + BAR_CHART.gap),
+      x: index * (width + gap),
       y: BAR_CHART.top + BAR_CHART.plot - height,
       width,
       height,
     };
   });
 }
+
+/**
+ * The second series' rect per point, stacked on that point's primary bar; `null` where it is 0.
+ * Same scale as `barRects`, so a stack is read against the same grid lines.
+ */
+export function secondaryRects(points: readonly ChartPoint[]): readonly (BarRect | null)[] {
+  const primary = barRects(points);
+  const max = maxOf(points);
+  return points.map((point, index) => {
+    const value = finite(point.secondary);
+    const below = primary[index];
+    if (value === 0 || below === undefined) return null;
+    const height = (value / max) * BAR_CHART.plot;
+    return { x: below.x, y: below.y - height, width: below.width, height };
+  });
+}

package/src/components/button-classes.ts

@@ -0,0 +1,25 @@
+// The classes a button's look is made of — asked by `<Button>` and by `<Link appearance="button">`,
+// so a control that submits and a control that navigates cannot drift into two looks. Keys into
+// `Button.module.scss`, never class names: the scoped name is the stylesheet's to give.
+
+import type { ButtonVariant, Size, Tone } from './variants';
+
+export interface ButtonLook {
+  variant?: ButtonVariant | undefined;
+  tone?: Tone | undefined;
+  size?: Size | undefined;
+  fullWidth?: boolean | undefined;
+}
+
+/** The classes of the element's CONTENT, which both elements wrap their label in. */
+export const BUTTON_CONTENT_KEYS = ['label', 'spinner'] as const;
+
+export function buttonClassKeys(look: ButtonLook): readonly string[] {
+  return [
+    'button',
+    `variant-${look.variant ?? 'primary'}`,
+    `tone-${look.tone ?? 'accent'}`,
+    `size-${look.size ?? 'md'}`,
+    ...(look.fullWidth === true ? ['full'] : []),
+  ];
+}

package/src/components/file-input-view.ts

@@ -106,22 +106,41 @@ export interface FileTarget {
   files: FileList | null;
 }
 
+/** Builds the `FileList` an input's `files` accepts — the one constructor the DOM offers for it. */
+export type FileListOf<TFile extends FileCandidate> = (files: readonly TFile[]) => FileList;
+
+function dataTransferList<TFile extends FileCandidate>(files: readonly TFile[]): FileList {
+  const transfer = new DataTransfer();
+  for (const one of files) transfer.items.add(one as unknown as File);
+  return transfer.files;
+}
+
 /**
- * Hand a drop's files to the real `<input>`, so a dropped file behaves exactly like a picked one.
+ * Make the real `<input>` hold exactly the files the control ACCEPTED, so the form posts what the
+ * control showed and nothing it refused.
  *
- * Without this a `<Dropzone name="avatar" required>` inside a `<form>` shows the accepted file and
- * then refuses to submit: `onSelect` fired, but `input.files` is still empty, so `required` blocks
- * on "Please select a file" and a submit that got past it would post no file at all. Native form
- * participation is what the `name`/`required` props promise. `files` is assignable from a
- * `DataTransfer`'s own `FileList` in every current engine — that is the supported way to do this.
+ * A drop never reaches the input on its own: without this a `<Dropzone name="avatar" required>`
+ * shows the accepted file and then refuses to submit. And handing it the whole drop posted the
+ * files `accept` / `maxBytes` / `maxFiles` turned away — `accept` is a hint to the picker, never a
+ * filter on `files`. So a `drop` with something accepted is adopted as the accepted list, and a
+ * drop with nothing accepted leaves an earlier pick alone, as a refused drop should. A `pick`
+ * already set `files` itself; it is narrowed only when it refused something — to an empty list if
+ * it refused everything, because the refused file is the one the form would otherwise post. A list
+ * is BUILT (`listOf`, a `DataTransfer` in a browser) only when something was refused.
  */
-export function adoptDroppedFiles(
+export function adoptAcceptedFiles<TFile extends FileCandidate>(
   input: FileTarget | undefined,
-  dropped: FileList | null | undefined,
+  offered: FileList | null | undefined,
+  selection: FileSelection<TFile>,
+  origin: 'drop' | 'pick',
+  listOf: FileListOf<TFile> = dataTransferList,
 ): void {
-  // An empty drop must not CLEAR a previous pick: the browser does not, and neither does this.
-  if (input === undefined || dropped === null || dropped === undefined || dropped.length === 0) {
-    return;
+  if (input === undefined) return;
+  if (origin === 'drop' && selection.accepted.length === 0) return;
+  if (selection.rejected.length > 0) {
+    input.files = listOf(selection.accepted);
+  } else if (origin === 'drop' && offered !== null && offered !== undefined) {
+    // Nothing refused: the drop's own list, which needs no constructor at all.
+    input.files = offered;
   }
-  input.files = dropped;
 }

package/src/components/link-classes.ts

@@ -0,0 +1,38 @@
+// Which stylesheet a `<Link>` reads and which of its classes — the one decision `appearance`
+// makes. Pure, so it is testable with no renderer: the `.tsx` only maps the answer onto a sheet.
+
+import { type ButtonLook, buttonClassKeys } from './button-classes';
+import type { Tone } from './variants';
+
+export interface LinkLook extends Omit<ButtonLook, 'tone'> {
+  appearance?: 'link' | 'button' | undefined;
+  underline?: 'always' | 'hover' | 'none' | undefined;
+  /** A text link's own two tones, or — as a button — any `Tone`. */
+  tone?: Tone | 'inherit' | undefined;
+}
+
+export interface LinkClasses {
+  /** `button` is `Button.module.scss`: one set of button styles, whichever element wears them. */
+  readonly sheet: 'link' | 'button';
+  readonly keys: readonly string[];
+}
+
+export function linkClasses(look: LinkLook): LinkClasses {
+  if (look.appearance === 'button') {
+    return {
+      sheet: 'button',
+      // `inherit` is a text link's tone and no button has it; the type refuses the pairing, and a
+      // caller that got past the type gets the default tone rather than a class nothing declares.
+      keys: buttonClassKeys({
+        variant: look.variant,
+        tone: look.tone === 'inherit' ? undefined : look.tone,
+        size: look.size,
+        fullWidth: look.fullWidth,
+      }),
+    };
+  }
+  return {
+    sheet: 'link',
+    keys: ['link', `underline-${look.underline ?? 'hover'}`, `tone-${look.tone ?? 'accent'}`],
+  };
+}

package/src/components/link-target.ts

@@ -19,5 +19,38 @@ export interface LinkTarget {
 export function linkTarget(href: string, declaredExternal?: boolean | undefined): LinkTarget {
   const safe = safeUrl(href, 'href');
   if (safe === null) return { href: undefined, external: false };
-  return { href: safe, external: declaredExternal === true || /^https?:\/\//.test(safe) };
+  return { href: safe, external: declaredExternal === true || namesAnotherOrigin(safe) };
+}
+
+/** An origin no real link can name: whatever resolves AWAY from it carried its own authority. */
+const SENTINEL_ORIGIN = 'http://link-target.invalid';
+
+/**
+ * Decided the way a browser resolves the href, not by its spelling: `//cdn.test`, `HTTPS://…` and
+ * a leading space all leave the page's origin, and a regex over the raw string read each of them
+ * as internal — no `noopener`, no external hint. A value the parser refuses is treated as external,
+ * because the hardening is the safe side of a wrong guess.
+ */
+function namesAnotherOrigin(href: string): boolean {
+  try {
+    const url = new URL(href, `${SENTINEL_ORIGIN}/`);
+    return (
+      (url.protocol === 'http:' || url.protocol === 'https:') && url.origin !== SENTINEL_ORIGIN
+    );
+  } catch {
+    return true;
+  }
+}
+
+/**
+ * The `rel` an anchor carries. A relation is ADDED to the external hardening, never traded for
+ * it — which is why `<Link>` takes the relation as a closed pair and not a free `rel` string a
+ * caller could use to write the hardening away.
+ */
+export function linkRel(
+  external: boolean,
+  relation?: 'next' | 'prev' | undefined,
+): string | undefined {
+  if (!external) return relation;
+  return relation === undefined ? 'noopener noreferrer' : `${relation} noopener noreferrer`;
 }

package/src/components/meter-view.ts

@@ -11,3 +11,16 @@ export function meterShare(value: number, max: number): number {
 export function meterWidth(share: number): string {
   return (share * 100).toFixed(1);
 }
+
+/**
+ * The `aria-valuenow` / `aria-valuemax` pair, from the SAME rule as the fill: a meter that draws
+ * full must not speak "7 of 4". With no usable maximum the bar is empty, and so is the range it
+ * speaks — 0 of 1, because `aria-valuemax` must stay above `aria-valuemin`.
+ */
+export function meterAria(
+  value: number,
+  max: number,
+): { readonly now: number; readonly max: number } {
+  if (!Number.isFinite(max) || max <= 0) return { now: 0, max: 1 };
+  return { now: Number.isFinite(value) ? Math.min(max, Math.max(0, value)) : 0, max };
+}

package/src/components/qr-matrix.ts

@@ -75,28 +75,15 @@ function drawAlignmentPattern(matrix: Matrix, centerRow: number, centerCol: numb
 function drawFunctionPatterns(matrix: Matrix, version: number): void {
   const size = matrix.size;
 
-  // Three finder patterns, each an 8x8 area (7x7 pattern plus a light separator ring); only the
-  // 7x7 pattern is drawn as dark/light above, so the surrounding separator is drawn explicitly.
+  // Three finder patterns. `drawFinderPattern`'s outermost ring (`dist === 4`) IS the light
+  // separator, clipped to the matrix — drawing a second ring one further out would claim row and
+  // column 8, the format strip and two timing modules.
   const corners: readonly (readonly [number, number])[] = [
     [3, 3],
     [3, size - 4],
     [size - 4, 3],
   ];
   for (const [row, col] of corners) drawFinderPattern(matrix, row, col);
-  // Separators: the light ring one module beyond each finder pattern, clipped to the matrix.
-  for (const [row, col] of corners) {
-    for (let d = -4; d <= 4; d++) {
-      for (const [r, c] of [
-        [row + d, col - 5],
-        [row + d, col + 5],
-        [row - 5, col + d],
-        [row + 5, col + d],
-      ] as const) {
-        if (r >= 0 && c >= 0 && r < size && c < size && !matrix.isSet(r, c))
-          matrix.set(r, c, false);
-      }
-    }
-  }
 
   // Timing patterns: row 6 and column 6, alternating dark/light, skipping cells the finder
   // patterns already claimed.
@@ -107,11 +94,14 @@ function drawFunctionPatterns(matrix: Matrix, version: number): void {
   }
 
   // Alignment pattern(s): every (row, col) pair from this version's coordinate list, except the
-  // one that overlaps the top-left finder pattern.
+  // three that would land on a finder pattern — (first, first), (first, last) and (last, first).
   const positions = ALIGNMENT_POSITIONS[version - 1] ?? [];
+  const first = positions[0];
+  const last = positions[positions.length - 1];
   for (const row of positions) {
     for (const col of positions) {
-      if (row === 6 && col === 6) continue;
+      if (row === first && (col === first || col === last)) continue;
+      if (row === last && col === first) continue;
       drawAlignmentPattern(matrix, row, col);
     }
   }
@@ -158,10 +148,11 @@ function drawFormatInfo(matrix: Matrix, maskPattern: number): void {
   matrix.set(8, 7, bit(8));
   for (let i = 9; i <= 14; i++) matrix.set(8, 14 - i, bit(i));
 
-  // The mirrored copy: bits 0-7 along row `size-1` down to `size-8` in column 8, bits 8-14 up
-  // column `size-1` down to `size-15` in row 8.
-  for (let i = 0; i <= 7; i++) matrix.set(size - 1 - i, 8, bit(i));
-  for (let i = 8; i <= 14; i++) matrix.set(8, size - 15 + i, bit(i));
+  // The second copy: bits 0-7 along row 8 from column `size-1` leftwards to `size-8`, bits 8-14
+  // down column 8 from row `size-7` to `size-1` — one short of the fixed dark module at
+  // (`size-8`, 8), which belongs to no format copy.
+  for (let i = 0; i <= 7; i++) matrix.set(8, size - 1 - i, bit(i));
+  for (let i = 8; i <= 14; i++) matrix.set(size - 15 + i, 8, bit(i));
 }
 
 /** Whether mask `pattern` (0-7, ISO 18004 §8.8.1) flips the module at `(row, col)`. */
@@ -198,11 +189,13 @@ function drawData(matrix: Matrix, codewords: readonly number[], pattern: number)
   let bitIndex = 0;
   let upward = true;
   for (let colPair = size - 1; colPair > 0; colPair -= 2) {
+    // The vertical timing column carries no data, so the strip that would straddle it moves one
+    // module left — which is also what makes column 0 the last strip's left half.
+    if (colPair === 6) colPair = 5;
     for (let count = 0; count < size; count++) {
       const row = upward ? size - 1 - count : count;
       for (let colOffset = 0; colOffset < 2; colOffset++) {
         const col = colPair - colOffset;
-        if (col === 6) continue; // the vertical timing column carries no data
         if (matrix.isSet(row, col)) continue;
         const bit = bits[bitIndex] ?? false;
         bitIndex++;

package/src/components/qr-reader.ts

@@ -0,0 +1,187 @@
+// TEST-ONLY: an independent QR reader for versions 1-3, byte mode, level M — written from ISO
+// 18004's layout, sharing no code with `qr-encode.ts`/`qr-matrix.ts`, so a placement defect in
+// the encoder cannot be mirrored here. Never exported from `index.ts`.
+
+/** The eight published level-M format strings (ISO 18004 Table C.1), indexed by mask pattern —
+ *  a table, not a BCH computation, so the reader does not share the encoder's arithmetic. */
+const LEVEL_M_FORMAT: readonly number[] = [
+  0b101010000010010, 0b101000100100101, 0b101111001111100, 0b101101101001011, 0b100010111111001,
+  0b100000011001110, 0b100111110010111, 0b100101010100000,
+];
+
+/** Total and data codewords per version, level M (ISO 18004 Table 9). */
+const CODEWORDS: ReadonlyMap<number, { readonly total: number; readonly data: number }> = new Map([
+  [1, { total: 26, data: 16 }],
+  [2, { total: 44, data: 28 }],
+  [3, { total: 70, data: 44 }],
+]);
+
+export interface QrReading {
+  readonly version: number;
+  readonly mask: number;
+  readonly codewords: readonly number[];
+  readonly text: string;
+  /** Every place the symbol departs from the standard's fixed layout, as `what@row,col`. */
+  readonly layoutFaults: readonly string[];
+}
+
+type Grid = readonly (readonly boolean[])[];
+
+const at = (grid: Grid, row: number, col: number): boolean => grid[row]?.[col] === true;
+
+export function isFunctionModule(size: number, row: number, col: number): boolean {
+  const inCorner = (r0: number, c0: number): boolean =>
+    row >= r0 && row < r0 + 8 && col >= c0 && col < c0 + 8;
+  if (inCorner(0, 0) || inCorner(0, size - 8) || inCorner(size - 8, 0)) return true;
+  if (row === 6 || col === 6) return true;
+  if (row === 8 && (col <= 8 || col >= size - 8)) return true;
+  if (col === 8 && (row <= 8 || row >= size - 8)) return true;
+  // Versions 2-3 have exactly one alignment pattern, centred 7 modules in from the far corner.
+  if (size > 21 && Math.abs(row - (size - 7)) <= 2 && Math.abs(col - (size - 7)) <= 2) return true;
+  return false;
+}
+
+function finderFaults(grid: Grid, size: number): string[] {
+  const faults: string[] = [];
+  for (const [r0, c0] of [
+    [0, 0],
+    [0, size - 7],
+    [size - 7, 0],
+  ] as const) {
+    for (let dr = -1; dr <= 7; dr++) {
+      for (let dc = -1; dc <= 7; dc++) {
+        const row = r0 + dr;
+        const col = c0 + dc;
+        if (row < 0 || col < 0 || row >= size || col >= size) continue;
+        const ring = Math.max(Math.abs(dr - 3), Math.abs(dc - 3));
+        const dark = ring <= 1 || ring === 3;
+        if (at(grid, row, col) !== dark) faults.push(`finder@${row},${col}`);
+      }
+    }
+  }
+  return faults;
+}
+
+function fixedFaults(grid: Grid, size: number): string[] {
+  const faults = finderFaults(grid, size);
+  for (let i = 8; i < size - 8; i++) {
+    if (at(grid, 6, i) !== (i % 2 === 0)) faults.push(`timing@6,${i}`);
+    if (at(grid, i, 6) !== (i % 2 === 0)) faults.push(`timing@${i},6`);
+  }
+  if (size > 21) {
+    const centre = size - 7;
+    for (let dr = -2; dr <= 2; dr++) {
+      for (let dc = -2; dc <= 2; dc++) {
+        const dark = Math.max(Math.abs(dr), Math.abs(dc)) !== 1;
+        if (at(grid, centre + dr, centre + dc) !== dark) {
+          faults.push(`alignment@${centre + dr},${centre + dc}`);
+        }
+      }
+    }
+  }
+  if (!at(grid, size - 8, 8)) faults.push(`dark-module@${size - 8},8`);
+  return faults;
+}
+
+type Cell = readonly [number, number];
+
+/** The cells of both format copies, bit 14 first; positions straight from ISO 18004 Figure 25. */
+export function formatCells(size: number): readonly [readonly Cell[], readonly Cell[]] {
+  const first: Cell[] = [];
+  for (let col = 0; col <= 8; col++) if (col !== 6) first.push([8, col]);
+  for (let row = 7; row >= 0; row--) if (row !== 6) first.push([row, 8]);
+  const second: Cell[] = [];
+  for (let row = size - 1; row >= size - 7; row--) second.push([row, 8]);
+  for (let col = size - 8; col < size; col++) second.push([8, col]);
+  return [first, second];
+}
+
+function formatCopies(grid: Grid, size: number): readonly [number, number] {
+  const read = (cells: readonly Cell[]): number =>
+    cells.reduce((acc, [row, col]) => (acc << 1) | (at(grid, row, col) ? 1 : 0), 0);
+  const [first, second] = formatCells(size);
+  return [read(first), read(second)];
+}
+
+function maskFlips(mask: number, row: number, col: number): boolean {
+  const formulas: readonly ((i: number, j: number) => boolean)[] = [
+    (i, j) => (i + j) % 2 === 0,
+    (i) => i % 2 === 0,
+    (_i, j) => j % 3 === 0,
+    (i, j) => (i + j) % 3 === 0,
+    (i, j) => (Math.floor(i / 2) + Math.floor(j / 3)) % 2 === 0,
+    (i, j) => ((i * j) % 2) + ((i * j) % 3) === 0,
+    (i, j) => (((i * j) % 2) + ((i * j) % 3)) % 2 === 0,
+    (i, j) => (((i * j) % 3) + ((i + j) % 2)) % 2 === 0,
+  ];
+  return formulas[mask]?.(row, col) === true;
+}
+
+function readCodewords(grid: Grid, size: number, mask: number, count: number): number[] {
+  const bits: number[] = [];
+  // Two-column strips from the right edge; the strip that would straddle the vertical timing
+  // column moves one left, so column 6 is never read and column 0 always is.
+  const strips: number[] = [];
+  for (let right = size - 1; right >= 1; right -= 2) strips.push(right > 6 ? right : right - 1);
+  strips.forEach((right, index) => {
+    const upward = index % 2 === 0;
+    for (let step = 0; step < size; step++) {
+      const row = upward ? size - 1 - step : step;
+      for (const col of [right, right - 1]) {
+        if (isFunctionModule(size, row, col)) continue;
+        bits.push(at(grid, row, col) !== maskFlips(mask, row, col) ? 1 : 0);
+      }
+    }
+  });
+  const words: number[] = [];
+  for (let i = 0; i < count; i++) {
+    words.push(bits.slice(i * 8, i * 8 + 8).reduce((acc, bit) => (acc << 1) | bit, 0));
+  }
+  return words;
+}
+
+/** Reed-Solomon syndromes over GF(256)/0x11d: all zero exactly when no codeword is corrupt. */
+export function syndromesZero(codewords: readonly number[], eccCount: number): boolean {
+  const exp: number[] = [];
+  let x = 1;
+  for (let i = 0; i < 255; i++) {
+    exp.push(x);
+    x = x & 0x80 ? ((x << 1) ^ 0x11d) & 0xff : x << 1;
+  }
+  const log = new Map<number, number>(exp.map((v, i) => [v, i]));
+  const mul = (a: number, b: number): number =>
+    a === 0 || b === 0 ? 0 : (exp[((log.get(a) ?? 0) + (log.get(b) ?? 0)) % 255] ?? 0);
+  for (let k = 0; k < eccCount; k++) {
+    let s = 0;
+    for (const word of codewords) s = mul(s, exp[k] ?? 1) ^ word;
+    if (s !== 0) return false;
+  }
+  return true;
+}
+
+/** Reads `grid` as a QR symbol. Never throws: a symbol that does not read is `text: ''` plus
+ *  whatever faults explain why. */
+export function readQr(grid: Grid): QrReading {
+  const size = grid.length;
+  const version = (size - 17) / 4;
+  const faults = fixedFaults(grid, size);
+  const [first, second] = formatCopies(grid, size);
+  if (first !== second) faults.push('format-copies-differ');
+  const mask = LEVEL_M_FORMAT.indexOf(first);
+  if (mask < 0) faults.push('format-not-level-m');
+  const total = CODEWORDS.get(version)?.total ?? 0;
+  const codewords = mask < 0 ? [] : readCodewords(grid, size, mask, total);
+  const dataCount = CODEWORDS.get(version)?.data ?? 0;
+  if (codewords.length === 0 || !syndromesZero(codewords, total - dataCount)) {
+    return { version, mask, codewords, text: '', layoutFaults: [...faults, 'reed-solomon'] };
+  }
+  const bits = codewords
+    .slice(0, dataCount)
+    .flatMap((word) => Array.from({ length: 8 }, (_, i) => (word >>> (7 - i)) & 1));
+  const field = (start: number, length: number): number =>
+    bits.slice(start, start + length).reduce((acc, bit) => (acc << 1) | bit, 0);
+  if (field(0, 4) !== 0b0100) return { version, mask, codewords, text: '', layoutFaults: faults };
+  const length = field(4, 8);
+  const bytes = Uint8Array.from({ length }, (_, i) => field(12 + i * 8, 8));
+  return { version, mask, codewords, text: new TextDecoder().decode(bytes), layoutFaults: faults };
+}