Files
web-alterflixhub/DESIGN.md
T
Bkk1234 301ad22a39 fix(css): cross-engine parity ให้ Firefox ใกล้ Chromium
- เพิ่ม scrollbar-width/scrollbar-color (::-webkit-scrollbar ใช้กับ Chromium/Safari เท่านั้น)
- color-scheme: dark บน html → select/สกรอลบาร์/ฟอร์มเนทีฟเป็นโทนเข้มทั้งสองเอนจิน
- ::selection สีแบรนด์ #A92626 (เดิมสีฟ้าตาม OS คนละเฉด)
- ::-moz-focus-inner reset กัน padding ภายในปุ่มที่ Firefox ใส่เอง
- -webkit-mask-image คู่กับ mask-image (Safari)
- ลด backdrop-blur hero 32px → 24px (budget ตาม DESIGN.md, FF แพงกว่ามาก)
- DESIGN.md: หัวข้อ Cross-engine parity · sw VERSION v2.0.2
2026-11-14 13:07:04 +07:00

47 KiB
Raw Blame History

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 — คลาสนี้ถูกใส่โดยสคริปต์ใน <head> (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) หรือ <Reveal> (app/components/site/Reveal.tsx) — มีกฎกันค้างซ่อน: บล็อกที่เลื่อนผ่านไปแล้ว (หรือถูกข้ามด้วยการกระโดด scroll) ต้องโผล่ทันที
  • hover ของการ์ดใช้ translate (Tailwind hover:-translate-y-1) ไม่ใช้ transform เพราะชนกับ keyframe ของ reveal · ทุกอนิเมชันต้องมีคู่มือปิดใน @media (prefers-reduced-motion: reduce)

PWA & accessibility contract (บังคับ)

  • ติดตั้งได้: <link rel="manifest"> อยู่ใน 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 + <ServiceWorkerSetup/> ใน 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) — บังคับ

เป้าหมาย: Firefox ต้องดูและรู้สึกใกล้ Chromium ที่สุด โดยไม่ต้องมี build แยก

  • สกรอลบาร์: Chromium/Safari ใช้ ::-webkit-scrollbar (5px, --muted-foreground/0.22) · Firefox ไม่รู้จัก → ต้องมี scrollbar-width: thin + scrollbar-color คู่กันเสมอ (ตอนนี้ประกาศที่ * ใน global.css) · ห้ามลบฝั่งใดฝั่งหนึ่ง
  • color-scheme: dark บน <html> — ทำให้ select/scrollbar/ฟอร์มเนทีฟ/autofill เป็นโทนเข้มทั้งสองเอนจิน (ถ้าไม่มี Firefox จะได้ select ขาวสว่างกลางธีมดำ)
  • ::selection ต้องประกาศเอง (#A92626 พื้น, ตัวอักษรขาว) — ไม่งั้นได้สีฟ้าตาม OS ซึ่งคนละเฉดในแต่ละเอนจิน
  • ::-moz-focus-inner reset (border:0; padding:0) สำหรับ button/input — Firefox ใส่ padding ภายในเองทำให้ปุ่มเตี้ย/กว้างต่างจาก Chromium เล็กน้อย
  • mask-image ต้องมีทั้ง -webkit-mask-image (Safari) และ mask-image (Firefox/Chromium)
  • <details>/<summary>: ซ่อน marker ด้วย list-none (Firefox ใช้ list-style: none) และ [&::-webkit-details-marker]:hidden (Chromium) — ต้องมีทั้งคู่
  • backdrop-blur: งบไม่เกิน 24px ต่อชั้น (เดิม hero ใช้ 32px) — backdrop-filter ของ Firefox แพงกว่ามากและทำให้เลื่อนกระตุก · ห้ามซ้อน blur หลายชั้นใน element เดียว
  • ห้ามใส่ -webkit-font-smoothing — ไม่มีผลใน Firefox ทำให้เห็นความต่างชัดขึ้นแทนที่จะเท่ากัน (การเรนเดอร์ฟอนต์ไทยสองเอนจินไม่มีทางเท่ากัน 100% — ยอมรับ)
  • สิ่งที่ต่างโดยธรรมชาติและไม่ต้องแก้: Firefox เดสก์ท็อปไม่มี navigator.share (fallback คัดลอกลิงก์ทำงานอยู่) · ไม่มี install prompt ของ PWA (beforeinstallprompt ไม่มี) · inertia การเลื่อนต่างกัน
  • ทดสอบ: เปิดทั้งสองเบราว์เซอร์ที่หน้า /, /cinema/<slug>, /for-cinemas, /admin — ดูสกรอลบาร์/select/<details>/ปุ่มต้องหน้าตาเดียวกัน

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) — อยู่ใน <form role="search"> เพื่อ 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)), ไม่กรอกก็แสดงชื่ออังกฤษ
  • <title> ของหน้ารายละเอียดสร้างจาก 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 เป็นตัวประกอบเท่านั้น