# Non-Linear: Views & UI

## Overview

Non-Linear provides two primary graph views, a flat fallback, and a cycle view. The interaction model is keyboard-first with a command palette as the primary navigation method.

## Layer Visibility

All graph views share a **layer toggle** — a set of controls that determine which of the four data layers are visible. Layers are independent overlays on the same spatial structure; toggling a layer on or off does not change node positions, only what information is rendered.

### Toggle Controls

A compact toggle bar sits in the view toolbar (near filtering and grouping controls). Each layer is a pill-style toggle:

```
[ Structure ] [ Work ] [ Connections ] [ Artifacts ]
     ●            ●          ○              ○
```

Active layers are highlighted; inactive layers are dimmed. At least Layer 1 (Structure) must be active — it cannot be toggled off since it is the base topology.

### Presets

Named presets configure common layer combinations with a single click:

| Preset | Layers Active | Use Case |
|--------|---------------|----------|
| **Default** | Structure + Work | Day-to-day issue tracking — the current behavior |
| **Architecture** | Structure + Connections | Impact analysis, dependency review, onboarding to codebase topology |
| **Context** | Structure + Artifacts | Onboarding, design review, gathering background on a component |
| **Full** | All four layers | Complete picture — useful for deep dives on a specific subtree |

Presets are accessible via the toggle bar dropdown and via the command palette (`Cmd+K` → "Switch layer preset").

### Keyboard Shortcuts

- `Alt+1` through `Alt+4` — toggle individual layers
- `Alt+0` — cycle through presets

### Layer Rendering

When multiple layers are active, each layer contributes distinct visual elements:

- **Layer 1 (Structure):** Component nodes and parent→child edges. Always the spatial backbone.
- **Layer 2 (Work):** Issue nodes nested under components. Work coordination edges (`blocks`, `duplicates`) drawn as dashed overlays between issues.
- **Layer 3 (Connections):** Technical dependency edges between components. Drawn as colored directional arrows (distinct color per link type: `imports`, `calls_api`, `depends_on`, `shares_db`).
- **Layer 4 (Artifacts):** Small attachment badges on nodes that have artifacts. Clicking a badge opens the artifact list in the detail panel.

## View 1: Layered Overview

**Purpose:** See the entire project structure at a glance, organized by abstraction level.

**Layout:** Rows arranged by depth in the decomposition tree. Each row represents one abstraction layer.

```
Layer 0 (root):     [My SaaS Project]
                    /        |         \
Layer 1:     [Auth]      [Billing]    [Dashboard]
              / \           |          /    \
Layer 2:  [Login] [SSO]  [Stripe]  [Charts] [Filters]
            |                         |
Layer 3:  [OAuth flow]             [Bar chart component]
```

### Behavior

- **Edges visible:** Parent→child edges always drawn. Overlay edges from active layers rendered on top — Layer 2 work links as dashed lines, Layer 3 code connections as colored directional arrows.
- **Backlink count badges:** Nodes show inbound link counts from active layers ("3 blocked" from Layer 2, "2 depend on this" from Layer 3).
- **Artifact badges:** When Layer 4 is active, nodes with artifacts show a paperclip badge with count.
- **Cycle highlighting:** Cycle members highlighted with color/tag (Layer 2).
- **Collapse/expand:** Each node can collapse its subtree. Collapsing a component hides its children across all active layers.
- **Zoom:** At high zoom, nodes show only title. At lower zoom, nodes show title + status + assignee. Layer 3 edge labels (link type) appear at medium zoom.
- **Filtering:** Filter by label, status, assignee. Non-matching nodes dimmed, not hidden (preserving structural context). Filters interact with layer toggles — filtering by status only affects Layer 2 nodes.
- **Node coloring:** Status-based by default (Layer 2). In Architecture preset (Layer 3 active, Layer 2 off), components colored by dependency fan-out (how many things depend on them).

## View 2: Focus Widget

**Purpose:** Inspect a single node and its immediate context.

**Layout:** Selected node in center. Parent shown above. Children shown below. Lateral links shown as badges or side panel.

### Behavior

- **Breadcrumb navigation:** Full root→node path as clickable segments at the top (e.g., `Project > Backend > Auth > Login Flow > Password Reset`).
- **Navigation:** Click any node to make it the new focus ("walking the tree").
- **Detail panel:** Full description, comments, change history timeline (compact, filterable by event type).
- **Backlinks section:** Inbound lateral links grouped by layer and type. Layer 2 links (blocks, duplicates) and Layer 3 links (depends_on, imports) are shown in separate collapsible groups.
- **Artifacts section:** When Layer 4 is active, a dedicated panel lists attached artifacts — thumbnails for images, icons for document links, download buttons for files.
- **Code connections section:** When Layer 3 is active, shows inbound/outbound technical dependencies for the focused component with link type and target component name.
- **Quick actions:** Change status, assign, add labels, add child, add link, attach artifact.

## View 3: Flat List / Board (Fallback)

**Purpose:** Quick triage, standup-style review, batch operations.

**Layout:** Standard list or Kanban board (columns = statuses).

- **Sorting:** By status, priority, assignee, updated date, creation date.
- **Grouping:** By parent node, label, assignee.
- **Bulk actions:** Multi-select for status change, assign, add labels.
- **Search:** Full-text search across titles and descriptions.

## View 4: Cycle View

**Purpose:** See current sprint/cycle work across all subtrees.

**Layout:** Flat list of current cycle members, grouped by subtree or status.

## Comments & Collaboration

### Threading Model

Comments are **flat and parented by nodes** — not nested under other comments. Each node has a single comment stream displayed in chronological order. This keeps the model simple and avoids deeply nested threads that become hard to follow.

Multiple node comment streams can be merged into a single chronological view (e.g., "show all comments across this subtree") for standup-style review.

### Markdown & Rich References

Comments use **GitHub-style markdown** with extensions for project references:

- `@alice`, `@agent-1` — mention a user or agent (triggers notification)
- `#NL-42` — link to an issue node
- `#NL-C12` — link to a component node
- `!123` — link to a merge request / pull request
- Bare commit SHAs (7+ chars) — auto-linked to the relevant repo
- Standard markdown: headings, lists, code blocks, inline code, bold/italic, images, links

Markdown is sanitized server-side before storage to prevent XSS (see Security in [09-TECH-STACK-AND-ARCHITECTURE.md](09-TECH-STACK-AND-ARCHITECTURE.md)).

### Reactions

Emoji reactions on comments — lightweight feedback without noise. Standard set (thumbs up/down, eyes, rocket, heart, etc.) plus custom emoji support deferred.

### Agent Comments

Agents post comments via the same API as humans. For structured output (test results, decomposition proposals, status reports), agents use markdown code blocks or tables within the comment body. No separate "bot message" type — agents are first-class actors in the comment stream, distinguished by their actor identity in the UI.

## Interaction Model

### Keyboard-First

Every action has a keyboard shortcut. Graph navigation:

- `Alt+↑` — navigate to parent
- `Alt+↓` — navigate to children
- `Alt+←/→` — navigate siblings
- Follow lateral links via shortcut

### Command Palette (`Cmd+K`)

The primary navigation and action method:

- Fuzzy search across all nodes, actions, views
- Context-aware: shows different actions depending on current view and selection
- Unified entry point for commands ("change status") and search results ("issues matching 'stripe'")

### Natural Language Node Creation (from Todoist)

Type in the command palette: "Add a bug under Auth > Login flow: password reset emails aren't sending, p0, assign to agent-1"

- Parses tree path via `>`, labels via `#` or keywords (`p0`, `bug`), assignment via `@`
- Fuzzy-matches node names in the path
- Falls back to inbox if path can't be resolved
- Agent can use same syntax via API

### Plan-Then-Apply

Structural changes show a preview before committing:

- **Reparent preview:** "Moving 'Auth' under 'Infrastructure' will: change depth from 1→2, move 12 child nodes, agent-1 will lose access (scoped to 'Backend' subtree)"
- **Bulk operations:** "Changing status of 8 nodes to 'done' — 3 have open blockers"
- **Delete preview:** "Deleting 'Legacy API' will remove 1 node + 7 children, break 3 lateral links"
- **Agent proposals:** agent submits a "plan" (e.g., proposed decomposition), human reviews diff-style and approves

## View Switching

Users can switch between views freely. The selected node context is preserved — if you're focused on "Login" in the Focus Widget and switch to Layered Overview, "Login" is highlighted/centered.

## Notifications (Scoped Watching)

### Watch Scoping

- **Watch granularity:** single node, subtree, or project-wide
- **Event type filters:** status changes, comments, new children, link changes, agent actions
- **Defaults:** watch nodes you created or are assigned to
- **Mute:** temporarily silence a noisy subtree
- **Agent filter:** "only notify me when agent-1 changes something"

### Delivery Channels

Notifications are delivered through three channels, configurable per user:

1. **In-app real-time (Centrifugo).** Connected clients receive instant push via Centrifugo WebSocket channels. Notifications appear in an in-app notification center (badge count + dropdown). This is the primary channel.
2. **Push notifications.** Web Push API for browser notifications when the tab is backgrounded. Tauri desktop uses native OS notifications via the Tauri notification plugin.
3. **Email.** For offline/away users. Two modes per user preference:
   - **Immediate:** one email per event (for high-priority watches only)
   - **Digest:** batched summary (hourly or daily, configurable)

Delivery is handled by the `tasks/notifications.py` Taskiq worker. The worker reads the user's watch configuration + delivery preferences, then fans out to the appropriate channels.

## Entry Experience

### New Project (Clean Start)

1. User creates a project → automatically creates root node with project name
2. User placed in Focus Widget on root node
3. Prompt to add first children (components/areas)
4. Command palette available immediately for keyboard-driven creation

### Import (v0.2+)

- Import from Linear, Jira, GitHub Issues
- System infers hierarchy from existing relationships
- User reviews and adjusts inferred tree before confirming