@decocms/start 2.26.0 → 2.27.0

package/MIGRATION_TOOLING_PLAN.md

@@ -1528,3 +1528,64 @@ What's still ahead:
 - **C8 (state persistence between migration phases)**: moderate effort, value mostly in skipping `npm install` on phase-9 retries. Polish.
 - **`vibe-dex/*` orphan branches in apps-start**: ✅ all 5 cleaned this wave.
 - **Apps registry (apps-start#18 + deco-start#81)**: defer until clear consumer.
+
+### Wave 16 (2026-05-02 — baggagio as production canary, stacked-PR pitfall RECURRENCE)
+
+User merged baggagio's PRs B1–B6 to use as guinea pig before applying the same patterns to casaevideo + lebiscuit (which ARE in production). Live validation found a critical fact: **only B1 (the bump) actually reached `main`**. PRs #13–#17 were all merged in GitHub UI but their merge commits ended up on the **previous PR's branch**, never on `main`.
+
+#### What happened (the same pitfall as Wave 8, recurring)
+
+Each PR was opened with `base = previous PR's branch`:
+
+| PR | Title | base | Merge commit landed on |
+|---|---|---|---|
+| #12 | bump 2.10→2.26 + apps 1.7→1.9 | `main` | ✅ `main` |
+| #13 | drop `src/sdk/clx.ts` | `chore/bump-deco-2.26-apps-1.9` | ❌ that branch |
+| #14 | createUseSuggestions factory | `chore/drop-local-clx` | ❌ that branch |
+| #15 | canonical `relative()` | `chore/use-framework-suggestions-factory` | ❌ that branch |
+| #16 | canonical `Picture` | `refactor/use-canonical-relative-url` | ❌ that branch |
+| #17 | drop dead `useUser` stub | `refactor/use-canonical-picture` | ❌ that branch |
+
+Each PR shows `state: MERGED` in GitHub. But the merge commit physically landed on each PR's source-branch tip, not on main. Result: all 5 cleanup PRs were silently orphaned.
+
+Detection method that worked: file-existence check on `git show main:<deleted-file>` — `clx.ts`, `url.ts`, `Picture.tsx`, `useUser.ts` were all still present on main despite their PRs being "merged". Exists/absent is a faster signal than diff browsing.
+
+#### Recovery: PR #18 — single consolidation
+
+The deepest stacked branch (`chore/drop-dead-local-useuser`) cumulatively contained all 5 cleanups (B2–B6) linearly stacked on B1. Opened [`baggagio-tanstack#18`](https://github.com/deco-sites/baggagio-tanstack/pull/18) as `chore/consolidate-b2-b6-to-main` → `main`, replaying the exact contents of #13–#17 in order. Diff vs main: **59 files changed, +70 / −240, 4 files deleted**. Typecheck + build clean. Preview at `pr-18-baggagio-tanstack.deco-cx.workers.dev` rendered identical homepage / PLP / PDP / search to current main with zero new console errors. Merged to main, deploy succeeded.
+
+#### Live validation post-merge (cumulative state on main)
+
+Tested via Playwright (cursor-ide-browser MCP) on `https://baggagio-tanstack.deco-cx.workers.dev/`:
+
+| Surface | Result | Notes |
+|---|---|---|
+| Homepage | ✅ Renders | Banner, categories, product carousel, footer all intact |
+| PLP `/s?q=mochila` | ✅ 927 produtos | Filter + sort UI present, all images load |
+| PDP `/mochila-masculina-executiva-para-notebook-horizonte/p` | ✅ Renders | Image gallery, prices, COMPRAR, frete calc, descrição all present |
+| Search suggestions endpoint | ✅ 200 | Empty `searches[]` confirmed pre-existing (matches www.bagaggio.com.br) |
+| `<picture>` HTML | ✅ 18 picture / 36 source | composable canonical pattern |
+| Console errors (filtered 3rd-party) | ✅ Same as before | `[inline-script polyfill]` + image preload warnings pre-existing on main |
+
+**Bonus discovery**: PR-B5 (canonical Picture) now correctly emits `<link rel="preload" as="image" media="(max-width: 767px)" imageSrcSet="..." fetchPriority="high">` for LCP banners — a real Web Vitals improvement that was NOT visible before the consolidation because Picture.tsx (the local wrapper without preload) was still on main.
+
+#### Each PR's safety verdict (for casaevideo + lebiscuit replay)
+
+| PR | Status | Safe to replay? |
+|---|---|---|
+| B1 — bump 2.x → 2.26 + apps 1.x → 1.9 | ✅ | YES — zero regressions on real site |
+| B2 — drop `src/sdk/clx.ts` | ✅ | YES — pure rewrite, framework export is byte-equivalent |
+| B3 — `createUseSuggestions` factory | ✅ | YES — wiring works end-to-end (200 status, payload reaches store) |
+| B4 — canonical `relative()` with `stripSearchParams` | ✅ | YES — only affects PLPs with `?skuId=` URL params, no functional regression |
+| B5 — canonical `Picture` from apps | ✅ + bonus | YES — adds proper `<link rel="preload" as="image" media>` for LCP |
+| B6 — drop dead `src/hooks/useUser.ts` | ✅ | YES — file had 0 external imports |
+
+**For casaevideo + lebiscuit**: same set of PRs is validated as safe. The replays (`C1`–`C11`, `L1`–`L11`) can proceed on production sites with confidence.
+
+### Wave 16 — discoveries
+
+- **Stacked-PR pitfall recurred even after Wave 8 documented it.** The Wave 8 mitigation ("verify base is main before merging") was not enforced; the user merged B2–B6 with original stacked bases. Stronger mitigation needed: when opening a stacked PR, **default to a single consolidating PR at the end** rather than 5 separate stacked merges. Single PR is one merge button, one CI run, one deploy — not 5 chances to mis-target the base.
+- **File-existence check is the fastest "did the merge actually land on main?" probe.** Faster than reading PR-stats, faster than diffing branches. `git show main:<deleted-file> 2>&1` — empty stderr means the deletion didn't reach main.
+- **Preview deploys via `wrangler versions upload --preview-alias` are cheap, fast (90 s), and PR-scoped.** Used `https://pr-N-baggagio-tanstack.deco-cx.workers.dev` to validate cumulative state BEFORE merging. Should be the default validation step for any consolidation PR.
+- **The canonical Picture component's per-source `<link rel="preload" as="image" media="...">` injection is a real LCP win** — but it only triggers when `<Picture preload={true}>` is set on the call site. Baggagio's `BannerCarousel.tsx` already passes `preload={lcp}` from the CMS config; the local Picture.tsx wrapper just didn't honor it. Migration to canonical IS a perf upgrade, not just a code-cleanup.
+- **Canary-driven validation matters even when the changes are mechanical.** I had high confidence the cumulative state would work (typecheck + build clean), but the live test is what surfaced the "PR-B5 actually emits preload links now" finding. Without the canary loop the perf delta would have been invisible.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/start",
-  "version": "2.26.0",
+  "version": "2.27.0",
   "type": "module",
   "description": "Deco framework for TanStack Start - CMS bridge, admin protocol, hooks, schema generation",
   "main": "./src/index.ts",
@@ -19,6 +19,9 @@
     "./sdk/useScript": "./src/sdk/useScript.ts",
     "./sdk/signal": "./src/sdk/signal.ts",
     "./sdk/clx": "./src/sdk/clx.ts",
+    "./sdk/cn": "./src/sdk/cn.ts",
+    "./sdk/encoding": "./src/sdk/encoding.ts",
+    "./sdk/http": "./src/sdk/http.ts",
     "./sdk/useSuggestions": "./src/sdk/useSuggestions.ts",
     "./sdk/retry": "./src/sdk/retry.ts",
     "./sdk/useId": "./src/sdk/useId.ts",
@@ -96,7 +99,9 @@
   },
   "dependencies": {
     "@deco-cx/warp-node": "^0.3.16",
+    "clsx": "^2.1.1",
     "fast-json-patch": "^3.1.0",
+    "tailwind-merge": "^3.3.1",
     "tsx": "^4.19.0",
     "ws": "^8.18.0"
   },

package/src/sdk/cn.test.ts

@@ -0,0 +1,34 @@
+import { describe, expect, it } from "vitest";
+import { clx, cn } from "./cn";
+
+describe("cn", () => {
+  it("joins strings", () => {
+    expect(cn("a", "b", "c")).toBe("a b c");
+  });
+
+  it("supports conditional objects", () => {
+    expect(cn("a", { b: true, c: false }, "d")).toBe("a b d");
+  });
+
+  it("filters out falsy values", () => {
+    expect(cn("a", null, undefined, false, 0 as any, "b")).toBe("a b");
+  });
+
+  it("merges conflicting Tailwind utilities (last one wins)", () => {
+    expect(cn("p-2", "p-4")).toBe("p-4");
+  });
+
+  it("merges hover variants independently from base utilities", () => {
+    expect(cn("p-2", "hover:p-4")).toBe("p-2 hover:p-4");
+  });
+});
+
+describe("clx (re-exported)", () => {
+  it("filters falsy and joins with single spaces", () => {
+    expect(clx("a", null, "b", undefined, "c")).toBe("a b c");
+  });
+
+  it("does NOT merge conflicting utilities (that's cn's job)", () => {
+    expect(clx("p-2", "p-4")).toBe("p-2 p-4");
+  });
+});

package/src/sdk/cn.ts

@@ -0,0 +1,28 @@
+/**
+ * `cn(...inputs)` — the canonical Tailwind class-name combinator
+ * (clsx + tailwind-merge). Every storefront we audited shipped a
+ * site-local copy of this; we promote it to the framework so sites
+ * can drop the duplicate.
+ *
+ * Behaviour:
+ *   - Accepts the full `clsx` input format (strings, objects, arrays,
+ *     conditionals, falsy values).
+ *   - De-duplicates conflicting Tailwind utilities via `tailwind-merge`
+ *     (e.g. `cn("p-2", "p-4")` → `"p-4"`).
+ *
+ * The simpler `clx` (no tailwind-merge, just `filter+join`) is still
+ * exported from `@decocms/start/sdk/clx` for cases where you want to
+ * keep the literal class string. Re-exported here so a single import
+ * covers both.
+ */
+
+import { clsx, type ClassValue } from "clsx";
+import { twMerge } from "tailwind-merge";
+
+export { clx } from "./clx";
+
+export function cn(...inputs: ClassValue[]): string {
+  return twMerge(clsx(inputs));
+}
+
+export type { ClassValue };

package/src/sdk/cookie.test.ts

@@ -0,0 +1,108 @@
+import { describe, expect, it } from "vitest";
+import {
+  deleteResponseCookie,
+  getCookies,
+  setResponseCookie,
+} from "./cookie";
+
+describe("getCookies", () => {
+  it("returns an empty object when no Cookie header is present", () => {
+    expect(getCookies(new Headers())).toEqual({});
+  });
+
+  it("parses a single cookie", () => {
+    const h = new Headers({ cookie: "session=abc" });
+    expect(getCookies(h)).toEqual({ session: "abc" });
+  });
+
+  it("parses multiple cookies separated by '; '", () => {
+    const h = new Headers({ cookie: "a=1; b=2; c=3" });
+    expect(getCookies(h)).toEqual({ a: "1", b: "2", c: "3" });
+  });
+
+  it("URL-decodes values", () => {
+    const h = new Headers({ cookie: "u=hello%20world" });
+    expect(getCookies(h)).toEqual({ u: "hello world" });
+  });
+
+  it("falls back to the raw value when decoding fails", () => {
+    // Lone '%' is invalid in URL encoding.
+    const h = new Headers({ cookie: "x=100%" });
+    expect(getCookies(h)).toEqual({ x: "100%" });
+  });
+
+  it("ignores entries without an '='", () => {
+    const h = new Headers({ cookie: "garbage; ok=yes" });
+    expect(getCookies(h)).toEqual({ ok: "yes" });
+  });
+
+  it("trims whitespace around names", () => {
+    const h = new Headers({ cookie: " a=1; b=2 " });
+    expect(getCookies(h)).toEqual({ a: "1", b: "2" });
+  });
+});
+
+describe("setResponseCookie", () => {
+  it("appends a Set-Cookie header with the cookie name and value", () => {
+    const h = new Headers();
+    setResponseCookie(h, { name: "session", value: "abc" });
+    expect(h.get("set-cookie")).toBe("session=abc");
+  });
+
+  it("serializes maxAge, path, secure, httpOnly, sameSite, domain", () => {
+    const h = new Headers();
+    setResponseCookie(h, {
+      name: "session",
+      value: "abc",
+      maxAge: 3600,
+      path: "/",
+      domain: "example.com",
+      secure: true,
+      httpOnly: true,
+      sameSite: "Lax",
+    });
+    const value = h.get("set-cookie")!;
+    expect(value).toContain("session=abc");
+    expect(value).toContain("Max-Age=3600");
+    expect(value).toContain("Domain=example.com");
+    expect(value).toContain("Path=/");
+    expect(value).toContain("Secure");
+    expect(value).toContain("HttpOnly");
+    expect(value).toContain("SameSite=Lax");
+  });
+
+  it("serializes expires as a UTC string", () => {
+    const h = new Headers();
+    const date = new Date("2030-01-01T00:00:00Z");
+    setResponseCookie(h, { name: "x", value: "y", expires: date });
+    expect(h.get("set-cookie")).toContain(`Expires=${date.toUTCString()}`);
+  });
+
+  it("appends multiple cookies (does not overwrite the first)", () => {
+    const h = new Headers();
+    setResponseCookie(h, { name: "a", value: "1" });
+    setResponseCookie(h, { name: "b", value: "2" });
+    // Headers.getAll isn't standard; getSetCookie() is the modern API.
+    const all = (h as any).getSetCookie?.() as string[] | undefined;
+    if (all) {
+      expect(all).toEqual(["a=1", "b=2"]);
+    } else {
+      // Fallback: the combined header value should mention both.
+      const v = h.get("set-cookie")!;
+      expect(v).toContain("a=1");
+      expect(v).toContain("b=2");
+    }
+  });
+});
+
+describe("deleteResponseCookie", () => {
+  it("emits a Set-Cookie that expires immediately", () => {
+    const h = new Headers();
+    deleteResponseCookie(h, "session", { path: "/" });
+    const value = h.get("set-cookie")!;
+    expect(value).toContain("session=");
+    expect(value).toContain("Max-Age=0");
+    expect(value).toContain(`Expires=${new Date(0).toUTCString()}`);
+    expect(value).toContain("Path=/");
+  });
+});

package/src/sdk/cookie.ts

@@ -37,3 +37,93 @@ export function decodeCookie(cookieValue: string): any {
     return null;
   }
 }
+
+// ---------------------------------------------------------------------------
+// Server-side cookie helpers — Web-platform / Workers-friendly.
+//
+// These mirror the surface area of Deno's `@std/http/cookie`, which deco
+// storefronts depended on heavily before TanStack/Workers migration. Sites
+// can now import from "@decocms/start/sdk/cookie" instead of shipping a
+// per-site shim or pulling JSR.
+// ---------------------------------------------------------------------------
+
+export interface Cookie {
+  name: string;
+  value: string;
+  expires?: Date | number;
+  maxAge?: number;
+  domain?: string;
+  path?: string;
+  secure?: boolean;
+  httpOnly?: boolean;
+  sameSite?: "Strict" | "Lax" | "None";
+}
+
+/**
+ * Parse all cookies from a Request's `Cookie` header into a plain object.
+ * Returns `{}` when no cookies are present. Values are URL-decoded.
+ *
+ * Equivalent to `getCookies(req.headers)` from `@std/http/cookie`.
+ */
+export function getCookies(headers: Headers): Record<string, string> {
+  const cookie = headers.get("cookie");
+  if (!cookie) return {};
+  const out: Record<string, string> = {};
+  for (const pair of cookie.split(/;\s*/)) {
+    const eq = pair.indexOf("=");
+    if (eq === -1) continue;
+    const name = pair.slice(0, eq).trim();
+    if (!name) continue;
+    const value = pair.slice(eq + 1).trim();
+    try {
+      out[name] = decodeURIComponent(value);
+    } catch {
+      out[name] = value;
+    }
+  }
+  return out;
+}
+
+/**
+ * Serialize a cookie spec and append a `Set-Cookie` header to a Response's
+ * `Headers`. Equivalent to `setCookie(headers, cookie)` from `@std/http/cookie`.
+ *
+ * Note: this uses `headers.append`, not `set`, so multiple cookies stack
+ * correctly (a single `Set-Cookie` header cannot represent multiple cookies).
+ */
+export function setResponseCookie(headers: Headers, cookie: Cookie): void {
+  const parts = [`${cookie.name}=${cookie.value}`];
+  if (cookie.expires !== undefined) {
+    const date = cookie.expires instanceof Date
+      ? cookie.expires
+      : new Date(cookie.expires);
+    parts.push(`Expires=${date.toUTCString()}`);
+  }
+  if (cookie.maxAge !== undefined) parts.push(`Max-Age=${cookie.maxAge}`);
+  if (cookie.domain) parts.push(`Domain=${cookie.domain}`);
+  if (cookie.path) parts.push(`Path=${cookie.path}`);
+  if (cookie.secure) parts.push("Secure");
+  if (cookie.httpOnly) parts.push("HttpOnly");
+  if (cookie.sameSite) parts.push(`SameSite=${cookie.sameSite}`);
+  headers.append("Set-Cookie", parts.join("; "));
+}
+
+/**
+ * Append a delete instruction (`Max-Age=0` + epoch `Expires`) for a cookie.
+ * `path` and `domain` should match the original `setResponseCookie` call to
+ * actually clear the cookie in the browser.
+ */
+export function deleteResponseCookie(
+  headers: Headers,
+  name: string,
+  attributes: { path?: string; domain?: string } = {},
+): void {
+  setResponseCookie(headers, {
+    name,
+    value: "",
+    expires: new Date(0),
+    maxAge: 0,
+    path: attributes.path,
+    domain: attributes.domain,
+  });
+}

package/src/sdk/encoding.test.ts

@@ -0,0 +1,71 @@
+import { describe, expect, it } from "vitest";
+import {
+  decodeBase64,
+  decodeBase64Url,
+  encodeBase64,
+  encodeBase64Url,
+} from "./encoding";
+
+describe("encodeBase64 / decodeBase64", () => {
+  it("round-trips ASCII strings", () => {
+    const data = "hello, world";
+    const b64 = encodeBase64(data);
+    expect(b64).toBe("aGVsbG8sIHdvcmxk");
+    const decoded = new TextDecoder().decode(decodeBase64(b64));
+    expect(decoded).toBe(data);
+  });
+
+  it("round-trips multi-byte UTF-8", () => {
+    const data = "São Paulo — café ☕";
+    const b64 = encodeBase64(data);
+    const decoded = new TextDecoder().decode(decodeBase64(b64));
+    expect(decoded).toBe(data);
+  });
+
+  it("accepts Uint8Array input", () => {
+    const bytes = new Uint8Array([1, 2, 3, 4, 5]);
+    const b64 = encodeBase64(bytes);
+    expect(decodeBase64(b64)).toEqual(bytes);
+  });
+
+  it("accepts ArrayBuffer input", () => {
+    const buf = new Uint8Array([255, 254, 253]).buffer;
+    const b64 = encodeBase64(buf);
+    expect(Array.from(decodeBase64(b64))).toEqual([255, 254, 253]);
+  });
+
+  it("handles inputs larger than the chunking window", () => {
+    // 0x8000 + 7 bytes — forces the chunking branch.
+    const bytes = new Uint8Array(0x8000 + 7);
+    for (let i = 0; i < bytes.length; i++) bytes[i] = i & 0xff;
+    const b64 = encodeBase64(bytes);
+    expect(decodeBase64(b64)).toEqual(bytes);
+  });
+});
+
+describe("encodeBase64Url / decodeBase64Url", () => {
+  it("uses URL-safe alphabet and strips padding", () => {
+    // Inputs that produce '+', '/', and padding under standard base64.
+    const bytes = new Uint8Array([251, 255, 191, 251, 239, 254]);
+    const standard = encodeBase64(bytes);
+    const url = encodeBase64Url(bytes);
+    // Every '+' becomes '-', '/' becomes '_', trailing '=' is stripped.
+    expect(url).toBe(
+      standard.replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, ""),
+    );
+    expect(url).not.toContain("+");
+    expect(url).not.toContain("/");
+    expect(url).not.toContain("=");
+  });
+
+  it("round-trips through the URL-safe pair", () => {
+    const data = new Uint8Array(64);
+    for (let i = 0; i < data.length; i++) data[i] = (i * 7) & 0xff;
+    expect(decodeBase64Url(encodeBase64Url(data))).toEqual(data);
+  });
+
+  it("decodes inputs missing their padding", () => {
+    // 'a' = 0x61. encodeBase64('a') = 'YQ==', URL form drops to 'YQ'.
+    expect(new TextDecoder().decode(decodeBase64Url("YQ"))).toBe("a");
+  });
+});

package/src/sdk/encoding.ts

@@ -0,0 +1,47 @@
+/**
+ * Web-platform base64 / base64url helpers.
+ *
+ * Replaces the surface area of Deno's `@std/encoding/base64` so deco
+ * storefronts on TanStack/Workers can drop the per-site shim.
+ *
+ * All implementations use the global `btoa` / `atob` (available in Workers,
+ * browsers, and Node 16+) so there is zero runtime dependency.
+ */
+
+function toBytes(data: ArrayBuffer | Uint8Array | string): Uint8Array {
+  if (typeof data === "string") return new TextEncoder().encode(data);
+  if (data instanceof ArrayBuffer) return new Uint8Array(data);
+  return data;
+}
+
+export function encodeBase64(data: ArrayBuffer | Uint8Array | string): string {
+  const bytes = toBytes(data);
+  // Build the binary string in chunks to avoid blowing the call stack on
+  // large inputs (`String.fromCharCode(...bytes)` spreads the entire array).
+  let bin = "";
+  const CHUNK = 0x8000;
+  for (let i = 0; i < bytes.byteLength; i += CHUNK) {
+    bin += String.fromCharCode(...bytes.subarray(i, i + CHUNK));
+  }
+  return btoa(bin);
+}
+
+export function decodeBase64(b64: string): Uint8Array {
+  const bin = atob(b64);
+  const out = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+  return out;
+}
+
+export function encodeBase64Url(data: ArrayBuffer | Uint8Array | string): string {
+  return encodeBase64(data)
+    .replace(/\+/g, "-")
+    .replace(/\//g, "_")
+    .replace(/=+$/, "");
+}
+
+export function decodeBase64Url(b64url: string): Uint8Array {
+  const padded = b64url.replace(/-/g, "+").replace(/_/g, "/");
+  const padLen = (4 - (padded.length % 4)) % 4;
+  return decodeBase64(padded + "=".repeat(padLen));
+}

package/src/sdk/http.test.ts

@@ -0,0 +1,71 @@
+import { describe, expect, it } from "vitest";
+import { HttpError, STATUS_CODE, UserAgent } from "./http";
+
+describe("STATUS_CODE", () => {
+  it("exposes common codes with the IANA-canonical names", () => {
+    expect(STATUS_CODE.OK).toBe(200);
+    expect(STATUS_CODE.MovedPermanently).toBe(301);
+    expect(STATUS_CODE.NotFound).toBe(404);
+    expect(STATUS_CODE.TooManyRequests).toBe(429);
+    expect(STATUS_CODE.InternalServerError).toBe(500);
+  });
+
+  it("is readonly at the type level", () => {
+    // @ts-expect-error — assigning into the const map should not type-check.
+    STATUS_CODE.OK = 999;
+    // Even though the assignment is allowed at runtime (frozen-by-convention),
+    // we just want the type to flag it. The value is whatever JS allows.
+    expect(typeof STATUS_CODE.OK).toBe("number");
+  });
+});
+
+describe("UserAgent", () => {
+  it("accepts a string and exposes it via toString", () => {
+    const ua = new UserAgent("Mozilla/5.0 (test)");
+    expect(ua.toString()).toBe("Mozilla/5.0 (test)");
+  });
+
+  it("treats null as an empty UA string", () => {
+    const ua = new UserAgent(null);
+    expect(ua.toString()).toBe("");
+  });
+
+  it("exposes empty browser/os/cpu/device/engine accessors", () => {
+    const ua = new UserAgent("anything");
+    expect(ua.browser).toEqual({});
+    expect(ua.os).toEqual({});
+    expect(ua.cpu).toEqual({});
+    expect(ua.device).toEqual({});
+    expect(ua.engine).toEqual({});
+  });
+});
+
+describe("HttpError", () => {
+  it("captures status and message", () => {
+    const err = new HttpError(404, "Missing");
+    expect(err).toBeInstanceOf(Error);
+    expect(err.name).toBe("HttpError");
+    expect(err.status).toBe(404);
+    expect(err.message).toBe("Missing");
+  });
+
+  it("defaults the message from the status when not provided", () => {
+    const err = new HttpError(503);
+    expect(err.message).toBe("HTTP 503");
+  });
+
+  it("preserves an optional body payload for downstream handling", () => {
+    const body = { code: "rate_limited" };
+    const err = new HttpError(429, "Too Many Requests", body);
+    expect(err.body).toEqual(body);
+  });
+
+  it("supports `instanceof` discrimination", () => {
+    const err = new HttpError(304);
+    function isNotModified(e: unknown): e is HttpError {
+      return e instanceof HttpError && e.status === 304;
+    }
+    expect(isNotModified(err)).toBe(true);
+    expect(isNotModified(new Error("nope"))).toBe(false);
+  });
+});

package/src/sdk/http.ts

@@ -0,0 +1,124 @@
+/**
+ * HTTP constants and small typed helpers — replaces the parts of Deno's
+ * `@std/http` (other than cookies, which live in `./cookie.ts`) that deco
+ * storefronts touch.
+ *
+ * Currently exposes:
+ *   - `STATUS_CODE` — full IANA status-code map (parity with @std/http).
+ *   - `UserAgent`   — minimal class with the same shape; does not parse
+ *                     the UA string (sites only used `.toString()` and
+ *                     basic browser/os accessors in dev). Replace with a
+ *                     real parser like `ua-parser-js` if you actually
+ *                     depend on the parsed fields.
+ */
+
+export const STATUS_CODE = {
+  Continue: 100,
+  SwitchingProtocols: 101,
+  Processing: 102,
+  EarlyHints: 103,
+  OK: 200,
+  Created: 201,
+  Accepted: 202,
+  NonAuthoritativeInfo: 203,
+  NoContent: 204,
+  ResetContent: 205,
+  PartialContent: 206,
+  MultiStatus: 207,
+  AlreadyReported: 208,
+  IMUsed: 226,
+  MultipleChoices: 300,
+  MovedPermanently: 301,
+  Found: 302,
+  SeeOther: 303,
+  NotModified: 304,
+  UseProxy: 305,
+  TemporaryRedirect: 307,
+  PermanentRedirect: 308,
+  BadRequest: 400,
+  Unauthorized: 401,
+  PaymentRequired: 402,
+  Forbidden: 403,
+  NotFound: 404,
+  MethodNotAllowed: 405,
+  NotAcceptable: 406,
+  ProxyAuthRequired: 407,
+  RequestTimeout: 408,
+  Conflict: 409,
+  Gone: 410,
+  LengthRequired: 411,
+  PreconditionFailed: 412,
+  ContentTooLarge: 413,
+  URITooLong: 414,
+  UnsupportedMediaType: 415,
+  RangeNotSatisfiable: 416,
+  ExpectationFailed: 417,
+  Teapot: 418,
+  MisdirectedRequest: 421,
+  UnprocessableEntity: 422,
+  Locked: 423,
+  FailedDependency: 424,
+  TooEarly: 425,
+  UpgradeRequired: 426,
+  PreconditionRequired: 428,
+  TooManyRequests: 429,
+  RequestHeaderFieldsTooLarge: 431,
+  UnavailableForLegalReasons: 451,
+  InternalServerError: 500,
+  NotImplemented: 501,
+  BadGateway: 502,
+  ServiceUnavailable: 503,
+  GatewayTimeout: 504,
+  HTTPVersionNotSupported: 505,
+  VariantAlsoNegotiates: 506,
+  InsufficientStorage: 507,
+  LoopDetected: 508,
+  NotExtended: 510,
+  NetworkAuthenticationRequired: 511,
+} as const;
+
+export type StatusCode = typeof STATUS_CODE[keyof typeof STATUS_CODE];
+
+/**
+ * Minimal stand-in for Deno's `@std/http`'s `UserAgent`. Captures the raw
+ * UA string and exposes the same field shape; does NOT parse. Replace with
+ * a real parser when you start depending on parsed fields.
+ */
+export class UserAgent {
+  ua: string;
+  browser: { name?: string; version?: string };
+  os: { name?: string; version?: string };
+  device: { vendor?: string; model?: string; type?: string };
+  cpu: { architecture?: string };
+  engine: { name?: string; version?: string };
+
+  constructor(ua: string | null) {
+    this.ua = ua ?? "";
+    this.browser = {};
+    this.os = {};
+    this.device = {};
+    this.cpu = {};
+    this.engine = {};
+  }
+
+  toString(): string {
+    return this.ua;
+  }
+}
+
+/**
+ * Lightweight HTTP error class. Drop-in for the `HttpError` shape that
+ * `deco-cx/apps` exposes — sites use it as `error instanceof HttpError &&
+ * error.status === 304` and similar.
+ */
+export class HttpError extends Error {
+  status: number;
+  body?: unknown;
+
+  constructor(status: number, message?: string, body?: unknown) {
+    super(message ?? `HTTP ${status}`);
+    this.name = "HttpError";
+    this.status = status;
+    this.body = body;
+  }
+}

package/src/sdk/useScript.test.ts

@@ -1,5 +1,11 @@
-import { describe, expect, it } from "vitest";
-import { inlineScript, useScript } from "./useScript";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  HTMX_LEGACY_URL,
+  inlineScript,
+  usePartialSection,
+  useScript,
+  useSection,
+} from "./useScript";
 
 describe("inlineScript", () => {
   it("returns dangerouslySetInnerHTML with the provided string", () => {
@@ -51,3 +57,72 @@ describe("useScript", () => {
     expect(result).toMatch(/^\(.*\)\(\)$/);
   });
 });
+
+// ---------------------------------------------------------------------------
+// Legacy HTMX stubs — useSection / usePartialSection
+// ---------------------------------------------------------------------------
+
+describe("useSection / usePartialSection (legacy HTMX stubs)", () => {
+  let warnSpy: ReturnType<typeof vi.spyOn>;
+  let prevNodeEnv: string | undefined;
+
+  beforeEach(() => {
+    // Reset the dedup set so each test sees a fresh warning fire.
+    delete (globalThis as any).__DECO_LEGACY_HTMX_WARNED;
+    prevNodeEnv = process.env.NODE_ENV;
+    process.env.NODE_ENV = "development";
+    warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    warnSpy.mockRestore();
+    if (prevNodeEnv === undefined) delete process.env.NODE_ENV;
+    else process.env.NODE_ENV = prevNodeEnv;
+  });
+
+  it("useSection returns a stable placeholder URL instead of throwing", () => {
+    expect(useSection()).toBe(HTMX_LEGACY_URL);
+    expect(useSection({ props: { x: 1 } })).toBe(HTMX_LEGACY_URL);
+  });
+
+  it("usePartialSection returns the same placeholder URL", () => {
+    expect(usePartialSection()).toBe(HTMX_LEGACY_URL);
+  });
+
+  it("warns on first call (in development)", () => {
+    useSection();
+    expect(warnSpy).toHaveBeenCalledTimes(1);
+    expect(warnSpy.mock.calls[0][0]).toMatch(/useSection/);
+    expect(warnSpy.mock.calls[0][0]).toMatch(/were removed/);
+    expect(warnSpy.mock.calls[0][0]).toMatch(/htmx-residue/);
+  });
+
+  it("dedups warnings: a second call to the same stub is silent", () => {
+    useSection();
+    useSection();
+    useSection();
+    expect(warnSpy).toHaveBeenCalledTimes(1);
+  });
+
+  it("tracks warnings per-stub: useSection and usePartialSection warn independently", () => {
+    useSection();
+    usePartialSection();
+    expect(warnSpy).toHaveBeenCalledTimes(2);
+    const messages = warnSpy.mock.calls.map((c) => c[0] as string);
+    expect(messages.some((m) => m.includes("useSection"))).toBe(true);
+    expect(messages.some((m) => m.includes("usePartialSection"))).toBe(true);
+  });
+
+  it("does NOT warn in production", () => {
+    process.env.NODE_ENV = "production";
+    useSection();
+    usePartialSection();
+    expect(warnSpy).not.toHaveBeenCalled();
+  });
+
+  it("returns the placeholder URL even in production (still safe to embed)", () => {
+    process.env.NODE_ENV = "production";
+    expect(useSection()).toBe(HTMX_LEGACY_URL);
+    expect(usePartialSection()).toBe(HTMX_LEGACY_URL);
+  });
+});

package/src/sdk/useScript.ts

@@ -150,21 +150,61 @@ export function inlineScript(js: string) {
  * See: deco-to-tanstack-migration skill, "useComponent / partial sections"
  * section, for the per-pattern recipes.
  *
- * Both stubs throw at runtime (and at import time, if you call them at
- * module top level) so legacy code surfaces a clear error instead of a
- * silent no-op.
+ * ## SSR-safe stub behavior (since 2.27)
+ *
+ * Earlier versions threw on call. That broke SSR for the *entire page* if a
+ * single section still imported `useSection` — even sections that the user
+ * never interacts with (e.g. legacy login form on the homepage). React's
+ * error boundary would catch the throw and degrade the whole route to
+ * client rendering.
+ *
+ * The current behavior:
+ *   - returns a stable placeholder URL (`HTMX_LEGACY_URL`) so it can be
+ *     embedded in `hx-get` / `hx-post` attributes without crashing the
+ *     SSR pass,
+ *   - logs a deduped `console.warn` (in dev only) per call site so the
+ *     migration signal stays loud,
+ *   - the `htmx-residue` audit rule still catalogues every call site for
+ *     systematic rewrite.
+ *
+ * This is a deliberate trade-off: SSR success > strict-throw enforcement.
+ * Audit + skill docs do the enforcement instead.
  */
 const DEPRECATION_MESSAGE =
   "[@decocms/start] useSection / usePartialSection were removed. " +
   "The Fresh/Deno HTMX partial-section pattern does not apply on " +
   "TanStack Start / Cloudflare Workers. Replace call-sites with " +
   "createServerFn + useMutation, or local React state. See the " +
-  "deco-to-tanstack-migration skill for per-pattern recipes.";
+  "deco-to-tanstack-migration skill for per-pattern recipes. " +
+  "Run `deco-post-cleanup` and look for rule [9] htmx-residue to find " +
+  "every site call-site that still depends on this.";
+
+/**
+ * Stable placeholder URL returned by the legacy `useSection` /
+ * `usePartialSection` stubs. Hitting this URL surfaces a clear error.
+ * Exported so frameworks/tests can match against it.
+ */
+export const HTMX_LEGACY_URL = "/__deco_legacy_htmx_section__";
+
+function warnLegacyHtmx(name: string) {
+  if (typeof process !== "undefined" && process.env?.NODE_ENV === "production") {
+    return;
+  }
+  if (typeof (globalThis as any).__DECO_LEGACY_HTMX_WARNED === "undefined") {
+    (globalThis as any).__DECO_LEGACY_HTMX_WARNED = new Set<string>();
+  }
+  const set = (globalThis as any).__DECO_LEGACY_HTMX_WARNED as Set<string>;
+  if (set.has(name)) return;
+  set.add(name);
+  console.warn(`[${name}] ${DEPRECATION_MESSAGE}`);
+}
 
-export function usePartialSection(_props?: Record<string, unknown>): never {
-  throw new Error(DEPRECATION_MESSAGE);
+export function usePartialSection(_props?: Record<string, unknown>): string {
+  warnLegacyHtmx("usePartialSection");
+  return HTMX_LEGACY_URL;
 }
 
-export function useSection(_props?: Record<string, unknown>): never {
-  throw new Error(DEPRECATION_MESSAGE);
+export function useSection(_props?: Record<string, unknown>): string {
+  warnLegacyHtmx("useSection");
+  return HTMX_LEGACY_URL;
 }