termal-repo

name

termal-repo

description

Work in the TermAl repository. Use when changing transcript virtualization, session pane scrolling, App live-state adoption and recovery, rendered Markdown diff editing, source renderers, persistence and revision handling, or repo-specific tests and invariants. Read this skill before editing code in this repo so ownership boundaries, scroll contracts, recovery semantics, and verification commands stay consistent.

TermAl Repo

Read First

• Use docs/bugs.md for current open bugs only. Do not treat Also fixed in the current tree entries as active work.
• Use docs/features/ for behavior and design notes. Read only the files that match the area you are changing:
  • docs/features/session-virtualized-transcript.md
  • docs/features/source-renderers.md
  • docs/features/sqlite-session-storage.md
  • docs/features/diff-review-workflow.md when changing diff UX

Ownership Boundaries

• ui/src/SessionPaneView.tsx
  • Own transcript keyboard paging, prompt-send bottom follow, jump-to-latest, and pane-level message-stack direct scroll writes.
• ui/src/panels/VirtualizedConversationMessageList.tsx
  • Own mounted-page reconciliation, spacer layout, page measurement, scroll classification, and mounted-band policy.
• ui/src/message-stack-scroll-sync.ts
  • Own the seam for programmatic transcript scroll writes. If the caller already knows the intent, include explicit scrollKind.
• ui/src/app-live-state.ts
  • Own state adoption, resync/reconnect logic, revision gating, and deferred open-session recovery intent.
• ui/src/app-session-actions.ts
  • Own create/fork/send/session mutation flows. Post-await UI updates must respect isMountedRef.
• ui/src/panels/DiffPanel.tsx and ui/src/panels/markdown-*
  • Own rendered-Markdown diff editing, LF-normalized offset math, rebase/save flow, and commit-range resolution.
• ui/src/source-renderers.ts
  • Own renderable-region detection and renderer ids. MonacoCodeEditor hosts inline zones; it does not invent renderer identity.

Hard Invariants

Transcript Virtualization

• Mounted pages are the live reading surface.
• Active reading is grow-first. Compaction belongs to idle.
• Keep the current reserve policy unless intentionally changing behavior:
  • 3 viewports above
  • 3 viewports below
  • 1 extra page below as hysteresis
• Heavy content inside mounted pages renders immediately.
• PageUp / PageDown are transcript-owned fixed-delta jumps. Do not hand them back to browser-native page scroll for session transcripts.
• When a code path writes transcript scrollTop directly, emit the matching MESSAGE_STACK_SCROLL_WRITE_EVENT. If the path is a seek/page jump, provide explicit scrollKind.

Session Create/Fork Recovery

• Stale create/fork responses must not open phantom sessions or panes.
• Recovery resync may preserve pending openSessionId / paneId, but that intent must only be consumed when the adopted session list actually contains the target session.
• Tests should pin:
  • no open before recovery
  • no open when the first recovery snapshot still omits the session
  • open only when a later adopted snapshot or SSE state includes it

Rendered Markdown And Source Renderers

• Rendered-Markdown commit math is LF-normalized.
• Preserve original document EOL style on save.
• Generated render output must not serialize back into source.
• Staged read-only rendered Markdown may allow caret/navigation, but not edits.
• Renderer ids must stay stable when edits do not semantically change the renderable block. Do not make ids depend on absolute line numbers if a more stable identity is available.

Persistence And Revision Handling

• Revision handling stays monotonic unless a restart/rollback path explicitly allows a downgrade.
• Do not reintroduce full-history persistence or state-adoption work on session create/fork paths.
• Restart/recovery logic must not accept late state from an older server instance once a newer instance has been adopted.

Area-Specific Checks

• Always run:

  • cargo check
  • cd ui && npx tsc --noEmit

• If changing transcript scroll, paging, mounted-range, or prompt-follow:

  • cd ui && npx vitest run src/panels/AgentSessionPanel.test.tsx
  • cd ui && npx vitest run src/App.scroll-behavior.test.tsx

• If changing create/fork/recovery/adoption behavior:

  • cd ui && npx vitest run src/App.session-lifecycle.test.tsx

• If changing rendered Markdown, diff edit, or commit-range logic:

  • cd ui && npx vitest run src/panels/DiffPanel.test.tsx
  • cd ui && npx vitest run src/panels/markdown-diff-segments.test.ts
  • cd ui && npx vitest run src/panels/markdown-commit-ranges.test.ts
  • cd ui && npx vitest run src/MarkdownContent.test.tsx

• If changing source renderers or inline zones:

  • cd ui && npx vitest run src/source-renderers.test.ts
  • plus the relevant SourcePanel/Monaco tests

Editing Guidance

• Prefer small helpers over adding more stateful branches to already-large UI files, but do not break the ownership boundaries above.
• Update the relevant docs/features/*.md file when behavior changes.
• Update docs/bugs.md only when an issue is actually fixed, newly introduced, or narrowed by real evidence.
• Keep user-visible keyboard behavior explicit. If a shortcut is pane-owned, keep editable-target guards and active-pane ownership intact.
• Do not commit or push unless the user explicitly asks.

Good Defaults

• Treat the focused AgentSessionPanel suite as the release gate for transcript virtualization work.
• Treat phantom-session prevention as non-negotiable for create/fork/recovery changes.
• Treat rendered-Markdown offset math and EOL preservation as one contract, not separate concerns.