@neurocode-ai/app 1.18.8

package/create-effect-simplification-spec.md

@@ -0,0 +1,515 @@
+# CreateEffect Simplification Implementation Spec
+
+Reduce reactive misuse across `packages/app`.
+
+---
+
+## Context
+
+This work targets `packages/app/src`, which currently has 101 `createEffect` calls across 37 files.
+
+The biggest clusters are `pages/session.tsx` (19), `pages/layout.tsx` (13), `pages/session/file-tabs.tsx` (6), and several context providers that mirror one store into another.
+
+Key issues from the audit:
+
+- Derived state is being written through effects instead of computed directly
+- Session and file resets are handled by watch-and-clear effects instead of keyed state boundaries
+- User-driven actions are hidden inside reactive effects
+- Context layers mirror and hydrate child stores with multiple sync effects
+- Several areas repeat the same imperative trigger pattern in multiple effects
+
+Keep the implementation focused on removing unnecessary effects, not on broad UI redesign.
+
+## Goals
+
+- Cut high-churn `createEffect` usage in the hottest files first
+- Replace effect-driven derived state with reactive derivation
+- Replace reset-on-key effects with keyed ownership boundaries
+- Move event-driven work to direct actions and write paths
+- Remove mirrored store hydration where a single source of truth can exist
+- Leave necessary external sync effects in place, but make them narrower and clearer
+
+## Non-Goals
+
+- Do not rewrite unrelated component structure just to reduce the count
+- Do not change product behavior, navigation flow, or persisted data shape unless required for a cleaner write boundary
+- Do not remove effects that bridge to DOM, editors, polling, or external APIs unless there is a clearly safer equivalent
+- Do not attempt a repo-wide cleanup outside `packages/app`
+
+## Effect Taxonomy And Replacement Rules
+
+Use these rules during implementation.
+
+### Prefer `createMemo`
+
+Use `createMemo` when the target value is pure derived state from other signals or stores.
+
+Do this when an effect only reads reactive inputs and writes another reactive value that could be computed instead.
+
+Apply this to:
+
+- `packages/app/src/pages/session.tsx:141`
+- `packages/app/src/pages/layout.tsx:557`
+- `packages/app/src/components/terminal.tsx:261`
+- `packages/app/src/components/session/session-header.tsx:309`
+
+Rules:
+
+- If no external system is touched, do not use `createEffect`
+- Derive once, then read the memo where needed
+- If normalization is required, prefer normalizing at the write boundary before falling back to a memo
+
+### Prefer Keyed Remounts
+
+Use keyed remounts when local UI state should reset because an identity changed.
+
+Do this with `sessionKey`, `scope()`, or another stable identity instead of watching the key and manually clearing signals.
+
+Apply this to:
+
+- `packages/app/src/pages/session.tsx:325`
+- `packages/app/src/pages/session.tsx:336`
+- `packages/app/src/pages/session.tsx:477`
+- `packages/app/src/pages/session.tsx:869`
+- `packages/app/src/pages/session.tsx:963`
+- `packages/app/src/pages/session/message-timeline.tsx:149`
+- `packages/app/src/context/file.tsx:100`
+
+Rules:
+
+- If the desired behavior is "new identity, fresh local state," key the owner subtree
+- Keep state local to the keyed boundary so teardown and recreation handle the reset naturally
+
+### Prefer Event Handlers And Actions
+
+Use direct handlers, store actions, and async command functions when work happens because a user clicked, selected, reloaded, or navigated.
+
+Do this when an effect is just watching for a flag change, command token, or event-bus signal to trigger imperative logic.
+
+Apply this to:
+
+- `packages/app/src/pages/layout.tsx:484`
+- `packages/app/src/pages/layout.tsx:652`
+- `packages/app/src/pages/layout.tsx:776`
+- `packages/app/src/pages/layout.tsx:1489`
+- `packages/app/src/pages/layout.tsx:1519`
+- `packages/app/src/components/file-tree.tsx:328`
+- `packages/app/src/pages/session/terminal-panel.tsx:55`
+- `packages/app/src/context/global-sync.tsx:148`
+- Duplicated trigger sets in:
+  - `packages/app/src/pages/session/review-tab.tsx:122`
+  - `packages/app/src/pages/session/review-tab.tsx:130`
+  - `packages/app/src/pages/session/review-tab.tsx:138`
+  - `packages/app/src/pages/session/file-tabs.tsx:367`
+  - `packages/app/src/pages/session/file-tabs.tsx:378`
+  - `packages/app/src/pages/session/file-tabs.tsx:389`
+  - `packages/app/src/pages/session/use-session-hash-scroll.ts:144`
+  - `packages/app/src/pages/session/use-session-hash-scroll.ts:149`
+  - `packages/app/src/pages/session/use-session-hash-scroll.ts:167`
+
+Rules:
+
+- If the trigger is user intent, call the action at the source of that intent
+- If the same imperative work is triggered from multiple places, extract one function and call it directly
+
+### Prefer `onMount` And `onCleanup`
+
+Use `onMount` and `onCleanup` for lifecycle-only setup and teardown.
+
+This is the right fit for subscriptions, one-time wiring, timers, and imperative integration that should not rerun for ordinary reactive changes.
+
+Use this when:
+
+- Setup should happen once per owner lifecycle
+- Cleanup should always pair with teardown
+- The work is not conceptually derived state
+
+### Keep `createEffect` When It Is A Real Bridge
+
+Keep `createEffect` when it synchronizes reactive data to an external imperative sink.
+
+Examples that should remain, though they may be narrowed or split:
+
+- DOM/editor sync in `packages/app/src/components/prompt-input.tsx:690`
+- Scroll sync in `packages/app/src/pages/session.tsx:685`
+- Scroll/hash sync in `packages/app/src/pages/session/use-session-hash-scroll.ts:149`
+- External sync in:
+  - `packages/app/src/context/language.tsx:207`
+  - `packages/app/src/context/settings.tsx:110`
+  - `packages/app/src/context/sdk.tsx:26`
+- Polling in:
+  - `packages/app/src/components/status-popover.tsx:59`
+  - `packages/app/src/components/dialog-select-server.tsx:273`
+
+Rules:
+
+- Keep the effect single-purpose
+- Make dependencies explicit and narrow
+- Avoid writing back into the same reactive graph unless absolutely required
+
+## Implementation Plan
+
+### Phase 0: Classification Pass
+
+Before changing code, tag each targeted effect as one of: derive, reset, event, lifecycle, or external bridge.
+
+Acceptance criteria:
+
+- Every targeted effect in this spec is tagged with a replacement strategy before refactoring starts
+- Shared helpers to be introduced are identified up front to avoid repeating patterns
+
+### Phase 1: Derived-State Cleanup
+
+Tackle highest-value, lowest-risk derived-state cleanup first.
+
+Priority items:
+
+- Normalize tabs at write boundaries and remove `packages/app/src/pages/session.tsx:141`
+- Stop syncing `workspaceOrder` in `packages/app/src/pages/layout.tsx:557`
+- Make prompt slash filtering reactive so `packages/app/src/components/prompt-input.tsx:652` can be removed
+- Replace other obvious derived-state effects in terminal and session header
+
+Acceptance criteria:
+
+- No behavior change in tab ordering, prompt filtering, terminal display, or header state
+- Targeted derived-state effects are deleted, not just moved
+
+### Phase 2: Keyed Reset Cleanup
+
+Replace reset-on-key effects with keyed ownership boundaries.
+
+Priority items:
+
+- Key session-scoped UI and state by `sessionKey`
+- Key file-scoped state by `scope()`
+- Remove manual clear-and-reseed effects in session and file context
+
+Acceptance criteria:
+
+- Switching session or file scope recreates the intended local state cleanly
+- No stale state leaks across session or scope changes
+- Target reset effects are deleted
+
+### Phase 3: Event-Driven Work Extraction
+
+Move event-driven work out of reactive effects.
+
+Priority items:
+
+- Replace `globalStore.reload` effect dispatching with direct calls
+- Split mixed-responsibility effect in `packages/app/src/pages/layout.tsx:1489`
+- Collapse duplicated imperative trigger triplets into single functions
+- Move file-tree and terminal-panel imperative work to explicit handlers
+
+Acceptance criteria:
+
+- User-triggered behavior still fires exactly once per intended action
+- No effect remains whose only job is to notice a command-like state and trigger an imperative function
+
+### Phase 4: Context Ownership Cleanup
+
+Remove mirrored child-store hydration patterns.
+
+Priority items:
+
+- Remove child-store hydration mirrors in `packages/app/src/context/global-sync/child-store.ts:184`, `:190`, `:193`
+- Simplify mirror logic in `packages/app/src/context/global-sync.tsx:130`, `:138`
+- Revisit `packages/app/src/context/layout.tsx:424` if it still mirrors instead of deriving
+
+Acceptance criteria:
+
+- There is one clear source of truth for each synced value
+- Child stores no longer need effect-based hydration to stay consistent
+- Initialization and updates both work without manual mirror effects
+
+### Phase 5: Cleanup And Keeper Review
+
+Clean up remaining targeted hotspots and narrow the effects that should stay.
+
+Acceptance criteria:
+
+- Remaining `createEffect` calls in touched files are all true bridges or clearly justified lifecycle sync
+- Mixed-responsibility effects are split into smaller units where still needed
+
+## Detailed Work Items By Area
+
+### 1. Normalize Tab State
+
+Files:
+
+- `packages/app/src/pages/session.tsx:141`
+
+Work:
+
+- Move tab normalization into the functions that create, load, or update tab state
+- Make readers consume already-normalized tab data
+- Remove the effect that rewrites derived tab state after the fact
+
+Rationale:
+
+- Tabs should become valid when written, not be repaired later
+- This removes a feedback loop and makes state easier to trust
+
+Acceptance criteria:
+
+- The effect at `packages/app/src/pages/session.tsx:141` is removed
+- Newly created and restored tabs are normalized before they enter local state
+- Tab rendering still matches current behavior for valid and edge-case inputs
+
+### 2. Key Session-Owned State
+
+Files:
+
+- `packages/app/src/pages/session.tsx:325`
+- `packages/app/src/pages/session.tsx:336`
+- `packages/app/src/pages/session.tsx:477`
+- `packages/app/src/pages/session.tsx:869`
+- `packages/app/src/pages/session.tsx:963`
+- `packages/app/src/pages/session/message-timeline.tsx:149`
+
+Work:
+
+- Identify state that should reset when `sessionKey` changes
+- Move that state under a keyed subtree or keyed owner boundary
+- Remove effects that watch `sessionKey` just to clear local state, refs, or temporary UI flags
+
+Rationale:
+
+- Session identity already defines the lifetime of this UI state
+- Keyed ownership makes reset behavior automatic and easier to reason about
+
+Acceptance criteria:
+
+- The targeted reset effects are removed
+- Changing sessions resets only the intended session-local state
+- Scroll and editor state that should persist are not accidentally reset
+
+### 3. Derive Workspace Order
+
+Files:
+
+- `packages/app/src/pages/layout.tsx:557`
+
+Work:
+
+- Stop writing `workspaceOrder` from live workspace data in an effect
+- Represent user overrides separately from live workspace data
+- Compute effective order from current data plus overrides with a memo or pure helper
+
+Rationale:
+
+- Persisted user intent and live source data should not mirror each other through an effect
+- A computed effective order avoids drift and racey resync behavior
+
+Acceptance criteria:
+
+- The effect at `packages/app/src/pages/layout.tsx:557` is removed
+- Workspace order updates correctly when workspaces appear, disappear, or are reordered by the user
+- User overrides persist without requiring a sync-back effect
+
+### 4. Remove Child-Store Mirrors
+
+Files:
+
+- `packages/app/src/context/global-sync.tsx:130`
+- `packages/app/src/context/global-sync.tsx:138`
+- `packages/app/src/context/global-sync.tsx:148`
+- `packages/app/src/context/global-sync/child-store.ts:184`
+- `packages/app/src/context/global-sync/child-store.ts:190`
+- `packages/app/src/context/global-sync/child-store.ts:193`
+- `packages/app/src/context/layout.tsx:424`
+
+Work:
+
+- Trace the actual ownership of global and child store values
+- Replace hydration and mirror effects with explicit initialization and direct updates
+- Remove the `globalStore.reload` event-bus pattern and call the needed reload paths directly
+
+Rationale:
+
+- Mirrors make it hard to tell which state is authoritative
+- Event-bus style state toggles hide control flow and create accidental reruns
+
+Acceptance criteria:
+
+- Child store hydration no longer depends on effect-based copying
+- Reload work can be followed from the event source to the handler without a reactive relay
+- State remains correct on first load, child creation, and subsequent updates
+
+### 5. Key File-Scoped State
+
+Files:
+
+- `packages/app/src/context/file.tsx:100`
+
+Work:
+
+- Move file-scoped local state under a boundary keyed by `scope()`
+- Remove any effect that watches `scope()` only to reset file-local state
+
+Rationale:
+
+- File scope changes are identity changes
+- Keyed ownership gives a cleaner reset than manual clear logic
+
+Acceptance criteria:
+
+- The effect at `packages/app/src/context/file.tsx:100` is removed
+- Switching scopes resets only scope-local state
+- No previous-scope data appears after a scope change
+
+### 6. Split Layout Side Effects
+
+Files:
+
+- `packages/app/src/pages/layout.tsx:1489`
+- Related event-driven effects near `packages/app/src/pages/layout.tsx:484`, `:652`, `:776`, `:1519`
+
+Work:
+
+- Break the mixed-responsibility effect at `:1489` into direct actions and smaller bridge effects only where required
+- Move user-triggered branches into the actual command or handler that causes them
+- Remove any branch that only exists because one effect is handling unrelated concerns
+
+Rationale:
+
+- Mixed effects hide cause and make reruns hard to predict
+- Smaller units reduce accidental coupling and make future cleanup safer
+
+Acceptance criteria:
+
+- The effect at `packages/app/src/pages/layout.tsx:1489` no longer mixes unrelated responsibilities
+- Event-driven branches execute from direct handlers
+- Remaining effects in this area each have one clear external sync purpose
+
+### 7. Remove Duplicate Triggers
+
+Files:
+
+- `packages/app/src/pages/session/review-tab.tsx:122`
+- `packages/app/src/pages/session/review-tab.tsx:130`
+- `packages/app/src/pages/session/review-tab.tsx:138`
+- `packages/app/src/pages/session/file-tabs.tsx:367`
+- `packages/app/src/pages/session/file-tabs.tsx:378`
+- `packages/app/src/pages/session/file-tabs.tsx:389`
+- `packages/app/src/pages/session/use-session-hash-scroll.ts:144`
+- `packages/app/src/pages/session/use-session-hash-scroll.ts:149`
+- `packages/app/src/pages/session/use-session-hash-scroll.ts:167`
+
+Work:
+
+- Extract one explicit imperative function per behavior
+- Call that function from each source event instead of replicating the same effect pattern multiple times
+- Preserve the scroll-sync effect that is truly syncing with the DOM, but remove duplicate trigger scaffolding around it
+
+Rationale:
+
+- Duplicate triggers make it easy to miss a case or fire twice
+- One named action is easier to test and reason about
+
+Acceptance criteria:
+
+- Repeated imperative effect triplets are collapsed into shared functions
+- Scroll behavior still works, including hash-based navigation
+- No duplicate firing is introduced
+
+### 8. Make Prompt Filtering Reactive
+
+Files:
+
+- `packages/app/src/components/prompt-input.tsx:652`
+- Keep `packages/app/src/components/prompt-input.tsx:690` as needed
+
+Work:
+
+- Convert slash filtering into a pure reactive derivation from the current input and candidate command list
+- Keep only the editor or DOM bridge effect if it is still needed for imperative syncing
+
+Rationale:
+
+- Filtering is classic derived state
+- It should not need an effect if it can be computed from current inputs
+
+Acceptance criteria:
+
+- The effect at `packages/app/src/components/prompt-input.tsx:652` is removed
+- Filtered slash-command results update correctly as the input changes
+- The editor sync effect at `:690` still behaves correctly
+
+### 9. Clean Up Smaller Derived-State Cases
+
+Files:
+
+- `packages/app/src/components/terminal.tsx:261`
+- `packages/app/src/components/session/session-header.tsx:309`
+
+Work:
+
+- Replace effect-written local state with memos or inline derivation
+- Remove intermediate setters when the value can be computed directly
+
+Rationale:
+
+- These are low-risk wins that reinforce the same pattern
+- They also help keep follow-up cleanup consistent
+
+Acceptance criteria:
+
+- Targeted effects are removed
+- UI output remains unchanged under the same inputs
+
+## Verification And Regression Checks
+
+Run focused checks after each phase, not only at the end.
+
+### Suggested Verification
+
+- Switch between sessions rapidly and confirm local session UI resets only where intended
+- Open, close, and reorder tabs and confirm order and normalization remain stable
+- Change workspaces, reload workspace data, and verify effective ordering is correct
+- Change file scope and confirm stale file state does not bleed across scopes
+- Trigger layout actions that previously depended on effects and confirm they still fire once
+- Use slash commands in the prompt and verify filtering updates as you type
+- Test review tab, file tab, and hash-scroll flows for duplicate or missing triggers
+- Verify global sync initialization, reload, and child-store creation paths
+
+### Regression Checks
+
+- No accidental infinite reruns
+- No double-firing network or command actions
+- No lost cleanup for listeners, timers, or scroll handlers
+- No preserved stale state after identity changes
+- No removed effect that was actually bridging to DOM or an external API
+
+If available, add or update tests around pure helpers introduced during this cleanup.
+
+Favor tests for derived ordering, normalization, and action extraction, since those are easiest to lock down.
+
+## Definition Of Done
+
+This work is done when all of the following are true:
+
+- The highest-leverage targets in this spec are implemented
+- Each removed effect has been replaced by a clearer pattern: memo, keyed boundary, direct action, or lifecycle hook
+- The "should remain" effects still exist only where they serve a real external sync purpose
+- Touched files have fewer mixed-responsibility effects and clearer ownership of state
+- Manual verification covers session switching, file scope changes, workspace ordering, prompt filtering, and reload flows
+- No behavior regressions are found in the targeted areas
+
+A reduced raw `createEffect` count is helpful, but it is not the main success metric.
+
+The main success metric is clearer ownership and fewer effect-driven state repairs.
+
+## Risks And Rollout Notes
+
+Main risks:
+
+- Keyed remounts can reset too much if state boundaries are drawn too high
+- Store mirror removal can break initialization order if ownership is not mapped first
+- Moving event work out of effects can accidentally skip triggers that were previously implicit
+
+Rollout notes:
+
+- Land in small phases, with each phase keeping the app behaviorally stable
+- Prefer isolated PRs by phase or by file cluster, especially for context-store changes
+- Review each remaining effect in touched files and leave it only if it clearly bridges to something external

package/e2e/performance/AGENTS.md

@@ -0,0 +1,13 @@
+- Prioritize stability, then simplicity, then measurement overhead.
+- Use Playwright for scenario control, isolation, and completion checks.
+- Use Chrome Performance traces for generic browser profiling.
+- Use Electron `contentTracing` for packaged multi-process profiling.
+- Keep custom probes only for product-specific measurements.
+- Do not duplicate measurements across the harness, probes, and traces.
+- Run benchmarks serially to avoid cross-test contention.
+- Run benchmarks against production builds.
+- Keep detailed profiling opt-in when it changes workload behavior.
+- Preserve raw diagnostic data or use lossless representations.
+- Do not enforce machine-dependent performance thresholds.
+- Assert scenario completion and metric collection only.
+- Keep normal test discovery free of manual benchmarks.

package/e2e/performance/README.md

@@ -0,0 +1,79 @@
+# Manual app performance suite
+
+The app's high-volume performance diagnostics live under `packages/app/e2e/performance` and are excluded from normal local and CI Playwright discovery. The benchmark config builds the app and serves the production bundle before running scenarios serially.
+
+Run the suite explicitly from `packages/app`:
+
+```sh
+bun run test:bench
+```
+
+PowerShell:
+
+```powershell
+$env:PLAYWRIGHT_WORKERS = "1"
+bun run test:bench
+```
+
+The suite contains:
+
+- cold and hot session-tab timing
+- home-session click timing split between content and titlebar-tab paint
+- single-session tab close timing through stable home restoration
+- cached session repaint and mutation tracing
+- streaming timeline throughput, RAF-gap, long-task, geometry, and remount diagnostics
+
+All benchmarks import the shared `benchmark` fixture. Pages created through Playwright's `page` fixture automatically capture main-frame navigation history and emit a Chrome trace when `OPENCODE_PERFORMANCE_TRACE_DIR` is set. Benchmarks that need isolated browser contexts use `withBenchmarkPage`, which owns the context and the same diagnostics lifecycle.
+
+New benchmarks should look like normal Playwright tests:
+
+```ts
+import { benchmark, expect } from "../benchmark"
+
+benchmark("measures one interaction", async ({ page, report }) => {
+  // Only scenario-specific setup and interaction belong here.
+  report({ durationMs: 42 })
+})
+```
+
+The fixture requires every benchmark to call `report()`, automatically names and closes traces, captures navigation history, attaches that history when a test fails, and emits metrics as a consistent `BENCHMARK` JSON line.
+
+```text
+BENCHMARK {"name":"...","context":{"project":"chromium","platform":"darwin"},"metrics":{...}}
+```
+
+Every observed page also emits `BENCHMARK_PAGE` with the same run ID, navigation history, and optional trace path before the final status-bearing `BENCHMARK` record. Chrome traces are browser-wide page-lifetime diagnostics; scenario metrics use narrower explicitly named observation windows.
+
+This follows the stack's own guidance: [Electron recommends repeated Chrome DevTools and Chrome Tracing measurement](https://www.electronjs.org/docs/latest/tutorial/performance), [Chrome DevTools recommends Performance recordings for runtime work](https://developer.chrome.com/docs/devtools/performance), and [Playwright uses traces for test debugging rather than renderer profiling](https://playwright.dev/docs/trace-viewer).
+
+These Playwright benchmarks profile the shared app renderer in Chromium. A future packaged Electron benchmark that needs main-process and multi-process attribution should use Electron's official [`contentTracing`](https://www.electronjs.org/docs/latest/api/content-tracing/) API rather than extending this renderer harness with bespoke process instrumentation.
+
+CPU and high-volume visual profiling are disabled by default. Set `TIMELINE_CPU_PROFILE=1` to enable both, or additionally set `TIMELINE_VISUAL_PROFILE=0` for CPU-only profiling.
+
+The streaming scenario's 30x CPU throttle is a deterministic stress profile, not a simulated end-user device.
+
+Benchmarks do not assert machine-dependent performance budgets. Streaming processes 160 deltas by default and reports renderer-observed completion time, throughput, RAF callback-gap distributions, frame-budget equivalents, and long tasks through final geometry settlement. Delta count and delivery batch are included in result context when overridden. These are main-thread callback diagnostics, not compositor presentation or dropped-frame measurements. Visual-only and geometry metrics are `null` when their probes are disabled. Tab metrics describe sampled DOM observations. Assertions verify scenario and metric collection completion. Repeated repaint states are run-length grouped, but every original observation timestamp is retained alongside raw mutation batches and layout shifts.
+
+Committed smoke and regression tests continue to own correctness coverage for pagination, tab paint, context resize, collapse state, and composer spacing.
+
+## Chrome traces
+
+Set `OPENCODE_PERFORMANCE_TRACE_DIR` to emit a standard Chrome DevTools trace for every benchmark page automatically:
+
+```sh
+OPENCODE_PERFORMANCE_TRACE_DIR=/tmp/opencode-performance-traces \
+bunx playwright test --config e2e/performance/playwright.config.ts \
+  timeline/session-tab-switch-benchmark.spec.ts
+```
+
+The emitted JSON is a standard Chrome trace and can be loaded directly into the Chrome DevTools Performance panel. `devtools-tracing` can optionally inspect it from the command line without adding package scripts or dependencies:
+
+Trace capture mirrors [Puppeteer's official tracing defaults and lifecycle](https://pptr.dev/api/puppeteer.tracing), using Chrome's `ReturnAsStream` transfer mode and failing when Chromium reports trace data loss.
+
+```sh
+bunx devtools-tracing stats <trace-path-from-BENCHMARK_PAGE>
+```
+
+INP analysis requires a trace with a supported navigation/interaction insight. Selector statistics require a trace captured with `OPENCODE_PERFORMANCE_SELECTOR_TRACE=1`.
+
+`e2e/performance/playwright.uncapped.config.ts` disables Chromium frame-rate limiting for explicit uncapped diagnostics. Native product benchmarks should use the default Playwright configuration.