From 9d8ff55e22f7275b885c9dd275031bfa6ede7bf0 Mon Sep 17 00:00:00 2001
From: Joseph Dale Banares <daleban.dev@gmail.com>
Date: Fri, 2 Oct 2026 17:12:26 +0800
Subject: [PATCH 1/2] docs(site): start the How it works rail unlit, in step
 with its first step

---
 site/components/landing/How.tsx | 12 +++++++-----
 site/e2e/smoke.spec.ts          |  2 ++
 2 files changed, 9 insertions(+), 5 deletions(-)

diff --git a/site/components/landing/How.tsx b/site/components/landing/How.tsx
index b27f441..e745a33 100644
--- a/site/components/landing/How.tsx
+++ b/site/components/landing/How.tsx
@@ -113,7 +113,10 @@ export function How({ demo, receipt, repair }: { demo: LaidOutDiagram; receipt:
       };
       layout();
       setPinned(true);
-      setStep(0);
+      const draw = (progress: number) => {
+        if (fill.current) fill.current.style.transform = `scaleX(${progress})`;
+        setStep(Math.min(3, Math.floor(progress * 4)));
+      };
       // CSS sticky does the pin; ScrollTrigger only reads how far through the runway the page is.
       const st = ScrollTrigger.create({
         trigger: p,
@@ -121,11 +124,10 @@ export function How({ demo, receipt, repair }: { demo: LaidOutDiagram; receipt:
         end: () => `+=${runway.current}`,
         invalidateOnRefresh: true,
         onRefreshInit: layout,
-        onUpdate: ({ progress }) => {
-          if (fill.current) fill.current.style.transform = `scaleX(${progress})`;
-          setStep(Math.min(3, Math.floor(progress * 4)));
-        },
+        onUpdate: ({ progress }) => draw(progress),
       });
+      // onUpdate waits for a scroll; until then the rail would keep its resting (full) fill.
+      draw(st.progress);
       return () => {
         st.kill();
         p.style.height = '';
diff --git a/site/e2e/smoke.spec.ts b/site/e2e/smoke.spec.ts
index f2105a9..2cf66a6 100644
--- a/site/e2e/smoke.spec.ts
+++ b/site/e2e/smoke.spec.ts
@@ -68,6 +68,8 @@ test('with motion allowed the walkthrough pins and the scroll picks its step', a
   await page.goto('/');
   const pin = page.locator('.how-pin');
   await expect(pin).toHaveAttribute('data-live', 'true');
+  // Before any scroll the rail is unlit, as step 1 is.
+  await expect.poll(() => page.locator('.hfill').evaluate((el) => getComputedStyle(el).transform)).toBe('matrix(0, 0, 0, 1, 0, 0)');
   const at = (f: number) =>
     page.evaluate((f) => {
       const p = document.querySelector<HTMLElement>('.how-pin')!;

From 543287519da02cf8fac8180cf3cbcbbb19d5e641 Mon Sep 17 00:00:00 2001
From: Joseph Dale Banares <daleban.dev@gmail.com>
Date: Fri, 2 Oct 2026 17:12:26 +0800
Subject: [PATCH 2/2] =?UTF-8?q?test(site):=20wait=20for=20the=20docs=20to?=
 =?UTF-8?q?=20hydrate=20before=20pressing=20=E2=8C=98K=20in=20the=20search?=
 =?UTF-8?q?=20test?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 site/e2e/smoke.spec.ts | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)

diff --git a/site/e2e/smoke.spec.ts b/site/e2e/smoke.spec.ts
index 2cf66a6..a7d4f6a 100644
--- a/site/e2e/smoke.spec.ts
+++ b/site/e2e/smoke.spec.ts
@@ -193,9 +193,12 @@ test('the old kind pages redirect into the docs', async ({ page }) => {
 
 test('the docs search opens with ⌘K, finds a field and goes to it', async ({ page }) => {
   await page.goto('/docs');
-  await page.keyboard.press('ControlOrMeta+k');
   const box = page.getByRole('combobox', { name: 'Search the docs' });
-  await expect(box).toBeFocused();
+  // The shortcut is bound once the page hydrates; a press before that lands nowhere.
+  await expect(async () => {
+    await page.keyboard.press('ControlOrMeta+k');
+    await expect(box).toBeFocused({ timeout: 500 });
+  }).toPass();
   await box.fill('statsNote');
   await expect(page.getByRole('option').first()).toContainText('statsNote');
   await page.keyboard.press('Enter');