@sayren/mcp 0.8.0 → 0.10.0

package/dist/index.mjs

@@ -749,10 +749,10 @@ const RULES = [
 		id: "buyer-token-cookie",
 		title: "구매자 토큰 쌍은 서버에서 HttpOnly 쿠키에 담는다",
 		why: "브라우저 JS나 `localStorage`에 둔 토큰은 스크립트 하나로 새 나간다. 리프레시 토큰이 새면 그 구매자 계정으로 계속 로그인된다",
-		fix: "로그인·가입·소셜 콜백을 서버 함수·서버 라우트에서 처리하고 받은 토큰 쌍을 `httpOnly` 쿠키 하나에 담는다. 브라우저 저장소에 토큰을 쓰지 않고, 인증 모듈(`@sayren/storefront-sdk/auth`)은 `*.server.ts`에서만 만든다",
-		example: "setCookie(\"sayren_member\", JSON.stringify({ accessToken, refreshToken, expiresAt }), {\n  httpOnly: true,\n  sameSite: \"lax\",\n  secure: process.env.NODE_ENV === \"production\",\n});",
+		fix: "로그인·가입·소셜 콜백을 서버 함수·서버 라우트에서 처리하고 받은 토큰 쌍을 `httpOnly` 쿠키 하나에 담는다. 브라우저 저장소에 토큰을 쓰지 않고, 인증 모듈(`@sayren/storefront-sdk/auth`)은 `*.server.ts`에서만 만든다. 프로덕션에서는 쿠키 이름에 `__Host-` 접두사를 붙이고 `secure`·`path: \"/\"`로 쓴다(`Domain`은 주지 않는다). 같은 상위 도메인의 다른 사이트가 심은 쿠키로 세션이 바뀌지 않는다",
+		example: "// 프로덕션은 __Host- 접두사 — Secure·Path=/·Domain 없음일 때만 브라우저가 받는다\nconst name = import.meta.env.PROD ? \"__Host-sayren_member\" : \"sayren_member\";\nsetCookie(name, JSON.stringify({ accessToken, refreshToken, expiresAt }), {\n  httpOnly: true,\n  sameSite: \"lax\",\n  path: \"/\",\n  secure: import.meta.env.PROD,\n});",
 		doc: "/guides/storefront-auth",
-		templateFile: "src/lib/session.server.ts"
+		templateFile: "src/lib/cookies.server.ts"
 	},
 	{
 		id: "buyer-session-refresh",
@@ -870,6 +870,8 @@ function verifySources(files) {
 		if (BROWSER_TOKEN_STORAGE.test(file.content)) inFile("buyer-token-cookie", file, "토큰을 브라우저 저장소(localStorage·sessionStorage)에 쓴다. 서버에서 HttpOnly 쿠키에 담는다", BROWSER_TOKEN_STORAGE);
 		const cookieWrite = /setCookie\(/;
 		if (cookieWrite.test(file.content) && /refreshToken/.test(file.content) && !/httpOnly/.test(file.content)) inFile("buyer-token-cookie", file, "토큰 쌍을 쿠키에 담는데 `httpOnly`가 없다. 브라우저 JS가 읽을 수 있다", cookieWrite);
+		const cookieDomain = /\bdomain\s*:/;
+		if (cookieWrite.test(file.content) && cookieDomain.test(file.content)) inFile("buyer-token-cookie", file, "서버 쿠키에 `domain`을 준다. 호스트 전용 쿠키로 두고(`domain` 생략) 프로덕션은 `__Host-` 접두사를 붙인다", cookieDomain);
 		const analyticsFactory = /createAnalytics\(/;
 		if (isServer && analyticsFactory.test(file.content)) inFile("analytics-start", file, "서버 파일에서 방문 분석을 시작한다. 서버에서는 아무것도 하지 않으니 브라우저(effect)에서 부른다", analyticsFactory);
 		if (isServer && /createStorefrontClient\(/.test(file.content) && !/analyticsIdsFromCookie|visitorId/.test(file.content)) inFile("analytics-ids", file, "서버 API 클라이언트에 방문 식별자가 없다. `...analyticsIdsFromCookie(request.headers.get(\"cookie\"))`를 넘긴다", /createStorefrontClient\(/);
@@ -885,6 +887,8 @@ function verifySources(files) {
 	if (has(".result(") && !has("PROCESSING")) inProject("payment-processing-status", "결과 확인 중(`PROCESSING`)일 때 결제 상태를 다시 조회하는 코드가 없다");
 	if (has("startPayment(") && has("zipCode") && !has("quoteDelivery(")) inProject("delivery-quote-preview", "배송지 우편번호를 받지만 `checkout.quoteDelivery`로 배송비를 다시 계산하는 코드가 없다");
 	if (has("createStorefrontAuth(")) {
+		const cookieFiles = cleaned.filter((file) => /setCookie\(/.test(file.content));
+		if (cookieFiles.length > 0 && !cookieFiles.some((file) => /httpOnly\s*:\s*true/.test(file.content))) inProject("buyer-token-cookie", "구매자 로그인을 쓰는데 서버 쿠키를 `httpOnly: true`로 쓰는 코드가 없다. 토큰 쌍이 브라우저 JS에 노출된다");
 		if (!has(".refresh(")) inProject("buyer-session-refresh", "로그인은 하지만 액세스 토큰을 갱신하는 코드가 없다(`auth.refresh(refreshToken)`)");
 		if (has(".session(") && !has(".signUp(")) inProject("buyer-signup", "이메일·비밀번호 로그인(`auth.session`)은 있지만 가입(`auth.signUp`)을 부르는 코드가 없다");
 		if (!matches(/\b(auth|authFor\(\))\.signOut\(|\.signOut\(\s*accessToken\b/)) inProject("buyer-signout", "로그아웃에서 리프레시 토큰을 폐기하는 코드가 없다(`auth.signOut(accessToken)`)");
@@ -1111,8 +1115,8 @@ server.registerTool("get_scaffold_plan", {
 		},
 		extensionPoints: [
 			{
-				what: "브랜드 색·서체",
-				where: "src/styles.css의 @theme"
+				what: "브랜드 색·서체·본문 폭",
+				where: "src/theme.css의 @theme"
 			},
 			{
 				what: "헤더·전역 내비",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sayren/mcp",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "type": "module",
   "bin": {
     "sayren-mcp": "./dist/index.mjs"
@@ -12,8 +12,8 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.22.0",
     "zod": "^4.6.5",
-    "@sayren/store-sdk": "^0.17.0",
-    "@sayren/storefront-sdk": "^0.14.0"
+    "@sayren/storefront-sdk": "^0.15.0",
+    "@sayren/store-sdk": "^0.19.0"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.5.14",

package/template/.template-meta.json

@@ -8,8 +8,8 @@
   },
   "versions": {
     "@sayren/contracts": "0.1.0",
-    "@sayren/store-sdk": "0.17.0",
-    "@sayren/storefront-sdk": "0.14.0",
+    "@sayren/store-sdk": "0.19.0",
+    "@sayren/storefront-sdk": "0.15.0",
     "@sayren/ui": "0.1.0"
   }
 }

package/template/README.md

@@ -97,7 +97,7 @@ EU 등 분석 쿠키에 사전 동의가 필요한 지역의 구매자를 받는
 
 | 자리 | 파일 |
 | --- | --- |
-| 브랜드 색·서체 | `src/styles.css`의 `@theme` |
+| 브랜드 색·서체·본문 폭 | `src/theme.css`의 `@theme` |
 | 헤더·전역 내비 | `src/components/site-header.tsx` |
 | 파비콘 | `public/favicon.svg` |
 | 상품 카드 | `src/components/product-card.tsx` |
@@ -127,6 +127,10 @@ EU 등 분석 쿠키에 사전 동의가 필요한 지역의 구매자를 받는
 - `src/lib/session.server.ts`·`src/start.ts` — 구매자 세션 쿠키와 갱신입니다. 갱신은 요청마다 한 번이고, 같은
   리프레시 토큰의 동시 갱신은 한 번으로 모읍니다. 리프레시 토큰은 한 번 쓰면 폐기되므로 각자 갱신하면 로그아웃됩니다.
   로그아웃은 서버에서 `auth.signOut()`으로 리프레시 토큰을 폐기한 뒤 쿠키를 지웁니다.
+- `src/lib/cookies.server.ts` — 서버 쿠키의 이름과 속성입니다. 프로덕션 빌드는 이름에 `__Host-` 접두사를 붙여
+  같은 상위 도메인의 다른 사이트가 심은 쿠키로 세션이 바뀌지 않게 합니다. 접두사를 빼거나 `Domain`을 주지 않습니다.
+  그래서 빌드 결과는 https(또는 localhost)에서만 로그인·장바구니가 유지됩니다. Safari는 http://localhost의 Secure 쿠키도
+  받지 않으므로 `pnpm start`로 확인할 때는 Chrome·Firefox를 쓰거나 https로 띄웁니다.
 - loader가 서버 함수로 데이터를 받아 그리는 구조 — 컴포넌트에서 다시 받으면 검색 노출과 첫 화면이 죽습니다.
   TanStack Query를 쓰는 화면도 loader의 `ensureQueryData`를 지우지 않습니다.
 - 결제 도메인 — 셀러 콘솔 설정 › 결제의 **결제 도메인**은 선택형 허용 목록입니다. 비워 두면 https 복귀 주소를 모두 받고,

package/template/src/components/fulfillment-codes.tsx

@@ -24,7 +24,7 @@ export function FulfillmentCodes({
   const [pending, setPending] = useState(false);
   const [error, setError] = useState<string | null>(null);
   const codes = item.fulfillment?.status === "FULFILLED" ? (item.fulfillment.codes ?? []) : [];
-  if (item.fulfillmentType !== "CODE" || codes.length === 0) return null;
+  if (item.fulfillmentSnapshot.type !== "CODE" || codes.length === 0) return null;
 
   const open = async () => {
     setPending(true);

package/template/src/components/fulfillment-downloads.tsx

@@ -22,7 +22,7 @@ export function FulfillmentDownloads({
   const [remaining, setRemaining] = useState<number | null>(null);
   const [error, setError] = useState<string | null>(null);
   const info = item.fulfillment?.status === "FULFILLED" ? item.fulfillment.download : null;
-  if (item.fulfillmentType !== "DOWNLOAD" || !info) return null;
+  if (item.fulfillmentSnapshot.type !== "DOWNLOAD" || !info) return null;
 
   const left = remaining ?? Math.max(info.limit - info.count, 0);
   const expired = info.expiresAt !== null && new Date(info.expiresAt).getTime() <= Date.now();

package/template/src/components/site-header.tsx

@@ -14,7 +14,7 @@ export function SiteHeader({ store }: { store: StoreBrand | null }) {
   const name = store?.name ?? "스토어";
   return (
     <header className="border-line border-b">
-      <div className="mx-auto flex w-full max-w-5xl flex-wrap items-center justify-between gap-3 px-4 py-4">
+      <div className="mx-auto flex w-full max-w-page flex-wrap items-center justify-between gap-3 px-4 py-4">
         <Link to="/" className="flex items-center gap-2 font-bold text-lg">
           {store?.logoUrl ? <img src={store.logoUrl} alt={name} className="h-8 w-auto" /> : name}
         </Link>

package/template/src/lib/cart-session.server.ts

@@ -1,4 +1,4 @@
-import { deleteCookie, getCookie, setCookie } from "@tanstack/react-start/server";
+import { clearServerCookie, readServerCookie, writeServerCookie } from "./cookies.server";
 
 /**
  * 비회원 장바구니 토큰 — 서버가 `X-Cart-Token` 헤더로 발급한다. 회원은 액세스 토큰으로
@@ -9,20 +9,14 @@ import { deleteCookie, getCookie, setCookie } from "@tanstack/react-start/server
 const CART_COOKIE = "sayren_cart";
 
 export function readCartToken(): string | null {
-  return getCookie(CART_COOKIE) || null;
+  return readServerCookie(CART_COOKIE) || null;
 }
 
 export function writeCartToken(token: string) {
-  setCookie(CART_COOKIE, token, {
-    httpOnly: true,
-    sameSite: "lax",
-    path: "/",
-    secure: process.env.NODE_ENV === "production",
-    maxAge: 60 * 60 * 24 * 30,
-  });
+  writeServerCookie(CART_COOKIE, token, 60 * 60 * 24 * 30);
 }
 
 /** 로그인하며 회원 장바구니로 합쳐진 뒤 지운다 */
 export function clearCartToken() {
-  deleteCookie(CART_COOKIE, { path: "/" });
+  clearServerCookie(CART_COOKIE);
 }

package/template/src/lib/cookies.server.test.ts

@@ -0,0 +1,54 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+const calls = vi.hoisted(() => ({
+  set: [] as unknown[][],
+  get: [] as unknown[][],
+  delete: [] as unknown[][],
+}));
+
+vi.mock("@tanstack/react-start/server", () => ({
+  setCookie: (...args: unknown[]) => calls.set.push(args),
+  getCookie: (...args: unknown[]) => {
+    calls.get.push(args);
+    return "v";
+  },
+  deleteCookie: (...args: unknown[]) => calls.delete.push(args),
+}));
+
+async function load(prod: boolean) {
+  vi.resetModules();
+  vi.stubEnv("PROD", prod);
+  return import("./cookies.server");
+}
+
+afterEach(() => {
+  vi.unstubAllEnvs();
+  calls.set.length = 0;
+  calls.get.length = 0;
+  calls.delete.length = 0;
+});
+
+describe("서버 쿠키", () => {
+  it("프로덕션은 __Host- 접두사 + Secure·Path=/·Domain 없음으로 쓰고 지운다", async () => {
+    const cookies = await load(true);
+    cookies.writeServerCookie("sayren_member", "x", 60);
+    cookies.readServerCookie("sayren_member");
+    cookies.clearServerCookie("sayren_member");
+    expect(calls.set[0]).toEqual([
+      "__Host-sayren_member",
+      "x",
+      { httpOnly: true, sameSite: "lax", path: "/", secure: true, maxAge: 60 },
+    ]);
+    expect(calls.get[0]).toEqual(["__Host-sayren_member"]);
+    // 옛 이름은 읽지 않는다 — 읽으면 다른 사이트가 심은 쿠키가 다시 통한다
+    expect(calls.get).toHaveLength(1);
+    expect(calls.delete[0]).toEqual(["__Host-sayren_member", { path: "/", secure: true }]);
+  });
+
+  it("개발 서버(http)는 접두사 없이 Secure 없이 쓴다", async () => {
+    const cookies = await load(false);
+    cookies.writeServerCookie("sayren_cart", "t", 10);
+    expect(calls.set[0]?.[0]).toBe("sayren_cart");
+    expect(calls.set[0]?.[2]).toMatchObject({ httpOnly: true, secure: false, path: "/" });
+  });
+});

package/template/src/lib/cookies.server.ts

@@ -0,0 +1,35 @@
+import { deleteCookie, getCookie, setCookie } from "@tanstack/react-start/server";
+
+/**
+ * 서버가 쓰는 쿠키(구매자 세션·비회원 장바구니·소셜 로그인 왕복)의 이름과 속성을 한 곳에서 정한다.
+ *
+ * 프로덕션 빌드는 이름에 `__Host-` 접두사를 붙인다. 브라우저는 이 접두사의 쿠키를 `Secure` + `Path=/` +
+ * `Domain` 없음일 때만 받는다. 그래서 같은 상위 도메인을 쓰는 다른 사이트(예: `other.example.com`)가
+ * `Domain=example.com`으로 심은 쿠키가 이 이름으로 들어오지 못한다. 남이 심은 세션·로그인 상태로
+ * 구매자를 로그인시키는 쿠키 주입을 막는 장치다. 접두사 없는 옛 이름은 읽지 않는다
+ * (읽으면 주입된 쿠키가 다시 통한다). 옛 이름으로 로그인해 있던 구매자는 한 번 다시 로그인한다.
+ *
+ * 개발 서버(http)는 `Secure` 쿠키를 받지 못하는 브라우저가 있어 접두사 없이 쓴다.
+ */
+const SECURE = import.meta.env.PROD;
+
+export const cookieName = (base: string): string => (SECURE ? `__Host-${base}` : base);
+
+export function readServerCookie(base: string): string | undefined {
+  return getCookie(cookieName(base));
+}
+
+export function writeServerCookie(base: string, value: string, maxAgeSec: number) {
+  setCookie(cookieName(base), value, {
+    httpOnly: true,
+    sameSite: "lax",
+    path: "/",
+    secure: SECURE,
+    maxAge: maxAgeSec,
+  });
+}
+
+/** 지울 때도 같은 속성을 준다 — `__Host-` 쿠키는 `Secure`·`Path=/`가 없으면 삭제 헤더도 거부된다 */
+export function clearServerCookie(base: string) {
+  deleteCookie(cookieName(base), { path: "/", secure: SECURE });
+}

package/template/src/lib/order-status.test.ts

@@ -1,29 +1,44 @@
 import { describe, expect, it } from "vitest";
 import { orderItemStatusLabel, withdrawalRestrictedLabel } from "./order-status";
 
+const SHIPPING = { type: "SHIPPING", requiresShipping: true } as const;
+const SERVICE = { type: "SERVICE", requiresShipping: false } as const;
+const PICKUP = { type: "PICKUP", requiresShipping: false } as const;
+
 describe("주문 상품 상태 라벨", () => {
   it("배송 상품은 배송 단계로 보인다", () => {
     expect(orderItemStatusLabel("DELIVERED")).toBe("배송 완료");
-    expect(orderItemStatusLabel("DELIVERED", "SHIPPING")).toBe("배송 완료");
-    expect(orderItemStatusLabel("CONFIRMED", "SHIPPING")).toBe("발송 준비");
+    expect(orderItemStatusLabel("DELIVERED", SHIPPING)).toBe("배송 완료");
+    expect(orderItemStatusLabel("CONFIRMED", SHIPPING)).toBe("발송 준비");
   });
 
   it("배송이 없는 상품의 DELIVERED는 제공 완료, 방문 수령은 수령 완료다", () => {
-    expect(orderItemStatusLabel("DELIVERED", "SERVICE")).toBe("제공 완료");
-    expect(orderItemStatusLabel("DELIVERED", "PICKUP")).toBe("수령 완료");
-    expect(orderItemStatusLabel("CONFIRMED", "SERVICE")).toBe("준비 중");
-    expect(orderItemStatusLabel("PAID", "PICKUP")).toBe("결제 완료");
+    expect(orderItemStatusLabel("DELIVERED", SERVICE)).toBe("제공 완료");
+    expect(orderItemStatusLabel("DELIVERED", PICKUP)).toBe("수령 완료");
+    expect(orderItemStatusLabel("CONFIRMED", SERVICE)).toBe("준비 중");
+    expect(orderItemStatusLabel("PAID", PICKUP)).toBe("결제 완료");
+    // 모르는 유형도 배송 여부로 가른다
+    expect(orderItemStatusLabel("DELIVERED", { type: "OTHER", requiresShipping: false })).toBe(
+      "제공 완료",
+    );
   });
 
   it("모르는 상태는 코드 그대로다", () => {
-    expect(orderItemStatusLabel("ON_HOLD", "SERVICE")).toBe("ON_HOLD");
+    expect(orderItemStatusLabel("ON_HOLD", SERVICE)).toBe("ON_HOLD");
   });
 });
 
 describe("청약철회 제한 표시", () => {
   it("제한 주문상품에만 라벨을 붙인다", () => {
-    expect(withdrawalRestrictedLabel({ withdrawalRestricted: true })).toBe("청약철회 제한 상품");
-    expect(withdrawalRestrictedLabel({ withdrawalRestricted: false })).toBeNull();
-    expect(withdrawalRestrictedLabel({})).toBeNull();
+    const download = (withdrawalRestricted: boolean) => ({
+      fulfillmentSnapshot: {
+        type: "DOWNLOAD" as const,
+        requiresShipping: false as const,
+        download: { withdrawalRestricted },
+      },
+    });
+    expect(withdrawalRestrictedLabel(download(true))).toBe("청약철회 제한 상품");
+    expect(withdrawalRestrictedLabel(download(false))).toBeNull();
+    expect(withdrawalRestrictedLabel({ fulfillmentSnapshot: SERVICE })).toBeNull();
   });
 });

package/template/src/lib/order-status.ts

@@ -1,4 +1,8 @@
-import { isShippingFulfillment, type OrderItemStatus } from "@sayren/storefront-sdk";
+import {
+  type MyOrderItemFulfillmentSnapshot,
+  type OrderItemStatus,
+  withdrawalRestrictedOfView,
+} from "@sayren/storefront-sdk";
 
 /** 주문 상품 상태 라벨 — 화면에 코드 대신 보인다. 서버가 상태를 더하면 코드 그대로 보인다 */
 const ORDER_ITEM_STATUS_LABELS: Record<OrderItemStatus, string> = {
@@ -22,9 +26,16 @@ function nonShippingLabel(status: string, fulfillmentType: string): string | nul
   return null;
 }
 
-export function orderItemStatusLabel(status: string, fulfillmentType?: string | null): string {
-  if (fulfillmentType && !isShippingFulfillment(fulfillmentType)) {
-    const label = nonShippingLabel(status, fulfillmentType);
+/**
+ * 주문 상품 상태 라벨. `fulfillment`는 주문상품의 `fulfillmentSnapshot`(주문 시점 이행)이다 — 배송이 없는 상품은 제공 단계로
+ * 보인다. 모르는 유형도 `requiresShipping`으로 가른다
+ */
+export function orderItemStatusLabel(
+  status: string,
+  fulfillment?: Pick<MyOrderItemFulfillmentSnapshot, "type" | "requiresShipping"> | null,
+): string {
+  if (fulfillment && !fulfillment.requiresShipping) {
+    const label = nonShippingLabel(status, fulfillment.type);
     if (label) return label;
   }
   return ORDER_ITEM_STATUS_LABELS[status as OrderItemStatus] ?? status;
@@ -34,8 +45,10 @@ export function orderItemStatusLabel(status: string, fulfillmentType?: string |
  * 청약철회 제한 주문상품(이슈 #48) — 구매자가 결제 전에 동의했고, 제공이 시작되면(첫 다운로드·열람) 단순 변심 취소·반품을
  * 받지 않는다. 주문 상세·비회원 주문 조회가 상품 옆에 붙인다.
  */
-export function withdrawalRestrictedLabel(item: { withdrawalRestricted?: boolean }): string | null {
-  return item.withdrawalRestricted ? "청약철회 제한 상품" : null;
+export function withdrawalRestrictedLabel(item: {
+  fulfillmentSnapshot: MyOrderItemFulfillmentSnapshot;
+}): string | null {
+  return withdrawalRestrictedOfView(item.fulfillmentSnapshot) ? "청약철회 제한 상품" : null;
 }
 
 /** 제공이 시작된 청약철회 제한 상품의 취소·반품 접수 거절(409 `WITHDRAWAL_RESTRICTED`) 안내 */

package/template/src/lib/session.server.ts

@@ -1,7 +1,7 @@
 import { ApiError, type TokenPair } from "@sayren/storefront-sdk/auth";
 import { getGlobalStartContext } from "@tanstack/react-start";
-import { deleteCookie, getCookie, setCookie } from "@tanstack/react-start/server";
 import { authFor } from "./api.server";
+import { clearServerCookie, readServerCookie, writeServerCookie } from "./cookies.server";
 
 /**
  * 구매자 세션 — 로그인 토큰 쌍을 HttpOnly 쿠키 하나에 둔다. 브라우저 JS는 토큰을 읽지 못하고,
@@ -11,8 +11,12 @@ import { authFor } from "./api.server";
  * 곧 끝나면 리프레시 토큰으로 새 쌍을 받아 쿠키를 갈아 끼운다. 리프레시 토큰이 거부되면(401: 14일 만료·폐기)
  * 쿠키를 지워 로그아웃 상태가 된다. 네트워크 오류·5xx 같은 일시 장애에는 쿠키를 지우지 않는다 — 다음 요청에서
  * 다시 갱신한다.
+ *
+ * 쿠키 이름은 프로덕션에서 `__Host-sayren_member`다(`cookies.server.ts`).
  */
 const SESSION_COOKIE = "sayren_member";
+/** 리프레시 토큰 수명(14일)과 맞춘다 */
+const SESSION_MAX_AGE_SEC = 60 * 60 * 24 * 14;
 
 interface StoredSession {
   accessToken: string;
@@ -53,7 +57,7 @@ function toStored(tokens: TokenPair): StoredSession {
 }
 
 function readSession(): StoredSession | null {
-  const raw = getCookie(SESSION_COOKIE);
+  const raw = readServerCookie(SESSION_COOKIE);
   if (!raw) return null;
   let value: unknown;
   try {
@@ -73,13 +77,8 @@ function readSession(): StoredSession | null {
 }
 
 function writeSession(session: StoredSession) {
-  setCookie(SESSION_COOKIE, JSON.stringify(session), {
-    httpOnly: true,
-    sameSite: "lax",
-    path: "/",
-    secure: process.env.NODE_ENV === "production",
-    maxAge: 60 * 60 * 24 * 14,
-  });
+  // HttpOnly — 브라우저 JS는 토큰을 읽지 못한다(`writeServerCookie`가 httpOnly·sameSite·secure를 싣는다)
+  writeServerCookie(SESSION_COOKIE, JSON.stringify(session), SESSION_MAX_AGE_SEC);
 }
 
 /**
@@ -117,5 +116,5 @@ export function signIn(tokens: TokenPair) {
 
 /** 로그아웃 — 쿠키를 지운다 */
 export function signOut() {
-  deleteCookie(SESSION_COOKIE, { path: "/" });
+  clearServerCookie(SESSION_COOKIE);
 }

package/template/src/lib/social-login.server.ts

@@ -1,4 +1,4 @@
-import { deleteCookie, getCookie, setCookie } from "@tanstack/react-start/server";
+import { clearServerCookie, readServerCookie, writeServerCookie } from "./cookies.server";
 
 /**
  * 소셜 로그인 왕복 상태 — 공급자로 보내기 전에 만든 state·PKCE verifier·돌아갈 곳을 HttpOnly 쿠키에 잠깐 둔다.
@@ -15,17 +15,11 @@ export interface SocialLoginState {
 }
 
 export function writeSocialLogin(value: SocialLoginState) {
-  setCookie(SOCIAL_COOKIE, JSON.stringify(value), {
-    httpOnly: true,
-    sameSite: "lax",
-    path: "/",
-    secure: process.env.NODE_ENV === "production",
-    maxAge: 60 * 10,
-  });
+  writeServerCookie(SOCIAL_COOKIE, JSON.stringify(value), 60 * 10);
 }
 
 export function readSocialLogin(): SocialLoginState | null {
-  const raw = getCookie(SOCIAL_COOKIE);
+  const raw = readServerCookie(SOCIAL_COOKIE);
   if (!raw) return null;
   let value: unknown;
   try {
@@ -50,5 +44,5 @@ export function readSocialLogin(): SocialLoginState | null {
 }
 
 export function clearSocialLogin() {
-  deleteCookie(SOCIAL_COOKIE, { path: "/" });
+  clearServerCookie(SOCIAL_COOKIE);
 }

package/template/src/routes/__root.tsx

@@ -82,11 +82,11 @@ function RootDocument({ children }: { children: React.ReactNode }) {
       <head>
         <HeadContent />
       </head>
-      <body className="min-h-screen bg-white text-ink">
+      <body className="min-h-screen bg-page text-ink">
         {/* URL 검색 파라미터(목록 검색어·카테고리·정렬·페이지)는 nuqs로 읽고 바꾼다 */}
         <NuqsAdapter>
           <SiteHeader store={store} />
-          <main className="mx-auto w-full max-w-5xl px-4 py-8">{children}</main>
+          <main className="mx-auto w-full max-w-page px-4 py-8">{children}</main>
         </NuqsAdapter>
         <Scripts />
       </body>

package/template/src/routes/guest-order.tsx

@@ -215,7 +215,7 @@ function GuestOrder() {
                       <span className="text-muted text-xs">{item.optionName}</span>
                     ) : null}
                     <span className="text-muted text-xs">
-                      {orderItemStatusLabel(item.status, item.fulfillmentType)} · 수량{" "}
+                      {orderItemStatusLabel(item.status, item.fulfillmentSnapshot)} · 수량{" "}
                       {item.quantity}개
                     </span>
                     {withdrawalRestrictedLabel(item) ? (

package/template/src/routes/orders.$orderId.tsx

@@ -230,7 +230,8 @@ function OrderDetail() {
                   <span className="text-muted text-xs">{item.optionName}</span>
                 ) : null}
                 <span className="text-muted text-xs">
-                  {orderItemStatusLabel(item.status, item.fulfillmentType)} · 수량 {item.quantity}개
+                  {orderItemStatusLabel(item.status, item.fulfillmentSnapshot)} · 수량{" "}
+                  {item.quantity}개
                   {item.canceledQuantity > 0
                     ? ` · 취소·반품 ${item.canceledQuantity}개 · 남은 수량 ${item.activeQuantity}개`
                     : null}
@@ -313,7 +314,9 @@ function OrderDetail() {
  * 배송 상품이거나 보여 줄 것이 없으면 그리지 않는다. 배송 상품이 아니므로 배송 조회 링크가 없다.
  */
 function FulfillmentInfo({ item }: { item: MyOrderItem }) {
-  const pickup = item.fulfillmentType === "PICKUP" ? item.pickupLocation : null;
+  const snapshot = item.fulfillmentSnapshot;
+  // 수령 장소는 주문 시점 스냅샷이다 — 셀러가 나중에 수령지를 바꿔도 이 주문의 안내는 그대로다
+  const pickup = snapshot.type === "PICKUP" ? snapshot.pickup.location : null;
   const note = item.fulfillment?.status === "FULFILLED" ? item.fulfillment.note : null;
   if (!pickup && !note) return null;
   return (

package/template/src/routes/products.$productId.tsx

@@ -1,4 +1,4 @@
-import { ApiError } from "@sayren/storefront-sdk";
+import { ApiError, type ProductFulfillmentView } from "@sayren/storefront-sdk";
 import { createFileRoute, Link, notFound, useNavigate } from "@tanstack/react-router";
 import { createServerFn } from "@tanstack/react-start";
 import { useState } from "react";
@@ -59,6 +59,27 @@ export const Route = createFileRoute("/products/$productId")({
   component: ProductDetail,
 });
 
+/** 상품 상세의 받는 방법 한 줄 — 배송 상품은 배송비·예상 기간, 그 밖의 유형은 배송 없이 받는 방법이다 */
+function deliveryNoteOf(fulfillment: ProductFulfillmentView): string {
+  switch (fulfillment.type) {
+    case "SHIPPING": {
+      const { deliveryType, deliveryFee, estimatedDays } = fulfillment.shipping;
+      const fee = deliveryType === "FREE" ? "무료배송" : `배송비 ${formatPrice(deliveryFee)}`;
+      return estimatedDays ? `${fee} · ${estimatedDays}` : fee;
+    }
+    case "DOWNLOAD":
+      return "결제 후 바로 내려받기";
+    case "CODE":
+      return "결제 후 코드 제공";
+    case "PICKUP":
+      return fulfillment.pickup.location
+        ? `방문 수령 · ${fulfillment.pickup.location.name}`
+        : "방문 수령";
+    default:
+      return fulfillment.requiresShipping ? "택배 배송" : "배송 없이 제공";
+  }
+}
+
 function ProductDetail() {
   const product = Route.useLoaderData();
   useTrack({ name: "product_view", productId: product.productId });
@@ -98,12 +119,7 @@ function ProductDetail() {
         <div className="space-y-2">
           <h1 className="font-bold text-2xl">{product.name}</h1>
           <p className="font-bold text-xl">{formatPrice(price)}</p>
-          <p className="text-muted text-sm">
-            {product.delivery.type === "FREE"
-              ? "무료배송"
-              : `배송비 ${formatPrice(product.delivery.fee)}`}
-            {product.delivery.estimatedDays ? ` · ${product.delivery.estimatedDays}` : ""}
-          </p>
+          <p className="text-muted text-sm">{deliveryNoteOf(product.fulfillment)}</p>
         </div>
 
         <form

package/template/src/styles.css

@@ -1,20 +1,14 @@
-@import "tailwindcss";
+/* 클래스는 src/만 훑는다 — 빌드 산출물(dist)·설치물을 훑으면 빌드마다 CSS가 달라지고 서버·브라우저 빌드의 파일 이름이 어긋난다 */
+@import "tailwindcss" source(".");
 /* 상세설명이 에디터가 내보낸 HTML이라 그 모양 규칙이 필요하다 — 사진 줄, 재생기 틀,
    구분선. 활자는 product-description.tsx가 정하고 이 파일은 건드리지 않는다. */
 @import "@avarlabs/editor/styles/reader.css";
 
 /*
- * 확장 지점 — 브랜드 색과 서체는 여기서 바꾼다. 화면 코드는 토큰만 쓰므로
- * 이 블록만 고쳐도 전체 톤이 바뀐다.
+ * 확장 지점 — 브랜드 색·서체·폭은 theme.css의 `@theme`에서 바꾼다. 화면 코드는 토큰만 쓰므로
+ * 그 파일만 고쳐도 전체 톤이 바뀐다.
  */
-@theme {
-  --color-ink: #202429;
-  --color-muted: #5f6773;
-  --color-line: #ededed;
-  --color-chip: #f5f5f5;
-  --color-point: #ff204b;
-  --font-sans: "Pretendard Variable", Pretendard, -apple-system, "Apple SD Gothic Neo", sans-serif;
-}
+@import "./theme.css";
 
 html {
   font-family: var(--font-sans);

package/template/src/theme.css

@@ -0,0 +1,17 @@
+/*
+ * 확장 지점 — 브랜드 색과 서체, 본문 폭은 여기서 바꾼다. 화면 코드는 토큰만 쓰므로
+ * 이 블록만 고쳐도 전체 톤이 바뀐다.
+ *
+ * - page: 페이지 바탕 · ink: 본문 글자와 주요 버튼 · muted: 보조 글자 · line: 구분선 · chip: 옅은 면 · point: 가격·할인 강조
+ * - container-page: 헤더와 본문의 최대 폭(`max-w-page`)
+ */
+@theme {
+  --color-page: #ffffff;
+  --color-ink: #202429;
+  --color-muted: #5f6773;
+  --color-line: #ededed;
+  --color-chip: #f5f5f5;
+  --color-point: #ff204b;
+  --font-sans: "Pretendard Variable", Pretendard, -apple-system, "Apple SD Gothic Neo", sans-serif;
+  --container-page: 64rem;
+}