---
phase: 04-foundation-flat-list-visual-chrome
plan: "02"
type: execute
wave: 2
depends_on:
  - "04-01"
files_modified:
  - possession/tui/app.py
  - possession/__main__.py
  - possession/tui/screens/splash.py
  - possession/tui/widgets/quickadd.py
autonomous: false
requirements:
  - SPSH-01
  - THEME-01
  - QADD-04

must_haves:
  truths:
    - "Running `python -m possession` shows a splash screen with ASCII art on launch"
    - "Pressing any key on the splash screen proceeds to the flat-list main screen"
    - "Running `python -m possession --transparent` starts the app with transparent background"
    - "Running `python -m possession` (no flag) uses the default Textual surface theme"
    - "Opening QuickAddBar with 'a' shows the format label 'name / description / room / container / category / date / cost' above the input and it stays visible while typing"
  artifacts:
    - path: "possession/tui/screens/splash.py"
      provides: "SplashScreen with ASCII art and any-key dismiss"
      contains: "class SplashScreen"
    - path: "possession/tui/app.py"
      provides: "PossessionApp with TITLE, transparent flag, splash push in on_mount"
      contains: "transparent"
    - path: "possession/__main__.py"
      provides: "CLI with --transparent flag"
      contains: "--transparent"
    - path: "possession/tui/widgets/quickadd.py"
      provides: "QuickAddBar with persistent format label above input"
      contains: "quickadd-label"
  key_links:
    - from: "possession/tui/app.py"
      to: "possession/tui/screens/splash.py"
      via: "push_screen(SplashScreen()) in on_mount()"
      pattern: "push_screen.*SplashScreen"
    - from: "possession/__main__.py"
      to: "possession/tui/app.py"
      via: "PossessionApp(db_path=..., transparent=args.transparent)"
      pattern: "transparent=args\\.transparent"
---

<objective>
Add three independent visual chrome features: splash screen on launch (SPSH-01), transparent background opt-in via --transparent flag (THEME-01), and persistent format label in QuickAddBar (QADD-04).

Purpose: Completes Phase 4 visual chrome. After Plan 01 establishes the flat list foundation, this plan adds the remaining UI polish. Each feature is independent — splash.py is a new file, app.py gets minimal additions, quickadd.py gets a compose-only change.

Output: splash.py, modified app.py, modified __main__.py, modified quickadd.py.
</objective>

<execution_context>
@/Users/paritoshpatil/.claude/get-shit-done/workflows/execute-plan.md
@/Users/paritoshpatil/.claude/get-shit-done/templates/summary.md
</execution_context>

<context>
@.planning/PROJECT.md
@.planning/ROADMAP.md
@.planning/STATE.md
@.planning/phases/04-foundation-flat-list-visual-chrome/04-RESEARCH.md
@.planning/phases/04-foundation-flat-list-visual-chrome/04-01-SUMMARY.md
@possession/tui/app.py
@possession/__main__.py
@possession/tui/widgets/quickadd.py
</context>

<tasks>

<task type="auto">
  <name>Task 1: Create SplashScreen and wire into app.py with transparent theme flag (SPSH-01 + THEME-01)</name>
  <files>
    possession/tui/screens/splash.py
    possession/tui/app.py
    possession/__main__.py
  </files>
  <action>
    **Part A: Create `possession/tui/screens/splash.py`**

    Create a new file (the `screens/` directory already exists):

    ```python
    from textual import events
    from textual.app import ComposeResult
    from textual.screen import Screen
    from textual.widgets import Static

    SPLASH_ART = r"""
     ____  ___  ____  ____  ____  ____  ____  ____  ___  _  _
    (  _ \/ __)( ___)(  __)/ ___)(  __)/ ___)/ ___)/   \( \/ )
     ) __/\__ \ ) _)  ) _) \___ \ ) _) \___ \\___ \( () ) )  /
    (__)  (___/(____)(____)(____/(____)(____/(____) \___/(_/\_/

                      press any key to continue
    """


    class SplashScreen(Screen):
        DEFAULT_CSS = """
        SplashScreen {
            align: center middle;
            background: $surface;
        }
        #splash-art {
            color: $primary;
            text-align: center;
        }
        """

        def compose(self) -> ComposeResult:
            yield Static(SPLASH_ART, id="splash-art")

        def on_key(self, event: events.Key) -> None:
            self.app.pop_screen()
    ```

    NOTE on push order: `SplashScreen` inherits from `Screen` (not `ModalScreen`). It is pushed ON TOP of `MainScreen`, so `MainScreen` is already loaded in the background when splash is visible. When `pop_screen()` is called, `MainScreen` is revealed and `on_screen_resume` fires (harmlessly reloads items — fast). This is correct and expected behavior.

    **Part B: Modify `possession/tui/app.py`**

    Update `PossessionApp` to:
    1. Add `TITLE = "Possession"` class attribute
    2. Add two CSS constants (`_CSS_DEFAULT`, `_CSS_TRANSPARENT`) as class attributes
    3. Accept `transparent: bool = False` in `__init__()`, set `self.CSS` after calling `super().__init__()` — instance attribute overrides class attribute at compose time
    4. Update `on_mount()` to push `MainScreen()` first, then `SplashScreen()` on top

    Full updated `app.py`:
    ```python
    from pathlib import Path
    from textual.app import App


    class PossessionApp(App):
        """Possession terminal inventory manager."""

        TITLE = "Possession"

        _CSS_DEFAULT = """
        Screen {
            background: $surface;
        }
        """
        _CSS_TRANSPARENT = """
        Screen {
            background: transparent;
        }
        DataTable {
            background: transparent;
        }
        """

        def __init__(self, db_path: Path, transparent: bool = False, **kwargs):
            super().__init__(**kwargs)
            self.db_path = db_path
            self.CSS = self._CSS_TRANSPARENT if transparent else self._CSS_DEFAULT

        def on_mount(self) -> None:
            from possession.tui.screens.main import MainScreen
            from possession.tui.screens.splash import SplashScreen
            self.push_screen(MainScreen())   # bottom of stack — loads in background
            self.push_screen(SplashScreen()) # top of stack — shown on launch
    ```

    NOTE: If the existing `app.py` already has `self.db_path` set in `__init__`, preserve that. The important additions are: `TITLE`, `_CSS_DEFAULT`/`_CSS_TRANSPARENT`, `transparent` param, `self.CSS` assignment, and the `SplashScreen` push in `on_mount`.

    NOTE on CSS assignment: Setting `self.CSS` (instance attribute) in `__init__` after calling `super().__init__()` overrides the class-level `CSS`. Textual reads the CSS attribute at compose time. If this proves unreliable during testing, the fallback is: instead of `self.CSS = ...`, use `self.add_class("transparent-mode")` and have both CSS rules in `DEFAULT_CSS` gated by `.transparent-mode`.

    **Part C: Modify `possession/__main__.py`**

    Add `--transparent` argument to the argparse parser (following the existing `--db` flag pattern):

    ```python
    parser.add_argument(
        "--transparent",
        action="store_true",
        default=False,
        help="Use terminal native background (transparent mode). "
             "Note: renders as opaque black inside tmux/multiplexers.",
    )
    ```

    Pass the flag to `PossessionApp`:
    ```python
    PossessionApp(db_path=resolved_path, transparent=args.transparent).run()
    ```

    Read the existing `__main__.py` first to understand the current `PossessionApp(...)` call pattern and update it correctly.
  </action>
  <verify>
    <automated>cd /Users/paritoshpatil/Personal/claude-projects/possession-terminal-2 && python -c "from possession.tui.screens.splash import SplashScreen; print('splash ok')" && python -c "from possession.tui.app import PossessionApp; print('app ok')" && python -m possession --help | grep transparent</automated>
    <manual>Run `python -m possession` — splash screen with ASCII art should appear; pressing any key should reveal the flat item list.</manual>
  </verify>
  <done>
    - `possession/tui/screens/splash.py` exists with `SplashScreen` class
    - `python -c "from possession.tui.screens.splash import SplashScreen"` exits 0
    - `python -m possession --help` shows `--transparent` option
    - `PossessionApp` in app.py has `TITLE = "Possession"`, `transparent` param, and `SplashScreen` push in `on_mount()`
  </done>
</task>

<task type="auto">
  <name>Task 2: Add persistent format label to QuickAddBar (QADD-04)</name>
  <files>possession/tui/widgets/quickadd.py</files>
  <action>
    Modify `QuickAddBar.compose()` to yield a persistent `Static` format hint label above the input. Update `DEFAULT_CSS` to use explicit `height: 2` (not `height: auto`) and add label styling.

    **Changes to quickadd.py:**

    1. Add module-level constant:
    ```python
    QUICKADD_FORMAT_HINT = "name / description / room / container / category / date / cost"
    ```

    2. Add `Static` to the `textual.widgets` import line (alongside `Input`).

    3. Modify `compose()` to yield the label first, then the existing inputs:
    ```python
    def compose(self) -> ComposeResult:
        yield Static(QUICKADD_FORMAT_HINT, id="quickadd-label")
        yield Input(
            placeholder="",   # removed old placeholder text — label carries the hint
            id="quickadd-input",
        )
        yield Input(
            placeholder="Room not found. Create it? [y/N]",
            id="quickadd-confirm",
            classes="hidden",
        )
    ```
    NOTE: If a third confirm input for Container also exists in the current compose(), preserve it. Only the format label and the removal of the quickadd-input placeholder are changed here.

    4. Update `DEFAULT_CSS` — change `height: auto` to `height: 2` and add label rules:
    ```
    QuickAddBar {
        height: 2;
        dock: bottom;
    }
    QuickAddBar.hidden {
        display: none;
    }
    #quickadd-label {
        height: 1;
        color: $text-muted;
        padding: 0 1;
    }
    ```
    NOTE: Read the existing `DEFAULT_CSS` in quickadd.py first. Preserve all existing rules not related to `height` on `QuickAddBar`. Only change the `height` value from `auto` to `2`. Add the `#quickadd-label` rule block.

    **Do NOT change:** Any event handlers, the `open()`/`close()` methods, the confirmation state machine, `_pending_parsed`, `_confirm_mode`, or any other logic. This is a pure `compose()` + CSS change.
  </action>
  <verify>
    <automated>cd /Users/paritoshpatil/Personal/claude-projects/possession-terminal-2 && python -c "from possession.tui.widgets.quickadd import QuickAddBar, QUICKADD_FORMAT_HINT; print('ok:', QUICKADD_FORMAT_HINT)" && grep "height: 2" possession/tui/widgets/quickadd.py && grep "quickadd-label" possession/tui/widgets/quickadd.py</automated>
    <manual>Run `python -m possession`, press 'a' to open QuickAddBar — the label "name / description / room / container / category / date / cost" should be visible above the input and remain visible while typing. The input should not be clipped or hidden.</manual>
  </verify>
  <done>
    - `QUICKADD_FORMAT_HINT` constant exists in quickadd.py
    - `#quickadd-label` Static is first yield in `compose()`
    - `QuickAddBar { height: 2 }` in DEFAULT_CSS (not `height: auto`)
    - `python -c "from possession.tui.widgets.quickadd import QuickAddBar"` exits 0
    - Format label remains visible while typing in the input
  </done>
</task>

<task type="checkpoint:human-verify" gate="blocking">
  <name>Checkpoint: Verify all Phase 4 visual chrome features end-to-end</name>
  <files>N/A — human verification, no files modified</files>
  <action>Human verifies all Phase 4 visual chrome features (splash screen, transparent flag, QuickAddBar label) work correctly in the live app.</action>
  <what-built>
    Complete Phase 4 visual chrome: SplashScreen on launch (SPSH-01), --transparent CLI flag (THEME-01), and persistent QuickAddBar format label (QADD-04). All three features plus the flat list from Plan 01.
  </what-built>
  <how-to-verify>
    1. Run: `python -m possession`
       Expected: Splash screen with "POSSESSION" ASCII art appears. Any key dismisses it.
       Expected: After dismiss, flat item list with "Possession" top bar is shown.

    2. Press 'a' to open QuickAddBar.
       Expected: The label "name / description / room / container / category / date / cost" is visible ABOVE the input field.
       Expected: The label stays visible as you type characters into the input.
       Press Escape to close.

    3. Run: `python -m possession --transparent`
       Expected: App launches (with or without splash) and the background uses terminal colors instead of Textual's surface color.
       (If running inside tmux, background may appear black — this is expected behavior.)

    4. Run: `python -m possession --help`
       Expected: `--transparent` option appears in the help output.

    5. Add a test item via 'a' (quick-add), confirm it appears in the flat list.
       Press 'e' on it — EditItemScreen opens. Press Escape to return.
       Flat list is still visible with all items.
  </how-to-verify>
  <verify>Human confirms all checks pass by typing "approved"</verify>
  <done>User types "approved" — all Phase 4 visual chrome features confirmed working</done>
  <resume-signal>Type "approved" if all checks pass, or describe any issues found</resume-signal>
</task>

</tasks>

<verification>
- `python -c "from possession.tui.screens.splash import SplashScreen"` exits 0
- `python -c "from possession.tui.widgets.quickadd import QUICKADD_FORMAT_HINT"` exits 0
- `python -m possession --help` contains `--transparent`
- `grep "height: 2" possession/tui/widgets/quickadd.py` matches
- `grep "SplashScreen" possession/tui/app.py` shows push_screen call
</verification>

<success_criteria>
- Splash screen appears on every launch; any key dismisses it
- `--transparent` flag accepted without error; changes background rendering
- QuickAddBar format label visible above input at all times while bar is open
- All Phase 4 requirements met: VIEW-01, TOPBAR-01, SPSH-01, THEME-01, QADD-04
</success_criteria>

<output>
After completion, create `.planning/phases/04-foundation-flat-list-visual-chrome/04-02-SUMMARY.md`
</output>
