# Task: Investigate and fix the first-open work preview layout

## Identity

- Task ID: 20261008-work-first-open-8ac7e621
- Mode: Feature
- Branch: codex/20261008-work-first-open-8ac7e621-work-first-open
- Worktree: /Users/chillishark/Makelore 麦洛/.codex-worktrees/makelore/20261008-work-first-open-8ac7e621
- Base commit: fe1a3775c5f785adaa6372bd7ea3102c79331656
- Owner: codex
- Status: Ready for Integration

## Scope

- Fix the first-open Work preview being pushed below the entire teacher welcome group. Renderer visibility only; preserve native-preview overlay clearance for real messages and hover introductions.

## Intent And Constraints

- User confirmed: temporarily hide welcome introductions on Work, restore on Operation Chat. Do not persist dismissal or change the three-operation-round introduction lifecycle, unread receipts, consultation entry, or preview startup.
- No running-app update, main merge, push, or cleanup requested for this change.

## Project Context Loaded

Task context:
- Task ID / mode / branch / worktree / base: exactly as Identity above; official start and status ownership verification passed.
- Other local tasks: 27 peer owner records inspected by read-only reviewer through their registered paths; no active conflicting layout work.
- Related completed scopes: teacher-group-intro, hover intro, preview toolbar, empty-work preview. Preserve grouped dismissal and real unread messages.

Read:
- Agent entry/read-before-planning, memory-index, planning-gate; this task record.
- Project positioning, current-state, decision-index, system-overview, business-rules, success-criteria (task-relevant sections).
- ADR-2026-09-22-coding-teacher; evidence-index, reflection-index, commitments; AGENTS.md and README.md.

Relevant understanding:
- Project goal: student creation workspace with Main-owned native Work preview and cloud-defined teachers.
- Integrated baseline: fe1a377, clean main. URL toolbar beside workspace tabs; native pixels avoid teacher DOM overlays.
- Root cause: bubbleRef points to the whole welcome group; usePreviewClearance offsets the whole panel below its bottom, wasting most of the first-open viewport.
- Constraints: only gate welcome rendering with the current tab; keep hook/persistence, real invitations, hover descriptions, and backend contracts unchanged.
- Canonical ADR still describes per-teacher introduction dismissal, superseded by the grouped implementation and README; this change preserves current grouped behavior.
- Evidence: user screenshots and static code; isolated browser measurements and regressions to follow. No applicable unresolved external commitment.
- Modules: TeacherCompanion, CodingChatPanel, related unit/browser/Electron fixtures and README.

Gate result: Passed.

## Plan

1. Add a presentation-only welcome visibility prop and derive it from the Work tab.
2. Cover hide/restore without consuming welcome state, real messages remaining visible, first-open preview geometry, and actual workspace integration.
3. Run focused unit/browser/Electron checks, typecheck, lint and production build; record evidence and hand off a committed feature branch.

## Outcome

- Added presentation-only `showWelcomes` to TeacherCompanion, controlled by `!agentBrowserOpen`. Both grouped introductions and the legacy static welcome are unmounted on Work, and return on Operation Chat if not already consumed by existing lifecycle rules.
- Real invitations/unread markers and hover descriptions remain visible with existing native-preview clearance. No persistent dismissal, model call, storage change, or preview startup change is triggered by this flag.
- Updated README, lifecycle unit regressions, four-size browser layout scenarios, and the existing actual Electron workspace test.
- Baseline reproduced in isolation: group height 440px; native preview was pushed down 391px, from top 107px to 498px. At 1280x800, height dropped from 639px to 248px; at 1440x900, from 739px to 348px. Fixed screenshots restore top 107px and full 639/739px height.
- Independent read-only review found no blocking issue, stale margin, ResizeObserver leak, or new first-open bounds race.

## Verification

- Typecheck, scoped ESLint, and production build:vite passed using pinned pnpm 10.33.4. Logs: `/tmp/makelore-first-work-{typecheck,lint,build}.log`.
- Focused units: 103 cases across teacher-companion, coding-chat-panel, and agent-browser-panel. Initial parallel run passed 102 and hit an existing asynchronous presentation assertion in unchanged agent-browser-panel; that file passed all 17 alone on retry. All changed-component tests passed initially. Logs: `/tmp/makelore-first-work-units.log`, `/tmp/makelore-first-work-browser-units-retry.log`.
- Browser layout suite: 18/18 passed, including 375/768/1280/1440px hide/restore, repeat visits, explicit dismissal, real messages, and hover clearance. Screenshots visually inspected; no horizontal overflow. `/tmp/work-first-open-browser-8ac7e621/run.log` and `results/`.
- Electron production-build fixture: 1/1 passed, proving actual workspace tab wiring, full-height preview, hover recovery, welcome restoration, teacher entry and retained drafts. `/tmp/makelore-first-work-electron.log`, `/tmp/makelore-first-work-electron-results/`.
- Baseline geometry and before/after images: `/tmp/work-first-open-repro-8ac7e621/`.
- Tests use isolated fixtures; installed app and user project/data were not changed. No installed-app update or native game-content acceptance claimed.

## Follow-ups

- Running-app update and main integration remain separate user-requested steps; feature branch is ready for handoff.

## Promotion Candidates

- Target: teacher ADR and system-overview. Proposal: static welcome introductions are paused on Work and restored on Operation Chat without consuming introduction or unread state; actual messages and hover descriptions retain native clearance. Evidence: user explicitly selected this behavior, focused lifecycle/browser/Electron regressions. Future impact: prevents reintroducing full-panel welcome clearance on first Work entry. Conflict: older ADR intro dismissal wording is stale relative to grouped implementation; leave it read-only in this feature. Further human confirmation for this visibility behavior is not required.