=== PAF-STUDIO CODE TERMINAL ARCHITECTURE & THEMING INVESTIGATION ===
Investigation Date: 2026-06-22
Read-only exploration of terminal.paf-studio.dev setup

1. CADDY CONFIGURATION
   File: /etc/caddy/previews/terminal.caddy
   Domain: terminal.paf-studio.dev
   
   Route mapping:
   - GET /                      → /opt/claude-code/public/terminal/index.html (static root page)
   - GET /terminal/api/sessions → /home/dev/.config/claude-code/terminal-sessions.json
   - GET /terminal/api/transfers/* → localhost:7683 (reverse proxy)
   - GET /terminal/*           → localhost:7681 (ttyd, base-path=/terminal)
   - GET /attach/*             → localhost:7682 (ttyd, base-path=/attach)

2. ROOT INDEX PAGE (LANDING / GATE LOCATION)
   File: /opt/claude-code/public/terminal/index.html (11.8 KB, human-readable HTML)
   
   Current behavior:
   - Serves a decorated landing page at terminal.paf-studio.dev root
   - Shows "PAF-STUDIO CODE" brand with purple/dark theme
   - Lists active tmux sessions (polled every 10 seconds from API)
   - Buttons: "Nouveau terminal" (new) and "Reprendre" (reconnect)
   - On button click: navigates to /terminal/?arg=<session_id>[&arg=<target>][&arg=reclaim]
   
   This page IS ALREADY a gate! But it's not a "press any key" gate—it's a session picker.
   
   Color scheme (CSS custom properties):
   --bg: #080812 (dark blue-black)
   --text: #f1f0ff (off-white purple)
   --amber: #ffcc33
   --green: #35d878
   --blue: #48a8ff
   --violet: #9a5cff
   --pink: #ff3f7f

3. TTYD SERVICES (2 running)
   
   Service 1: ttyd.service (main terminal)
   Port: 7681
   Invocation:
   /usr/bin/ttyd \
     -p 7681 \
     -i 127.0.0.1 \
     -W (writable) \
     -a (url-arg enabled) \
     -I /opt/claude-code/ttyd-index.html (custom index) \
     -T xterm-256color \
     -t scrollback=50000 \
     -t macOptionClickForcesSelection=true \
     -P 10 (ping interval) \
     -c archibald:ArchibaldCochonouDu974! (basic auth) \
     --base-path /terminal \
     /opt/claude-code/cc-web
   
   Service 2: ttyd-attach.service (experimental attach)
   Port: 7682
   Same config + base-path=/attach + runs /opt/claude-code/cc-attach

4. TTYD CUSTOM INDEX
   File: /opt/claude-code/ttyd-index.html (602 lines, heavily minified)
   
   This is the index served INSIDE the ttyd terminal (when you navigate to /terminal/?arg=...).
   NOT the root landing page.
   
   Contains full xterm.js + ttyd client libraries (bundled, minified).
   Hardcoded theme in JavaScript (extracted below).

5. TTYD DEFAULT THEME (CURRENT)
   Location: /opt/claude-code/ttyd-index.html (embedded in minified bundle)
   
   Colors (xterm.js 16-color palette):
   foreground:      #d2d2d2 (light gray)
   background:      #2b2b2b (dark gray)
   cursor:          #adadad (medium gray)
   
   Standard colors:
   black:           #000000
   red:             #d81e00
   green:           #5ea702
   yellow:          #cfae00
   blue:            #427ab3
   magenta:         #89658e
   cyan:            #00a7aa
   white:           #dbded8
   
   Bright colors:
   brightBlack:     #686a66
   brightRed:       #f54235
   brightGreen:     #99e343
   brightYellow:    #fdeb61
   brightBlue:      #84b0d8
   brightMagenta:   #bc94b7
   brightCyan:      #37e6e8
   brightWhite:     #f1f1f0
   
   Font:
   fontFamily: "Consolas,Liberation Mono,Menlo,Courier,monospace"
   fontSize: 13

6. REQUEST FLOW (BROWSER REQUEST → TERMINAL)
   
   browser on terminal.paf-studio.dev
        ↓
   Caddy reverse proxy (paf-studio.dev domain config)
        ↓
   GET / → serves /opt/claude-code/public/terminal/index.html
        ↓
   User clicks "Nouveau terminal" or "Reprendre"
        ↓
   Navigates to /terminal/?arg=<session_id>[&arg=target][&arg=reclaim]
        ↓
   Caddy matches /terminal/* rule
        ↓
   Reverse proxy to localhost:7681 (ttyd service)
        ↓
   ttyd at /terminal/:
      - Initializes xterm.js WebSocket connection
      - Authenticates with basic auth (archibald:...)
      - Loads /opt/claude-code/ttyd-index.html (custom index)
      - Applies embedded xterm theme
      - Mounts /opt/claude-code/cc-web as shell command
      - cc-web spawns/attaches tmux session based on ?arg= params
        ↓
   tmux terminal pane appears in browser

7. GATE FEATURE INSERTION POINTS
   
   Option A: "Press any key to enter" splash at /
   
   Current state: /opt/claude-code/public/terminal/index.html is a session picker.
   
   Feasibility: HIGH
   - Modify /opt/claude-code/public/terminal/index.html to add a splash screen
   - On first load, show splash overlay with "Press any key to enter"
   - Store flag in sessionStorage / localStorage
   - On key press: hide splash, show session list
   - Must preserve current button functionality
   
   Pros:
   - User lands at the gate before seeing sessions
   - Can apply "base terminal theme" colors to splash background
   - No ttyd configuration changes needed
   - Non-breaking change
   
   Cons:
   - Session list still visible behind (could be opacity'd)
   - Splash must be in the same HTML file (or a separate one served by Caddy)
   
   Option B: Custom splash page + 301 redirect
   
   Feasibility: MEDIUM
   - Create new HTML file: /opt/claude-code/public/terminal/splash.html
   - Modify Caddy config: serve splash.html at / (instead of index.html)
   - On key press: redirect to /sessions or load index.html
   - Update routing to show actual /terminal/index.html at a subpath
   
   Pros:
   - Cleaner separation of concerns
   
   Cons:
   - Extra Caddy config change
   - More complex redirects
   
   Option C: "Base terminal theme" application to splash
   
   The "base terminal theme" from ttyd (hardcoded in ttyd-index.html) can be replicated:
   background: #2b2b2b (dark gray)
   foreground: #d2d2d2 (light gray)
   
   This could be applied to a splash screen by modifying the root index.html's CSS.
   OR: could pass theme as query param or cookie to ttyd at /terminal/?...
   
   BUT: ttyd does NOT support dynamic theme injection via URL params or cookies.
   The theme is baked into the minified ttyd-index.html bundle.
   
   To truly apply theme across splash + terminal:
   1. Rebuild ttyd-index.html with new theme (requires Node/Webpack)
   2. OR use CSS to mimic the theme colors on the landing page
   
8. SYSTEMIC CONSTRAINTS & SUMMARY
   
   Current architecture:
   - Landing page (Caddy static file serve): /opt/claude-code/public/terminal/index.html
   - Terminal WebSocket (ttyd): localhost:7681
   - Theming: hardcoded in minified ttyd-index.html
   - Auth: basic auth enforced by ttyd service
   
   Gating feasibility:
   ✓ Easy: add "press any key" overlay to landing page HTML
   ✓ Easy: apply #2b2b2b background to gate splash
   ✓ Medium: theme consistency across splash + terminal (CSS-based mimic)
   ✗ Hard: dynamic theme injection into ttyd (requires rebuild)
   ✗ Hard: ttyd's --client-option does NOT parse theme JSON (only supports scalar values like scrollback)
   
   Recommended approach:
   1. Modify /opt/claude-code/public/terminal/index.html
   2. Add full-screen splash overlay on first page load
   3. Overlay displays "Press any key to enter" message
   4. Splash background color: #2b2b2b (match ttyd terminal bg)
   5. Text color: #d2d2d2 (match ttyd foreground)
   6. On key press: fade out splash, reveal session list
   7. Store flag in sessionStorage to not re-show splash on session picker button clicks
   8. No changes needed to Caddy, ttyd services, or ttyd-index.html