# Visual Design Contract `AGENTS.md` is the canonical statement of the blank-canvas rule — check `app/routes/_index.tsx` and `app/global.css`, preserve any real UI/brand already there, and only treat the canvas as blank when those files still show the starter's placeholder. This file does not restate that rule; it records **this app's** visual direction. The fields below are the source of truth for that direction: once filled in, read and preserve them on every build; while they are still empty, the first substantial UI pass fills them in. ## Non-negotiable: impress by default When this app is still a blank canvas, every app generated from this template must look **spectacular on first load**, even when the build prompt gives no design direction. "Looks like a clean, intentional product" is the floor, not the goal. When no direction is supplied, you still commit to one — do not default to safe gray SaaS: - Commit to one concrete visual world (see the `frontend-design` skill and its `references/visual-direction.md`). Do not ship the neutral placeholder theme. - Choose a product-fitting accent family and set it in the `app/global.css` tokens for **both** light and dark. Never leave the 0%-saturation default as the shipped palette. - Establish a clear type hierarchy, a consistent spacing rhythm, and one signature detail (a considered empty state, a distinctive header, a crafted primary action) that makes the surface feel designed for its domain. - Get focus, hover, empty, loading, and dark-mode states right — that polish is the difference between an AI demo and a product. Pick a direction and execute it fully; never average toward generic SaaS. Once a direction is established and recorded below, preserve and extend it rather than starting over unless otherwise directed to. ## Fill in before building the first surface Once the fields below are filled in, they describe this app's established visual direction — read and preserve them on every subsequent build; do not re-derive a new direction. The first UI pass must fill these fields in as part of that build, not leave them as an empty template. - Product mode: `experience` - Audience and cadence: Thai moviegoers browsing independent cinemas; occasional discovery. - Visual world (name + the feeling it creates): Dim indie screening room — friendly, warm, a little playful (pixel-style logo, rounded chips and cards). - Palette family + neutral undertone: Cinema crimson (#8F0808 / #A92626 / #D47272) on near-black neutrals (#0D0D0D, #1B1B1B, #242424) with a slight warm cast. - Type treatment: Inter + Noto Sans Thai; Jersey 15 pixel face for the AlterFlixHub wordmark only. เนื้อความยาว (บทความ/ย่อหน้าอ่านต่อเนื่อง เช่นหน้า /about) ใช้ `font-content` = IBM Plex Sans Thai Looped (มีหัว, 400/500) — หัวข้อและ UI ยังเป็น Inter + Noto Sans Thai ตามเดิม - Composition: Full-bleed hero with crimson glow, centered glass search box, 4-column card grid at 1224px max. - Shape language: Soft radii (8px controls, 18px pills, 16-20px cards), frosted-glass panels. - Anti-references (defaults this app must not drift toward): Gray SaaS dashboards, light themes, neon gradients, heavy chrome. ## โลโก้ (ห้ามเปลี่ยนแปลง — ห้ามตีความใหม่) สเปกนี้เป็นข้อบังคับ ใช้กับทุกหน้าและทุกภาษาที่รองรับ: | หัวข้อ | ค่าที่กำหนด | |---|---| | คำ | `AlterFlixHub` — ตัวสะกด/ตัวพิมพ์นี้เท่านั้น (ไม่ ALL CAPS, ไม่เว้นวรรค, ไม่แปล) | | ฟอนต์ | `Jersey 15` **เท่านั้น** ห้ามใช้ Inter หรือฟอนต์อื่นแทน | | น้ำหนัก/สไตล์ | ตามฟอนต์ดั้งเดิม — ห้ามใส่ bold/italic/uppercase/letter-spacing/เงา/ไล่สี | | สี | `#8F0808` เท่านั้น (ทุกสถานะ รวม hover/active) | | ขนาด header (navbar) | `text-4xl` = **36px** | | ขนาด footer | `text-2xl` = **24px** | | ตำแหน่ง | header: element แรก ชิดซ้ายสุด และคลิกกลับหน้าแรกได้ · footer: ซ้ายสุดของแถว | - ไม่อนุญาตให้เพิ่มขนาดที่สาม หรือเปลี่ยนสี/ฟอนต์แม้ในสถานะ hover/active - ใช้ `Logo` เป็นข้อความแทนช่องรูปที่ยังไม่มีในแกลเลอรีหน้าโรงหนัง (`Gallery`) — ช่องหลัก `size="md"` (36px), ช่องย่อย `size="sm"` (24px) เท่านั้น; ข้อความ alt ยังใช้ `gallery.main/second/third` เพื่อการเข้าถึง - การเปลี่ยนใด ๆ ต้องได้อนุมัติจากเจ้าของโปรเจกต์ก่อน แล้วอัปเดตพร้อมกันทั้งตารางนี้, `LOGO_SPEC` (`app/lib/design-tokens.ts`) และ `app/components/site/Logo.spec.ts` - ตัวบังคับเชิงโค้ด: `Logo` อ่านค่าจาก `LOGO_SPEC` ผ่าน `logoClasses()` — ถ้ามีคนแก้สเปก เทสต์ `Logo.spec.ts` จะพังทันที ## Layout contract (บังคับ) - หน้าเว็บจบที่ footer เสมอ: `SiteShell` เป็น `flex flex-col min-h-dvh` + เนื้อหาอยู่ใน `flex-1` (block ไม่ใช่ flex-col เพื่อไม่ให้ `main` ที่มี `mx-auto` หดเป็น max-content) - ของตกแต่งพื้นหลัง (รูปฮีโร่, gradient, glow) ต้องอยู่ใน `BackdropFrame` = `absolute inset-0 overflow-hidden` เสมอ — ถ้าปล่อยเป็น absolute ลอย ๆ ที่ใช้ `top-[…px]`/`bottom` ค่าเยอะ ๆ จะยืด `scrollHeight` ให้ยาวเกินเนื้อหา ทำให้มีพื้นที่ว่างเลื่อนได้ใต้ footer - แสงที่ต้องอยู่ช่วงล่างของหน้าให้ยึด `bottom-*` ไม่ใช่ `top-[px]` ตายตัว เพราะความสูงหน้าเปลี่ยนตามจำนวนการ์ดที่แสดง ## Motion contract (บังคับ) - อนิเมชันทั้งหมดอยู่ใน `app/global.css` ใต้ `html.fx-motion` — คลาสนี้ถูกใส่โดยสคริปต์ใน `` (`MOTION_INIT_SCRIPT`, `app/lib/motion.ts`) **เฉพาะเมื่อผู้ใช้ไม่ได้ขอ `prefers-reduced-motion: reduce`** → ปิด JS หรือ reduced motion = ไม่มีอะไรถูกซ่อน (ห้ามเขียน `opacity:0` นอกขอบเขตนี้) - ใช้ `transform`/`opacity` เท่านั้น ห้าม animate `width/height/top/left` · ระยะเวลา: เร็ว 160ms · ปกติ 280ms · **เปลี่ยนหน้า 460ms (`--fx-page`)** · reveal 640ms · หน่วงต่อชิ้นไม่เกิน ~240ms - "ค่อย ๆ โผล่เมื่อเลื่อนถึง" ใช้ `useReveal` (`app/hooks/use-reveal.ts`) หรือ `` (`app/components/site/Reveal.tsx`) — มีกฎกันค้างซ่อน: บล็อกที่เลื่อนผ่านไปแล้ว (หรือถูกข้ามด้วยการกระโดด scroll) ต้องโผล่ทันที - hover ของการ์ดใช้ `translate` (Tailwind `hover:-translate-y-1`) ไม่ใช้ `transform` เพราะชนกับ keyframe ของ reveal · ทุกอนิเมชันต้องมีคู่มือปิดใน `@media (prefers-reduced-motion: reduce)` ## PWA & accessibility contract (บังคับ) - **ติดตั้งได้**: `` อยู่ใน `app/root.tsx` (ห้ามลบ) · `public/manifest.json` ต้องมี `display: standalone`, `id`, `scope`, `start_url: "/"`, `lang` และไอคอน **PNG** 192/512 + maskable 512 (Chrome ไม่รับ SVG, iOS ไม่รับ SVG) · `apple-touch-icon` ต้องชี้ `icon-180.png` - **ไอคอน**: ไฟล์จริงคือ `public/icon-192.png` / `icon-512.png` / `icon-maskable-512.png` / `icon-180.png` (สร้างจาก PNG 1024 ที่ฝังอยู่ใน `icon-512.svg`) — SVG เดิมเหลือไว้เป็น favicon เท่านั้น - **service worker**: `public/sw.js` — หน้าเว็บ network-first (ออฟไลน์ → แคชหน้า → `offline.html`), static cache-first + revalidate เบื้องหลัง, ไม่แคช `/api/*` และไม่แตะ `/app/*` `/node_modules/*` `/@*` (โมดูล dev) · ลงทะเบียนผ่าน `app/lib/pwa.ts` + `` ใน `root.tsx` - **ทุกครั้งที่ปล่อยเวอร์ชัน ให้ bump `VERSION` ใน `public/sw.js`** — `activate` จะลบแคชที่ไม่ตรงเวอร์ชัน (เคสจริง: แคช `alterflixhub-v1.2.0` ค้างหลังลบไฟล์ sw ออก ทำให้หน้าเว็บเสิร์ฟของเก่า) - **ห้ามปิดการซูม**: viewport ต้องเป็น `width=device-width, initial-scale=1` เท่านั้น (WCAG 1.4.4) - **contrast ที่วัดจริง** (พื้น `#0D0D0D`): `#B3B3B3` 9.27 · `#D47272` 5.97 · **`#A92626` = 2.77 → ห้ามใช้กับตัวอักษร** (ใช้ได้เฉพาะเส้นขอบ/พื้น) · placeholder ช่องค้นหาใช้ `#8A8A8A` (4.77 บน `#1F1F1F`) ไม่ใช่ `#454545` (1.72) - **hit area ≥ 44px**: ปุ่มที่หน้าตาเล็กกว่า (ใกล้ฉัน 20px, TH/EN 26px, chip 38px, ลูกศรแกลเลอรี 40px) ขยายด้วย `after:absolute after:-inset-*` — ห้ามเปลี่ยนความสูงที่มองเห็นเพื่อเพิ่ม hit area ## Cross-engine parity (Chromium / Firefox / Safari) — บังคับ เป้าหมาย: **Firefox และ Safari ต้องดู/รู้สึกใกล้ Chromium ที่สุด** โดยไม่ต้องมี build แยก · กฎทั้งหมดอยู่ใน `app/global.css` หัวข้อ "ความเท่ากันข้ามเอนจิน" - **สำคัญ: ต้องอยู่ใน `@layer base`** — CSS ที่ไม่ใส่ layer จะชนะ utility ของ Tailwind ทั้งหมด (เคสจริง: `input { font-size: 16px }` แบบ unlayered ทับ `text-sm` ทำให้ desktop กลายเป็น 16px) - **สกรอลบาร์**: Chromium/Safari ใช้ `::-webkit-scrollbar` (5px, `--muted-foreground/0.22`) · Firefox ไม่รู้จัก → ต้องมี `scrollbar-width: thin` + `scrollbar-color` คู่กันเสมอ · ห้ามลบฝั่งใดฝั่งหนึ่ง - **`color-scheme: dark` บน ``** — ทำให้ select/scrollbar/ฟอร์มเนทีฟ/autofill เป็นโทนเข้มทุกเอนจิน - **`::selection`** ต้องประกาศเอง (`#A92626` พื้น, ตัวอักษรขาว) — ไม่งั้นได้สีฟ้าตาม OS ซึ่งคนละเฉดในแต่ละเอนจิน - **`::-moz-focus-inner`** reset (`border:0; padding:0`) สำหรับ `button`/`input` - **`mask-image`** ต้องมีทั้ง `-webkit-mask-image` (Safari) และ `mask-image` (Firefox/Chromium) - **`
/`**: ซ่อน marker ด้วย `list-none` (Firefox) **และ** `[&::-webkit-details-marker]:hidden` (Chromium/Safari) - **`backdrop-blur`**: งบไม่เกิน **24px** ต่อชั้น (hero เดิม 32px) · `-webkit-backdrop-filter` มาจาก Tailwind เอง ไม่ต้องเขียนเพิ่ม · ระวัง `position: sticky` + blur บน iOS (อาจกระพริบ) - **iOS Safari**: ฟอร์มทุกช่องต้อง **≥16px บนมือถือ** (`text-base sm:text-sm`) ไม่งั้นเบราว์เซอร์ซูมหน้าเองเมื่อโฟกัส — **ห้ามแก้ด้วย `user-scalable=no`** (ผิด WCAG 1.4.4) · `input[type=search]` ต้อง `appearance: none` (iOS ใส่กรอบ/มุมโค้งเอง) · `-webkit-tap-highlight-color: transparent` และ `-webkit-text-size-adjust: 100%` - **ห้ามใส่ `-webkit-font-smoothing`** — ไม่มีผลใน Firefox และทำให้ความต่างชัดขึ้น - **สิ่งที่ต่างโดยธรรมชาติ ไม่ต้องแก้**: Firefox ไม่มี `navigator.share` / install prompt · Safari ไม่มี install prompt (`beforeinstallprompt` ไม่มี แต่ `display: standalone` ใน manifest ทำให้ติดตั้งจากเมนูแชร์ได้) · iOS ล้าง cache ของ SW เมื่อไม่ใช้งาน 7 วัน (ITP) · inertia การเลื่อนต่างกัน - ทดสอบ: `/`, `/cinema/`, `/for-cinemas`, `/admin` ในทั้งสามเอนจิน — สกรอลบาร์/select/`
`/ปุ่ม/ขนาดช่องค้นหาต้องเท่ากัน (มือถือ 16px, เดสก์ท็อป 14px) ## Agent-Native is structural, not visual This shell already meets the Agent-Native contract: data in SQL, actions as the single source of truth, application state for navigation/selection, and real-time sync. **Chat and the agent rail are opt-in, not default.** Build the product UI first. Add an `AgentSidebar`, a full-page chat route, or `sendToAgentChat` handoffs only when the user asks for agent interaction — and when you do, follow `agent-native-toolkit` and `frontend-design` → Agent Surface And Page Boundaries so the surfaces are wired correctly. ## Guardrails - Keep semantic token names and shared component seams intact; express the direction through token _values_, type, spacing, and composition — not by forking the design system. - Density comes from data, not prose. Subtract explanatory chrome; never subtract the visual craft that makes the app impressive. - Compare against real products in the chosen mode, not against the starter. ## Code map Single source of truth per concern — do not duplicate these: - `app/lib/cinemas.ts` — ข้อมูลโรงหนัง + ฟังก์ชันกรอง/ค้นหา (`filterCinemas`, `matchesQuery`, `findCinemaBySlug`, `formatDistance`) - การค้นหา (`filterCinemas`) เป็นแบบ **ทุกคำต้องเจอ (AND) เรียงสลับได้** และค้นทุกอย่างที่ผู้ใช้เห็นบนการ์ด: `name` / `name_th` / slug / `location_label(+_en)` / `address_lines(+_en)` / ทางเดินทาง / tag + ป้ายหมวดตามภาษา / คำอธิบาย — ต้องส่ง `tagLabels: messages.tags` เข้ามาด้วย ไม่งั้นค้นคำหมวดภาษาอังกฤษไม่เจอ - ข้อความผ่าน `normalizeSearchText` (NFKC, ตัดอักขระล่องหน, ตัวพิมพ์เล็ก, แปลงตัวคั่นเป็นช่องว่าง) และ `foldSearchText` (ตัดวรรณยุกต์/สระบน-ล่าง) → "Française" = "francaise", "เฮ้าส์" = "เฮาส", พิมพ์ไม่ครบก็เจอ - ผลลัพธ์เรียงตามความตรง: ชื่อเท่ากัน 3 · ชื่อขึ้นต้นด้วยคำ 2 · ชื่อมีคำอยู่ข้างใน 1.2 · หมวด/สถานที่/รายละเอียดน้ำหนักต่ำกว่า (คะแนนเท่ากันคงลำดับเดิม) - **ปุ่ม "ค้นหา"/Enter ไม่ได้ทำหน้าที่กรอง** (กรองสดทุกคีย์อยู่แล้วใน `onChange`) — อยู่ใน `
` เพื่อ `preventDefault` (กันหน้าโหลดใหม่) + `blur()` ปิดคีย์บอร์ดมือถือ + `scrollIntoView()` ไปที่หัวข้อผลลัพธ์ (`scroll-mt-[88px]`, เคารพ `prefers-reduced-motion`) · ห้ามเปลี่ยนปุ่มนี้เป็น `type="button"` เฉย ๆ (จะกลับไปเป็นปุ่มหลอก) - `app/lib/design-tokens.ts` — ค่าสีจาก Figma สำหรับ inline style (Tailwind class ยังเป็น literal เสมอ) - `app/lib/i18n/` — `messages.ts` (ข้อความ TH/EN ทั้งหมด คีย์หมวดหมู่/tag/ชำระเงิน/สิ่งอำนวยความสะดวก), `index.tsx` (`LocaleProvider`, `useI18n`, cookie `locale`) - ข้อความทุกคำใน UI ต้องมาจาก `messages` ไม่ hardcode ใน component · หมวดหมู่และ tag เก็บคีย์เป็นภาษาไทยเสมอ (ใช้กรองข้อมูล) แล้วแปลด้วย `messages.categories` / `messages.tags` - ข้อความอังกฤษของเนื้อหาโรงหนังเป็นฟิลด์เสริม `location_label_en` / `description_en` / `address_lines_en` / `value_en` — ไม่กรอกก็ fallback ไทย · ชื่อไทยใช้ `name_th` (+ helper `cinemaName(cinema, locale)`), ไม่กรอกก็แสดงชื่ออังกฤษ - `` ของหน้ารายละเอียดสร้างจาก loader ของ route เอง (`meta({ loaderData })` — เวอร์ชันนี้ส่ง `loaderData` ไม่ใช่ `data`) - `<head>` (title/description) ไม่เปลี่ยนตามภาษา; ภาษาเริ่มต้นเลือกตามลำดับ **?lang= → localStorage → cookie → ไทย** (`resolveInitialLocale`) — ตั้งใจไม่ใช้ `navigator.language` เพราะเว็บไทย-first - สลับภาษาได้ 2 ทาง: ปุ่มภาษาที่ header (ปุ่มเดียว + dropdown TH/EN — ดูหัวข้อตัวสลับภาษาด้านล่าง) หรือลิงก์ `?lang=en` ที่บังคับภาษาและ SSR ใส่ `<html lang>` ถูกต้อง - การเลือกถูกเก็บทั้ง cookie และ localStorage (รองรับเบราว์เซอร์ที่บล็อกคุกกี้) และซิงก์ข้ามแท็บผ่าน `storage` event - `app/components/site/` — โครงร่วม: `SiteShell` (flex column + `min-h-screen`, เนื้อหา `flex-1` เพื่อดัน footer ไปท้ายจอ), `SiteHeader`, `SiteFooter` (ความกว้างเนื้อหา cap ที่ 1016px เท่าคอลัมน์ฮีโร่ ไม่ยืดตามกริดการ์ด), `Logo`, `CinemaCard`, `CinemaGrid` + `CategoryFilter` - ปุ่มแชร์ (`app/components/site/ShareButton.tsx` + `app/lib/share.ts`) - ลิงก์สร้างจาก **origin ของ request** (root loader คืน `siteUrl` → `ShareOriginProvider`) + พาธย่อ `/c/<slug>` — ไม่ฝังโดเมนในโค้ด และไม่ต้องตั้ง env - `/c/<slug>` (`app/routes/c.$slug.tsx`) เป็น **302 redirect** ไป `/cinema/<slug>` — ลิงก์สั้นพอแปะในแชท แต่ไม่มีเนื้อหาสอง URL ให้ SEO ปวดหัว - ลำดับการแชร์: `navigator.share` (ถ้ามี) → `navigator.clipboard.writeText` → `<textarea>` + `execCommand` (origin ที่ไม่ใช่ HTTPS) → `failed` · คัดลอกสำรองเสมอเพื่อให้เดสก์ท็อปได้อะไรกลับไป - แสดงผลด้วย `role="status" aria-live="polite"` (การ์ด = `sr-only`, ท้ายหน้า = ข้อความข้างปุ่ม) และรีเซ็ตใน 2.5 วิ - ตำแหน่ง: การ์ดหน้าแรก = ปุ่มกลมมุมขวาบน (`variant="icon"`, `size-9`) · ท้ายหน้ารายละเอียด = แถบ "แชร์หน้านี้" (`variant="wide"`, `min-h-11`) หลังส่วน "โรงหนังอิสระอื่นๆ" - **หน้าตาตามธีม (ห้ามเปลี่ยนเป็นสีอื่น)**: การ์ด = ชิปแก้ว `rounded-xl` + `bg-[#1B1B1B]/80` + `backdrop-blur-xl` + `border-white/10` (สูตรเดียวกับแผงข้อมูลบนการ์ด) ไอคอนขาว → hover `#D47272` + ขอบ `#A92626/60` · แถบท้ายหน้า = `rounded-lg` + `bg-[#1B1B1B]/80` + `border-[#332B2B]` · สถานะสำเร็จ (คัดลอก/แชร์แล้ว) = ไอคอน `IconCheck` สี `#D47272` + ขอบ `#D47272/50` · hit area 44–48px ด้วย `after:-inset-*` (ไม่ขยายขนาดที่มองเห็น) - `app/components/home/` — ส่วนของหน้าแรก (`HeroSection`) - `app/components/cinema/` — ส่วนของหน้ารายละเอียด (`Gallery`, `CinemaSummary`, `TransportList`, `ContactPanel`, `FacilitiesSection`, `LocationPanel`, `CinemaNotFound`) - `app/routes/about.tsx` — หน้า "เกี่ยวกับเรา" (route `/about`, เมนูอยู่ทั้ง header และ footer, ใช้ `<Link>` ของ react-router จึงสลับหน้าแบบ SPA ไม่โหลดเอกสารใหม่) · เนื้อความเป็น `font-content` (มีหัว) ขนาด 17-18px `leading-[1.95]`, นำ 19-21px, หัวข้อยังเป็น Inter ตามเดิม - `docs/architecture.html` — แผนผังการทำงาน Frontend / Backend / Data (เอกสารประกอบ ไม่ถูก build เข้าแอป) เปิดด้วยเบราว์เซอร์ได้ตรง ๆ - `app/routes/_index.tsx` (หน้าแรก) และ `app/routes/cinema.$slug.tsx` (รายละเอียด) — ประกอบ component + จัดการ state ของ route เท่านั้น ข้อมูลมาจาก `useContent()` - `app/routes/admin_.login.tsx` (หน้า login) และ `app/routes/admin.tsx` (แดชบอร์ด **7 แท็บ**: โรงหนัง / หน้าเกี่ยวกับเรา / สำหรับคนรักหนัง / สำหรับคนทำโรงหนัง / คำศัพท์หลายภาษา / Footer-ไอคอน / สถิติการค้นหา) — ใช้ `admin_.login` เพื่อให้เป็น route พี่น้องของ `/admin` (ถ้าตั้งชื่อ `admin.login` จะกลายเป็น route ลูกที่ไม่มี `<Outlet/>` แล้วหน้าว่าง) - ฟอร์มโรงหนังแบ่งเป็น **หมวดพับได้** (`app/components/admin/AdminSection.tsx` ใช้ `<details>/<summary>` เนทีฟ) เปิดไว้เฉพาะ "ข้อมูลหลัก" — เพิ่มหมวดใหม่ให้ใช้คอมโพเนนต์นี้เสมอ อย่าเรียงช่องยาวรวดเดียว - ช่อง slug (`SlugInput.tsx`): ดึงจากชื่ออังกฤษอัตโนมัติ (`suggestSlug`) จนกว่าจะแก้เอง · กันค่าว่าง/ซ้ำ · เตือนว่าลิงก์เดิมจะใช้ไม่ได้ ## หลังบ้าน (admin) - ข้อมูลที่แก้ได้เก็บที่ `data/content/content.json` (สร้างจาก seed อัตโนมัติครั้งแรก) — หน้าเว็บอ่านผ่าน `readContent()` ใน loader ของ `app/root.tsx` แล้วกระจายด้วย `ContentProvider` - API: `POST /api/admin/login` · `POST /api/admin/logout` · `GET /api/admin/session` · `GET|PUT /api/admin/content` · `POST /api/admin/cinemas/import` (วาง JSON ทับตาม slug) - ล็อกอินเริ่มต้น: ผู้ใช้ `it is me` / รหัส `it is me&it is me` — เปลี่ยนได้ด้วย env `ADMIN_USERNAME`, `ADMIN_PASSWORD`, `ADMIN_SESSION_SECRET`; session เป็น cookie HttpOnly ที่เซ็น HMAC (8 ชั่วโมง) - คำศัพท์ในหลังบ้านคือ dot path ของข้อความในหน้าเว็บ (`hero.subtitle`) ต่อภาษา — ค่าว่างแปลว่าใช้ค่าเดิมจาก `messages.ts` - Footer เก็บเป็นรายการ `{icon_name, label, href}` — ไอคอนที่เลือกได้อยู่ใน `app/components/site/footer-icons.ts` - หน้า "เกี่ยวกับเรา" แก้ได้ที่แท็บ `หน้าเกี่ยวกับเรา` (`app/components/admin/AboutEditor.tsx`) — เก็บเป็น `about: { th, en }` ใน `content.json` แต่ละภาษามี `title`, `lead`, `sections[]`, `contactHeading`, `contactNote` - ฟิลด์ที่เว้นว่างจะถูกเติมด้วยค่าเริ่มต้นจาก `MESSAGES[locale].about` ตอน sanitize (`sanitizeAbout`) — ไฟล์เก่าที่ไม่มีคีย์ `about` จึงยังใช้งานได้ - `app/routes/about.tsx` อ่านจาก `useContent().about[locale]` เท่านั้น ไม่ผูกกับข้อความใน `messages.ts` อีก - ตัวแก้ไขมีแท็บภาษา + ตัวอย่างหน้าเว็บสด และปุ่ม "คืนค่าตั้งต้น" ต่อภาษา - หน้า **"สำหรับคนทำโรงหนัง"** (`/for-cinemas`) และ **"สำหรับคนรักหนัง"** (`/for-film-lovers`) — บทความแบบ **บล็อก** ที่แก้ได้จากหลังบ้าน (`ArticleEditor` คนละแท็บ) และเรนเดอร์ผ่าน component ร่วม `app/components/site/ArticlePage.tsx` - ข้อมูล: `forCinemas: { th, en }` และ `forFilmLovers: { th, en }` ใน `content.json` แต่ละภาษา = `{ title, lead, blocks[], contactHeading, contactNote }` - `blocks[]` มี 2 ชนิด: `{ type: "paragraph", text }` และ `{ type: "image", src, alt, caption }` — เรียงตามลำดับในอาร์เรย์เท่านั้น (มีปุ่ม ↑ ↓ / ลบ ในหลังบ้าน) - ตัวช่วยบริสุทธิ์อยู่ที่ `app/lib/article.ts` (`sanitizeArticleBlocks`, `moveBlock`, `removeBlock`, `createParagraphBlock`, `createImageBlock`) — ตัวตรวจฝั่งเซิร์ฟเวอร์คือ `sanitizeForCinemas` / `sanitizeForFilmLovers` ซึ่งใช้ตัวกลาง `sanitizeArticlePage` (ทิ้งบล็อกว่าง/ผิดชนิด, เติมค่าเริ่มต้นจาก `seedForCinemas()` / `seedForFilmLovers()`) - ภาษาภาพเดียวกับ `/about`: กรอบ 1440 + `px-[108px]`, `font-content` (IBM Plex Sans Thai Looped), การ์ดติดต่อไล่แดงขอบ `rgba(169,38,38,0.45)` + ไอคอนโซเชียลชุดเดียวกับ footer · มีลิงก์ใน header และ footer - header: มือถือ (< `sm`) ยุบเมนูทั้งสามหน้าไว้ใน `<details>` (native, คีย์บอร์ด/Esc ใช้ได้) เพราะป้ายภาษาไทยยาวและโลโก้มีขนาดตายตัวตามสเปก — อย่าเพิ่มลิงก์ตรงบนมือถืออีก - ตัวสลับภาษา (`LocaleSwitcher`) เป็น **ปุ่มเดียว + dropdown** (ไม่ใช่ปุ่ม TH/EN สองปุ่ม) — ต้องมี `aria-haspopup="menu"` / `aria-expanded`, ตัวเลือกเป็น `role="menuitemradio"` + `aria-checked`, เลื่อนด้วยลูกศรขึ้น/ลงได้ และปิดด้วย Esc/คลิกนอกเมนู - ลำดับโรงหนังในหลังบ้าน (`app/components/admin/CinemaList.tsx`) — ลำดับในอาร์เรย์ `cinemas` = ลำดับที่หน้าเว็บแสดง - โหมด **ลำดับที่จัดไว้** (ค่าเริ่มต้น): ลากวางสลับที่ได้ หรือกด ↑ ↓ ทีละขั้น (คีย์บอร์ดใช้ได้) · เมื่อลำดับต่างจากที่บันทึกจะมีปุ่ม **บันทึกลำดับใหม่** (`PUT /api/admin/content` ส่งเฉพาะ `cinemas`) หรือจะกด **บันทึกทั้งหมด** ในฟอร์มก็ได้ - โหมด **ก-ฮ**: เรียงชื่อไทยด้วย `Intl.Collator("th")` — เป็นเพียงมุมมอง ลากสลับไม่ได้จนกว่าจะกด **ใช้ลำดับ ก-ฮ นี้** - ฟังก์ชันบริสุทธิ์ที่ใช้ซ้ำได้: `sortCinemasByName` · `moveCinema` · `shiftCinema` · `hasSameOrder` - ช่องกรอกหลายค่าในหลังบ้าน (`app/components/admin/CommaListInput.tsx`) — หมวด/ชำระเงินแก้เป็น `CommaListInput` - เก็บข้อความดิบใน `draft` ระหว่างพิมพ์ จึงพิมพ์ `,` คั่นได้จริง (ถ้าผูก array เข้า `value` ตรง ๆ ตัวคั่นจะถูกตัดทิ้งทุกคีย์) - ตอนออกจากช่อง (blur) ค่อย normalize เป็น `", "` · รับ `,` และ `、` เป็นตัวคั่นด้วย · `parseCommaList` ใช้ซ้ำได้ - สิ่งอำนวยความสะดวก **ผูกกับโรงหนังแต่ละโรง** (ไม่มีแท็บส่วนกลางแล้ว) — `cinema.facilities` = หัวข้อที่มีจริง, `cinema.facility_details[key] = { label?, sub_th?, sub_en? }` = ข้อความเฉพาะโรง - ในฟอร์มโรงหนัง: ชิปเลือกหัวข้อ → ด้านล่างมีช่อง "ชื่อหัวข้อ" (ช่องเดียว ใช้ทั้ง TH/EN) - ช่องคำอธิบาย TH/EN แสดงเฉพาะ slug `house-cinema-samyan` (ข้อมูลครบแล้ว) — โรงอื่นไม่ต้องกรอก - หน้าเว็บแสดงคำอธิบายเฉพาะที่มีค่าใน `facility_details` (ไม่กรอก = ไม่แสดงบรรทัดคำอธิบาย) · ไม่เลือกหัวข้อเลย → "ไม่มีข้อมูล" - ฟังก์ชันที่เกี่ยวข้อง: `cinemaFacilities()` (เรียงตาม `FACILITY_KEYS`) · UI หลังบ้าน `app/components/admin/CinemaFacilitiesEditor.tsx` - ที่ตั้ง (`app/lib/map-embed.ts`) — ลำดับ: `map_url` (Google Maps) → `coordinates` (0,0 ถือว่าไม่กรอก) → "ไม่มีข้อมูล"; iframe ใช้ `maps.google.com/maps?q=…&output=embed` (ไม่ต้องมี API key) - การเดินทาง (`app/components/admin/TransportEditor.tsx`) — แก้ `transport[]` (icon/TH/EN) ต่อโรง; แถวที่ยังไม่กรอกจะไม่แสดงบนหน้าเว็บ - ช่องทางติดต่อ (`app/components/admin/ContactsEditor.tsx`) — แก้ `contacts[]` = `{ label, value, href }` ต่อโรง (ป้ายชื่อมี datalist แนะนำ Website/Facebook/Call ฯลฯ) · หัวข้อการ์ดใช้ `contact_heading` ต่อโรง ไม่กรอก = `detail.contactTitle` ## กติกาข้อมูล (บังคับ — กันข้อมูลหาย) - `readContent()` เขียน seed **เฉพาะกรณีไฟล์ไม่มี (`ENOENT`)** เท่านั้น — ถ้าไฟล์ parse/sanitize ไม่ผ่านให้ **โยน error** ห้ามเขียนทับด้วย seed (เคสจริง: เคยทำให้ข้อมูล 20 โรงหายระหว่างแก้โค้ด) - ก่อนแก้ `data/content/content.json` ด้วยสคริปต์ ให้ `cp` สำรองไว้ที่ `.output/content.json.bakN` ทุกครั้ง - ฟิลด์ใหม่ใน `Cinema` ต้องมีค่าเริ่มต้นที่ปลอดภัยเมื่อข้อมูลเก่าไม่มีฟิลด์นั้น (เช่น `facilities` → `[]`, `facility_details` → `{}`) และต้องผ่าน `sanitizeCinemas()` - โรงที่ `hidden: true` ต้องถูกกรองด้วย `publiclyVisible()` ก่อนแสดง/จัดอันดับ ## หมวดหมู่ (categories) - ลำดับ/รายการทั้งหมดอยู่ใน `CINEMA_CATEGORIES` (`app/lib/cinemas.ts`) — แถบกรองหน้าแรกและชิปในหลังบ้านอ่านจากที่เดียวกัน - ชื่อที่แสดงมาจาก `messages.categories` + `messages.tags` (TH/EN) และ override ได้ผ่าน `site.terms` (`categories.<คีย์>`) - เพิ่มหมวดใหม่ = แก้ 3 ที่พร้อมกัน: `CINEMA_CATEGORIES` → `categories` (TH/EN) → เพิ่ม term ใน `content.json` (ถ้าต้องการให้แก้คำแปลในหลังบ้านได้) - หมวดที่เพิ่มล่าสุด: `กลุ่มคนฉายหนัง` (Film collectives) · `หนังไทย` (Thai films) - `ทั้งหมด` ใช้เป็น "ไม่กรอง" และไม่ถูกเสนอในชิปของหลังบ้าน (`ASSIGNABLE_CATEGORIES` ตัดออกให้) ## คอมโพเนนต์หลังบ้าน (`app/components/admin/`) | ไฟล์ | ใช้ทำอะไร | |---|---| | `AdminSection.tsx` | การ์ดหมวดพับได้ (details/summary + badge + description) | | `CinemaList.tsx` | รายชื่อโรง: เรียง ก-ฮ (`Intl.Collator("th")`) + ลากวาง/↑↓ สลับตำแหน่ง | | `ChipPicker.tsx` | ชิปเลือกหลายค่า (หมวด/สิ่งอำนวยความสะดวก) + `toggleValue()` | | `CommaListInput.tsx` | ช่องหลายค่าคั่น `,` (เก็บ draft กันตัวคั่นถูกกลืน) + `parseCommaList()` | | `SlugInput.tsx` | slug: `normalizeSlug()` · `suggestSlug()` · `slugProblem()` | | `PhotosEditor.tsx` | รูปโรงหนัง (`photos[]`) — รูปแรกเป็นปกการ์ดหน้าแรก | | `TransportEditor.tsx` | วิธีเดินทาง (`transport[]`) | | `ContactsEditor.tsx` | ช่องทางติดต่อ (`contacts[]`) | | `CinemaFacilitiesEditor.tsx` | ข้อความสิ่งอำนวยความสะดวกต่อโรง (`facility_details`) | | `AboutEditor.tsx` | เนื้อหาหน้า "เกี่ยวกับเรา" | ## รูปภาพ - `cinema.photos[0]` = **รูปปกการ์ดหน้าแรก** (`CinemaCard`) — ไม่มีรูป = ใช้ gradient 4 แบบ (`CARD_GRADIENTS`) - หน้า detail ใช้ `Gallery`: มีไม่ครบ 3 รูป ช่องที่ว่างแสดง **โลโก้ AlterFlixHub** (ดูหัวข้อโลโก้) - รูปในเครื่องวางที่ `public/images/…` แล้วใส่ path `/images/…` (ไฟล์ `hero.png` ใช้เป็นพื้นหลังฮีโร่หน้าแรก) ## ลำดับการ์ดหน้าแรก (สลับทุกวัน) - `app/lib/daily-order.ts` — `dailyOrder(items, idOf, key)` คำนวณลำดับจาก "วันที่" ล้วน ๆ (ไม่เก็บ state) - เงื่อนไขบังคับ: **โรงหนึ่งต้องไม่ได้อยู่ตำแหน่งการ์ดเดิม 2 วันติดกัน** - permutation ฐาน = seeded shuffle (Fisher–Yates + mulberry32) จากลำดับที่แอดมินจัดไว้ → คงที่ทุกวัน - หมุน (rotate) ด้วย offset รายวันในช่วง `1..n-1` และ offset วันติดกันไม่เท่ากัน → ทุกโรงเลื่อนตำแหน่งแน่นอน - n = 2 สลับวันละครั้ง · รายการ < 2 คงเดิม - ทุกคนเห็นลำดับเดียวกันในวันเดียวกัน (คีย์วันที่แบบ UTC จาก loader → ไม่มี hydration mismatch) - ลำดับนี้ทำงาน **ก่อน** ตัวกรองหมวด/คำค้น — ผลกรองจึงสลับตามไปด้วย; ถ้าผู้ใช้กด "ใกล้ฉัน" การเรียงตามระยะทางยังชนะเสมอ - ตรวจด้วยสเปก `app/lib/daily-order.spec.ts` (n = 2..40 × 10 วัน, ไม่มีตำแหน่งซ้ำวันติดกัน) ## สถิติการค้นหา (privacy-first, แนว Umami) - เก็บ event แบบ append-only ที่ `data/analytics/events.jsonl` (หมุนไฟล์เมื่อเกิน 8 MB, เก็บล่าสุด 50k event) - ตัวรับ event: `POST /api/analytics/collect` (สาธารณะ) — ไม่ใช้คุกกี้ ไม่เก็บ IP/User-Agent ดิบ ระบุผู้เข้าชมด้วย `sha256(เกลือรายวัน | ip | ua)` 16 ตัวอักษร - ชนิด event: `search` (query/category/result_count) · `cinema_select` (slug/source/position) · `cinema_view` · `near_me` - ฝั่งเว็บเรียกผ่าน `trackEvent()` (`app/lib/analytics-client.ts`) — กลืน error, กัน event ซ้ำใน 1.5 วินาที, ค้นหาจะถูกบันทึกหลังผู้ใช้หยุดพิมพ์ 900 ms และต้องมี ≥ 2 ตัวอักษร - สรุปผล: `summarize(events, days)` (`app/lib/analytics.server.ts`) → คำค้นยอดนิยม, คำค้นที่ไม่พบผล, CTR, ผลลัพธ์เฉลี่ย, หมวดที่ถูกใช้, โรงหนังที่ถูกเปิด/คลิก, การค้นหารายวัน - ดูได้ที่หลังบ้าน แท็บ **สถิติการค้นหา** (`GET /api/admin/analytics?days=1|7|30|90`, ต้องล็อกอิน) - ตั้ง `ANALYTICS_SALT` ใน env เพื่อไม่ให้ hash ผู้เข้าชมคาดเดาได้ข้าม deployment ## SEO และการป้องกัน AI (บังคับ) - **ไม่ฝังโดเมนในโค้ด (บังคับ)**: ทุกที่ที่ต้องใช้ URL เต็ม (canonical, OG, JSON-LD, sitemap, robots, ลิงก์แชร์) ต้องมาจาก origin ของ **request จริง** ผ่าน `originFromRequest()` / `originFromHeaders()` (`app/lib/request-origin.ts`) — รองรับ `x-forwarded-host`/`x-forwarded-proto` ของ reverse proxy · ตั้ง env `SITE_URL` เฉพาะเวลาต้องบังคับโดเมน (ปกติไม่ต้อง) - `meta()` ไม่มี access ต่อ request → route ที่มี meta ต้องมี loader คืน `{ origin }` ด้วย (`resolvePageOrigin()` ใน `app/lib/page-origin.ts`) แล้วอ่าน `loaderData.origin` · root loader คืน `siteUrl` ให้ปุ่มแชร์ใช้ผ่าน `ShareOriginProvider` - ทุกหน้าใช้ `pageMeta()` (`app/lib/seo.ts`) — ได้ title, description, canonical, robots, OG, Twitter ครบชุด · route ห้ามเขียน `{ title }` / `<meta>` เอง - JSON-LD: `WebSite` + `Organization` (+ `SearchAction`) ที่หน้าแรก · `BreadcrumbList` ทุกหน้าย่อย · `MovieTheater` หน้าโรงหนัง · `Article` หน้าบทความ - `SearchAction` ชี้ไป `/?q=<คำค้น>` — หน้าแรกจึง**ต้อง**อ่าน `q` จาก URL มาเป็นค่าเริ่มต้นของช่องค้นหา (ถ้าเปลี่ยนกลไกค้นหา ต้องแก้ทั้งคู่) - **ห้ามใส่ hreflang**: เว็บเดียวสลับภาษาได้ด้วย toggle (ไม่แยก URL) — ใส่แล้วจะกลายเป็นสัญญาณเนื้อหาซ้ำ - หน้า `/admin`, `/admin/login` = `noindex, nofollow` (หน้าโรงที่ไม่พบก็ noindex) - `server/routes/robots.txt.ts` — เปิด search engine หลัก, ปิด `/api/`, `/admin`, `/_agent-native/`, `/c/` (ลิงก์ย่อ), และบล็อก AI crawler 21 ตัว · บรรทัด `Sitemap:` ต่อจาก origin ของ request (ห้ามเปลี่ยนกลับเป็นไฟล์ static) - `public/ai.txt` — ประกาศไม่ให้นำเนื้อหาไปฝึกโมเดล (ไฟล์ static, ไม่มีโดเมนอยู่ในเนื้อหา) - `/sitemap.xml` เป็น **Nitro route** (`server/routes/sitemap.xml.ts`) ไม่ใช่ React Router route — เพราะ SSR handler ของ framework ตอบ 404 ให้พาธที่ลงท้ายด้วยนามสกุลไฟล์ · ตัวสร้าง XML แยกอยู่ที่ `app/lib/sitemap.ts` (มี unit test) และ**ต้องข้ามโรงที่ `hidden`** - OG image: `public/og/alterflixhub-1200x630.png` (1200×630, โลโก้ Jersey 15 สี `#8F0808` ตามสเปกโลโก้) — **ห้ามพิมพ์โดเมนลงบนภาพ** (ภาพเป็น static แก้ตาม request ไม่ได้) · เปลี่ยนคำบนภาพแล้วต้องสร้างใหม่ ไม่ใช้ภาพ placeholder ## หมวด "ยอดนิยม" (จากสถิติ ไม่ใช่ป้ายมือ) - `app/lib/popularity.server.ts` — `computePopularity()` อ่าน `events.jsonl` แล้วให้สถานะ + อันดับ (memo 5 นาที) - **เงื่อนไขเปิดใช้: ต้องมีประวัติข้อมูล ≥ 180 วัน (6 เดือน)** — `ready=false` จนกว่าจะครบ เพื่อไม่ให้ฐานผู้ชมเล็ก ๆ ครองอันดับ - ระหว่างยังไม่ครบ: หมวด "ยอดนิยม" ใช้ `tags` ที่ตั้งไว้ (พฤติกรรมเดิม) **โดยไม่แสดงข้อความแจ้งบนหน้าเว็บ** — สถานะ/วันเหลือดูได้จาก `computePopularity()` หรือหลังบ้านเท่านั้น (ผู้ใช้สั่งลบข้อความออกจากหน้าแรก) - คะแนนเมื่อพร้อมใช้: `cinema_view` = 1 · `cinema_select` = 1.5 (เจตนาชัดกว่า) × decay ครึ่งชีวิต 30 วัน · นับเฉพาะ 90 วันล่าสุด · เอา top 8 - โรงที่ถูกซ่อน (`hidden`) ไม่ถูกจัดอันดับ/แสดง - ค่าคงที่: `POPULARITY_MIN_HISTORY_DAYS` · `POPULARITY_WINDOW_DAYS` · `POPULARITY_TOP_N` เพิ่มหน้าใหม่: ใส่ component ที่ `app/components/<domain>/` แล้วให้ route เป็นตัวประกอบเท่านั้น