From a3309d344e15106dc89c8487324448bd9b5a40d3 Mon Sep 17 00:00:00 2001
From: yigitdot <yigitgurbulak4@gmail.com>
Date: Mon, 25 May 2026 17:07:32 +0300
Subject: [PATCH 1/6] chore(theme): drop unreferenced --font-sans token
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The `--font-sans` entry in `@theme inline` was never read: `html, body`
applies `font-family: var(--font-geist-sans), …` directly, and no
component uses the `font-sans` utility class (verified by grep across
`.ts(x)` / `.mdx`). Removing it loses no behavior — the `font-sans`
utility falls back to Tailwind's default sans stack — and shrinks the
theme surface.

Closes #105

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 app/globals.css | 1 -
 1 file changed, 1 deletion(-)

diff --git a/app/globals.css b/app/globals.css
index 2597936..354d3b1 100644
--- a/app/globals.css
+++ b/app/globals.css
@@ -22,7 +22,6 @@
   --color-ink: var(--ink);
   --color-paper: var(--paper);
   --color-whisper: var(--whisper);
-  --font-sans: var(--font-geist-sans);
 
   /* Shared content rail: every Frame centers within --frame-max. */
   --frame-max: 1280px;

From 9b176938d3425ffc2da95621b6d9052f8385ffe4 Mon Sep 17 00:00:00 2001
From: yigitdot <yigitgurbulak4@gmail.com>
Date: Mon, 25 May 2026 17:08:16 +0300
Subject: [PATCH 2/6] refactor(theme): promote --frame-* tokens to Tailwind v4
 namespaces
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Finishes the migration left at the end of #78 / #101: the typography
half landed under the `--text-*` namespace (Approach A); the layout
half stayed as raw vars consumed via `px-[var(--frame-gutter)]` /
`max-w-[var(--frame-max)]` arbitrary-value classes (Approach B).

Renames so layout tokens auto-generate utilities:
- `--frame-gutter`    → `--spacing-frame-gutter` ⇒ `px-frame-gutter`
- `--frame-pad-y`     → `--spacing-frame-pad-y`  ⇒ `py-frame-pad-y`
- `--frame-max`       → `--container-frame`      ⇒ `max-w-frame`
- `--frame-min-h-cap` → `--spacing-frame-min-h: min(100svh, 54rem)`
  ⇒ `min-h-frame-min-h` (the `min()` was already at the lone call
  site; folding it into the token removes the last arbitrary value)

Frame.tsx, Footer.tsx, and Chrome.tsx's <nav> switch to the generated
utilities. The mobile-menu close button's raw CSS ref becomes
`right: var(--spacing-frame-gutter)`. The `--nav-h` comment block is
updated to match.

Closes #102

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 app/globals.css            | 22 +++++++++++-----------
 components/site/Chrome.tsx |  4 ++--
 components/site/Footer.tsx |  4 ++--
 components/ui/Frame.tsx    |  6 +++---
 4 files changed, 18 insertions(+), 18 deletions(-)

diff --git a/app/globals.css b/app/globals.css
index 354d3b1..85521b4 100644
--- a/app/globals.css
+++ b/app/globals.css
@@ -6,15 +6,15 @@
   --whisper: #0f9d6a;
   /* Intentionally 0: anchor jumps land flush at viewport top (under
      the fixed nav). Section headers don't get clipped because every
-     Frame's --frame-pad-y floor (5rem = 80px) sits comfortably above
-     the current fixed-nav height (py-5 + 30px wordmark ≈ 70px),
+     Frame's --spacing-frame-pad-y floor (5rem = 80px) sits comfortably
+     above the current fixed-nav height (py-5 + 30px wordmark ≈ 70px),
      leaving ~10px of breathing room below the nav. If the nav grows
      past 5rem, set --nav-h to the measured nav height — Frame already
      applies scroll-mt-[var(--nav-h)] on every section, so anchor
      offsets pick it up automatically. (Bumping the 5rem floor on
-     --frame-pad-y only helps below ~889px — above that the clamp's
-     9vw term already exceeds 5rem, so a bigger floor does nothing on
-     desktop.) */
+     --spacing-frame-pad-y only helps below ~889px — above that the
+     clamp's 9vw term already exceeds 5rem, so a bigger floor does
+     nothing on desktop.) */
   --nav-h: 0;
 }
 
@@ -23,15 +23,15 @@
   --color-paper: var(--paper);
   --color-whisper: var(--whisper);
 
-  /* Shared content rail: every Frame centers within --frame-max. */
-  --frame-max: 1280px;
-  --frame-gutter: clamp(1.5rem, 4vw, 4rem);
-  --frame-pad-y: clamp(
+  /* Shared content rail: every Frame centers within --container-frame. */
+  --container-frame: 1280px;
+  --spacing-frame-gutter: clamp(1.5rem, 4vw, 4rem);
+  --spacing-frame-pad-y: clamp(
     5rem,
     9vw,
     7rem
   ); /* floor coupled to nav height — see --nav-h note above */
-  --frame-min-h-cap: 54rem;
+  --spacing-frame-min-h: min(100svh, 54rem);
 
   /* Type scale: micro and CTA are fixed; body and headlines scale with viewport.
      Named under Tailwind v4's --text-* namespace so `text-body`, `text-h1`, …
@@ -1008,7 +1008,7 @@ a.underline-brutal:hover .arrow {
 .mm-toggle {
   position: fixed;
   top: 24px;
-  right: var(--frame-gutter);
+  right: var(--spacing-frame-gutter);
   z-index: 65;
   width: 22px;
   height: 22px;
diff --git a/components/site/Chrome.tsx b/components/site/Chrome.tsx
index 0117ed5..6bfa6ce 100644
--- a/components/site/Chrome.tsx
+++ b/components/site/Chrome.tsx
@@ -188,11 +188,11 @@ export function Chrome() {
       data-scrolled={scrolled ? "true" : undefined}
       data-tone={onDark ? "ink" : "paper"}
       data-mobile-open={mobileOpen ? "true" : undefined}
-      className={`chrome-nav fixed inset-x-0 top-0 z-50 px-[var(--frame-gutter)] py-5 ${
+      className={`chrome-nav fixed inset-x-0 top-0 z-50 px-frame-gutter py-5 ${
         onDark ? "text-paper" : "text-ink"
       }`}
     >
-      <div className="mx-auto grid w-full max-w-[var(--frame-max)] grid-cols-[1fr_auto_1fr] items-center gap-4">
+      <div className="mx-auto grid w-full max-w-frame grid-cols-[1fr_auto_1fr] items-center gap-4">
         <Link
           href="/#intro"
           onClick={handleNavClick}
diff --git a/components/site/Footer.tsx b/components/site/Footer.tsx
index a8d366d..75ae98e 100644
--- a/components/site/Footer.tsx
+++ b/components/site/Footer.tsx
@@ -2,8 +2,8 @@ import { links } from "@/lib/links";
 
 export function Footer() {
   return (
-    <footer className="bg-paper px-[var(--frame-gutter)] pb-10 text-ink">
-      <div className="@container mx-auto flex max-w-[var(--frame-max)] flex-col gap-3">
+    <footer className="bg-paper px-frame-gutter pb-10 text-ink">
+      <div className="@container mx-auto flex max-w-frame flex-col gap-3">
         <span aria-hidden className="rule opacity-40" />
         <div className="grid grid-cols-1 gap-2 text-micro tracking-[0.2em] uppercase opacity-80 @md:grid-cols-3 @md:items-center">
           <span>© decdn labs · open source</span>
diff --git a/components/ui/Frame.tsx b/components/ui/Frame.tsx
index b1b6a06..02f1545 100644
--- a/components/ui/Frame.tsx
+++ b/components/ui/Frame.tsx
@@ -29,8 +29,8 @@ export function Frame({
   children,
 }: FrameProps) {
   const sectionClass = [
-    "relative flex flex-col scroll-mt-[var(--nav-h)] px-[var(--frame-gutter)] py-[var(--frame-pad-y)]",
-    fill && "min-h-[min(100svh,var(--frame-min-h-cap))]",
+    "relative flex flex-col scroll-mt-[var(--nav-h)] px-frame-gutter py-frame-pad-y",
+    fill && "min-h-frame-min-h",
     TONE_CLASS[tone],
     className,
   ]
@@ -38,7 +38,7 @@ export function Frame({
     .join(" ");
   return (
     <section id={id} aria-labelledby={`${id}-h`} className={sectionClass}>
-      <div className="@container relative z-10 mx-auto flex w-full max-w-[var(--frame-max)] flex-1 flex-col">
+      <div className="@container relative z-10 mx-auto flex w-full max-w-frame flex-1 flex-col">
         {children}
       </div>
     </section>

From 39ac7c863e3bcc4bb023057ba49f7f65058a0a54 Mon Sep 17 00:00:00 2001
From: yigitdot <yigitgurbulak4@gmail.com>
Date: Mon, 25 May 2026 17:08:42 +0300
Subject: [PATCH 3/6] refactor(chrome): extract resolveActiveSection helper +
 unit tests
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The home-route-gated nav-tone ternary in `Chrome.tsx` (the #112 fix
plus the back-nav flash guard) was load-bearing but uncovered. Pulling
it into a pure helper lets it be unit-tested without dragging in
jsdom / RTL / IntersectionObserver mocks — the function takes
`(pathname, scrolled, observed, fallback)` and is independent of any
runtime.

Adds five cases from the issue, including the two regressions the
original fix exists to prevent: off-home stale `active` (the #112 bug)
and back-nav pre-scroll flash. `vitest.config.ts`'s existing
`**/*.test.ts` include glob picks the new file up unchanged.

Closes #117

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 components/site/Chrome.tsx            |  8 ++++-
 components/site/chrome-active.test.ts | 46 +++++++++++++++++++++++++++
 components/site/chrome-active.ts      |  8 +++++
 3 files changed, 61 insertions(+), 1 deletion(-)
 create mode 100644 components/site/chrome-active.test.ts
 create mode 100644 components/site/chrome-active.ts

diff --git a/components/site/Chrome.tsx b/components/site/Chrome.tsx
index 6bfa6ce..afc3f3f 100644
--- a/components/site/Chrome.tsx
+++ b/components/site/Chrome.tsx
@@ -6,6 +6,7 @@ import { usePathname } from "next/navigation";
 import { links } from "@/lib/links";
 import { homeHashSectionId, shouldInterceptNavClick } from "@/lib/scroll";
 import { MobileMenu } from "@/components/site/MobileMenu";
+import { resolveActiveSection } from "@/components/site/chrome-active";
 
 const SECTION_IDS = ["intro", "compare", "method", "faq", "contact"] as const;
 // Hash anchors are written `/#section`. Required because this nav also
@@ -174,7 +175,12 @@ export function Chrome() {
   // and on the first render after a client nav `active` still holds the
   // previous route's last value until the [pathname] effects re-sync.
   // `scrolled` doubles as a proxy for "past the intro hero".
-  const effectiveActive = pathname === "/" && scrolled ? active : "intro";
+  const effectiveActive = resolveActiveSection(
+    pathname,
+    scrolled,
+    active,
+    "intro",
+  );
   const onDark = DARK_SECTIONS.has(effectiveActive);
   // The toggle is portalled to <body> (see MobileMenu.tsx) and lives
   // on top of the paper panel while the drawer is open — force it to
diff --git a/components/site/chrome-active.test.ts b/components/site/chrome-active.test.ts
new file mode 100644
index 0000000..53a4775
--- /dev/null
+++ b/components/site/chrome-active.test.ts
@@ -0,0 +1,46 @@
+import { describe, expect, it } from "vitest";
+import { resolveActiveSection } from "./chrome-active";
+
+describe("resolveActiveSection", () => {
+  it.each([
+    {
+      name: "off-home + scrolled falls back (the #112 bug)",
+      pathname: "/blog/foo/",
+      scrolled: true,
+      observed: "compare",
+      expected: "intro",
+    },
+    {
+      name: "home but not yet scrolled falls back (back-nav flash guard)",
+      pathname: "/",
+      scrolled: false,
+      observed: "compare",
+      expected: "intro",
+    },
+    {
+      name: "home + scrolled returns the observed dark section",
+      pathname: "/",
+      scrolled: true,
+      observed: "compare",
+      expected: "compare",
+    },
+    {
+      name: "home + scrolled passes other DARK_SECTIONS members through",
+      pathname: "/",
+      scrolled: true,
+      observed: "faq",
+      expected: "faq",
+    },
+    {
+      name: "off-home dominates regardless of scrolled state",
+      pathname: "/blog/",
+      scrolled: false,
+      observed: "faq",
+      expected: "intro",
+    },
+  ] as const)("$name", ({ pathname, scrolled, observed, expected }) => {
+    expect(resolveActiveSection(pathname, scrolled, observed, "intro")).toBe(
+      expected,
+    );
+  });
+});
diff --git a/components/site/chrome-active.ts b/components/site/chrome-active.ts
new file mode 100644
index 0000000..68fe96f
--- /dev/null
+++ b/components/site/chrome-active.ts
@@ -0,0 +1,8 @@
+export function resolveActiveSection<T>(
+  pathname: string,
+  scrolled: boolean,
+  observed: T,
+  fallback: T,
+): T {
+  return pathname === "/" && scrolled ? observed : fallback;
+}

From 4b08b391b61d14befd11fdfa0c9310d3a525e534 Mon Sep 17 00:00:00 2001
From: yigitdot <yigitgurbulak4@gmail.com>
Date: Mon, 25 May 2026 19:48:21 +0300
Subject: [PATCH 4/6] chore(chrome): drop #112 back-reference from test name
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The "(the #112 bug)" parenthetical belongs in PR / commit history,
not in a long-lived test name where it rots once the issue is
forgotten. The behavior the test guards (off-home + scrolled →
fall back) is already self-describing.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 components/site/chrome-active.test.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/components/site/chrome-active.test.ts b/components/site/chrome-active.test.ts
index 53a4775..e137a0e 100644
--- a/components/site/chrome-active.test.ts
+++ b/components/site/chrome-active.test.ts
@@ -4,7 +4,7 @@ import { resolveActiveSection } from "./chrome-active";
 describe("resolveActiveSection", () => {
   it.each([
     {
-      name: "off-home + scrolled falls back (the #112 bug)",
+      name: "off-home + scrolled falls back",
       pathname: "/blog/foo/",
       scrolled: true,
       observed: "compare",

From 0730f827e97c21947d5eb8cb0e9d8c7f887f8dd8 Mon Sep 17 00:00:00 2001
From: yigitdot <yigitgurbulak4@gmail.com>
Date: Mon, 25 May 2026 22:17:43 +0300
Subject: [PATCH 5/6] refactor(chrome): tighten resolveActiveSection types +
 add exact-match test

Addresses review feedback on the helper introduced in 39ac7c8:

- Constrain `<T extends string>` so unrelated types can't unify
  silently (`resolveActiveSection(p, s, 42, "intro")` stops
  compiling). Preserves the literal-union inference at the call site.
- Move the multi-line guard rationale from above the call site in
  Chrome.tsx to above the function in chrome-active.ts, where the
  `pathname === "/" && scrolled` logic actually lives. The original
  framing leaked Chrome.tsx-specific vocabulary (`DARK_SECTIONS`,
  `text-paper`); tightened to describe the helper's own contract.
- Add a 6th vitest case asserting the helper is exact-match
  (`/?utm=x` falls back), defending against a future caller that
  swaps usePathname() for something query-/hash-including.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 components/site/Chrome.tsx            | 5 -----
 components/site/chrome-active.test.ts | 7 +++++++
 components/site/chrome-active.ts      | 8 +++++++-
 3 files changed, 14 insertions(+), 6 deletions(-)

diff --git a/components/site/Chrome.tsx b/components/site/Chrome.tsx
index afc3f3f..7700361 100644
--- a/components/site/Chrome.tsx
+++ b/components/site/Chrome.tsx
@@ -170,11 +170,6 @@ export function Chrome() {
     return () => window.removeEventListener("scroll", onScroll);
   }, [pathname]);
 
-  // Guard against a stale `active` landing in `DARK_SECTIONS` and painting
-  // `text-paper` over a paper-toned page: off-home the IO observes nothing,
-  // and on the first render after a client nav `active` still holds the
-  // previous route's last value until the [pathname] effects re-sync.
-  // `scrolled` doubles as a proxy for "past the intro hero".
   const effectiveActive = resolveActiveSection(
     pathname,
     scrolled,
diff --git a/components/site/chrome-active.test.ts b/components/site/chrome-active.test.ts
index e137a0e..5958435 100644
--- a/components/site/chrome-active.test.ts
+++ b/components/site/chrome-active.test.ts
@@ -38,6 +38,13 @@ describe("resolveActiveSection", () => {
       observed: "faq",
       expected: "intro",
     },
+    {
+      name: "home with query string falls back (exact match)",
+      pathname: "/?utm=x",
+      scrolled: true,
+      observed: "compare",
+      expected: "intro",
+    },
   ] as const)("$name", ({ pathname, scrolled, observed, expected }) => {
     expect(resolveActiveSection(pathname, scrolled, observed, "intro")).toBe(
       expected,
diff --git a/components/site/chrome-active.ts b/components/site/chrome-active.ts
index 68fe96f..65bd59f 100644
--- a/components/site/chrome-active.ts
+++ b/components/site/chrome-active.ts
@@ -1,4 +1,10 @@
-export function resolveActiveSection<T>(
+// Why both `pathname === "/"` and `scrolled` must hold for `observed` to win:
+// - Off-home, the caller's section observer holds stale values from the
+//   previous home-route render — off-home reads must dominate.
+// - On home, `scrolled` doubles as a "past the intro hero" proxy that
+//   suppresses the brief window after a client-side back-nav resets scroll
+//   to top while the observer's last value is still in flight.
+export function resolveActiveSection<T extends string>(
   pathname: string,
   scrolled: boolean,
   observed: T,

From 86293ff33fda1a7571525d18d5ef75e1646e04fd Mon Sep 17 00:00:00 2001
From: yigitdot <yigitgurbulak4@gmail.com>
Date: Mon, 25 May 2026 22:40:37 +0300
Subject: [PATCH 6/6] refactor(chrome): drop T extends string + correct guard
 rationale
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Walks back two refinements from 0730f82:

- The constraint blocked no real misuse — the sole call site already
  infers T to a literal-string union from the caller's typing.
- The rehomed comment said the off-home observer "holds stale values"
  but the observer is never built off-home (Chrome.tsx's IO useEffect
  early-returns when no section nodes exist). It also kept the inherited
  "past the intro hero" framing for `scrolled`, which is misleading —
  scrolled flips at scrollY > 8, well inside intro. Rewritten as the
  "new observer has had a moment to fire" heuristic it actually is,
  with the back-nav restored-scroll caveat noted.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 components/site/chrome-active.ts | 15 ++++++++-------
 1 file changed, 8 insertions(+), 7 deletions(-)

diff --git a/components/site/chrome-active.ts b/components/site/chrome-active.ts
index 65bd59f..1a6b0b5 100644
--- a/components/site/chrome-active.ts
+++ b/components/site/chrome-active.ts
@@ -1,10 +1,11 @@
-// Why both `pathname === "/"` and `scrolled` must hold for `observed` to win:
-// - Off-home, the caller's section observer holds stale values from the
-//   previous home-route render — off-home reads must dominate.
-// - On home, `scrolled` doubles as a "past the intro hero" proxy that
-//   suppresses the brief window after a client-side back-nav resets scroll
-//   to top while the observer's last value is still in flight.
-export function resolveActiveSection<T extends string>(
+// Both `pathname === "/"` and `scrolled` must hold for `observed` to win.
+// Off-home, the caller's observer never gets built but `active` still
+// holds its last home-route value — the home check stops that stale value
+// painting. On home, `active` is briefly stale between the route-change
+// render and the new observer's first callback; `scrolled` (scrollY > 8)
+// stands in for "observer has had a moment to fire". Caveat: back-nav
+// with restored scroll skips this — a brief stale-tone flash is possible.
+export function resolveActiveSection<T>(
   pathname: string,
   scrolled: boolean,
   observed: T,