Refine reference target lifecycle

Author: jensenojs

AGENTS.md

@@ -21,3 +21,105 @@ Use `scripts/dependency-topology/scan_topology.py` to inspect and track architec
 - Pass `--snapshot <git-ref>` for historical snapshots
 - Pass `--json` when feeding outputs into scripts or agents
 - Keep architecture cleanup discussions anchored on scanner output instead of ad-hoc grep chains
+
+## Runtime Performance Profiling
+
+Use this section when there is a runtime performance problem or a credible performance report: slow render, delayed keypress, streaming lag, startup slowdown, a profiler screenshot, or a benchmark/test showing a regression. Before changing code for that problem, capture evidence and reduce it to a cost model. Pick the profiling method by what is available; do not require a specific plugin.
+
+### Capture options
+
+Use the first option that fits the machine and the symptom.
+
+#### Instrumentation profiler
+
+Use this when a profiler plugin is already available. It records function call trees with time and count.
+
+Example with `folke/snacks.nvim`, if it is installed:
+
+```vim
+:lua Snacks.profiler.start()
+" reproduce the slow action once
+:lua Snacks.profiler.stop({ pick = true })
+```
+
+Read it as a call tree. Parent time includes child time. `count` is useful for spotting repeated work.
+
+#### LuaJIT sampling profiler
+
+Use this when no profiler plugin is available. Neovim normally exposes LuaJIT's profiler as `jit.p`.
+
+```vim
+:lua require('jit.p').start('fl', '/tmp/nvim-jit-profile.log')
+" reproduce the slow action once
+:lua require('jit.p').stop()
+```
+
+Open `/tmp/nvim-jit-profile.log`. Treat it like a sampled CPU profile: it shows where Lua spent CPU time by stack/location, but it does not give exact call counts. If the issue is repeated work, pair it with a counter or scoped timer.
+
+#### Scoped wall-time timer
+
+Use this when the question is “which lifecycle boundary blocks the user?” or when sampling does not show wall-clock delay. Add temporary instrumentation around suspected boundaries only while investigating.
+
+```lua
+local uv = vim.uv or vim.loop
+local start = uv.hrtime()
+-- code under investigation
+local elapsed_ms = (uv.hrtime() - start) / 1e6
+vim.notify(string.format('opencode profile: <name> %.2fms', elapsed_ms))
+```
+
+For repeated calls, accumulate count and total time:
+
+```lua
+_G.opencode_perf = _G.opencode_perf or {}
+local p = _G.opencode_perf[name] or { count = 0, total_ms = 0 }
+p.count = p.count + 1
+p.total_ms = p.total_ms + elapsed_ms
+_G.opencode_perf[name] = p
+```
+
+Remove temporary instrumentation before committing unless the user explicitly asks for a diagnostic hook.
+
+#### Startup profile
+
+Use this only for startup or plugin-load regressions:
+
+```bash
+nvim --startuptime /tmp/nvim-startuptime.log
+```
+
+This is not a runtime action profiler. Do not use it to explain a slow keypress, render flush, or streaming callback.
+
+### Interpret the profile
+
+Start from the user-visible trigger, then walk down the stack.
+
+Record:
+
+```text
+trigger:        <user action that starts the slow path>
+blocking point: <render before display | keypress | streaming callback | startup>
+hot stack:      <caller -> callee -> hotspot>
+count:          <hotspot calls per trigger, or "sampled" if using jit.p>
+cost:           <hotspot total time and per-call time if available>
+repeated unit:  <message | part | line | file | buffer | session>
+invariant data: <inputs that are unchanged across repeated calls>
+```
+
+Rules for reading evidence:
+
+- In instrumentation traces, parent time includes child time. If parent and child times are almost equal, optimize the child or the child's call frequency.
+- In sampling traces, sample share is not exact wall time and does not prove call count. Use it to find the hot stack, then verify count with instrumentation or counters.
+- A 400 ms function called 10 times is a repeated-work problem. A 4 s function called once is a single expensive operation.
+- Do not optimize tiny high-count helpers unless their caller stack explains the user-visible delay.
+
+### Fix criteria
+
+A valid fix must change one measured fact:
+
+- remove expensive work from the blocking path;
+- move invariant work to the smallest valid lifecycle boundary;
+- defer work to an explicit user action;
+- reduce repeated calls and prove the new call count with a test.
+
+Do not add a cache until its invalidation boundary is named. Acceptable boundaries are concrete lifecycle points such as one render flush, one full session render, one keypress, one state change subscription, or one buffer change. Add a regression test that fails on the old call count.

lua/opencode/init.lua

@@ -59,7 +59,6 @@ function M.setup(opts)
   require('opencode.event_manager').setup()
   require('opencode.context').setup()
   require('opencode.ui.context_bar').setup()
-  require('opencode.ui.reference_picker').setup()
 end
 
 return M

lua/opencode/types.lua

@@ -545,6 +545,48 @@
 ---@field display_line number Line number to display the action
 ---@field range? { from: number, to: number } Optional range for the action
 
+---@class CodeReferenceTextRange
+---@field start_offset integer Raw part text offset, 1-based inclusive
+---@field end_offset integer Raw part text offset, 1-based inclusive
+
+---@class CodeReference
+---@field session_id string
+---@field message_id string
+---@field part_id string
+---@field path string
+---@field line? integer
+---@field col? integer
+---@field source_kind 'assistant_text'|'tool_file_path'
+---@field raw_range? CodeReferenceTextRange Required for assistant_text references
+---@field order integer Smaller values appear earlier in the session message/part/text order.
+
+---@class SymbolSnapshotCycle
+
+---@class FormatterContext
+---@field interactive boolean
+---@field get_child_parts? fun(session_id: string): OpencodeMessagePart[]?
+---@field current_refs? CodeReference[]
+---@field current_files? string[]
+---@field symbol_cycle? SymbolSnapshotCycle
+
+---@class OutputTargetRange
+---@field line integer Output-local line, 1-based
+---@field start_col integer Output-local column, 0-based inclusive
+---@field end_col integer Output-local column, 0-based exclusive
+
+---@class OutputTarget
+---@field kind 'file'|'diff'|'symbol'
+---@field range OutputTargetRange
+---@field path? string
+---@field line? integer
+---@field col? integer
+---@field token? string
+---@field candidate_files? string[]
+
+---@class RenderedTarget: OutputTarget
+---@field part_id string
+---@field message_id string
+
 ---@alias OutputExtmarkType vim.api.keyset.set_extmark & {start_col:0}
 ---@alias OutputExtmark OutputExtmarkType|fun():OutputExtmarkType
 

lua/opencode/ui/AGENTS.md

@@ -0,0 +1,63 @@
+# AGENTS.md (ui)
+
+This directory owns the rendered conversation UI and the interactive targets drawn on top of assistant text.
+
+## Reference target model
+
+The stable chain is:
+
+```text
+assistant text
+  -> reference_parser: positioned mention spans
+  -> reference_facts: current-session refs + current executable file list
+  -> formatter/render: screen-coordinate file and symbol targets
+  -> navigation: execute the current RenderState target only
+```
+
+`reference_parser` only identifies text spans. It does not prove that a file exists. It must keep separate non-overlapping mentions even when they point to the same path. Path-level dedupe belongs only to picker-style file lists.
+
+`reference_facts` is the maintained projection from current session messages. It owns two facts: current refs from assistant text and tool file-path facts, and the current executable file list derived from those refs. A file is executable when the referenced path currently exists on disk. This file list is the authority for rendering file affordances.
+
+`formatter` must not parse assistant text or scan session messages. It consumes `context.current_refs` and `context.current_files`. A mention becomes an icon, highlight, and `RenderState` file target only when its path is present in `current_files`. A missing file mention stays ordinary text.
+
+Symbol targets are bounded by the same file list. During a render cycle, `symbol_snapshot.new_cycle()` may reuse per-file Tree-sitter work inside that cycle. Symbol truth must not become long-lived UI state.
+
+`navigation` consumes `RenderState` targets. It must not rediscover targets from the output buffer text. Keypress executes the target that render already produced; it is not a target lifecycle or refresh boundary.
+
+Assistant message updates maintain `reference_facts` incrementally. New reference mentions extend the current refs and rebuild the executable file list before the affected rendered text parts are formatted.
+
+`file.edited`, `file.watcher.updated`, and local buffer file lifecycle events are render invalidation boundaries. Local writes, buffer renames, buffer unloads, shell-change notifications, server file edits, and watcher add/change/unlink events can change executable files and symbol truth without changing assistant text. They refresh the reference file list and dirty currently rendered assistant text parts. The next render recreates or removes affordances through the same path: current refs, current file list, current Tree-sitter snapshot, formatter output.
+
+This invalidation is limited to parts already in `RenderState`. Lazy-rendered history that is not in the output buffer waits for its normal render path. In normal edits the reference file list often stays the same; only symbol truth changes, so the next render reuses the same reference files and a fresh per-render Tree-sitter cycle.
+
+## Expected failure diagnosis
+
+If a visible path does not jump, inspect in this order:
+
+```text
+cursor position
+  -> renderer.get_target_at_position(line, col)
+  -> reference_facts.current_files()
+  -> formatter context for that render
+  -> navigation result
+```
+
+If `reference_facts.current_refs()` contains a mention but `renderer.get_target_at_position()` is nil, the problem is render projection or file-list membership.
+
+If `renderer.get_target_at_position()` returns a target but jump fails, the problem is keypress-time execution or a missing edit invalidation event. Keypress must not patch the rendered state; fix the save/edit invalidation path.
+
+If a nonexistent file has an icon or highlight, the bug is in render projection. Do not add cwd/root fallback code in `formatter`; fix the file list or the mention source.
+
+## Editing rule
+
+Prefer removing duplicate derivations over adding recovery paths. The UI should have one path from facts to rendered targets, and one path from rendered targets to execution.
+
+Do not add a second resolver layer, compatibility shim, screen-text scanner, or root fallback to hide a broken file list.
+
+## Regression commands
+
+- `./run_tests.sh -t tests/unit/reference_facts_spec.lua`
+- `./run_tests.sh -t tests/unit/formatter_spec.lua`
+- `./run_tests.sh -t tests/unit/navigation_spec.lua`
+- `./run_tests.sh -t tests/unit/renderer_targets_spec.lua`
+- `./run_tests.sh -t tests/replay/renderer_spec.lua`

lua/opencode/ui/autocmds.lua

@@ -39,6 +39,17 @@ function M.setup_autocmds(windows)
     end,
   })
 
+  vim.api.nvim_create_autocmd({ 'BufWritePost', 'BufFilePost', 'BufDelete', 'BufWipeout', 'FileChangedShellPost' }, {
+    group = group,
+    pattern = '*',
+    callback = function(args)
+      if args.file == '' then
+        return
+      end
+      require('opencode.ui.renderer.events').invalidate_reference_targets_for_file_change()
+    end,
+  })
+
   vim.api.nvim_create_autocmd('WinEnter', {
     group = group,
     pattern = '*',

lua/opencode/ui/event_scope.lua

@@ -87,6 +87,9 @@ local policies = {
   ['file.edited'] = function()
     return true
   end,
+  ['file.watcher.updated'] = function()
+    return true
+  end,
   ['custom.restore_point.created'] = function()
     return true
   end,