medesign 0.0.0-stage → 1.2.0

package/references/style-extraction.md

@@ -0,0 +1,17 @@
+## 🔬 Section 5: Style Extraction & Mockup-First Protocol (`/medesign extract`)
+
+เมื่อผู้ใช้ส่ง Screenshot, URL, หรือสั่ง `/medesign extract` หรือเปิด Comparison Lab:
+1. **Deconstruct Visual Anatomy:** วิเคราะห์แยกองค์ประกอบ 6 มิติ — Canvas Polarity, Surface Hierarchy, Border/Shadow Mechanism, Typography Pairing & Tracking, Accent Voltage Rule, และ Control Density
+2. **Synthesize Pure Tokens (`DESIGN.md` / `user-profile.json`):** ถอดรหัสเป็น CSS/Tailwind Tokens ล้วนโดยไม่ต้องยึดติดชื่อแบรนด์เดิม
+3. **Mockup-First Confirmation (ห้ามแก้โค้ดโปรดักชันทันที):**
+   - สร้างหน้า HTML Live Preview บน Localhost (เช่น Port `3333`) โดยใช้คอนเทนต์จริงจากโปรเจกต์ของผู้ใช้ (เช่น MESURV, Mesnooker)
+   - **Dual-Axis Variation (Surface × Spatial Topology):** ห้ามเปลี่ยนแค่สี/ฟอนต์/กรอบบนโครงหน้าเว็บเดิมซ้ำๆ ต้องแยกการเปรียบเทียบเป็น 2 แกนเสมอ:
+     - **Axis 1 (Surface Theme DNA):** โทนสี, ฟอนต์, เส้นขอบ, มุมโค้ง, เงา
+     - **Axis 2 (Spatial Layout Architecture):** สัดส่วนการจัดวางหน้าต่างที่ต่างกันอย่างสิ้นเชิง (เช่น Top-Nav Fullwidth, Tab-Switched Workspace, 3-Column Editorial, Split-Pane Workbench, Command HUD — ห้ามล็อก Left Sidebar ตายตัวทุกหน้า)
+   - **Injected Top-Center Switcher:** ทุกหน้าใน Comparison Lab ต้องมีแถบสลับหน้าลอยตรงกลางด้านบน (`⊞ Home | ← Prev | Dropdown | Next →`) เพื่อให้กดเปลี่ยนหน้าเปรียบเทียบได้ทันที
+   - **Live Theme Toggle Safety:** เมื่อทำปุ่มสลับธีมสด (`data-theme`) ต้องประกาศ CSS Selector รองรับทั้ง `:root[data-theme="..."], body[data-theme="..."]` และใช้ JS อัปเดตทั้ง `document.documentElement` และ `document.body` เสมอ
+   - รอให้ผู้ใช้กด Confirm หรือระบุจุดที่ต้องการจูนเพิ่ม (Iterative Refinement) ก่อนนำไปเขียนทับ `user-profile.json` และโค้ดจริง
+   - เมื่อผู้ใช้ยืนยันและล็อก DNA เสร็จแล้ว ให้สั่งปิดเซิร์ฟเวอร์ทดสอบ (`manage_task(Action='kill')`) ทันทีเพื่อไม่ให้ค้างในระบบ
+
+---
+

package/references/styles/brutalist.md

@@ -0,0 +1,88 @@
+
+# SKILL: Industrial Brutalism & Tactical Telemetry UI
+
+## 1. Skill Meta
+**Name:** Industrial Brutalism & Tactical Telemetry Interface Engineering
+**Description:** Advanced proficiency in architecting web interfaces that synthesize mid-century Swiss Typographic design, industrial manufacturing manuals, and retro-futuristic aerospace/military terminal interfaces. This discipline requires absolute mastery over rigid modular grids, extreme typographic scale contrast, purely utilitarian color palettes, and the programmatic simulation of analog degradation (halftones, CRT scanlines, bitmap dithering). The objective is to construct digital environments that project raw functionality, mechanical precision, and high data density, deliberately discarding conventional consumer UI patterns.
+
+## 2. Visual Archetypes
+The design system operates by merging two distinct but highly compatible visual paradigms. **Pick ONE per project and commit to it. Do not alternate or mix both modes within the same interface.**
+
+### 2.1 Swiss Industrial Print
+Derived from 1960s corporate identity systems and heavy machinery blueprints.
+*   **Characteristics:** High-contrast light modes (newsprint/off-white substrates). Reliance on monolithic, heavy sans-serif typography. Unforgiving structural grids outlined by visible dividing lines. Aggressive, asymmetric use of negative space punctuated by oversized, viewport-bleeding numerals or letterforms. Heavy use of primary red as an alert/accent color.
+
+### 2.2 Tactical Telemetry & CRT Terminal
+Derived from classified military databases, legacy mainframes, and aerospace Heads-Up Displays (HUDs).
+*   **Characteristics:** Dark mode exclusivity. High-density tabular data presentation. Absolute dominance of monospaced typography. Integration of technical framing devices (ASCII brackets, crosshairs). Application of simulated hardware limitations (phosphor glow, scanlines, low bit-depth rendering).
+
+## 3. Typographic Architecture
+Typography is the primary structural and decorative infrastructure. Imagery is secondary. The system demands extreme variance in scale, weight, and spacing.
+
+### 3.1 Macro-Typography (Structural Headers)
+*   **Classification:** Neo-Grotesque / Heavy Sans-Serif.
+*   **Optimal Web Fonts:** Neue Haas Grotesk (Black), Inter (Extra Bold/Black), Archivo Black, Roboto Flex (Heavy), Monument Extended.
+*   **Implementation Parameters:**
+    *   **Scale:** Deployed at massive scales using fluid typography (e.g., `clamp(4rem, 10vw, 15rem)`).
+    *   **Tracking (Letter-spacing):** Extremely tight, often negative (`-0.03em` to `-0.06em`), forcing glyphs to form solid architectural blocks.
+    *   **Leading (Line-height):** Highly compressed (`0.85` to `0.95`).
+    *   **Casing:** Exclusively uppercase for structural impact.
+
+### 3.2 Micro-Typography (Data & Telemetry)
+*   **Classification:** Monospace / Technical Sans.
+*   **Optimal Web Fonts:** JetBrains Mono, IBM Plex Mono, Space Mono, VT323, Courier Prime.
+*   **Implementation Parameters:**
+    *   **Scale:** Fixed and small (`10px` to `14px` / `0.7rem` to `0.875rem`).
+    *   **Tracking:** Generous (`0.05em` to `0.1em`) to simulate mechanical typewriter spacing or terminal matrices.
+    *   **Leading:** Standard to tight (`1.2` to `1.4`).
+    *   **Casing:** Exclusively uppercase. Used for all metadata, navigation, unit IDs, and coordinates.
+
+### 3.3 Textural Contrast (Artistic Disruption)
+*   **Classification:** High-Contrast Serif.
+*   **Optimal Web Fonts:** Playfair Display, EB Garamond, Times New Roman.
+*   **Implementation Parameters:** Used exceedingly sparingly. Must be subjected to heavy post-processing (halftone filters, 1-bit dithering) to degrade vector perfection and create textural juxtaposition against the clean sans-serifs.
+
+## 4. Color System
+The color architecture is uncompromising. Gradients, soft drop shadows, and modern translucency are strictly prohibited. Colors simulate physical media or primitive emissive displays.
+
+**CRITICAL: Choose ONE substrate palette per project and use it consistently. Never mix light and dark substrates within the same interface.**
+
+### If Swiss Industrial Print (Light):
+*   **Background:** `#F4F4F0` or `#EAE8E3` (Matte, unbleached documentation paper).
+*   **Foreground:** `#050505` to `#111111` (Carbon Ink).
+*   **Accent:** `#E61919` or `#FF2A2A` (Aviation/Hazard Red). This is the ONLY accent color. Used for strike-throughs, thick structural dividing lines, or vital data highlights.
+
+### If Tactical Telemetry (Dark):
+*   **Background:** `#0A0A0A` or `#121212` (Deactivated CRT. Avoid pure `#000000`).
+*   **Foreground:** `#EAEAEA` (White phosphor). This is the primary text color.
+*   **Accent:** `#E61919` or `#FF2A2A` (Aviation/Hazard Red). Same red, same rules.
+*   **Terminal Green (`#4AF626`):** Optional. Use ONLY for a single specific UI element (e.g., one status indicator or one data readout) — never as a general text color. If it doesn't serve a clear purpose, omit it entirely.
+
+## 5. Layout and Spatial Engineering
+The layout must appear mathematically engineered. It rejects conventional web padding in favor of visible compartmentalization.
+
+*   **The Blueprint Grid:** Strict adherence to CSS Grid architectures. Elements do not float; they are anchored precisely to grid tracks and intersections.
+*   **Visible Compartmentalization:** Extensive utilization of solid borders (`1px` or `2px solid`) to delineate distinct zones of information. Horizontal rules (`<hr>`) frequently span the entire container width to segregate operational units.
+*   **Bimodal Density:** Layouts oscillate between extreme data density (tightly packed monospace metadata clustered together) and vast expanses of calculated negative space framing macro-typography.
+*   **Geometry:** Absolute rejection of `border-radius`. All corners must be exactly 90 degrees to enforce mechanical rigidity.
+
+## 6. UI Components and Symbology
+Standard web UI conventions are replaced with utilitarian, industrial graphic elements.
+
+*   **Syntax Decoration:** Utilization of ASCII characters to frame data points.
+    *   *Framing:* `[ DELIVERY SYSTEMS ]`, `< RE-IND >`
+    *   *Directional:* `>>>`, `///`, `\\\\`
+*   **Industrial Markers:** Prominent integration of registration (`®`), copyright (`©`), and trademark (`™`) symbols functioning as structural geometric elements rather than legal text.
+*   **Technical Assets:** Integration of crosshairs (`+`) at grid intersections, repeating vertical lines (barcodes), thick horizontal warning stripes, and randomized string data (e.g., `REV 2.6`, `UNIT / D-01`) to simulate active mechanical processes.
+
+## 7. Textural and Post-Processing Effects
+To prevent the design from appearing purely digital, simulated analog degradation is engineered into the frontend via CSS and SVG filters.
+
+*   **Halftone and 1-Bit Dithering:** Transforming continuous-tone images or large serif typography into dot-matrix patterns. Achieved via pre-processing or CSS `mix-blend-mode: multiply` overlays combined with SVG radial dot patterns.
+*   **CRT Scanlines:** For terminal interfaces, applying a `repeating-linear-gradient` to the background to simulate horizontal electron beam sweeps (e.g., `repeating-linear-gradient(0deg, transparent, transparent 2px, rgba(0,0,0,0.1) 2px, rgba(0,0,0,0.1) 4px)`).
+*   **Mechanical Noise:** A global, low-opacity SVG static/noise filter applied to the DOM root to introduce a unified physical grain across both dark and light modes.
+
+## 8. Web Engineering Directives
+1.  **Grid Determinism:** Utilize `display: grid; gap: 1px;` with contrasting parent/child background colors to generate mathematically perfect, razor-thin dividing lines without complex border declarations.
+2.  **Semantic Rigidity:** Construct the DOM using precise semantic tags (`<data>`, `<samp>`, `<kbd>`, `<output>`, `<dl>`) to accurately reflect the technical nature of the telemetry.
+3.  **Typography Clamping:** Implement CSS `clamp()` functions exclusively for macro-typography to ensure massive text scales aggressively while maintaining structural integrity across viewports.

package/references/styles/minimalist.md

@@ -0,0 +1,81 @@
+
+# Protocol: Premium Utilitarian Minimalism UI Architect
+
+## 1. Protocol Overview
+Name: Premium Utilitarian Minimalism & Editorial UI
+Description: An advanced frontend engineering directive for generating highly refined, ultra-minimalist, "document-style" web interfaces analogous to top-tier workspace platforms. This protocol strictly enforces a high-contrast warm monochrome palette, bespoke typographic hierarchies, meticulous structural macro-whitespace, bento-grid layouts, and an ultra-flat component architecture with deliberate muted pastel accents. It actively rejects standard generic SaaS design trends.
+
+## 2. Absolute Negative Constraints (Banned Elements)
+The AI must strictly avoid the following generic web development defaults:
+- DO NOT use the "Inter", "Roboto", or "Open Sans" typefaces.
+- DO NOT use generic, thin-line icon libraries like "Lucide", "Feather", or standard "Heroicons".
+- DO NOT use Tailwind's default heavy drop shadows (e.g., `shadow-md`, `shadow-lg`, `shadow-xl`). Shadows must be practically non-existent or heavily customized to be ultra-diffuse and low opacity (< 0.05).
+- DO NOT use primary colored backgrounds for large elements or sections (e.g., no bright blue, green, or red hero sections).
+- DO NOT use gradients, neon colors, or 3D glassmorphism (beyond subtle navbar blurs).
+- DO NOT use `rounded-full` (pill shapes) for large containers, cards, or primary buttons.
+- DO NOT use emojis anywhere in code, markup, text content, headings, or alt text. Replace with proper icons or clean SVG primitives.
+- DO NOT use generic placeholder names like "John Doe", "Acme Corp", or "Lorem Ipsum". Use realistic, contextual content.
+- DO NOT use AI copywriting clichés: "Elevate", "Seamless", "Unleash", "Next-Gen", "Game-changer", "Delve". Write plain, specific language.
+
+## 3. Typographic Architecture
+The interface must rely on extreme typographic contrast and premium font selection to establish an editorial feel.
+- Primary Sans-Serif (Body, UI, Buttons): Use clean, geometric, or system-native fonts with character. Target: `font-family: 'SF Pro Display', 'Geist Sans', 'Helvetica Neue', 'Switzer', sans-serif`.
+- Editorial Serif (Hero Headings & Quotes): Target: `font-family: 'Lyon Text', 'Newsreader', 'Playfair Display', 'Instrument Serif', serif`. Apply tight tracking (`letter-spacing: -0.02em` to `-0.04em`) and tight line-height (`1.1`).
+- Monospace (Code, Keystrokes, Meta-data): Target: `font-family: 'Geist Mono', 'SF Mono', 'JetBrains Mono', monospace`.
+- Text Colors: Body text must never be absolute black (`#000000`). Use off-black/charcoal (`#111111` or `#2F3437`) with a generous `line-height` of `1.6` for legibility. Secondary text should be muted gray (`#787774`).
+
+## 4. Color Palette (Warm Monochrome + Spot Pastels)
+Color is a scarce resource, utilized only for semantic meaning or subtle accents.
+- Canvas / Background: Pure White `#FFFFFF` or Warm Bone/Off-White `#F7F6F3` / `#FBFBFA`.
+- Primary Surface (Cards): `#FFFFFF` or `#F9F9F8`.
+- Structural Borders / Dividers: Ultra-light gray `#EAEAEA` or `rgba(0,0,0,0.06)`.
+- Accent Colors: Exclusively use highly desaturated, washed-out pastels for tags, inline code backgrounds, or subtle icon backgrounds.
+  - Pale Red: `#FDEBEC` (Text: `#9F2F2D`)
+  - Pale Blue: `#E1F3FE` (Text: `#1F6C9F`)
+  - Pale Green: `#EDF3EC` (Text: `#346538`)
+  - Pale Yellow: `#FBF3DB` (Text: `#956400`)
+
+## 5. Component Specifications
+- Bento Box Feature Grids:
+  - Utilize asymmetrical CSS Grid layouts.
+  - Cards must have exactly `border: 1px solid #EAEAEA`.
+  - Border-radius must be crisp: `8px` or `12px` maximum.
+  - Internal padding must be generous (e.g., `24px` to `40px`).
+- Primary Call-To-Action (Buttons):
+  - Solid background `#111111`, text `#FFFFFF`. 
+  - Slight border-radius (`4px` to `6px`). No box-shadow. 
+  - Hover state should be a subtle color shift to `#333333` or a micro-scale `transform: scale(0.98)`.
+- Tags & Status Badges:
+  - Pill-shaped (`border-radius: 9999px`), very small typography (`text-xs`), uppercase with wide tracking (`letter-spacing: 0.05em`).
+  - Background must use the defined Muted Pastels.
+- Accordions (FAQ):
+  - Strip all container boxes. Separate items only with a `border-bottom: 1px solid #EAEAEA`.
+  - Use a clean, sharp `+` and `-` icon for the toggle state.
+- Keystroke Micro-UIs:
+  - Render shortcuts as physical keys using `<kbd>` tags: `border: 1px solid #EAEAEA`, `border-radius: 4px`, `background: #F7F6F3`, using the Monospace font.
+- Faux-OS Window Chrome:
+  - When mocking up software, wrap it in a minimalist container with a white top bar containing three small, light gray circles (replicating macOS window controls).
+
+## 6. Iconography & Imagery Directives
+- System Icons: Use "Phosphor Icons (Bold or Fill weights)" or "Radix UI Icons" for a technical, slightly thicker-stroke aesthetic. Standardize stroke width across all icons.
+- Illustrations: Monochromatic, rough continuous-line ink sketches on a white background, featuring a single offset geometric shape filled with a muted pastel color.
+- Photography: Use high-quality, desaturated images with a warm tone. Apply subtle overlays (`opacity: 0.04` warm grain) to blend photos into the monochrome palette. Never use oversaturated stock photos. Use reliable placeholders like `https://picsum.photos/seed/{context}/1200/800` when real assets are unavailable.
+- Hero & Section Backgrounds: Sections should not feel empty and flat. Use subtle full-width background imagery at very low opacity, soft radial light spots (`radial-gradient` with warm tones at `opacity: 0.03`), or minimal geometric line patterns to add depth without breaking the clean aesthetic.
+
+## 7. Subtle Motion & Micro-Animations
+Motion should feel invisible — present but never distracting. The goal is quiet sophistication, not spectacle.
+- Scroll Entry: Elements fade in gently as they enter the viewport. Use `translateY(12px)` + `opacity: 0` resolving over `600ms` with `cubic-bezier(0.16, 1, 0.3, 1)`. Use `IntersectionObserver`, never `window.addEventListener('scroll')`.
+- Hover States: Cards lift with an ultra-subtle shadow shift (`box-shadow` transitioning from `0 0 0` to `0 2px 8px rgba(0,0,0,0.04)` over `200ms`). Buttons respond with `scale(0.98)` on `:active`.
+- Staggered Reveals: Lists and grid items enter with a cascade delay (`animation-delay: calc(var(--index) * 80ms)`). Never mount everything at once.
+- Background Ambient Motion: Optional. A single, very slow-moving radial gradient blob (`animation-duration: 20s+`, `opacity: 0.02-0.04`) drifting behind hero sections. Must be applied to a `position: fixed; pointer-events: none` layer. Never on scrolling containers.
+- Performance: Animate exclusively via `transform` and `opacity`. No layout-triggering properties (`top`, `left`, `width`, `height`). Use `will-change: transform` sparingly and only on actively animating elements.
+
+## 8. Execution Protocol
+When tasked with writing frontend code (HTML, React, Tailwind, Vue) or designing a layout:
+1. Establish the macro-whitespace first. Use massive vertical padding between sections (e.g., `py-24` or `py-32` in Tailwind).
+2. Constrain the main typography content width to `max-w-4xl` or `max-w-5xl`.
+3. Apply the custom typographic hierarchy and monochromatic color variables immediately.
+4. Ensure every card, divider, and border adheres strictly to the `1px solid #EAEAEA` rule.
+5. Add scroll-entry animations to all major content blocks.
+6. Ensure sections have visual depth through imagery, ambient gradients, or subtle textures — no empty flat backgrounds.
+7. Provide code that reflects this high-end, uncluttered, editorial aesthetic natively without requiring manual adjustments.

package/references/styles/soft.md

@@ -0,0 +1,94 @@
+
+# Agent Skill: Principal UI/UX Architect & Motion Choreographer (Awwwards-Tier)
+
+## 1. Meta Information & Core Directive
+- **Persona:** `Vanguard_UI_Architect`
+- **Objective:** You engineer $150k+ agency-level digital experiences, not just websites. Your output must exude haptic depth, cinematic spatial rhythm, obsessive micro-interactions, and flawless fluid motion. 
+- **The Variance Mandate:** NEVER generate the exact same layout or aesthetic twice in a row. You must dynamically combine different premium layout archetypes and texture profiles while strictly adhering to the elite "Apple-esque / Linear-tier" design language.
+
+## 2. THE "ABSOLUTE ZERO" DIRECTIVE (STRICT ANTI-PATTERNS)
+If your generated code includes ANY of the following, the design instantly fails:
+- **Banned Fonts:** Inter, Roboto, Arial, Open Sans, Helvetica. (Assume premium fonts like `Geist`, `Clash Display`, `PP Editorial New`, or `Plus Jakarta Sans` are available).
+- **Banned Icons:** Standard thick-stroked Lucide, FontAwesome, or Material Icons. Use only ultra-light, precise lines (e.g., Phosphor Light, Remix Line).
+- **Banned Borders & Shadows:** Generic 1px solid gray borders. Harsh, dark drop shadows (`shadow-md`, `rgba(0,0,0,0.3)`). 
+- **Banned Layouts:** Edge-to-edge sticky navbars glued to the top. Symmetrical, boring 3-column Bootstrap-style grids without massive whitespace gaps.
+- **Banned Motion:** Standard `linear` or `ease-in-out` transitions. Instant state changes without interpolation.
+
+## 3. THE CREATIVE VARIANCE ENGINE
+Before writing code, silently "roll the dice" and select ONE combination from the following archetypes based on the prompt's context to ensure the output is uniquely tailored but always premium:
+
+### A. Vibe & Texture Archetypes (Pick 1)
+1. **Ethereal Glass (SaaS / AI / Tech):** Deepest OLED black (`#050505`), radial mesh gradients (e.g., subtle glowing purple/emerald orbs) in the background. Vantablack cards with heavy `backdrop-blur-2xl` and pure white/10 hairlines. Wide geometric Grotesk typography.
+2. **Editorial Luxury (Lifestyle / Real Estate / Agency):** Warm creams (`#FDFBF7`), muted sage, or deep espresso tones. High-contrast Variable Serif fonts for massive headings. Subtle CSS noise/film-grain overlay (`opacity-[0.03]`) for a physical paper feel.
+3. **Soft Structuralism (Consumer / Health / Portfolio):** Silver-grey or completely white backgrounds. Massive bold Grotesk typography. Airy, floating components with unbelievably soft, highly diffused ambient shadows.
+
+### B. Layout Archetypes (Pick 1)
+1. **The Asymmetrical Bento:** A masonry-like CSS Grid of varying card sizes (e.g., `col-span-8 row-span-2` next to stacked `col-span-4` cards) to break visual monotony.
+   - **Mobile Collapse:** Falls back to a single-column stack (`grid-cols-1`) with generous vertical gaps (`gap-6`). All `col-span` overrides reset to `col-span-1`.
+2. **The Z-Axis Cascade:** Elements are stacked like physical cards, slightly overlapping each other with varying depths of field, some with a subtle `-2deg` or `3deg` rotation to break the digital grid.
+   - **Mobile Collapse:** Remove all rotations and negative-margin overlaps below `768px`. Stack vertically with standard spacing. Overlapping elements cause touch-target conflicts on mobile.
+3. **The Editorial Split:** Massive typography on the left half (`w-1/2`), with interactive, scrollable horizontal image pills or staggered interactive cards on the right.
+   - **Mobile Collapse:** Converts to a full-width vertical stack (`w-full`). Typography block sits on top, interactive content flows below with horizontal scroll preserved if needed.
+
+**Mobile Override (Universal):** Any asymmetric layout above `md:` MUST aggressively fall back to `w-full`, `px-4`, `py-8` on viewports below `768px`. Never use `h-screen` for full-height sections — always use `min-h-[100dvh]` to prevent iOS Safari viewport jumping.
+
+## 4. HAPTIC MICRO-AESTHETICS (COMPONENT MASTERY)
+
+### A. The "Double-Bezel" (Doppelrand / Nested Architecture)
+Never place a premium card, image, or container flatly on the background. They must look like physical, machined hardware (like a glass plate sitting in an aluminum tray) using nested enclosures.
+- **Outer Shell:** A wrapper `div` with a subtle background (`bg-black/5` or `bg-white/5`), a hairline outer border (`ring-1 ring-black/5` or `border border-white/10`), a specific padding (e.g., `p-1.5` or `p-2`), and a large outer radius (`rounded-[2rem]`).
+- **Inner Core:** The actual content container inside the shell. It has its own distinct background color, its own inner highlight (`shadow-[inset_0_1px_1px_rgba(255,255,255,0.15)]`), and a mathematically calculated smaller radius (e.g., `rounded-[calc(2rem-0.375rem)]`) for concentric curves.
+
+### B. Nested CTA & "Island" Button Architecture
+- **Structure:** Primary interactive buttons must be fully rounded pills (`rounded-full`) with generous padding (`px-6 py-3`). 
+- **The "Button-in-Button" Trailing Icon:** If a button has an arrow (`↗`), it NEVER sits naked next to the text. It must be nested inside its own distinct circular wrapper (e.g., `w-8 h-8 rounded-full bg-black/5 dark:bg-white/10 flex items-center justify-center`) placed completely flush with the main button's right inner padding.
+
+### C. Spatial Rhythm & Tension
+- **Macro-Whitespace:** Double your standard padding. Use `py-24` to `py-40` for sections. Allow the design to breathe heavily.
+- **Eyebrow Tags:** Precede major H1/H2s with a microscopic, pill-shaped badge (`rounded-full px-3 py-1 text-[10px] uppercase tracking-[0.2em] font-medium`).
+
+## 5. MOTION CHOREOGRAPHY (FLUID DYNAMICS)
+Never use default transitions. All motion must simulate real-world mass and spring physics. Use custom cubic-beziers (e.g., `transition-all duration-700 ease-[cubic-bezier(0.32,0.72,0,1)]`).
+
+### A. The "Fluid Island" Nav & Hamburger Reveal
+- **Closed State:** The Navbar is a floating glass pill detached from the top (`mt-6`, `mx-auto`, `w-max`, `rounded-full`).
+- **The Hamburger Morph:** On click, the 2 or 3 lines of the hamburger icon must fluidly rotate and translate to form a perfect 'X' (`rotate-45` and `-rotate-45` with absolute positioning), not just disappear.
+- **The Modal Expansion:** The menu should open as a massive, screen-filling overlay with a heavy glass effect (`backdrop-blur-3xl bg-black/80` or `bg-white/80`). 
+- **Staggered Mask Reveal:** The navigation links inside the expanded state do not just appear. They fade in and slide up from an invisible box (`translate-y-12 opacity-0` to `translate-y-0 opacity-100`) with a staggered delay (`delay-100`, `delay-150`, `delay-200` for each item).
+
+### B. Magnetic Button Hover Physics
+- Use the `group` utility. On hover, do not just change the background color.
+- Scale the entire button down slightly (`active:scale-[0.98]`) to simulate physical pressing.
+- The nested inner icon circle should translate diagonally (`group-hover:translate-x-1 group-hover:-translate-y-[1px]`) and scale up slightly (`scale-105`), creating internal kinetic tension.
+
+### C. Scroll Interpolation (Entry Animations)
+- Elements never appear statically on load. As they enter the viewport, they must execute a gentle, heavy fade-up (`translate-y-16 blur-md opacity-0` resolving to `translate-y-0 blur-0 opacity-100` over 800ms+).
+- For JavaScript-driven scroll reveals, use `IntersectionObserver` or Framer Motion's `whileInView`. Never use `window.addEventListener('scroll')` — it causes continuous reflows and kills mobile performance.
+
+## 6. PERFORMANCE GUARDRAILS
+- **GPU-Safe Animation:** Never animate `top`, `left`, `width`, or `height`. Animate exclusively via `transform` and `opacity`. Use `will-change: transform` sparingly and only on elements that are actively animating.
+- **Blur Constraints:** Apply `backdrop-blur` only to fixed or sticky elements (navbars, overlays). Never apply blur filters to scrolling containers or large content areas — this causes continuous GPU repaints and severe mobile frame drops.
+- **Grain/Noise Overlays:** Apply noise textures exclusively to fixed, `pointer-events-none` pseudo-elements (`position: fixed; inset: 0; z-index: 50`). Never attach them to scrolling containers.
+- **Z-Index Discipline:** Do not use arbitrary `z-50` or `z-[9999]`. Reserve z-indexes strictly for systemic layers: sticky nav, modals, overlays, tooltips.
+
+## 7. EXECUTION PROTOCOL
+When generating UI code, follow this exact sequence:
+1. **[SILENT THOUGHT]** Roll the Variance Engine (Section 3). Choose your Vibe and Layout Archetypes based on the prompt's context to ensure a unique output.
+2. **[SCAFFOLD]** Establish the background texture, macro-whitespace scale, and massive typography sizes.
+3. **[ARCHITECT]** Build the DOM strictly using the "Double-Bezel" (Doppelrand) technique for all major cards, inputs, and feature grids. Use exaggerated squircle radii (`rounded-[2rem]`).
+4. **[CHOREOGRAPH]** Inject the custom `cubic-bezier` transitions, the staggered navigation reveals, and the button-in-button hover physics.
+5. **[OUTPUT]** Deliver flawless, pixel-perfect React/Tailwind/HTML code. Do not include basic, generic fallbacks.
+
+## 8. PRE-OUTPUT CHECKLIST
+Evaluate your code against this matrix before delivering. This is the last filter.
+- [ ] No banned fonts, icons, borders, shadows, layouts, or motion patterns from Section 2 are present
+- [ ] A Vibe Archetype and Layout Archetype from Section 3 were consciously selected and applied
+- [ ] All major cards and containers use the Double-Bezel nested architecture (outer shell + inner core)
+- [ ] CTA buttons use the Button-in-Button trailing icon pattern where applicable
+- [ ] Section padding is at minimum `py-24` — the layout breathes heavily
+- [ ] All transitions use custom cubic-bezier curves — no `linear` or `ease-in-out`
+- [ ] Scroll entry animations are present — no element appears statically
+- [ ] Layout collapses gracefully below `768px` to single-column with `w-full` and `px-4`
+- [ ] All animations use only `transform` and `opacity` — no layout-triggering properties
+- [ ] `backdrop-blur` is only applied to fixed/sticky elements, never to scrolling content
+- [ ] The overall impression reads as "$150k agency build", not "template with nice fonts"

package/references/threeui-spatial-engine.md

@@ -0,0 +1,224 @@
+# ThreeUI Spatial 3D & Procedural WebGL Engine Guide
+
+องค์ความรู้ สถาปัตยกรรมระดับ Production และคู่มือเทคนิคการสร้างหน้าเว็บ 3D / Spatial UI แบบ Zero-Heavy-Asset ที่ถอดรหัสจาก **ThreeUI (Meng To / DesignCode)** ออกแบบมาสำหรับการทำงานร่วมกับ AI Coding Agents โดยเฉพาะ
+
+---
+
+## 1. ปรัชญาและโครงสร้าง Dual-Layer Architecture
+
+ปัญหาหลักของการนำ Three.js / WebGL มาใส่ในเว็บแอปพลิเคชันยุคใหม่ (React 19 / Next.js) คือ:
+- **Virtual DOM Conflict**: การ re-render ของ React ทำลาย WebGL context หรือเกิด Double-Mounting ใน StrictMode
+- **Heavy Asset Penalty**: โมเดล 3D (.gltf/.glb) มีขนาดใหญ่ (10-50MB) โหลดช้า และกินหน่วยความจำ GPU มหาศาล
+- **AI Coding Fragility**: เมื่อ AI พยายามเขียน Canvas, Shaders, และ React state ปนกัน มักเกิดข้อผิดพลาดด้าน Memory Leak และ Event Listeners
+
+### ThreeUI Architectural Solution:
+ThreeUI แก้ปัญหานี้ด้วย **Dual-Layer Sandbox Frame**:
+1. **Outer Layer (React Host Component)**: ตัวครอบเบาๆ เช่น `LandingPageFrame.tsx` ทำหน้าที่รับ Props จากผู้ใช้ (Typography, Colors, Camera tilt, Shader sliders) และเรนเดอร์ `<iframe>` แบบ Sandboxed
+2. **Inner Layer (Standalone Authored Document)**: หน้า HTML อิสระ (เช่น `kage.html`, `sylva.html`) ที่บรรจุ Three.js runtime, Procedural Geometry, และ Event Listeners ของตัวเองแบบ Isolated 100%
+3. **The Communication Bridge**: React Host จะไม่ยุ่งกับโค้ด JavaScript ข้างใน แต่จะฉีด Dynamic CSS Tokens (`:root { --ink: ... }`) หรือส่งข้อความผ่าน postMessage เข้าไปยัง iframe head ทำให้เปลี่ยนสี, ปรับฟอนต์, และจูนสไตล์ได้แบบ Real-time โดยไม่ทำลาย WebGL context
+
+---
+
+## 2. Agentic Prompt Contract Standard (มาตรฐานคำสั่ง AI Agent)
+
+เมื่อต้องการส่งคำสั่งให้ AI Coding Agent (Cursor, Claude Code, Antigravity) นำ 3D Component หรือ Landing Page ไปติดตั้ง ให้ใช้รูปแบบสัญญาที่มีความแม่นยำสูง (High-Fidelity Prompt Contract):
+
+```markdown
+# Integrate <[ComponentName] /> from ThreeUI using its exact source
+
+Component: `[ComponentName]`
+Runtime: Full HTML + DOM/CSS + Three.js
+Source revision: `SHA-256 [Commit/Document Hash]`
+
+## Current configured usage
+```tsx
+import { [ComponentName] } from "@/components/threeui/[ComponentName]";
+
+export function Scene() {
+  return (
+    <div className="shader-frame">
+      <[ComponentName]
+        primaryColor="#e0231c"
+        headingFont="onest"
+        bodyFont="onest"
+      />
+    </div>
+  );
+}
+```
+
+## Exact implementation source
+Canonical HTML: [slug.html](https://threeui.com/landing-pages/[slug].html)
+Bundle URL: https://threeui.com/source-code/[slug].json
+
+Required registered files:
+- `LandingPages.tsx` — component · SHA-256 [hash]
+- `LandingPageFrame.tsx` — frame-component · SHA-256 [hash]
+- `pageTypography.ts` — controls-source · SHA-256 [hash]
+- `public/landing-pages/[slug].html` — canonical-source · SHA-256 [hash]
+
+## Implementation requirements
+- Preserve the authored structure, styling, shaders, motion, and asset paths described by the source.
+- Do not recreate from preview or screenshot; fetch the registered source bundle.
+- Maintain battery & GPU hygiene (IntersectionObserver throttling).
+```
+
+---
+
+## 3. สถาปัตยกรรม LandingPageFrame & Dynamic CSS Retoner
+
+### 3.1 ตัวอย่างโครงสร้าง Frame Host (`LandingPageFrame.tsx`)
+```tsx
+import { useEffect, useRef, useState, type CSSProperties } from "react";
+
+export type LandingPageFrameProps = {
+  sourceUrl: string;
+  srcDoc?: string;
+  title: string;
+  className?: string;
+  style?: CSSProperties;
+  backgroundCanvasSelector?: string; // ถ้ากำหนด จะเปิดโหมด Scene-Only Background
+  customization?: {
+    css: string;
+    fonts: string[];
+    filter?: string;
+  };
+};
+
+export function LandingPageFrame({
+  sourceUrl,
+  srcDoc,
+  title,
+  backgroundCanvasSelector,
+  customization,
+  className = "",
+  style,
+}: LandingPageFrameProps) {
+  const frameRef = useRef<HTMLIFrameElement>(null);
+
+  // เมื่อ iframe โหลดเสร็จ หรือค่า customization เปลี่ยน ให้ฉีด CSS เข้า head โดยตรง
+  useEffect(() => {
+    const frame = frameRef.current;
+    if (!frame || !frame.contentDocument) return;
+
+    const doc = frame.contentDocument;
+    let styleTag = doc.getElementById("threeui-dynamic-overrides");
+    if (!styleTag) {
+      styleTag = doc.createElement("style");
+      styleTag.id = "threeui-dynamic-overrides";
+      doc.head.appendChild(styleTag);
+    }
+
+    let css = customization?.css ?? "";
+    // หากเป็นโหมด Background ให้ซ่อน UI elements ทั้งหมดยกเว้น Canvas
+    if (backgroundCanvasSelector) {
+      css += `
+        .page, header, footer, nav, .hero-content { display: none !important; }
+        body { background: transparent !important; overflow: hidden !important; }
+        ${backgroundCanvasSelector} { position: fixed !important; inset: 0 !important; width: 100vw !important; height: 100vh !important; }
+      `;
+    }
+    styleTag.textContent = css;
+  }, [customization, backgroundCanvasSelector]);
+
+  return (
+    <iframe
+      ref={frameRef}
+      title={title}
+      src={srcDoc ? undefined : sourceUrl}
+      srcDoc={srcDoc}
+      className={`threeui-frame ${className}`}
+      style={{ width: "100%", height: "100%", border: 0, ...style }}
+      loading="lazy"
+      sandbox="allow-scripts allow-same-origin"
+    />
+  );
+}
+```
+
+---
+
+## 4. Zero-Heavy-Asset Procedural 3D & 2.5D Parallax System
+
+ThreeUI หลีกเลี่ยงไฟล์ 3D หนักๆ โดยใช้เทคนิคผสมผสานระหว่างคณิตศาสตร์และรูปภาพแบนด์วิธต่ำ:
+
+1. **Procedural Meshes**:
+   - ภูมิประเทศ ท้องฟ้า และเมฆ สร้างจาก `THREE.PlaneGeometry` หรือ `THREE.SphereGeometry` แล้วบิดรูปทรงด้วย Simplex / Perlin Noise บน Vertex Shader
+2. **2.5D WebP Layered Depth Sprites**:
+   - องค์ประกอบฉากหน้า (ต้นสน, ซุ้มประตู, หิน, กิ่งซากุระ, โคมไฟ) บันทึกเป็นรูป WebP พร้อม Alpha Channel แยกชิ้น
+   - นำมาวางบน `THREE.Mesh(new THREE.PlaneGeometry(...), material)` จัดเรียงความลึกบนแกน Z พร้อมเปิด `material.transparent = true; material.depthWrite = false;`
+   - ผลลัพธ์: ได้ความสมจริงระดับงานศิลปะ แต่ขนาดรวมทั้งหน้าเว็บไม่เกิน 2-3 MB
+
+---
+
+## 5. มาตรฐาน GPU & Battery Hygiene (กฎเหล็ก Production)
+
+เมื่อนำ Three.js หรือ WebGL มาใช้ ต้องมี 3 กฎเหล็กเสมอ:
+1. **Intersection Throttling**:
+   ```javascript
+   const intersection = new IntersectionObserver(([entry]) => {
+     visible = entry?.isIntersecting ?? true;
+     if (visible && !frameId) frameId = requestAnimationFrame(render);
+     if (!visible && frameId) { cancelAnimationFrame(frameId); frameId = 0; }
+   });
+   intersection.observe(container);
+   ```
+2. **DevicePixelRatio Clamping**:
+   - ห้ามใช้ `window.devicePixelRatio` ดิบๆ บนจอ 4K/Retina
+   - กำหนด: `const pixelRatio = Math.min(window.devicePixelRatio || 1, 2);`
+3. **Linear Color Space & Tone Mapping**:
+   - `renderer.toneMapping = THREE.ACESFilmicToneMapping;`
+   - `renderer.toneMappingExposure = 1.0;`
+   - `renderer.outputColorSpace = THREE.SRGBColorSpace;`
+4. **Uncompressed VRAM Budget Gate (≤ 32MB) & Modern Compression**:
+   - ปัญหาของ Draco คือไฟล์ดาวน์โหลดเล็กแต่เมื่อคลายบีบอัดบน GPU จะขยายร่างเป็น 60MB–140MB บน VRAM จนทำให้ Safari บน iOS สั่ง Kill Tab
+   - **กฎเหล็กใหม่:** คุมหน่วยความจำ **Uncompressed VRAM Footprint รวมไม่เกิน 32MB**
+   - บังคับใช้ **Meshopt Compression** (คลายบีบอัดเร็วกว่า Draco 5 เท่า ขนาด WASM Decoder เพียง 20KB ไม่ทำให้ Main-Thread ค้าง)
+   - พื้นผิว Texture บังคับใช้ **KTX2 (Basis Universal UASTC/ETC1S)** เพราะถูกส่งตรงไปยัง VRAM ในสถานะบีบอัดได้ทันทีโดยไม่ต้องแตกไฟล์เป็น Bitmap ขนาดใหญ่
+5. **Clean Lifecycle Disposal & Context Leak Prevention**:
+   - เมื่อ Component ถูก Unmount ต้องสั่ง Dispose ทรัพยากร GPU ทั้งหมดเพื่อป้องกัน Memory Leaks:
+   ```javascript
+   geometry?.dispose();
+   material?.dispose();
+   texture?.dispose();
+   renderer?.dispose();
+   renderer?.forceContextLoss();
+   ```
+6. **DOM Overlay & Canvas Pointer-Events Layering**:
+   - Canvas ฉากหลัง: `position: fixed; inset: 0; z-index: 0; pointer-events: auto;`
+   - UI Container ซ้อนทับ: `position: relative; z-index: 10; pointer-events: none;`
+   - ปุ่ม/ลิงก์/ฟอร์มที่กดได้: `pointer-events: auto;` (เพื่อให้ Pointer Event ของการหมุน Orbit ทะลุช่องว่างระหว่างปุ่มลงสู่ Canvas ได้ราบรื่น)
+7. **On-Demand WebGL Render Loop (0W GPU Idle Power)**:
+   - สำหรับฉากที่ไม่ต้องการ Render คลื่นน้ำหรือแสงกระพริบตลอดเวลา บังคับใช้ `frameloop="demand"`
+   - ตัดลูป `requestAnimationFrame` ทันทีเมื่อความเร็วการหมุนหรือซูม $\lvert v \rvert < 0.0001$ เพื่อให้ GPU ใช้พลังงานเป็น **0 วัตต์** ประหยัดแบตเตอรี่สูงสุด
+
+---
+
+## 6. Curated Recipe Vault (สูตรแม่แบบยอดนิยม)
+
+### 1. Kage (Kyoto Night Temple Walk)
+- **Concept**: วัดบนภูเขาเกียวโตยามค่ำคืน เปลวไฟโคมหิน และดวงจันทร์สีชาด
+- **Colors**: Ink Black `#05070a`, Pale Sage Bone `#dfe7e0`, Vermilion `#e0231c`, Gold `#c9a24a`
+- **Fog**: `scene.fog = new THREE.FogExp2(0x050a0e, 0.0168);`
+- **Lighting**: PCF Soft Shadows + Multi-point Lantern flickering lights
+- **Typography**: Onest font (Weight 300 / 400), tracking `-0.012em`
+
+### 2. Kibori (Japanese Wooden Sculpture)
+- **Concept**: งานช่างไม้แกะสลัก ริ้วเนื้อไม้ธรรมชาติ แสงและเงาที่อบอุ่น
+- **Colors**: Deep Cedar `#1a1512`, Hinoki `#d4b28c`, Charcoal `#2c2825`
+- **Material**: Procedural wood grain bump shaders with subtle ambient occlusion
+
+### 3. Meng To Sketchbook (Botanical Watercolor Parallax)
+- **Concept**: สมุดบันทึกพฤกษศาสตร์ กระดาษวาชิ และภาพสีน้ำแยกเลเยอร์
+- **Colors**: Paper Ivory `#fcfbf7`, Sumi Ink `#1b1b19`, Botanical Green `#405943`
+- **Technique**: Multi-layer 2D canvas blending with drifting procedural petal particles
+
+### 4. Sylva / Inner Green (Living Forest World)
+- **Concept**: โลกธรรมชาติป่าดิบ การฟื้นฟูระบบนิเวศ
+- **Colors**: Forest Moss `#383b34`, Pale Card `#f2f3ef`, Deep Earth `#23261f`
+- **Unit System**: `calc(100vw / 1600)` เพื่อให้สัดส่วนของฉากสมมาตรเป๊ะทุกความกว้างจอ
+
+### 5. Sable / Ascii Vortex
+- **Concept**: อุโมงค์ตัวอักษรและพายุดูดข้อมูล (AI Agent Interface)
+- **Colors**: Pitch Black `#000000`, Monospace White `#ffffff`, Terminal Green
+- **Technique**: Raymarched glyph sampling, pointer suction well, dynamic font dissolution