@sayren/mcp 0.1.8 → 0.1.10

package/dist/index.mjs

@@ -373,12 +373,12 @@ function readWorkspaceVersions(packagesDir) {
 */
 const HERE = dirname(fileURLToPath(import.meta.url));
 /** 번들에 복사된 template/ 이 먼저이고, 저장소에서 바로 실행할 때는 templates/ 를 쓴다 */
-const CANDIDATES = [join(HERE, "..", "template"), join(HERE, "..", "..", "..", "templates", "storefront-react-router")];
+const CANDIDATES = [join(HERE, "..", "template"), join(HERE, "..", "..", "..", "templates", "storefront-tanstack-router")];
 const SKIP_DIRS = new Set([
 	"node_modules",
-	"build",
-	".react-router",
 	"dist",
+	".output",
+	".tanstack",
 	".git"
 ]);
 /**
@@ -491,7 +491,7 @@ async function runCreate(argv) {
 const RULES = [
 	{
 		id: "server-only-env",
-		title: "`process.env`는 `*.server.ts`에만 둔다",
+		title: "`process.env`는 `*.server.ts`에만 두고 서버 함수 안에서 읽는다",
 		why: "브라우저 번들에 들어가면 `process is not defined`로 그 화면 모듈이 통째로 깨진다. 결제 화면에서 터지면 결제가 시작조차 안 된다"
 	},
 	{
@@ -506,7 +506,7 @@ const RULES = [
 	},
 	{
 		id: "loader-first",
-		title: "데이터는 loader에서 받는다",
+		title: "데이터는 라우트 loader에서 받는다(서버 함수 `createServerFn`)",
 		why: "클라이언트에서 다시 받으면 첫 화면이 비고 검색 노출이 죽는다. SSR을 끄지 않는다"
 	},
 	{
@@ -516,7 +516,7 @@ const RULES = [
 	},
 	{
 		id: "popup-client-submit",
-		title: "주문서 제출은 클라이언트 제출(`<Form>`)로 한다",
+		title: "주문서 제출은 클라이언트 제출(`onSubmit` + 서버 함수)로 한다",
 		why: "네이티브 폼은 문서를 다시 그려 팝업 제어 상태가 사라진다. 결제창이 빈 창으로 남는다"
 	},
 	{
@@ -551,6 +551,8 @@ function stripComments(source) {
 }
 const CLIENT_FILE = /\.(ts|tsx)$/;
 const SERVER_FILE = /\.server\.(ts|tsx)$/;
+/** 문서를 다시 부르는 폼 — method나 action을 단 <form> */
+const NATIVE_SUBMIT_FORM = /<form\s[^>]*\b(method|action)=/;
 /**
 * 만들어진 프로젝트의 소스를 규칙과 대조한다. 정적 검사라 모든 문제를 잡지는 못하지만,
 * 여기 있는 것들은 실제로 반복해서 깨지는 것들이다.
@@ -607,10 +609,10 @@ function verifySources(files) {
 			file: file.path,
 			detail: "서버 API 클라이언트에 방문 식별자가 없다. `...analyticsIdsFromCookie(request.headers.get(\"cookie\"))`를 넘긴다"
 		});
-		if (/requestPayment\(/.test(file.content) && /<form\s/.test(file.content)) findings.push({
+		if (/requestPayment\(/.test(file.content) && NATIVE_SUBMIT_FORM.test(file.content)) findings.push({
 			ruleId: "popup-client-submit",
 			file: file.path,
-			detail: "결제 화면이 네이티브 <form>을 쓴다. react-router의 <Form>으로 바꾼다"
+			detail: "결제 화면이 네이티브 폼 제출(method·action)을 쓴다. onSubmit에서 preventDefault 후 서버 함수를 부른다"
 		});
 	}
 	if (has("requestPayment(") && !has("Origin")) findings.push({
@@ -659,7 +661,7 @@ server.registerTool("get_store_context", {
 }, async () => text(await fetchStoreContext(config)));
 server.registerTool("get_scaffold_plan", {
 	title: "스토어프론트 생성 계획",
-	description: "React Router(SSR) 스토어프론트를 만드는 순서와 지켜야 할 규칙, 그리고 템플릿 파일 목록을 준다. 구현을 시작하기 전에 부른다.",
+	description: "TanStack Router(TanStack Start, SSR) 스토어프론트를 만드는 순서와 지켜야 할 규칙, 그리고 템플릿 파일 목록을 준다. 구현을 시작하기 전에 부른다.",
 	inputSchema: {}
 }, async () => {
 	const store = await fetchStoreContext(config).catch(() => null);
@@ -683,26 +685,27 @@ server.registerTool("get_scaffold_plan", {
 		extensionPoints: [
 			{
 				what: "브랜드 색·서체",
-				where: "app/app.css의 @theme"
+				where: "src/styles.css의 @theme"
 			},
 			{
 				what: "헤더·전역 내비",
-				where: "app/components/site-header.tsx"
+				where: "src/components/site-header.tsx"
 			},
 			{
 				what: "상품 카드",
-				where: "app/components/product-card.tsx"
+				where: "src/components/product-card.tsx"
 			},
 			{
 				what: "화면 추가",
-				where: "app/routes.ts"
+				where: "src/routes/ 에 파일 추가(파일 기반 라우트, routeTree.gen.ts는 dev·build가 다시 만든다)"
 			}
 		],
 		doNotTouch: [
-			"app/lib/payment-popup.ts — 결제 팝업 규칙",
-			"app/lib/api.server.ts — 테넌트 헤더·토큰 전달·부모 origin·방문 식별 쿠키",
-			"app/lib/analytics.ts — 방문 분석 시작(브라우저 한 번)과 시작 전 이벤트 큐",
-			"loader에서 데이터를 받는 구조"
+			"src/lib/payment-popup.ts — 결제 팝업 규칙",
+			"src/lib/api.server.ts — 테넌트 헤더·토큰 전달·부모 origin·방문 식별 쿠키",
+			"src/lib/session.server.ts·src/start.ts — 구매자 세션 쿠키와 요청마다 한 번 하는 토큰 갱신",
+			"src/lib/analytics.ts — 방문 분석 시작(브라우저 한 번)과 시작 전 이벤트 큐",
+			"라우트 loader가 서버 함수(createServerFn)로 데이터를 받는 구조"
 		],
 		rules: RULES,
 		templateFiles: listTemplateFiles()
@@ -841,9 +844,9 @@ server.registerTool("verify_storefront", {
 });
 const SKIP = new Set([
 	"node_modules",
-	"build",
 	"dist",
-	".react-router",
+	".output",
+	".tanstack",
 	".git"
 ]);
 async function collectSources(dir) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sayren/mcp",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "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.5.0",
-    "@sayren/storefront-sdk": "^0.6.0"
+    "@sayren/storefront-sdk": "^0.7.0",
+    "@sayren/store-sdk": "^0.7.0"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.5.14",

package/template/.template-meta.json

@@ -7,8 +7,8 @@
     "zod": "^4.6.5"
   },
   "versions": {
-    "@sayren/store-sdk": "0.5.0",
-    "@sayren/storefront-sdk": "0.6.0",
+    "@sayren/store-sdk": "0.7.0",
+    "@sayren/storefront-sdk": "0.7.0",
     "@sayren/ui": "0.1.0"
   }
 }

package/template/README.md

@@ -1,4 +1,4 @@
-# 스토어프론트 템플릿 (React Router SSR)
+# 스토어프론트 템플릿 (TanStack Router · TanStack Start SSR)
 
 sayren MCP가 내려주는 스토어프론트 시작점이다. 구매 흐름 전체가 이미 붙어 있다.
 홈, 목록·검색, 상세, 장바구니, 주문서·결제 팝업, 완료, 로그인, 주문 내역이다.
@@ -19,34 +19,51 @@ pnpm dev
 | `SAYREN_ANALYTICS_DEBUG` | `1`이면 localhost에서도 방문 분석을 보낸다 |
 
 `pnpm dev`는 프로젝트 루트의 `.env`에서 `SAYREN_*`를 읽는다. 셸에서 준 값이 우선한다.
-`pnpm start`(빌드 결과 실행)는 `.env`를 읽지 않으므로 환경변수로 넘긴다.
+`pnpm build`는 `dist/`에 클라이언트와 서버 번들을 만들고, `pnpm start`는 그 결과를 띄워 확인한다.
+운영 배포는 호스팅에 맞는 TanStack Start 배포 설정(Node 서버, Cloudflare Workers, Vercel 등)을 더한다.
+
+## 구조
+
+| 자리 | 하는 일 |
+| --- | --- |
+| `src/routes/` | 파일 기반 라우트. 파일 이름이 곧 경로다(`products.$productId.tsx` → `/products/:productId`) |
+| `src/routeTree.gen.ts` | 라우트 트리. `pnpm dev`·`pnpm build`가 다시 만든다. 손으로 고치지 않는다 |
+| `src/start.ts` | 전역 요청 미들웨어. 서버 함수 CSRF 검사와 구매자 세션 갱신 |
+| `src/lib/*.server.ts` | 서버 전용 코드. `process.env`·쿠키·API 클라이언트는 여기에만 둔다 |
+
+화면 데이터는 라우트 `loader`가 서버 함수(`createServerFn`)를 불러 받는다. 첫 요청은 서버에서 그리고, 이후 이동은
+브라우저가 같은 서버 함수를 호출한다. 담기·결제 요청·로그인 같은 쓰기도 서버 함수라 토큰이 브라우저 JS에 나가지 않는다.
 
 ## 방문 분석
 
-`app/lib/analytics.ts`가 브라우저에서 방문 분석을 시작한다. 페이지뷰·체류는 자동으로 세고, 상품 조회·목록 노출·검색은
-화면에서 `useTrack`으로 남긴다. 장바구니·결제·구매는 `app/lib/api.server.ts`가 방문자 쿠키를 API 요청 헤더에 실어
+`src/lib/analytics.ts`가 브라우저에서 방문 분석을 시작한다. 페이지뷰·체류는 자동으로 세고, 상품 조회·목록 노출·검색은
+화면에서 `useTrack`으로 남긴다. 장바구니·결제·구매는 `src/lib/api.server.ts`가 방문자 쿠키를 API 요청 헤더에 실어
 서버가 기록한다. localhost에서는 보내지 않는다. 개발 중에 확인하려면 `SAYREN_ANALYTICS_DEBUG=1`을 준다.
 동의 기본값은 `granted`(바로 수집)다. 개인정보를 저장하지 않는 1st-party 쿠키라 국내 쇼핑몰 기준으로 정했다.
-EU 등 분석 쿠키에 사전 동의가 필요한 지역의 구매자를 받는다면 `app/lib/analytics.ts`의 `consent`를 `"pending"`으로 바꾸고,
+EU 등 분석 쿠키에 사전 동의가 필요한 지역의 구매자를 받는다면 `src/lib/analytics.ts`의 `consent`를 `"pending"`으로 바꾸고,
 쿠키 동의 배너에서 `setConsent("granted" | "denied")`를 부른다. 동의 전에는 쿠키를 만들지 않고 이벤트를 모아 두었다가 동의하면 보낸다.
 
 ## 확장 지점
 
 | 자리 | 파일 |
 | --- | --- |
-| 브랜드 색·서체 | `app/app.css`의 `@theme` |
-| 헤더·전역 내비 | `app/components/site-header.tsx` |
-| 상품 카드 | `app/components/product-card.tsx` |
-| 화면 추가 | `app/routes.ts` |
+| 브랜드 색·서체 | `src/styles.css`의 `@theme` |
+| 헤더·전역 내비 | `src/components/site-header.tsx` |
+| 상품 카드 | `src/components/product-card.tsx` |
+| 화면 추가 | `src/routes/`에 파일 추가 |
 
 ## 건드리지 않는 편이 좋은 것
 
-- `app/lib/payment-popup.ts` — 결제 팝업 규칙이다. 팝업은 클릭 콜스택에서 동기적으로 열고,
+- `src/lib/payment-popup.ts` — 결제 팝업 규칙이다. 팝업은 클릭 콜스택에서 동기적으로 열고,
   postMessage는 origin과 source를 모두 검증하며, 결과 없이 닫히면 서버에 상태를 물어본다.
   하나라도 어기면 결제가 조용히 실패한다.
-- `app/lib/api.ts` — 테넌트 헤더와 토큰 전달 방식이다. 토큰을 모듈 전역에 담으면 서버 렌더에서
+- `src/lib/api.server.ts` — 테넌트 헤더와 토큰 전달 방식이다. 토큰을 모듈 전역에 담으면 서버 렌더에서
   다른 사용자의 요청에 섞인다.
-- loader에서 데이터를 받아 그리는 구조 — 클라이언트에서 다시 받으면 검색 노출과 첫 화면이 죽는다.
+- `src/lib/session.server.ts`·`src/start.ts` — 구매자 세션 쿠키와 갱신이다. 갱신은 요청마다 한 번이고, 같은
+  리프레시 토큰의 동시 갱신은 한 번으로 모은다. 리프레시 토큰은 한 번 쓰면 폐기되므로 각자 갱신하면 로그아웃된다.
+- loader가 서버 함수로 데이터를 받아 그리는 구조 — 컴포넌트에서 다시 받으면 검색 노출과 첫 화면이 죽는다.
+- 주문서 제출 방식 — `onSubmit`에서 `preventDefault` 후 서버 함수를 부른다. 네이티브 폼 제출은 문서를 다시 불러
+  열어 둔 결제 팝업의 제어를 잃는다.
 
 ## 주의
 

package/template/_gitignore

@@ -1,4 +1,6 @@
-.react-router/
-build/
 node_modules/
+dist/
+.output/
+.tanstack/
+.nitro/
 .env

package/template/package.json

@@ -1,35 +1,33 @@
 {
-  "name": "@sayren/template-storefront-react-router",
+  "name": "@sayren/template-storefront-tanstack-router",
   "version": "0.1.0",
   "private": true,
   "type": "module",
   "scripts": {
-    "dev": "react-router dev --port 4010",
-    "build": "react-router build",
-    "start": "react-router-serve ./build/server/index.js",
+    "dev": "vite dev --port 4010",
+    "build": "vite build",
+    "start": "vite preview --port 4010",
     "lint": "biome check --write . && tsc --noEmit",
-    "typecheck": "react-router typegen && tsc --noEmit",
+    "typecheck": "tsc --noEmit",
     "test": "vitest run"
   },
   "dependencies": {
     "@avarlabs/editor": "^0.1.0",
-    "@react-router/node": "^8.4.0",
-    "@react-router/serve": "^8.4.0",
     "@sayren/storefront-sdk": "workspace:*",
     "@tailwindcss/vite": "^4.3.3",
-    "isbot": "^5.1.0",
+    "@tanstack/react-router": "^1.170.38",
+    "@tanstack/react-start": "^1.168.56",
     "react": "^19.3.0",
     "react-dom": "^19.3.0",
-    "react-router": "^8.4.0",
     "tailwindcss": "^4.3.3",
     "zod": "catalog:"
   },
   "devDependencies": {
     "@biomejs/biome": "catalog:",
-    "@react-router/dev": "^8.4.0",
     "@types/node": "^24.13.5",
     "@types/react": "^19.3.0",
     "@types/react-dom": "^19.3.0",
+    "@vitejs/plugin-react": "^6.1.1",
     "typescript": "catalog:",
     "vite": "^8.3.0",
     "vitest": "catalog:"

package/template/{app → src}/components/product-card.tsx

@@ -1,5 +1,5 @@
 import type { ProductCard as ProductCardData } from "@sayren/storefront-sdk";
-import { Link } from "react-router";
+import { Link } from "@tanstack/react-router";
 import { formatPrice } from "../lib/format";
 
 /** 상품 카드 — 확장 지점: 찜 버튼·리뷰 별점 같은 요소는 여기에 붙인다 */
@@ -7,7 +7,11 @@ export function ProductCard({ product }: { product: ProductCardData }) {
   const price = product.discountedPrice ?? product.salePrice;
 
   return (
-    <Link to={`/products/${product.productId}`} className="group flex flex-col gap-2">
+    <Link
+      to="/products/$productId"
+      params={{ productId: product.productId }}
+      className="group flex flex-col gap-2"
+    >
       <div className="relative aspect-square overflow-hidden rounded-lg bg-chip">
         <img
           src={product.thumbnailUrl}

package/template/{app → src}/components/product-description.tsx

@@ -10,7 +10,7 @@
  * 가 React가 이스케이프 렌더 → XSS·표시 깨짐이 모두 방지된다.
  *
  * 확장 지점 — 활자(본문 크기·제목·인용)는 아래 클래스가 정한다. 사진 줄·재생기 틀·
- * 구분선 같은 에디터 고유 모양은 `app.css`가 불러오는 reader.css가 맡는다.
+ * 구분선 같은 에디터 고유 모양은 `styles.css`가 불러오는 reader.css가 맡는다.
  */
 const EDITOR_HTML_START = /^\s*<(?:p|h[1-6]|ul|ol|hr|figure|table|blockquote|pre)[\s>/]/i;
 

package/template/{app → src}/components/site-header.tsx

@@ -1,4 +1,4 @@
-import { Link } from "react-router";
+import { Link } from "@tanstack/react-router";
 
 /** 확장 지점 — 로고·전역 내비게이션은 여기서 바꾼다 */
 export function SiteHeader() {
@@ -18,6 +18,9 @@ export function SiteHeader() {
           <Link to="/orders" className="hover:text-point">
             주문 내역
           </Link>
+          <Link to="/account" className="hover:text-point">
+            내 정보
+          </Link>
         </nav>
       </div>
     </header>

package/template/src/components/submit-button.tsx

@@ -0,0 +1,32 @@
+import { useHydrated } from "@tanstack/react-router";
+
+/**
+ * 제출 버튼 — 하이드레이션 전 클릭은 onSubmit이 붙기 전이라 유실되거나 문서를 다시 부른다.
+ * 붙은 뒤에만 누를 수 있게 한다.
+ */
+export function SubmitButton({
+  disabled,
+  className,
+  name,
+  value,
+  children,
+}: {
+  disabled?: boolean;
+  className: string;
+  name?: string;
+  value?: string;
+  children: React.ReactNode;
+}) {
+  const hydrated = useHydrated();
+  return (
+    <button
+      type="submit"
+      name={name}
+      value={value}
+      disabled={!hydrated || disabled}
+      className={className}
+    >
+      {children}
+    </button>
+  );
+}

package/template/{app → src}/lib/analytics.ts

@@ -13,7 +13,7 @@ import { useEffect } from "react";
  * 기록한다(`api.server.ts`가 방문자·세션 쿠키를 헤더로 싣는다).
  */
 
-/** 루트 loader가 내려주는 값 */
+/** 루트 loader(서버 함수)가 내려주는 값 */
 export interface AnalyticsConfig {
   apiBaseUrl: string;
   storeCode: string;

package/template/{app → src}/lib/api.server.ts

@@ -1,9 +1,10 @@
 import { analyticsIdsFromCookie, createStorefrontClient } from "@sayren/storefront-sdk";
 import { createStorefrontAuth } from "@sayren/storefront-sdk/auth";
+import { getRequest } from "@tanstack/react-start/server";
 import { API_BASE_URL, resolveStoreCode } from "./config.server";
 
 /**
- * 서버(loader·action)에서 쓰는 스토어프론트 API 클라이언트.
+ * 서버(서버 함수·서버 라우트)에서 쓰는 스토어프론트 API 클라이언트.
  *
  * 테넌트는 `X-Store-Code` 헤더로 보낸다. 토큰은 요청마다 넘긴다 — 모듈 전역에 담으면 서버 렌더에서
  * 다른 사용자의 요청에 섞인다.
@@ -13,16 +14,16 @@ import { API_BASE_URL, resolveStoreCode } from "./config.server";
  * 비회원 장바구니 토큰은 서버가 새로 발급할 수 있다. `onCartToken`으로 받아 쿠키에 다시 심는다.
  */
 export function apiFor(
-  request: Request,
   options: {
     accessToken?: string | null;
     cartToken?: string | null;
     onCartToken?: (token: string) => void;
   } = {},
 ) {
+  const request = getRequest();
   return createStorefrontClient({
     baseUrl: API_BASE_URL,
-    storeCode: resolveStoreCode(request),
+    storeCode: resolveStoreCode(),
     accessToken: options.accessToken ?? undefined,
     cartToken: options.cartToken ?? undefined,
     onCartToken: options.onCartToken,
@@ -41,6 +42,6 @@ export function apiFor(
  * 구매자 인증 — 로그인·가입·비회원 세션·토큰 갱신. 화면은 이 앱이 그리고 계정은 sayren이 보관한다.
  * 결과 토큰은 `session.server.ts`가 HttpOnly 쿠키에 둔다.
  */
-export function authFor(request: Request) {
-  return createStorefrontAuth({ baseUrl: API_BASE_URL, storeCode: resolveStoreCode(request) });
+export function authFor() {
+  return createStorefrontAuth({ baseUrl: API_BASE_URL, storeCode: resolveStoreCode() });
 }

package/template/{app → src}/lib/api.ts

@@ -1,7 +1,7 @@
 import { createStorefrontClient } from "@sayren/storefront-sdk";
 import type { PublicConfig } from "./config";
 
-/** 브라우저용 — loader가 내려준 설정으로 만든다(결제 상태 폴링에 쓴다) */
+/** 브라우저용 — 서버 함수가 내려준 설정으로 만든다(결제 상태 폴링에 쓴다) */
 export function browserApi(config: PublicConfig) {
   return createStorefrontClient({ baseUrl: config.apiBaseUrl, storeCode: config.storeCode });
 }

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

@@ -0,0 +1,28 @@
+import { deleteCookie, getCookie, setCookie } from "@tanstack/react-start/server";
+
+/**
+ * 비회원 장바구니 토큰 — 서버가 `X-Cart-Token` 헤더로 발급한다. 회원은 액세스 토큰으로
+ * 장바구니를 찾지만 비회원은 이 토큰이 유일한 열쇠라, 잃어버리면 담은 상품이 사라진다.
+ *
+ * 서버 함수·서버 라우트 안에서만 부른다(요청 쿠키를 읽고 응답 쿠키를 쓴다).
+ */
+const CART_COOKIE = "sayren_cart";
+
+export function readCartToken(): string | null {
+  return getCookie(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,
+  });
+}
+
+/** 로그인하며 회원 장바구니로 합쳐진 뒤 지운다 */
+export function clearCartToken() {
+  deleteCookie(CART_COOKIE, { path: "/" });
+}

package/template/src/lib/checkout-intent.test.ts

@@ -0,0 +1,27 @@
+import { describe, expect, it } from "vitest";
+import { checkoutIntentFrom, checkoutSearch } from "./checkout-intent";
+
+describe("주문서 진입 의도", () => {
+  it("장바구니 항목이 있으면 장바구니 주문이다", () => {
+    expect(checkoutIntentFrom(checkoutSearch.parse({ cartItemId: ["a", "b"] }))).toEqual({
+      cartItemIds: ["a", "b"],
+    });
+    expect(checkoutIntentFrom(checkoutSearch.parse({ cartItemId: "a" }))).toEqual({
+      cartItemIds: ["a"],
+    });
+  });
+
+  it("상품이 있으면 바로구매이고 수량은 1 이상 정수로 맞춘다", () => {
+    expect(checkoutIntentFrom(checkoutSearch.parse({ productId: "p", quantity: "2.7" }))).toEqual({
+      directItem: { productId: "p", optionId: undefined, quantity: 2 },
+    });
+    expect(
+      checkoutIntentFrom(checkoutSearch.parse({ productId: "p", optionId: "o", quantity: -1 })),
+    ).toEqual({ directItem: { productId: "p", optionId: "o", quantity: 1 } });
+  });
+
+  it("조건이 없으면 null이다", () => {
+    expect(checkoutIntentFrom(checkoutSearch.parse({}))).toBeNull();
+    expect(checkoutIntentFrom(checkoutSearch.parse({ cartItemId: [] }))).toBeNull();
+  });
+});

package/template/{app → src}/lib/checkout-intent.ts

@@ -1,5 +1,7 @@
+import { z } from "zod";
+
 /**
- * 주문서 진입 의도 — URL 파라미터로 받는다.
+ * 주문서 진입 의도 — URL 검색 파라미터로 받는다.
  *
  * 스토어프론트 API에는 "만들어 둔 주문서 다시 조회"가 없다. 주문서 세션은 만들 때 한 번 내려오고
  * 짧게 만료된다. 그래서 주문서 화면은 들어올 때마다 세션을 새로 만든다. 조건이 URL에 있으면
@@ -8,22 +10,32 @@
  * 값을 사용자가 바꿀 수 있지만 위험하지 않다. 장바구니 항목은 장바구니 토큰으로 소유가 확인되고,
  * 가격·재고는 서버가 다시 계산한다.
  */
+export const checkoutSearch = z.object({
+  cartItemId: z
+    .union([z.string(), z.array(z.string())])
+    .optional()
+    .catch(undefined),
+  productId: z.string().optional().catch(undefined),
+  optionId: z.string().optional().catch(undefined),
+  quantity: z.coerce.number().optional().catch(undefined),
+});
+export type CheckoutSearch = z.infer<typeof checkoutSearch>;
+
 export interface CheckoutIntent {
   cartItemIds?: string[];
   directItem?: { productId: string; optionId?: string; quantity: number };
 }
 
-export function checkoutIntentFrom(params: URLSearchParams): CheckoutIntent | null {
-  const cartItemIds = params.getAll("cartItemId").filter(Boolean);
+export function checkoutIntentFrom(search: CheckoutSearch): CheckoutIntent | null {
+  const cartItemIds = [search.cartItemId ?? []].flat().filter(Boolean);
   if (cartItemIds.length) return { cartItemIds };
 
-  const productId = params.get("productId");
-  if (!productId) return null;
-  const quantity = Number(params.get("quantity") ?? 1);
+  if (!search.productId) return null;
+  const quantity = search.quantity ?? 1;
   return {
     directItem: {
-      productId,
-      optionId: params.get("optionId") ?? undefined,
+      productId: search.productId,
+      optionId: search.optionId || undefined,
       quantity: Number.isFinite(quantity) && quantity > 0 ? Math.floor(quantity) : 1,
     },
   };

package/template/{app → src}/lib/config.server.ts

@@ -1,8 +1,9 @@
+import { getRequestHeader } from "@tanstack/react-start/server";
 import { storeCodeFromHost } from "./config";
 
 /**
  * 서버 전용 설정 — `.server.ts`라 브라우저 번들에 들어가지 않는다. `process.env`를 여기에만 둔다.
- * 브라우저에 필요한 값은 loader가 내려준다(`PublicConfig`).
+ * 브라우저에 필요한 값은 서버 함수가 내려준다(`PublicConfig`).
  */
 export const API_BASE_URL = process.env.SAYREN_API_URL ?? "https://api.sayren.app/storefront/v1";
 
@@ -11,10 +12,10 @@ export const ANALYTICS_DEBUG = process.env.SAYREN_ANALYTICS_DEBUG === "1";
 
 const FIXED_STORE_CODE = process.env.SAYREN_STORE_CODE ?? "";
 
-/** 요청에서 테넌트를 정한다 — 고정 값이 먼저이고, 없으면 호스트 서브도메인에서 뽑는다 */
-export function resolveStoreCode(request: Request): string {
+/** 이 요청의 테넌트 — 고정 값이 먼저이고, 없으면 호스트 서브도메인에서 뽑는다 */
+export function resolveStoreCode(): string {
   if (FIXED_STORE_CODE) return FIXED_STORE_CODE;
-  const fromHost = storeCodeFromHost(request.headers.get("host"));
+  const fromHost = storeCodeFromHost(getRequestHeader("host"));
   if (fromHost) return fromHost;
   throw new Error(
     "스토어 코드를 알 수 없어요. SAYREN_STORE_CODE 환경변수를 설정하거나 서브도메인으로 서비스해주세요",

package/template/{app → src}/lib/config.ts

@@ -12,7 +12,7 @@ export function storeCodeFromHost(host: string | null | undefined): string | nul
   return labels.length >= 3 ? (labels[0] ?? null) : null;
 }
 
-/** loader가 브라우저로 내려주는 값 */
+/** 서버 함수가 브라우저로 내려주는 값 */
 export interface PublicConfig {
   apiBaseUrl: string;
   storeCode: string;

package/template/src/lib/format.test.ts

@@ -0,0 +1,14 @@
+import { describe, expect, it } from "vitest";
+import { formatDateTime, formatPrice } from "./format";
+
+describe("표시 형식", () => {
+  it("가격은 천 단위로 끊고 원을 붙인다", () => {
+    expect(formatPrice(129000)).toBe("129,000원");
+  });
+
+  it("시각은 서울 시간 24시간제 숫자로 쓴다(서버·브라우저 결과가 같다)", () => {
+    expect(formatDateTime("2026-09-24T13:05:00.000Z")).toBe("2026. 9. 24. 22:05");
+    expect(formatDateTime("2026-09-24T15:00:00.000Z")).toBe("2026. 9. 25. 00:00");
+    expect(formatDateTime(null)).toBe("-");
+  });
+});

package/template/src/lib/format.ts

@@ -0,0 +1,30 @@
+const KRW = new Intl.NumberFormat("ko-KR");
+
+export function formatPrice(amount: number): string {
+  return `${KRW.format(amount)}원`;
+}
+
+/**
+ * 서버가 그린 글자와 하이드레이션 결과가 같아야 한다. 그래서 시간대를 고정하고(서버는 대개 UTC), 로케일 문구
+ * ("오후" 같은 말)는 쓰지 않고 숫자만 조립한다. 로케일 데이터가 적게 들어간 Node 빌드에서도 결과가 같다.
+ * 다른 나라 구매자를 받으면 `TIME_ZONE`을 바꾼다.
+ */
+const TIME_ZONE = "Asia/Seoul";
+
+const DATE_PARTS = new Intl.DateTimeFormat("en-US", {
+  timeZone: TIME_ZONE,
+  year: "numeric",
+  month: "numeric",
+  day: "numeric",
+  hour: "2-digit",
+  minute: "2-digit",
+  hourCycle: "h23",
+});
+
+/** `2026. 9. 24. 22:05` */
+export function formatDateTime(value: string | null | undefined): string {
+  if (!value) return "-";
+  const parts: Record<string, string> = {};
+  for (const part of DATE_PARTS.formatToParts(new Date(value))) parts[part.type] = part.value;
+  return `${parts.year}. ${parts.month}. ${parts.day}. ${parts.hour}:${parts.minute}`;
+}

package/template/{app → src}/lib/safe-redirect.ts

@@ -3,7 +3,7 @@
  * `//evil.com`과 `/\evil.com`은 브라우저가 외부 주소로 해석하므로 두 번째 글자가 `/`·`\`면 거부하고,
  * 제어 문자(탭·개행은 URL 파싱에서 지워진다)도 거부한다.
  */
-export function safeRedirect(value: FormDataEntryValue | null): string {
+export function safeRedirect(value: unknown): string {
   const fallback = "/orders";
   if (typeof value !== "string" || !value.startsWith("/")) return fallback;
   if (value[1] === "/" || value[1] === "\\") return fallback;