@buildinams/core 0.3.0 → 0.4.0

package/docs/cookies.md

@@ -0,0 +1,354 @@
+# Cookies
+
+Typesafe cookies with one API for the server (Next.js) and the client.
+
+```ts
+import {
+	browserCookies,
+	cookieSchema,
+	defineCookie,
+} from "@buildinams/core/cookies";
+```
+
+- **Define once**: name, value type, default and attributes live in one `defineCookie()` call.
+- **Same API everywhere**: `cookie.get(store)`, `cookie.set(store, value)`, `cookie.delete(store)`. Only the `store` differs per environment.
+- **Safe reads**: cookies are user input. A missing _or invalid_ value returns the fallback (`defaultValue`, or `null`), never a wrongly typed value.
+
+## Quick start
+
+### 1. Define the cookie
+
+Define a cookie next to the code it belongs to, in its vertical slice: the session cookie with the auth logic, the
+cart cookie with the cart. Keep the definition in a module **without** `"use client"` / `"use server"`, so both
+environments can import it.
+
+```ts
+// src/features/theme/cookies.ts
+import { cookieSchema, defineCookie } from "@buildinams/core/cookies";
+
+export const themeCookie = defineCookie({
+	name: "theme",
+	schema: cookieSchema.enum(["light", "dark"]),
+	defaultValue: "light",
+	options: { maxAge: 60 * 60 * 24 * 365, sameSite: "lax" },
+});
+```
+
+### 2. Pick the store for your environment
+
+| Where                           | Read with                                           | Write with                               |
+| ------------------------------- | --------------------------------------------------- | ---------------------------------------- |
+| Server component                | `await cookies()`                                   | ❌ not allowed by Next.js                |
+| Server action / route handler   | `await cookies()`                                   | `await cookies()`                        |
+| Proxy / middleware              | `request.cookies`                                   | `response.cookies` (from `NextResponse`) |
+| Client component / browser code | `browserCookies`                                    | `browserCookies`                         |
+| Client component, reactive      | `useCookieValue()` from `@buildinams/react/cookies` | `browserCookies`                         |
+
+`cookies` is imported from `next/headers`.
+
+### 3. Use it
+
+```ts
+// Server component
+import { cookies } from "next/headers";
+import { themeCookie } from "@/features/theme/cookies";
+
+const theme = themeCookie.get(await cookies()); // "light" | "dark"
+```
+
+```ts
+// Server action
+"use server";
+
+import { cookies } from "next/headers";
+import { themeCookie } from "@/features/theme/cookies";
+
+export const setTheme = async (theme: "light" | "dark") => {
+	themeCookie.set(await cookies(), theme);
+};
+```
+
+```ts
+// src/proxy.ts (Next 16+). Next 15 and earlier: src/middleware.ts exporting `middleware`, same body.
+import { NextResponse, type NextRequest } from "next/server";
+import { visitsCookie } from "@/features/visits/cookies"; // cookieSchema.number(), defaultValue: 0
+
+export const proxy = (request: NextRequest) => {
+	const response = NextResponse.next();
+	visitsCookie.set(response.cookies, visitsCookie.get(request.cookies) + 1);
+	return response;
+};
+```
+
+```ts
+// Browser (event handler, effect, non-React code)
+import { browserCookies } from "@buildinams/core/cookies";
+import { themeCookie } from "@/features/theme/cookies";
+
+themeCookie.set(browserCookies, "dark");
+themeCookie.get(browserCookies); // "dark"
+themeCookie.delete(browserCookies);
+```
+
+### 4. React
+
+Read with `useCookieValue` from `@buildinams/react/cookies`; write with the cookie itself, exactly as anywhere else.
+
+The server can't see the browser's cookies from a client component, so read the cookie in the server component and
+pass it to the hook as the second argument:
+
+```tsx
+// app/page.tsx (server component)
+import { cookies } from "next/headers";
+import { themeCookie } from "@/features/theme/cookies";
+import { ThemeToggle } from "./theme-toggle";
+
+export default async function Page() {
+	return <ThemeToggle serverTheme={themeCookie.get(await cookies())} />;
+}
+```
+
+```tsx
+// app/theme-toggle.tsx
+"use client";
+
+import type { CookieReadValue } from "@buildinams/core/cookies";
+import { browserCookies } from "@buildinams/core/cookies";
+import { useCookieValue } from "@buildinams/react/cookies";
+import { themeCookie } from "@/features/theme/cookies"; // defaultValue: "light"
+
+type Theme = CookieReadValue<typeof themeCookie>; // "light" | "dark"
+
+export const ThemeToggle = ({ serverTheme }: { serverTheme: Theme }) => {
+	const theme = useCookieValue(themeCookie, serverTheme); // "light" | "dark"
+
+	return (
+		<>
+			<button
+				onClick={() =>
+					themeCookie.set(browserCookies, theme === "light" ? "dark" : "light")
+				}
+			>
+				{theme}
+			</button>
+			<button onClick={() => themeCookie.delete(browserCookies)}>Reset</button>
+		</>
+	);
+};
+```
+
+`useCookieValue(cookie, serverValue?)` returns:
+
+- On the server and during hydration: `serverValue`, or `undefined` without one (the value isn't known yet, even
+  with a `defaultValue`).
+- After hydration: the parsed value, or the cookie's `defaultValue` (`null` without one) when it's missing or invalid.
+  A cookie deleted in the browser reads as `null`, never as the stale `serverValue`.
+
+Without a server value, handle `undefined` yourself. A consent banner, for example, should only show once the cookie is
+known to be missing, or it flashes for users who already answered:
+
+```tsx
+const consent = useCookieValue(consentCookie); // Consent | null | undefined
+
+if (consent !== null) return null; // not known yet, or already answered
+return <ConsentBanner />;
+```
+
+- **Hydration never mismatches**, as long as `serverValue` is exactly what the server rendered (the prop from the
+  server component). Don't compute it differently on the client.
+- **Don't apply a server value with `??`**: `useCookieValue(c) ?? serverValue` also replaces `null` (deleted in the
+  browser) with the stale server value. Pass it as the second argument instead.
+- **httpOnly cookies are a compile error**: the browser can't read them. Don't pass their values to client
+  components either.
+- Re-renders after writes through `browserCookies`, and on `cookieStore` change events, window focus and tab visibility
+  changes. A cookie set by a server action shows up via `cookieStore` change events (or the next focus in browsers
+  without the Cookie Store API).
+
+## Defining cookies
+
+```ts
+defineCookie({
+	name: string,                // cookie name in the browser
+	schema: CookieSchema<Value>, // how Value <-> string is converted (see below)
+	defaultValue?: Value,        // returned when missing/invalid; without it reads return `Value | null`
+	options?: CookieOptions,     // attributes applied on every write
+});
+```
+
+### Schemas
+
+| Schema                        | Value type                   | Stored as               |
+| ----------------------------- | ---------------------------- | ----------------------- |
+| `cookieSchema.string()`       | `string`                     | as-is                   |
+| `cookieSchema.number()`       | `number` (finite)            | `"42"`                  |
+| `cookieSchema.boolean()`      | `boolean`                    | `"true"` / `"false"`    |
+| `cookieSchema.enum([...])`    | union of the listed literals | as-is                   |
+| `cookieSchema.json(validate)` | return type of `validate`    | `JSON.stringify(value)` |
+
+`json` requires a validator, because a cookie can contain anything. A zod/valibot `parse` fits directly:
+
+```ts
+const ConsentSchema = z.object({
+	analytics: z.boolean(),
+	marketing: z.boolean(),
+});
+
+export const consentCookie = defineCookie({
+	name: "consent",
+	schema: cookieSchema.json(ConsentSchema.parse),
+});
+```
+
+Need the same validation elsewhere (form data, request bodies)? Export the schema next to the cookie and reuse it:
+
+```ts
+export const themeSchema = cookieSchema.enum(["light", "dark"]);
+export const themeCookie = defineCookie({
+	name: "theme",
+	schema: themeSchema,
+	defaultValue: "light",
+});
+
+// server action
+const theme = themeSchema.parse(String(formData.get("theme"))); // throws on invalid input
+```
+
+Custom schema: any object with `parse(raw: string): Value` (throws when invalid) and `serialize(value: Value): string`. Don't URL-encode in `serialize`; the store does that.
+
+```ts
+const dateSchema: CookieSchema<Date> = {
+	parse: (raw) => {
+		const date = new Date(raw);
+		if (Number.isNaN(date.getTime())) throw new Error("Invalid date");
+		return date;
+	},
+	serialize: (value) => value.toISOString(),
+};
+```
+
+### Options
+
+Fixed on the definition and applied to every write and to `delete()`. Same names as Next.js' `cookies().set()` options.
+
+| Option        | Default                 | Notes                                                                    |
+| ------------- | ----------------------- | ------------------------------------------------------------------------ |
+| `path`        | `"/"`                   |                                                                          |
+| `domain`      | —                       |                                                                          |
+| `maxAge`      | session                 | Seconds, relative to the write                                           |
+| `secure`      | `false`                 | Required when `sameSite: "none"`                                         |
+| `sameSite`    | browser default (`lax`) | `"lax"`, `"strict"`, `"none"`                                            |
+| `httpOnly`    | `false`                 | Hidden from client JS. Makes the definition a `ServerCookie` (see below) |
+| `partitioned` | `false`                 |                                                                          |
+| `priority`    | —                       | `"low"`, `"medium"`, `"high"`                                            |
+
+A single write can override the lifetime only: `cookie.set(store, value, { maxAge: 60 })` or `{ expires: date }`.
+Everything else stays on the definition, so `delete()` always targets the same cookie. There's no `expires` on the
+definition: it would be computed once, when the module loads.
+
+### Server-only cookies
+
+`httpOnly: true` returns a `ServerCookie`. It has the same API, but passing `browserCookies` (or using it with
+`useCookieValue`) is a compile error. The browser can't read or write it.
+
+```ts
+export const sessionCookie = defineCookie({
+	name: "session",
+	schema: cookieSchema.string(),
+	options: { httpOnly: true, secure: true, sameSite: "lax" },
+});
+
+sessionCookie.get(await cookies()); // ✅
+sessionCookie.get(browserCookies); // ❌ type error
+```
+
+## API
+
+```ts
+const cookie = defineCookie({ ... });
+
+cookie.get(store)                     // Value with a defaultValue, Value | null without
+cookie.set(store, value, lifetime?)   // lifetime: { maxAge?, expires? }
+cookie.delete(store)
+cookie.name
+cookie.httpOnly
+```
+
+Types:
+
+```ts
+import type {
+	Cookie, // Cookie<Value, HasDefault>: a cookie usable on server and client
+	ServerCookie, // ServerCookie<Value, HasDefault>: an httpOnly cookie, server stores only
+	CookieWriteValue, // CookieWriteValue<typeof themeCookie> -> "light" | "dark"
+	CookieReadValue, // CookieReadValue<typeof consentCookie> -> Consent | null
+	CookieSchema, // { parse(raw): Value; serialize(value): string }
+	CookieReader, // { get(name) }: any readable store
+	CookieWriter, // { set(name, value, attributes) }: any writable store
+} from "@buildinams/core/cookies";
+
+// accept any theme-like cookie, with or without a default
+const label = (cookie: Cookie<"light" | "dark">) => cookie.name;
+```
+
+`CookieReader` / `CookieWriter` are structural: Next.js' cookie stores satisfy them without adapters. For other
+frameworks or tests, pass any object with matching `get` / `set`.
+
+## Rules (for humans and agents)
+
+1. **Never read or write a cookie by its raw name.** Add a `defineCookie()` to the slice that owns the cookie and use that.
+2. **Never `JSON.parse` / cast cookie values.** Pick or write a schema; reads are validated through it.
+3. **Pass the store explicitly.** Server: `await cookies()` / `request.cookies` / `response.cookies`. Client: `browserCookies`.
+4. **Don't write cookies in server components.** Use a server action, route handler or proxy (middleware before Next 16).
+5. **Keep httpOnly cookies on the server.** The types enforce it; read them on the server and pass down what the client needs.
+6. **Keep values small.** Browsers cap a cookie at ~4KB including its name and attributes.
+
+## Adding a cookie: checklist
+
+1. Add a `defineCookie()` export to the slice that owns the cookie (e.g. `src/features/auth/cookies.ts`), in a module without `"use client"` / `"use server"`.
+2. Choose a schema; add `defaultValue` if a missing cookie has a sensible meaning.
+3. Set `options` (`maxAge`, `sameSite`, `httpOnly` for server-only data).
+4. Read/write via `cookie.get(store)` / `cookie.set(store, value)` with the store from the table above.
+5. Unit-test logic that depends on the cookie by passing a fake store (see below).
+
+## Testing
+
+Pass a plain object, or Next.js' cookie classes, as the store:
+
+```ts
+import {
+	RequestCookies,
+	ResponseCookies,
+} from "next/dist/server/web/spec-extension/cookies";
+
+const request = new RequestCookies(new Headers({ cookie: "theme=dark" }));
+expect(themeCookie.get(request)).toBe("dark");
+
+const headers = new Headers();
+themeCookie.set(new ResponseCookies(headers), "dark");
+expect(headers.get("set-cookie")).toContain("theme=dark");
+
+// minimal fake
+const store = new Map<string, string>();
+const fake = {
+	get: (name: string) =>
+		store.has(name) ? { value: store.get(name)! } : undefined,
+	set: (name: string, value: string) => void store.set(name, value),
+};
+```
+
+In the browser (jsdom), `browserCookies` works against `document.cookie` directly.
+
+## How it works
+
+- Values are URL-encoded on write and decoded on read, matching Next.js. A cookie written in the browser reads the same on the server, and vice versa.
+- `delete()` writes an empty value with `maxAge: 0` and an `expires` in the past, using the definition's `path` and `domain`.
+- `browserCookies.subscribe(listener)` fires after `browserCookies.set()`, on `cookieStore` change events (where supported), on window `focus` and on `visibilitychange`.
+
+## Decisions
+
+- [Cookies take their store as an argument](decisions/004-cookies-explicit-store.md)
+- [Invalid cookies read as missing](decisions/005-cookies-invalid-reads-fall-back.md)
+- [httpOnly cookies are server-only in the types](decisions/006-cookies-server-only-types.md)
+- [Cookie attributes live on the definition](decisions/007-cookies-options-on-definition.md)
+- [Cookies are defined in their vertical slice](decisions/008-cookies-in-vertical-slices.md)
+- [`useCookieValue()` takes the server's value](../../react/docs/decisions/008-cookie-server-value.md) (`@buildinams/react`)

package/docs/decisions/001-analytics-project-events.md

@@ -0,0 +1,31 @@
+# Projects own their event catalog
+
+Date: 2026-11-11
+
+Status: accepted
+
+## Context
+
+Projects track their own events (`newsletterSignedUp`, `orderPlaced`, …) with their own data: a product page has a `{ product, variant }` from its Storefront API query, a card a `{ product }`. Each provider names events its own way: GA4 `view_item`, Shopify `product_viewed`, Meta `ViewContent`. And developers, agents and analysts want to read which events a project tracks, what each means and where it goes, so the catalog can't only live in types.
+
+Options considered:
+
+- **A global `Register` interface** projects augment with `declare module`. One global the library's plugins can't constrain, with `.d.ts` pitfalls.
+- **Canonical shapes** (`StandardEvents`, `AnalyticsItem`) that projects flatten their data into. Each destination rebuilds its provider's format, losing whatever the canonical item lacks.
+- **A catalog value from the project**, with the library's structures generic over the project's data.
+
+## Decision
+
+- **The catalog is a value:** `defineEvents({ name: { description, payload: shape<T>() } })`, passed to `createAnalytics<Events>({ events })`. `shape<T>()` holds nothing at runtime; `description` is required.
+- **Trackers carry their entries.** `domWatcher.events` and `cartChanges.events` describe exactly what the installed plugins report, typed with the project's data as declared on the plugins, so shapes are declared once.
+- **Library structure, project leaves.** What the library reports has a fixed structure, e.g. `itemViewed: { item, list?, index?, promotion? }`, with the project's item, list, promotion and cart item as leaves.
+- **One vocabulary, no provider's.** Tracking's names (`pageViewed`, `itemsViewed`, `addedToCart`, …) are the catalog's; the project's own events follow them: camelCase, past tense. Provider names live in mappings ([ADR 010](010-analytics-destination-contract.md)).
+- **`analytics.routes()`** reads the catalog against the destinations: per event, its description and who receives it, with what consent.
+
+## Consequences
+
+- No module augmentation, so no `interface` exception. `Events` is passed explicitly: inferring it from `events` breaks `map()`'s inference of prebuilt mappings in the same call.
+- There's no canonical item, so every destination needs a small adapter from the project's data (`ga4Mapping({ item })`, `shopifyMapping({ product })`).
+- Payloads may hold rich objects, copied by `structuredClone` on every `track()`; the docs recommend lean fragments.
+- Descriptions ship in the bundle. They're short, and they make the catalog readable at runtime.
+- Development warns about catalog events no destination receives, and tracked names missing from the catalog.

package/docs/decisions/002-tracking-dom-opt-in.md

@@ -0,0 +1,29 @@
+# Opt-in markup tracking
+
+Date: 2026-11-05
+
+Status: accepted
+
+## Context
+
+Tracking every `<a href>` and `<form>` unless an ancestor opts out tracks a lot nobody asked for on an ecommerce site:
+
+- **Personal data in URLs:** password reset, order status and unsubscribe links send their tokens to GA4. One forgotten opt-out leaks them.
+- **Noise and cost:** filters, pagination and swatches each become a `click`, billed per request by server-side GTM.
+- **A broad switch:** an opt-out also silences product and promotion clicks inside it.
+
+Options considered: opt-out per plugin, a click `location` as the opt-in, per-element types only, an opt-in for a subtree, a mode per plugin, and selectors in config.
+
+## Decision
+
+Nothing is tracked from markup without a type in `data-track` that asks for it:
+
+- `click` and `form` track that element.
+- `auto-links` and `auto-forms` (`track({ auto })`) track every link or form inside. Buttons always need `click`, as their text rarely says what they do, and videos are never auto-tracked.
+- The nearest `auto` decides, so `auto-none` (`track({ auto: false })`) turns it off for a subtree.
+
+## Consequences
+
+- Forgetting a type loses a click rather than leaking a URL.
+- Projects mark their header, navigation and footer once; a rich-text renderer wraps its output in `auto-links`.
+- Analytics doesn't clean URLs: a query parameter allowlist was tried and dropped, as tags read the page URL themselves and GA4's data redaction covers it at the source.

package/docs/decisions/003-tracking-element-data.md

@@ -0,0 +1,27 @@
+# One `track()` marks an element, with data off the HTML
+
+Date: 2026-11-05
+
+Status: accepted
+
+## Context
+
+Markup tracking read each element's data from a JSON attribute per kind (`data-track-item`, `data-track-promotion`, …), in a compact encoding to keep product grids small. That puts every product's data in the HTML, again in the server component payload, and needs its own parser and errors. A prototype (branch `prototype/track-dom-element-data`) compared JSON attributes, a hybrid, element data only, and splitting by size.
+
+Splitting by size first took a helper per case: one for string attributes, one returning `{ ref, attributes }` for data, one to combine them. A promotion in the hero took three calls and a ref set separately.
+
+## Decision
+
+The watcher's `track(spec)` marks an element: one object keyed by type, returning props to spread.
+
+- **Attribute types** (`pageView`, `click`, `location`, `auto`, `video`, `form`, `scroll`) take a few strings, written as `data-track-<field>` attributes that server components and CMS markup can write. `true` when all fields are optional.
+- **Data types** (`viewItem`, `quickView`, `list`, `item`, `promotion`) take the project's data, or a function building it. `track()` then also returns a `ref`, which sets it as a property on the element, under `Symbol.for()`, ignored when equal to the current data.
+- **Types are listed in `data-track`**, kebab-case, so CMS markup writes them by hand. Without a framework, the `ref` called with an element sets the data and the type.
+
+## Consequences
+
+- Several types on one element are one call, e.g. `track({ promotion, location: { name: "hero" } })`. An element with its own ref needs a ref that calls both.
+- `track()` only returns a `ref` for data types, so server components spread it for attribute types. Product, list and promotion data needs a client component, and isn't tracked before hydration.
+- The HTML carries only types: about 0.8 KB instead of 9 KB for a 48-product grid in the prototype.
+- A forgotten `ref` fails silently, so `ecommerce()` warns in development about visible elements still without data after 2 seconds.
+- Element data isn't in the Elements panel or GTM's DOM variables, only in the console under `Symbol.for("@buildinams/core/tracking/dom")`.

package/docs/decisions/004-cookies-explicit-store.md

@@ -0,0 +1,26 @@
+# Cookies take their store as an argument
+
+Date: 2026-11-03
+
+Status: accepted
+
+## Context
+
+A Next.js project reads and writes cookies in five places, each with its own API: `await cookies()` in server components, server actions and route handlers, `request.cookies` and `response.cookies` in the proxy, and `document.cookie` in the browser. Server components can read but not write. Each cookie also has a name, a value type and attributes that every one of those places has to agree on.
+
+Options considered:
+
+- **Detect the environment** inside the cookie: `themeCookie.get()` calls `cookies()` on the server and reads `document.cookie` in the browser. The shortest call, but `cookies()` is async and only works in a request scope, the proxy has two stores to choose from, and the cookie module would import `next/headers`, tying it to Next.js.
+- **A cookie per environment**: `serverCookie()` and `clientCookie()` wrappers. Each is simple, but the definition is repeated or split, and they drift.
+- **The store as an argument**: one definition, and `get(store)`, `set(store, value)`, `delete(store)`.
+
+## Decision
+
+A cookie from `defineCookie()` takes the store as its first argument. A store is structural: `CookieReader` is anything with `get(name)` returning `{ value } | undefined`, `CookieWriter` anything with `set(name, value, attributes)`. Next.js' `cookies()`, `RequestCookies` and `ResponseCookies` fit without adapters. `browserCookies` is the store for the browser, on `document.cookie`, and adds `subscribe()` for changes.
+
+## Consequences
+
+- The same definition works in every environment, and which store a call uses is visible at the call site.
+- `@buildinams/core/cookies` doesn't import Next.js. Other frameworks, and tests, pass any object with `get` and `set`.
+- Writing in a server component is still Next.js' runtime error, not a type error: `await cookies()` has a `set` there too.
+- Values are URL-encoded the way Next.js does, so a cookie written by one store reads the same in another.

package/docs/decisions/005-cookies-invalid-reads-fall-back.md

@@ -0,0 +1,27 @@
+# Invalid cookies read as missing
+
+Date: 2026-11-03
+
+Status: accepted
+
+## Context
+
+Cookies are user input. Visitors edit them, old deploys leave values in an earlier format, other scripts write the same name, and a value can be cut off. A typed read that trusts the raw string returns a value of the wrong type with nothing to show for it.
+
+Options considered:
+
+- **Cast**: return the raw string as the value type. What untyped code does today, with the type checker's blessing.
+- **Throw** on an invalid value. Loud, but one bad cookie breaks a page render, and every read needs a `try`.
+- **A result type**: `{ ok: true, value } | { ok: false, error }`. Precise, but every caller unwraps it to do the same thing: use a fallback.
+- **Fall back**: an invalid value reads like a missing one.
+
+## Decision
+
+Every cookie has a schema, a `parse(raw)` that throws when the value is invalid and a `serialize(value)`. `get()` returns the parsed value, and when the cookie is missing or `parse` throws, the definition's `defaultValue`, or `null` without one. `cookieSchema` has `string`, `number`, `boolean`, `enum` and `json(validate)`; `json` requires a validator, which a zod or valibot `parse` fits directly.
+
+## Consequences
+
+- A read never returns a wrongly typed value, and never throws.
+- With a `defaultValue` the read type is `Value`, without one `Value | null`, so callers handle a missing cookie where it matters.
+- An invalid cookie is silent. Debugging means calling the schema's `parse()` with the raw value, which throws with the reason.
+- An invalid cookie stays in the browser until it's written or deleted.

package/docs/decisions/006-cookies-server-only-types.md

@@ -0,0 +1,19 @@
+# httpOnly cookies are server-only in the types
+
+Date: 2026-11-03
+
+Status: accepted
+
+## Context
+
+An httpOnly cookie, like a session, can't be read or written from JavaScript in the browser. Read through `document.cookie` it's simply missing, so code that passes `browserCookies` to it doesn't fail: it reads the fallback, and a write is ignored. Both look like bugs somewhere else.
+
+## Decision
+
+`defineCookie()` with `options: { httpOnly: true }` returns a `ServerCookie` instead of a `Cookie`. It has the same API, but its methods take server stores only: `browserCookies` carries a brand that `ServerCookieReader` and `ServerCookieWriter` exclude, so passing it is a compile error. `useCookieValue()` only accepts a `Cookie`. At runtime, `browserCookies.set()` still throws for an httpOnly write.
+
+## Consequences
+
+- Reading a session cookie in a client component is caught by the type checker, not in production.
+- `httpOnly` has to be a literal in the definition for the type to follow: an `httpOnly` from a variable typed `boolean` gives `Cookie | ServerCookie`, which callers have to narrow.
+- What the client needs from an httpOnly cookie is read on the server and passed down, so it's a deliberate choice.

package/docs/decisions/007-cookies-options-on-definition.md

@@ -0,0 +1,25 @@
+# Cookie attributes live on the definition
+
+Date: 2026-11-03
+
+Status: accepted
+
+## Context
+
+A cookie is identified by its name, `path` and `domain`. A `delete()`, or a write, with another `path` or `domain` than the original write creates a second cookie with the same name, or leaves the old one in place. Attributes like `sameSite` and `secure` are easy to forget on one write among many.
+
+Options considered:
+
+- **Attributes per write**, like Next.js' `cookies().set()`. Flexible, but every call site repeats them and can get them wrong.
+- **Defaults on the definition, overridable per write.** Shorter, but an override of `path` or `domain` breaks `delete()` in the same way.
+- **Fixed on the definition, with only the lifetime per write.**
+
+## Decision
+
+`defineCookie({ options })` fixes `path` (default `"/"`), `domain`, `maxAge`, `secure`, `sameSite`, `httpOnly`, `partitioned` and `priority`, with Next.js' names. `set(store, value, { maxAge })` or `{ expires }` can change the lifetime of one write. `delete()` writes an empty value with `maxAge: 0` and the definition's `path` and `domain`. There's no `expires` on the definition.
+
+## Consequences
+
+- `delete()` always targets the cookie `set()` wrote.
+- A cookie that needs other attributes in some places, like another `path`, is a second definition.
+- `expires` on the definition would be computed once, when the module loads, and go stale in a long-running server. A lifetime that lasts is a `maxAge`; a fixed date is an `expires` per write.

package/docs/decisions/008-cookies-in-vertical-slices.md

@@ -0,0 +1,24 @@
+# Cookies are defined in their vertical slice
+
+Date: 2026-11-08
+
+Status: accepted
+
+## Context
+
+Every cookie is a `defineCookie()` call, and code reads and writes it only through that definition. The definitions need a home in the project.
+
+Options considered:
+
+- **One shared module**, e.g. `src/cookies.ts`, with every cookie. Easy to audit, but it couples unrelated features, grows into a file every feature changes, and pulls auth's cookies into the theme toggle's imports.
+- **In the slice that owns the cookie**: the session cookie with the auth logic, the cart cookie with the cart.
+
+## Decision
+
+A cookie is defined next to the code it belongs to, e.g. `src/features/auth/cookies.ts`. The module has no `"use client"` or `"use server"`, so both server and client code can import it.
+
+## Consequences
+
+- A feature's cookies change, and are removed, with the feature.
+- There's no single list of a project's cookies. Search for `defineCookie(` for an inventory, e.g. for a cookie policy.
+- A cookie read by several slices, like consent, belongs to the slice that writes it, and the others import it from there.

package/docs/decisions/009-analytics-consent-targets.md

@@ -0,0 +1,29 @@
+# Consent targets are separate from destinations
+
+Date: 2026-11-08
+
+Status: accepted
+
+## Context
+
+Providers play up to three roles around consent:
+
+| Role                  | Does            | Providers                                                   |
+| --------------------- | --------------- | ----------------------------------------------------------- |
+| **Consent source**    | Decides consent | Cookiebot, OneTrust, Shopify's privacy banner               |
+| **Consent target**    | Is told consent | Google Consent Mode, Shopify Customer Privacy, Meta consent |
+| **Event destination** | Receives events | GTM, Shopify's analytics bus, Meta Pixel                    |
+
+With only sources and destinations, destinations forwarded consent themselves, behind flags (`forwardConsent`, `setConsentMode`) that encoded which consent platform the project uses. A wrong flag failed silently.
+
+Options considered: sources that describe themselves, integrations bundling a provider's roles, consent as an event on the bus, and consent targets as a third role.
+
+## Decision
+
+`createAnalytics({ consentTargets })` takes objects with a `name` and `apply(consent)`. Each answer is applied to every target before destinations receive events under it, except a target named like the source, so consent is never written back to its platform. Destinations only handle events, and get the current answer with each one.
+
+## Consequences
+
+- Switching consent platforms changes `consent`, and adds or removes `googleConsentMode()`. No destination changes.
+- A source and its platform's target must share a name, e.g. `"shopify"`.
+- A provider that needs both roles, like Meta, is a target and a destination, wired up separately.

package/docs/decisions/010-analytics-destination-contract.md

@@ -0,0 +1,29 @@
+# Destinations declare what they accept; projects map onto it
+
+Date: 2026-11-10
+
+Status: accepted
+
+## Context
+
+Every destination received every event and mapped it to its provider internally, with a `switch` that dropped what it didn't handle and an untyped `map` option to adjust the result. What a destination needed (Shopify drops products without `variantId` or `price`) was a runtime warning, not a type.
+
+Options considered: mapping as an option on each destination, or a typed contract with mapping in core, as one call with consent or two.
+
+## Decision
+
+- **A destination is `AnalyticsDestination<Accepts>`**, shaped like Hydrogen's `StorefrontAnalyticsDestination`: a `name`, and `setup({ subscribe })` that subscribes to each event it accepts, in its provider's vocabulary. `setup` runs once, before consent, and mustn't load the provider's script.
+- **`map(destination, mapping)`** maps the project's events onto it, returning a destination that accepts the project's events and lists them in `events`, for `routes()`. Each entry returns one of the destination's events, several, or `null`.
+- **`withConsent(destination, requires)`** adds the consent it requires, which is all `createAnalytics()` takes. `requires` is mandatory: the categories, or `"none"` for providers that gate on consent themselves. A default of `"none"` would send a forgotten marketing pixel events before the visitor answers.
+- **`mapEvery(events, toEvent)`** maps every catalog event, spread before specific entries; a destination can't fall back by itself, as it only knows the events it subscribes to.
+- **Builders per destination** map what tracking reports over the project's adapters: `ga4Mapping<Events>({ item, … })` and `shopifyMapping<Events>({ product, … })`, spread to extend or override. `toGa4CustomEvent` sends other events under their name in snake_case.
+
+A type prototype checked about 120 events with 150 mapping entries in 0.16 s.
+
+## Consequences
+
+- A wrong event, a missing required field or an entry for an undeclared event is a compile error. `map()` rejects unknown keys itself, as inferred mappings skip excess property checks.
+- Whether a provider counts as analytics or marketing is the project's call, per destination.
+- A destination typed by the project's events, e.g. a log, needs only `withConsent()`.
+- It's Hydrogen's pattern, not its type: a Hydrogen destination can't be used as-is.
+- A destination mapped more than once is set up once.