ShaftHQ
diff --git a/‎src/pages/index.module.css‎
Lines changed: 70 additions & 7 deletions b/‎src/pages/index.module.css‎
Lines changed: 70 additions & 7 deletions
diff --git a/‎src/pages/index.tsx‎
Lines changed: 24 additions & 2 deletions b/‎src/pages/index.tsx‎
Lines changed: 24 additions & 2 deletions
diff --git a/‎test-screenshots/01-homepage-before-chat.png‎
-136 KB b/‎test-screenshots/01-homepage-before-chat.png‎
-136 KB
diff --git a/‎tests/e2e/composited-contrast.spec.js‎
Lines changed: 88 additions & 0 deletions b/‎tests/e2e/composited-contrast.spec.js‎
Lines changed: 88 additions & 0 deletions
diff --git a/‎tests/e2e/homepage.spec.js‎
Lines changed: 56 additions & 1 deletion b/‎tests/e2e/homepage.spec.js‎
Lines changed: 56 additions & 1 deletion
@@ -164,7 +164,7 @@
 }
 
 .actions :global(.button) {
-  height: 3.45rem;
+  min-height: 3.45rem;
   min-width: 0;
   max-width: 100%;
   padding: 0.82rem 1.15rem !important;
@@ -214,7 +214,11 @@
 
 .hero .actions :global(.button--secondary),
 .finalCta .actions :global(.button--secondary) {
-  border-color: rgba(var(--site-color-muted-rgb), 0.42);
+  /* 0.42 measured 2.94:1 against the hero backdrop -- under WCAG 1.4.11's
+     3:1 floor for a UI component boundary (#898 finding 14). 0.48 clears it
+     with headroom (~3.4:1); raising alpha per the issue's own guidance
+     rather than the text color, which already passes on its own. */
+  border-color: rgba(var(--site-color-muted-rgb), 0.48);
   background: rgba(var(--site-color-muted-rgb), 0.08);
   color: var(--site-color-on-dark);
 }
@@ -504,7 +508,7 @@
   color: var(--site-color-primary);
   font-weight: var(--site-font-weight-bold);
   transform: none;
-  content: '+';
+  content: '+' / '';
 }
 
 .audienceSection {
@@ -517,12 +521,14 @@
 .audienceGrid {
   display: grid;
   grid-template-columns: repeat(2, minmax(0, 1fr));
+  grid-template-rows: auto auto 1fr;
   gap: 1rem;
 }
 
 .audienceLane {
   display: grid;
-  grid-template-rows: 2.1rem 4.4rem 1fr;
+  grid-row: span 3;
+  grid-template-rows: subgrid;
   row-gap: 0.8rem;
   min-width: 0;
   padding: 1.35rem;
@@ -605,6 +611,22 @@
   color: var(--ifm-font-color-base);
 }
 
+.dependencySnippet {
+  max-width: 480px;
+  margin: 0 auto 2rem;
+  text-align: left;
+}
+
+.dependencyLabel {
+  margin: 0 0 0.5rem;
+  color: var(--ifm-color-emphasis-800);
+  font-family: var(--ifm-font-family-monospace);
+  font-size: var(--site-font-small);
+  font-weight: var(--site-font-weight-medium);
+  letter-spacing: 0.1em;
+  text-transform: uppercase;
+}
+
 .pathGrid {
   display: grid;
   grid-template-columns: repeat(5, minmax(0, 1fr));
@@ -772,6 +794,7 @@
 .evidenceLoop {
   display: grid;
   grid-template-columns: repeat(5, minmax(0, 1fr));
+  grid-template-rows: auto auto 1fr;
   gap: 0;
   border: 1px solid var(--ifm-color-emphasis-200);
   border-radius: 8px;
@@ -783,7 +806,8 @@
 .loopStep {
   position: relative;
   display: grid;
-  grid-template-rows: 1.8rem 3rem 1fr;
+  grid-row: span 3;
+  grid-template-rows: subgrid;
   row-gap: 0.9rem;
   min-height: 210px;
   padding: 1.25rem;
@@ -807,7 +831,7 @@
   top: 1rem;
   right: 1rem;
   color: var(--site-color-primary);
-  content: '>';
+  content: '>' / '';
   font-weight: var(--site-font-weight-bold);
 }
 
@@ -839,6 +863,23 @@
   color: var(--ifm-color-emphasis-800);
 }
 
+.loopReturn {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  gap: 0.55rem;
+  margin: 1rem 0 0;
+  color: var(--ifm-color-emphasis-800);
+  font-size: var(--site-font-label);
+  font-weight: var(--site-font-weight-medium);
+}
+
+.loopReturn svg {
+  width: 0.85rem;
+  height: 0.85rem;
+  color: var(--site-color-primary);
+}
+
 .featureLinks {
   margin-top: 1.5rem;
 }
@@ -977,7 +1018,6 @@
   transition:
     opacity 540ms ease var(--reveal-delay),
     transform 540ms cubic-bezier(0.2, 0.8, 0.2, 1) var(--reveal-delay);
-  will-change: opacity, transform;
 }
 
 :global(html[data-reveal-ready='true']) .revealVisible {
@@ -1023,6 +1063,29 @@
   .heroGrid {
     max-width: 920px;
   }
+
+  .pathGrid,
+  .evidenceLoop,
+  .footerBadges {
+    grid-template-columns: repeat(2, minmax(0, 1fr));
+  }
+
+  .pathGrid,
+  .evidenceLoop {
+    gap: 1rem;
+    border: 0;
+    overflow: visible;
+    background: transparent;
+    box-shadow: none;
+  }
+
+  .pathCard,
+  .loopStep,
+  .loopStep:last-child {
+    border: 1px solid var(--ifm-color-emphasis-200);
+    border-radius: 8px;
+    box-shadow: 0 14px 34px rgba(var(--site-color-deep-alt-rgb), 0.06);
+  }
 }
 
 @media (max-width: 980px) {
 
@@ -5,8 +5,10 @@ import Layout from '@theme/Layout';
 import Heading from '@theme/Heading';
 import {FontAwesomeIcon} from '@fortawesome/react-fontawesome';
 import {faSlack} from '@fortawesome/free-brands-svg-icons';
-import {faBookOpen, faStar, faTerminal} from '@fortawesome/free-solid-svg-icons';
+import {faBookOpen, faRotateLeft, faStar, faTerminal} from '@fortawesome/free-solid-svg-icons';
+import CodeBlock from '@theme/CodeBlock';
 import ParticleBackground from '@site/src/components/ParticleBackground';
+import releases from '@site/src/data/releases.json';
 import snippets from '@site/src/data/snippets.json';
 import styles from './index.module.css';
 
@@ -222,20 +224,28 @@ function useHoverGlow(): void {
     }
 
     const glowTargets = Array.from(document.querySelectorAll<HTMLElement>('[data-hover-glow]'));
+    const rects = new WeakMap<HTMLElement, DOMRect>();
+
+    const cacheRect = (event: PointerEvent) => {
+      const target = event.currentTarget as HTMLElement;
+      rects.set(target, target.getBoundingClientRect());
+    };
 
     const updatePointer = (event: PointerEvent) => {
       const target = event.currentTarget as HTMLElement;
-      const rect = target.getBoundingClientRect();
+      const rect = rects.get(target) ?? target.getBoundingClientRect();
       target.style.setProperty('--hover-x', `${event.clientX - rect.left}px`);
       target.style.setProperty('--hover-y', `${event.clientY - rect.top}px`);
     };
 
     glowTargets.forEach((target) => {
+      target.addEventListener('pointerenter', cacheRect, { passive: true });
       target.addEventListener('pointermove', updatePointer, { passive: true });
     });
 
     return () => {
       glowTargets.forEach((target) => {
+        target.removeEventListener('pointerenter', cacheRect);
         target.removeEventListener('pointermove', updatePointer);
       });
     };
@@ -364,6 +374,14 @@ function GuidePathSection(): JSX.Element {
           <Heading as="h2" id="guide-paths-heading">Get started in minutes.</Heading>
           <p>Install, configure, write a readable test, run it headlessly, and review the evidence before starring the repository.</p>
         </div>
+        <div className={styles.dependencySnippet} data-testid="landing-dependency-snippet">
+          <p className={styles.dependencyLabel}>Add the dependency</p>
+          <CodeBlock language="xml">{`<dependency>
+  <groupId>io.github.shafthq</groupId>
+  <artifactId>shaft-engine</artifactId>
+  <version>${releases.engineVersion}</version>
+</dependency>`}</CodeBlock>
+        </div>
         <div className={styles.pathGrid} role="group" aria-labelledby="guide-paths-heading">
           {guidePaths.map((path) => (
             <Link className={`${styles.pathCard} ${styles.reveal}`} to={path.to} key={path.title} data-reveal data-hover-glow>
@@ -493,6 +511,10 @@ function AgentSection(): JSX.Element {
             </div>
           ))}
         </div>
+        <p className={styles.loopReturn} data-testid="landing-evidence-loop-return">
+          <FontAwesomeIcon icon={faRotateLeft} aria-hidden="true" />
+          Improve loops back to Execute — every run repeats the cycle.
+        </p>
         <div className={styles.featureLinks} data-testid="landing-agent-links">
           <Link data-testid="landing-agent-mcp-link" to="/docs/agentic/mcp">MCP setup and commands</Link>
           <Link to="/docs/agentic/doctor">Diagnose with Doctor</Link>
 
@@ -194,6 +194,81 @@ function interiorSampler(inset) {
   };
 }
 
+// Composites `fg` (with alpha) over `bg` using the standard "over" formula.
+function compositeOver(fg, bg) {
+  return {
+    r: fg.r * fg.a + bg.r * (1 - fg.a),
+    g: fg.g * fg.a + bg.g * (1 - fg.a),
+    b: fg.b * fg.a + bg.b * (1 - fg.a),
+  };
+}
+
+// Regression guard for #898 finding 14. Measures the hero/final secondary
+// button's border -- a UI component boundary under WCAG 1.4.11 (>=3:1
+// against the adjacent surrounding color) -- without needing sub-pixel
+// screenshot sampling of the 1px stroke itself (the existing 6x6-block
+// averaging used elsewhere in this file would blur a 1px line into the
+// fill/background either side of it). Instead: read the border's own rgba
+// color (a flat, non-gradient value) via getComputedStyle, sample the real
+// composited backdrop just outside the button's box, then composite the
+// border color over that background analytically and measure contrast
+// against the same background -- i.e. the boundary color vs. its adjacent
+// color, which is exactly what 1.4.11 asks for.
+async function measureBorderContrast(page, selector) {
+  const locator = page.locator(selector).first();
+  await locator.scrollIntoViewIfNeeded();
+
+  const info = await locator.evaluate((el) => {
+    const rect = el.getBoundingClientRect();
+    const style = getComputedStyle(el);
+    const borderMatch = style.borderTopColor.match(/rgba?\((\d+),\s*(\d+),\s*(\d+)(?:,\s*([\d.]+))?\)/);
+    return {
+      rect: {x: rect.x, y: rect.y, width: rect.width, height: rect.height},
+      border: {
+        r: +borderMatch[1],
+        g: +borderMatch[2],
+        b: +borderMatch[3],
+        a: borderMatch[4] !== undefined ? +borderMatch[4] : 1,
+      },
+    };
+  });
+
+  // Sample the hero backdrop just above the button: clear of the button's
+  // own fill/border/box-shadow and of any neighbouring button.
+  const bgPoint = {x: info.rect.x + info.rect.width / 2, y: info.rect.y - 10};
+
+  const screenshot = (await page.screenshot()).toString('base64');
+  const bg = await page.evaluate(async ({screenshot, point}) => {
+    const img = new Image();
+    img.src = `data:image/png;base64,${screenshot}`;
+    await new Promise((resolve, reject) => {
+      img.onload = resolve;
+      img.onerror = reject;
+    });
+    const canvas = document.createElement('canvas');
+    canvas.width = img.naturalWidth;
+    canvas.height = img.naturalHeight;
+    const ctx = canvas.getContext('2d');
+    ctx.drawImage(img, 0, 0);
+    const blockSize = 6;
+    const d = ctx.getImageData(
+      Math.round(point.x - blockSize / 2),
+      Math.round(point.y - blockSize / 2),
+      blockSize,
+      blockSize,
+    ).data;
+    let r = 0, g = 0, b = 0;
+    const n = d.length / 4;
+    for (let i = 0; i < d.length; i += 4) {
+      r += d[i]; g += d[i + 1]; b += d[i + 2];
+    }
+    return {r: r / n, g: g / n, b: b / n};
+  }, {screenshot, point: bgPoint});
+
+  const compositedBorder = compositeOver(info.border, bg);
+  return {ratio: contrastRatio(compositedBorder, bg), border: info.border, bg};
+}
+
 test.beforeEach(async ({page}) => {
   await page.setViewportSize({width: 1280, height: 900});
   await page.goto('/');
@@ -253,3 +328,16 @@ test('hero primary CTA clears WCAG AA contrast against its own button fill', asy
     interiorSampler(10),
   );
 });
+
+test('hero secondary CTA border clears WCAG 1.4.11 non-text contrast (#898 finding 14)', async ({page}) => {
+  const {ratio, border, bg} = await measureBorderContrast(page, '[data-testid="landing-hero-quickstart-cta"]');
+  expect(
+    ratio,
+    `secondary button border rgba(${border.r},${border.g},${border.b},${border.a}) composited over measured bg ` +
+      `rgb(${bg.r.toFixed(1)},${bg.g.toFixed(1)},${bg.b.toFixed(1)}) = ${ratio.toFixed(2)}:1, needs >= 3:1`,
+  ).toBeGreaterThanOrEqual(3);
+});
+
+test('hero trust links clear WCAG AA text contrast against their real composited background (#898 finding 14)', async ({page}) => {
+  await assertClearsContrast(page, '.heroTrustLinks a', '[class*="heroTrustLinks"] a', adjacentSampler);
+});
@@ -222,9 +222,12 @@ test('landing page keeps mobile motion and CTAs inside the viewport', async ({pa
             rect.right > parentRect.right + 1 ||
             rect.left < -1 ||
             rect.right > viewportWidth + 1,
+          // #898 finding 21: height: 3.45rem -> min-height must mean a
+          // wrapped two-line label no longer overflows its own button box.
+          overflowsVertically: link.scrollHeight > link.clientHeight + 1,
         };
       })
-      .filter((button) => button.overflows || button.width > button.parentWidth + 1);
+      .filter((button) => button.overflows || button.width > button.parentWidth + 1 || button.overflowsVertically);
   });
   expect(overflowingButtons).toEqual([]);
 
@@ -251,3 +254,55 @@ test('landing page keeps mobile motion and CTAs inside the viewport', async ({pa
     }));
   }).toEqual({opacity: '0', state: 'rolled-back'});
 });
+
+// Regression guard for #898 finding 21. The 761-900px band keeps the
+// 3-column-turned-2-column CTA grid active (single-column starts at 760px)
+// while each column is narrow enough to wrap a label like "Read quick
+// start" -- previously unguarded, since the mobile check above only runs at
+// 375px and only checked horizontal overflow.
+test('landing page CTA buttons do not overflow when their label wraps at 800px (#898 finding 21)', async ({page}) => {
+  await page.setViewportSize({width: 800, height: 900});
+  await page.goto('/');
+
+  const checkOverflow = async (testId) => page.evaluate((id) => {
+    return Array.from(document.querySelectorAll(`[data-testid="${id}"] .button`))
+      .map((button) => ({
+        text: button.textContent.trim().replace(/\s+/g, ' '),
+        overflowsVertically: button.scrollHeight > button.clientHeight + 1,
+      }))
+      .filter((button) => button.overflowsVertically);
+  }, testId);
+
+  expect(await checkOverflow('landing-hero-actions')).toEqual([]);
+  await page.getByTestId('landing-final').scrollIntoViewIfNeeded();
+  await expect.poll(() => page.getByTestId('landing-final').evaluate((el) => getComputedStyle(el).opacity)).toBe('1');
+  expect(await checkOverflow('landing-final')).toEqual([]);
+});
+
+// Regression guard for #898 finding 19. The 5-column path/loop/badge grids
+// previously collapsed straight from 5 columns to 1 at 980px, with no
+// intermediate step -- leaving ~150px-wide cards in the 981-1180px band.
+// A 1180px breakpoint now gives them a 2-column step first.
+for (const width of [1000, 1100, 1180]) {
+  test(`landing page path/loop grids use an intermediate column step at ${width}px (#898 finding 19)`, async ({page}) => {
+    await page.setViewportSize({width, height: 900});
+    await page.goto('/');
+
+    const countColumns = async (selector) => page.locator(selector).evaluate((el) => {
+      return getComputedStyle(el).gridTemplateColumns.trim().split(/\s+/).length;
+    });
+
+    const pathColumns = await countColumns('[data-testid="landing-pathfinder"] [aria-labelledby="guide-paths-heading"]');
+    const loopColumns = await countColumns('[data-testid="landing-evidence-loop"]');
+
+    expect(pathColumns).toBeGreaterThanOrEqual(2);
+    expect(pathColumns).toBeLessThan(5);
+    expect(loopColumns).toBeGreaterThanOrEqual(2);
+    expect(loopColumns).toBeLessThan(5);
+
+    const overflowsHorizontally = await page.evaluate(() => {
+      return document.documentElement.scrollWidth > document.documentElement.clientWidth + 1;
+    });
+    expect(overflowsHorizontally).toBe(false);
+  });
+}