flatrender/docs/SESSION_HANDOFF.md

FlatRender V2 — Session Handoff & Gotchas

Context captured 2026-06-05 so it survives a Claude-account/machine change. The ~/.claude memory is machine-local; this file is the portable copy.

How to run (V2 stack)

# Backend services + infra (Postgres + MinIO) — V2 compose, NOT the default docker-compose.yml
docker compose -f docker-compose.v2.yml --env-file .env.v2 up -d
# Rebuild one service after a code change:
docker compose -f docker-compose.v2.yml --env-file .env.v2 build <svc> && \
docker compose -f docker-compose.v2.yml --env-file .env.v2 up -d <svc>
# Services: identity-svc, content-svc, file-svc, studio-svc, render-svc, notification-svc, gateway, frontend

• Open the app at http://172.28.144.1:3000 (the host LAN IP), NOT localhost.
• Gateway: :8088. JWT secret + service creds live in .env.v2.
• DB: single Postgres flatrender, one schema per service (identity, content, studio, render, file, …). User postgres.
• DB migrations: backend/db/migrations/NN_*.sql, applied once by scripts/init-db.sh on first volume creation. New SQL files must be applied manually: docker exec fr2-postgres psql -U postgres -d flatrender -f ... (or inline -c).

⚠️ Critical gotchas (these have each cost hours)

1. Localhost is VPN-hijacked. EonVPN intercepts 127.0.0.1:*. Curl/loopback to localhost returns junk/000 even when the app is up. Use the LAN IP 172.28.144.1, or docker exec <container> wget -qO- http://<svc>:<port>.

2. Non-secure browser context. Because the app is served over http://172.28.144.1 (plain HTTP, non-localhost), the browser is a non-secure context → crypto.randomUUID, crypto.subtle, clipboard, etc. are undefined. NEVER call them in client code — use src/lib/uuid.ts uuid() (falls back to crypto.getRandomValues). This silently broke the entire studio editor (crypto.randomUUID is not a function).

3. Studio service binds camelCase JSON (no snake_case naming policy, unlike identity/content which use SnakeCaseLower). Frontend→studio request bodies MUST be camelCase (originalProjectId, not original_project_id) or fields drop to defaults (Guid.Empty). Studio responses are camelCase too.

4. EF Core global query filters (HasQueryFilter(DeletedAt==null)) require .IgnoreQueryFilters() to see/revive soft-deleted rows (bit the AEP import apply).

5. AE automation runs on a Windows node via node-agent.exe (PULL model: agent dials render-svc with HMAC). Before each AE launch the agent kills stale AE processes + clears crash/Safe-Mode markers (SCRPriorState.json + registry AppStates) and launches AE with the project as an arg (bypasses the Home screen). Heavy expression-driven AEPs take >10min to open → FIX scans are now binary-only (services/render/internal/aep/parse.go ParseNames reads frl_/frd_ names from the .aep RIFX directly; no AE).

What this session built (commits 6e5efbd → 5b2617d)

• AE scan hardening: binary FIX scanner (no AE, never hangs); kill stale AE + clear crash dialog before each launch.
• Profile = data-collection surface (for future AI video gen, NO resume builder): full editable profile (avatar upload + slogan/about/company/website/country/birthdate/gender), /api/profile + user-scoped /api/profile/upload. Identity DTOs widened (no migration — columns existed).
• Role-aware nav: UserMenu (avatar + dropdown; admins get Admin Panel link) replaces Sign-In when logged in; real avatars in dashboard sidebar + admin shell; Avatar primitive; getNavUser().
• Template detail page wired to real content (fetchProject(slug); was hardcoded demo catalog → 404'd).
• "Use template" works end-to-end: StudioService.CreateProjectAsync deep-copies the content template scene graph (scenes + content elements + scene colors + shared colors) into the editable studio project via one atomic cross-schema SQL copy (enum cols cast ::text; temp _scene_map). /api/projects resolves container slug → published variant project. Aspect-ratio picker (16:9/1:1/9:16) on the detail page drives which variant is copied.

⏭️ NEXT UP — Studio↔Template binding EPIC (agreed priority)

Phase B DONE (commits a69bc62 B1, 47a4ced B2). Edit→render binding works:

• B1 ✅ studio input edits persist to saved_scene_contents via studio-svc PATCH /v1/saved-projects/{id}/contents (Next /api/projects/[id]/contents); the persistence hook pushes edited values (bridged c-<key> layers) on every save.

• B2 ✅ render-svc claim now includes bindings (GetRenderBindings = saved_scene_contents with non-empty value); node-agent binder.go emits a JSON bind-spec + downloads media, runs the data-driven bind.jsx via afterfx (sets Source Text, replaces footage) → saves bound.aep → aerender renders THAT.

• VERIFY (needs node-agent re-run): re-run the updated node-agent.exe, edit a text input in the studio (wait for "saved"), render, confirm the MP4 shows the edited text. Colours (saved_shared_colors → spec.colors) + footage-item media (vs layer-source) are follow-ups.

• Done since: per-tier render height (#36), FIX-hides-add-scene (#42), admin/renders pagination + user-name links + output (#41), Persian/Jalali date pickers (#40).

• Still open in B: colours binding (saved_shared_colors → spec.colors), footage-item media (vs layer-source), deeper per-input controllers in the admin scene-inputs editor.

• Next epic phase: A admin preset stories (premade videos — model preset_stories/preset_scenes exists, no endpoints/UI; detail "ویدیوهای ساخته‌شده" is placeholder), and C AE single-frame scene snapshots (scenes.snapshot_url empty → node aerender -s 0 -e 0).

Also smaller, still open: per-tier render height (render-svc r_height hardcoded 1080 + node ffmpeg scale), FIX hides add-scene (mode not plumbed into studio store), Persian/Jalali date pickers in admin, admin/renders pagination + video/output + user-name → profile link, deeper per-input controllers in the admin scene-inputs editor.

Done follow-ups (this session)

• Scene-graph copy now includes repeater children, characters/controllers, color-presets.
• Admin CAN edit any user's full profile (Users → «پروفایل»).
• Studio now shows ALL template inputs (contents→layers bridge).

Debugging client-side behavior

No Playwright/Puppeteer in the repo. To reproduce browser issues headlessly: npm i puppeteer-core in a temp dir, launch the user's Chrome (C:\Program Files\Google\Chrome\Application\chrome.exe), set the auth cookie via page.setCookie({name:'fr_access', value:<JWT>, url:'http://172.28.144.1:3000'}), and listen on page.on('pageerror') / console. Mint a test admin JWT with the .env.v2 JWT_SECRET (HS256; claims sub=real user id, tenant_id, is_admin:"true", role:"Admin", iss:"flatrender-identity", aud:"flatrender").