better patterns

README.md

@@ -41,7 +41,7 @@ New plans start with a random laying pattern. Click the numbered room, materials
 - Geometry follows measured vectors, checks final-wall length/direction, detects crossings and validates opening bounds and overlaps. A small accepted closure residual snaps only the final wall to the origin, with a visible warning. A mismatch can indicate measurement error or an irregular wall; lengths and corner angles alone cannot identify or reconstruct a bow. Remeasure and represent known changes of direction as additional segments.
 - Polygon offsets and clipping use `clipper-lib` at 0.001 mm internal precision. Displayed cut dimensions round up to the next 0.5 mm; angles display to 0.1°. New cutting blanks reserve that rounded length plus kerf so the displayed cuts fit their source board. Finished polygon coordinates retain their original precision. The supplied cut templates contain board-relative polygon vertices and edge lengths for angled and notched pieces.
 - Laminate is inset from every wall, including fireplace recesses. Interior rows retain full factory width. When the final row would be narrower than the minimum, the first and last rows share the width equally. A bounded search also compares other feasible edge-row arrangements, including row seams aligned with inward corners to avoid unnecessary notches and tapered tips.
-- Brick uses a half-board stagger. Random is deterministic and discourages staircase runs, near-equal successive steps and repeating joint alignments, including steps that wrap across a board length. Pattern preferences never invalidate a physically valid plan when tight offset limits force repetition. The offset is the nearest end-joint distance on the adjacent row's grid, not a distance from a wall. Half a board is the largest possible nearest-joint offset. Settings that cannot be met produce an error instead of a partial layout.
+- Brick uses a half-board stagger. Random is deterministic and discourages staircase runs, near-equal successive steps and repeating joint alignments, including steps that wrap across a board length. H-pattern avoidance checks joints two rows apart at the scale of a board width, so small misalignments still count as a visible repeat. Pattern preferences never invalidate a physically valid plan when tight offset limits force repetition. The offset is the nearest end-joint distance on the adjacent row's grid, not a distance from a wall. Half a board is the largest possible nearest-joint offset. Settings that cannot be met produce an error instead of a partial layout.
 - Minimum laminate sizes apply to each clipped piece's bounding length/width. Irregular shapes can still have narrow tips or necks; their exact templates are available in the cut popups. Product-specific click systems and assembly sequences are not simulated.
 - Offcut reuse preserves the needed left/right factory ends. Only full-width end remnants are available for reuse; ripped side strips and shaped scraps are conservatively waste. Crosscuts include kerf. The stock count is actual allocated boards, not an area-only estimate. Waste includes kerf and unused material, including still-usable stock remainders.
 - Skirting internal corners use coped joints. The blank keeps the wall-corner long point instead of subtracting the receiving board’s thickness; the cope preparation is half the measured turn. Earlier walls receive adjoining later walls, so installation order has no cycle. At square corners, a 4,000 mm wall keeps a 4,000 mm blank; with 18 mm skirting at both corners its exposed front length is 3,964 mm. Non-square receiving ends have a wall-fitting bevel. External corners use equal mitres. Minimum sizes check the exposed face and installed body after corner and door allowances. Preparation previews and dashed body edges guide marking; the actual moulding profile must be scribed and back-cut, since thickness alone does not define it. This follows [Gary Katz’s coping and long-point measurement guidance](https://www.finehomebuilding.com/pdf/021174063.pdf); the general-angle allowances are derived from intersecting wall faces.

benchmarks/README.md

@@ -7,6 +7,8 @@ remainders, fireplaces in both directions, room-order permutations, tight and ex
 stagger limits, fractional stock, large floors, and both supplied angled rooms.
 `--output=/tmp/results.json` saves a run; `--compare=/tmp/results.json` compares
 against a previous iteration. Do not overwrite the baseline to hide regressions.
+`h-pattern-baseline.json` separately freezes both options immediately before the
+visual H-pattern correction, evaluated using the broader alignment metric below.
 
 ## Fixed metrics
 
@@ -14,18 +16,23 @@ against a previous iteration. Do not overwrite the baseline to hide regressions.
   and additional shaping edges. Skirting includes bevel and coping operations.
 - **Cut difficulty:** shaping passes, then rip passes, used to break equal saw-count
   ties. This is an explicit proxy, not an estimate of minutes or tool-specific effort.
-- **Random appearance:** the existing repetition penalty, evaluated independently
+- **Legacy repetition:** the original penalty, evaluated independently
   from the output rows. It penalises nearby repeating joints, similar consecutive
   steps and staircases, including steps that wrap across a board length. Raw repeat,
-  similar-step and staircase counts are also reported. A lower score is better.
+  similar-step and staircase counts are also reported. This stays unchanged for
+  historical comparisons, but its 3%-of-board-length alignment tolerance missed visible H patterns.
+- **Near-H row pairs:** joints two rows apart separated by less than one board width,
+  capped at one sixth of the board length. This catches the 40–150 mm misalignments
+  that still look like an H. Current appearance cost is the legacy penalty plus
+  12 per near-H pair, so avoiding an H outweighs several same-direction steps.
 - **Waste:** purchased stock minus installed material, including kerf. The report
   gives board counts and waste percentages weighted by purchased stock.
 - **Validity and runtime:** errors, elapsed time, p95 and maximum case time. Tests
   separately verify coverage, non-overlapping row bands, minimum sizes, stagger,
   factory ends, rounded stock consumption, cut accounting, references and input purity.
 
-Minimise cuts orders `(passes, shaping, rips, pattern penalty, boards)`.
-Maximise randomness orders `(pattern penalty, passes, shaping, rips, boards)`.
+Minimise cuts orders `(passes, shaping, rips, appearance cost, boards)`.
+Maximise randomness orders `(appearance cost, passes, shaping, rips, boards)`.
 Validity precedes either objective. Skirting orders `(passes, waste)`.
 
 ## Measured results
@@ -34,25 +41,52 @@ Totals across the same 84 cases, September 2026:
 
 | Metric              | Original | Minimise cuts | Maximise randomness |
 | ------------------- | -------: | ------------: | ------------------: |
-| Flooring saw passes |    2,177 |     **1,741** |           **1,994** |
-| Shaping passes      |      192 |           184 |                 185 |
-| Rip passes          |      414 |           402 |                 405 |
-| Pattern penalty     |      265 |         1,349 |             **113** |
-| Flooring boards     |    3,561 |         3,537 |               3,579 |
-| Flooring waste      |    8.20% |         7.57% |               8.66% |
+| Flooring saw passes |    2,177 |     **1,741** |           **2,113** |
+| Shaping passes      |      192 |           184 |                 188 |
+| Rip passes          |      414 |           402 |                 409 |
+| Legacy penalty      |      265 |         2,207 |                 346 |
+| Flooring boards     |    3,561 |         3,548 |               3,551 |
+| Flooring waste      |    8.20% |         7.85% |               7.94% |
 | Invalid cases       |        0 |             0 |                   0 |
 
-Minimise cuts saves **20.0%** of saw passes. Maximise randomness reduces the pattern
-penalty **57.4%**, while also saving **8.4%** of saw passes. For random flooring in the
-default 4,800 × 3,600 mm room, 38 passes become **24** or **30**, respectively; both options use 76
+Minimise cuts saves **20.0%** of saw passes. Maximise randomness saves **2.9%** of saw
+passes against the original planner. For random flooring in the default
+4,800 × 3,600 mm room, 38 passes become **24** or **31**, respectively; both options use 76
 boards and have approximately 1.2% waste.
 
 Skirting drops from **1,447 to 1,436 passes**. It uses 521 boards instead of 513:
 cutting effort now takes precedence over waste, which rises from 9.28% to 10.68%.
 Eight cases improve and 76 tie.
-For flooring, 78 cut-priority cases improve and six tie. Appearance priority improves
-72, ties 11, and uses one extra cut in `rectangle-38` despite the same zero pattern
-penalty. The bounded search does not establish global optimality.
+For flooring, 78 cut-priority cases improve and six tie against the original planner.
+The bounded search does not establish global optimality.
+
+## H-pattern correction
+
+The first optimisation reported a 57% lower legacy penalty, but visual inspection
+showed that the metric was too narrow. The default appearance-priority room still
+had **11 near-H row pairs**, despite no repeats within the old 36 mm tolerance.
+The candidate hash also generated almost identical offsets for adjacent candidate
+numbers. A final bit-mixing step now spreads those candidates across the allowed range.
+
+| Metric                    | Cuts before | Cuts now | Random before | Random now |
+| ------------------------- | ----------: | -------: | ------------: | ---------: |
+| Near-H row pairs          |         515 |      247 |           557 |      **6** |
+| Saw passes                |       1,741 |    1,741 |         1,994 |      2,113 |
+| Boards                    |       3,537 |    3,548 |         3,579 |      3,551 |
+| Waste                     |       7.57% |    7.85% |         8.66% |      7.94% |
+| Default-room near-H pairs |          17 |       17 |            11 |      **0** |
+| Default-room saw passes   |          24 |       24 |            30 |         31 |
+
+Appearance priority removes **98.9%** of near-H pairs for **6.0%** more cuts than the
+previous iteration. All six remaining pairs are in `forced-alternation`, whose
+600 mm minimum pieces force alternating starts. It improves 79 cases and ties five
+under the corrected objective. Ten additional room seeds also produce zero near-H pairs.
+
+The tradeoff is explicit: the old direction-run/staircase score increases, and the
+randomness option uses more cuts. Cuts-first retains its total saw count but three
+individual cases use extra cuts (`two-rooms-reversed-6`, `angled`, `angled-f8`).
+It can still show H patterns when avoiding them requires extra cuts; the UI explains
+this beside the laying-pattern choice. Both frozen baselines remain unchanged.
 
 ## Iterations retained
 
@@ -74,6 +108,9 @@ penalty. The bounded search does not establish global optimality.
    the optimiser.
 8. Compare exact three-piece skirting fills with the original packing. This improves
    two cases for a small additional calculation cost.
+9. Add the board-scale H penalty and mix the offset hash. Search size and geometry
+   constraints stay unchanged. Before/after drawings were checked for the default
+   rectangle, fireplace and large floor, alongside the numeric metrics.
 
 ## Experiments rejected
 
@@ -90,5 +127,6 @@ These are indicative timings, not CI thresholds. Ordinary option changes reuse t
 already calculated plans. A separate 500-row, 2,000-board boundary check completes
 without an error; temporary stock is repacked before enforcing the board limit.
 
-Tests enforce the retained aggregate improvements as well as physical invariants.
-Metric definitions and input cases stay fixed while search strategies change.
+Tests enforce aggregate cutting budgets, broad H avoidance and physical invariants.
+The original metrics and cases remain fixed; the new H metric has its own frozen
+baseline so the correction does not rewrite the earlier results.

benchmarks/metrics.ts

@@ -6,6 +6,7 @@ export function flooringMetrics(plan: FlooringPlan, s: FlooringSettings) {
   let ripCuts = 0;
   let patternPenalty = 0;
   let repeats = 0;
+  let nearH = 0;
   let similarSteps = 0;
   let staircases = 0;
   for (const piece of plan.pieces) {
@@ -32,6 +33,8 @@ export function flooringMetrics(plan: FlooringPlan, s: FlooringSettings) {
     if (recent.length >= 2) {
       const movement = step(recent.at(-1)!, phase);
       const previous = step(recent.at(-2)!, recent.at(-1)!);
+      // Near-aligned joints with one intervening row still read as an H at the scale of the boards.
+      if (Math.abs(step(recent.at(-2)!, phase)) < Math.min(s.width, s.length / 6) - 0.01) nearH++;
       patternPenalty += Number(Math.abs(Math.abs(movement) - s.length / 2) <= 0.01);
       for (let distance = 2; distance <= recent.length; distance++) {
         if (Math.abs(step(recent.at(-distance)!, phase)) <= similar) {
@@ -59,6 +62,7 @@ export function flooringMetrics(plan: FlooringPlan, s: FlooringSettings) {
     ripCuts,
     patternPenalty,
     repeats,
+    nearH,
     similarSteps,
     staircases,
     boards: plan.boardCount,
@@ -78,7 +82,7 @@ export function skirtingMetrics(plan: SkirtingPlan) {
 }
 
 export function compareFlooring(
-  a: ReturnType<typeof flooringMetrics>,
+  a: Omit<ReturnType<typeof flooringMetrics>, 'nearH'>,
   b: typeof a,
   random = false,
 ) {
@@ -93,6 +97,19 @@ export function compareFlooring(
   );
 }
 
+/** Current appearance score adds broad H alignments; the original metric stays comparable. */
+export function compareCurrentFlooring(
+  a: ReturnType<typeof flooringMetrics>,
+  b: typeof a,
+  random = false,
+) {
+  return compareFlooring(
+    { ...a, patternPenalty: a.patternPenalty + 12 * a.nearH },
+    { ...b, patternPenalty: b.patternPenalty + 12 * b.nearH },
+    random,
+  );
+}
+
 export function compareSkirting(a: ReturnType<typeof skirtingMetrics>, b: typeof a) {
   return a.errors - b.errors || a.cuts - b.cuts || a.waste - b.waste;
 }

scripts/benchmark-planner.mjs

@@ -42,12 +42,23 @@ try {
       .find((arg) => arg.startsWith('--compare='))
       ?.slice('--compare='.length);
     const baseline = JSON.parse(await readFile(comparison ?? baselinePath, 'utf8'));
+    const currentAppearance = baseline.every((row) => typeof row.flooring.nearH === 'number');
+    console.log(
+      currentAppearance
+        ? 'Comparisons include the broad H-alignment penalty.'
+        : 'Historical comparisons use the original narrow repetition score; broad H counts follow separately.',
+    );
     const sum = (rows, key, metric) => rows.reduce((total, row) => total + row[key][metric], 0);
     const summary = [];
     for (const kind of ['flooring', 'skirting']) {
       const compare =
         kind === 'flooring'
-          ? (a, b) => metrics.compareFlooring(a, b, random)
+          ? (a, b) =>
+              (currentAppearance ? metrics.compareCurrentFlooring : metrics.compareFlooring)(
+                a,
+                b,
+                random,
+              )
           : metrics.compareSkirting;
       const changes = results.map((result) => {
         const previous = baseline.find((row) => row.name === result.name);
@@ -94,6 +105,24 @@ try {
         }),
       ),
     );
+    const hBaseline = JSON.parse(
+      await readFile(new URL('../benchmarks/h-pattern-baseline.json', import.meta.url), 'utf8'),
+    );
+    const mode = random ? 'random' : 'cuts';
+    const hBefore = hBaseline.reduce((total, row) => total + row[mode].nearH, 0);
+    const hChanges = results.map((row) =>
+      metrics.compareCurrentFlooring(
+        row.flooring,
+        hBaseline.find((previous) => previous.name === row.name)[mode],
+        random,
+      ),
+    );
+    console.log(
+      `Against the pre-H-fix layout: near-H row pairs ${hBefore} → ${sum(results, 'flooring', 'nearH')}; ` +
+        `${hChanges.filter((change) => change < 0).length} improved, ` +
+        `${hChanges.filter((change) => change === 0).length} tied, ` +
+        `${hChanges.filter((change) => change > 0).length} regressed under the current objective.`,
+    );
   }
   for (const key of ['floorMs', 'skirtMs']) {
     const times = results.map((row) => row[key]).sort((a, b) => a - b);

src/components/MaterialsEditor.tsx

@@ -76,7 +76,7 @@ export function MaterialsEditor({
           </div>
           <p className="helper">
             {f.pattern === 'random'
-              ? 'Varied joints for a natural look. Choose fewer cuts or a more varied arrangement below.'
+              ? 'Maximise randomness spreads out joints to avoid H shapes. Minimise cuts can repeat joint positions.'
               : 'A regular pattern with each row staggered by half a board.'}
           </p>
         </div>

src/lib/flooring.ts

@@ -524,8 +524,10 @@ function randomPatternPenalty(
   // Half-board steps have equally near joints in both directions and tend to look brick-like.
   let penalty = close(Math.abs(step), s.length / 2) ? 1 : 0;
   for (let distance = 2; distance <= recent.length; distance++) {
-    if (Math.abs(jointStep(recent.at(-distance)!.offset, phase, s.length)) <= similar)
-      penalty += 5 - distance;
+    const separation = Math.abs(jointStep(recent.at(-distance)!.offset, phase, s.length));
+    // Two rows apart, joints within a board width still read as an H, even without exact alignment.
+    if (distance === 2 && separation < Math.min(s.width, s.length / 6) - EPSILON) penalty += 12;
+    if (separation <= similar) penalty += 5 - distance;
   }
   if (step * previousStep > 0) {
     penalty += 1;
@@ -644,6 +646,12 @@ function fraction(seed: string): number {
     hash ^= seed.charCodeAt(i);
     hash = Math.imul(hash, 16777619);
   }
+  // Avalanche the final bits: adjacent candidate numbers must not yield almost identical offsets.
+  hash ^= hash >>> 16;
+  hash = Math.imul(hash, 0x85ebca6b);
+  hash ^= hash >>> 13;
+  hash = Math.imul(hash, 0xc2b2ae35);
+  hash ^= hash >>> 16;
   return (hash >>> 0) / 4294967296;
 }
 

tests/flooring.test.ts

@@ -324,13 +324,9 @@ describe('laminate planning', () => {
         // Similar signed steps across three rows produce a visible staircase, even with small kerf drift.
         expect(Math.abs(steps[i] - steps[i - 1])).toBeGreaterThan(36);
         // Returning to almost the same joint line two rows later produces an H/brick repeat.
-        expect(Math.abs(signedDistance(phases[i - 1], phases[i + 1]))).toBeGreaterThan(36);
-      }
-      for (let i = 2; i < steps.length; i++) {
-        expect(
-          steps.slice(i - 2, i + 1).every((step) => step > 0) ||
-            steps.slice(i - 2, i + 1).every((step) => step < 0),
-        ).toBe(false);
+        expect(Math.abs(signedDistance(phases[i - 1], phases[i + 1]))).toBeGreaterThanOrEqual(
+          s.width,
+        );
       }
       // Breaking the old regular pattern must not increase the stock requirement for these rooms.
       expect(plan.boardCount).toBeLessThanOrEqual(boardBudget);

tests/optimisation.test.ts

@@ -2,14 +2,16 @@ import { describe, expect, it } from 'vitest';
 import { plannerCases } from '../benchmarks/cases';
 import {
   compareFlooring,
+  compareCurrentFlooring,
   compareSkirting,
   flooringMetrics,
   skirtingMetrics,
 } from '../benchmarks/metrics';
 import baseline from '../benchmarks/baseline.json';
+import hBaseline from '../benchmarks/h-pattern-baseline.json';
 import { planFlooringOptions } from '../src/lib/flooring';
 import { planSkirting } from '../src/lib/skirting';
-import { defaultProject, rectangle } from '../src/lib/defaults';
+import { defaultProject, fireplace, rectangle } from '../src/lib/defaults';
 import { buildGeometry, insetPolygon, signedArea } from '../src/lib/geometry';
 import type { FlooringPlan, Project } from '../src/lib/types';
 
@@ -118,8 +120,15 @@ describe('measured optimiser quality', () => {
       const random = flooringMetrics(options.random, project.flooring);
       const before = baseline.find((row) => row.name === name)!;
       expect(compareFlooring(cuts, before.flooring)).toBeLessThanOrEqual(0);
-      expect(compareFlooring(cuts, random)).toBeLessThanOrEqual(0);
-      expect(compareFlooring(random, cuts, true)).toBeLessThanOrEqual(0);
+      expect(compareCurrentFlooring(cuts, random)).toBeLessThanOrEqual(0);
+      expect(compareCurrentFlooring(random, cuts, true)).toBeLessThanOrEqual(0);
+      const previousAppearance = hBaseline.find((row) => row.name === name)!;
+      expect(compareCurrentFlooring(random, previousAppearance.random, true)).toBeLessThanOrEqual(
+        0,
+      );
+      expect(random.nearH).toBeLessThanOrEqual(previousAppearance.random.nearH);
+      // Only this fixture's 600 mm minimum pieces force alternating starts.
+      if (name !== 'forced-alternation') expect(random.nearH).toBe(0);
       validateFlooring(options.cuts, project);
       if (options.random !== options.cuts) validateFlooring(options.random, project);
       expect(compareSkirting(skirt, before.skirting)).toBeLessThanOrEqual(0);
@@ -129,17 +138,20 @@ describe('measured optimiser quality', () => {
   );
 
   it('retains the measured improvements across the complete fixed corpus', () => {
-    const totals = { cuts: 0, randomCuts: 0, pattern: 0, skirtingCuts: 0 };
+    const totals = { cuts: 0, randomCuts: 0, pattern: 0, nearH: 0, skirtingCuts: 0 };
     for (const c of cases) {
       const { options, skirt } = resultFor(c);
       totals.cuts += options.cuts.cuts;
       totals.randomCuts += options.random.cuts;
       totals.pattern += flooringMetrics(options.random, c.project.flooring).patternPenalty;
+      totals.nearH += flooringMetrics(options.random, c.project.flooring).nearH;
       totals.skirtingCuts += skirt.cuts;
     }
     expect(totals.cuts).toBeLessThanOrEqual(1741); // Original: 2177.
-    expect(totals.randomCuts).toBeLessThanOrEqual(1994);
-    expect(totals.pattern).toBeLessThanOrEqual(113); // Original: 265.
+    // Broader H avoidance costs more cuts, while still beating the original 2177 passes.
+    expect(totals.randomCuts).toBeLessThanOrEqual(2113);
+    expect(totals.nearH).toBeLessThanOrEqual(6); // Before the visual correction: 557.
+    expect(totals.pattern).toBeLessThanOrEqual(346); // Retain the separate legacy diagnostic.
     expect(totals.skirtingCuts).toBeLessThanOrEqual(1436); // Original: 1447.
   });
 
@@ -154,4 +166,18 @@ describe('measured optimiser quality', () => {
     expect(plan.cuts).toBe(750);
     expect(plan.coveredArea).toBe(4500 * 95000);
   });
+
+  it.each(Array.from({ length: 10 }, (_, i) => i + 1))(
+    'avoids broad H joints with independent room seed %i',
+    (seed) => {
+      const project = defaultProject();
+      project.rooms = [
+        seed % 2 ? rectangle(`holdout-${seed}`) : fireplace(`holdout-${seed}`, 'Fireplace'),
+      ];
+      const plan = planFlooringOptions(project.rooms, project.flooring, project.tolerance).random;
+      expect(flooringMetrics(plan, project.flooring).nearH).toBe(0);
+      expect(plan.boardCount).toBeLessThanOrEqual(seed % 2 ? 76 : 74);
+      validateFlooring(plan, project);
+    },
+  );
 });