# Scene Navigator

Scene Navigator is a minimal scene outline for Obsidian. It lists single-line
HTML comments from the active Markdown note and lets you jump to their exact
position.

When the editor cursor is inside a scene, these commands are also available
from the Command Palette and can be assigned shortcuts under **Settings →
Hotkeys**:

- **Scene Navigator: Copy current scene** copies the complete current scene.
- **Scene Navigator: Select current scene** selects the complete current scene.

```markdown
<!-- first encounter – v.07 -->
```

The comment appears in the sidebar as:

> first encounter – v.07

Scene Navigator uses ordinary HTML comments. It does not introduce a custom
file format, and your notes remain fully usable without the plugin.

## Quick start

1. Add a single-line comment such as `<!-- first encounter – v.07 -->` to a
   Markdown note.
2. Run **Scene Navigator: Open navigator** or select its ribbon icon.
3. Select a scene name in the sidebar to jump to its marker.

## Commands and suggested hotkeys

Scene Navigator does not assign default hotkeys, so it cannot overwrite an
existing shortcut. Open **Settings → Hotkeys**, search for **Scene Navigator**,
and assign only the commands you want.

| Command | What it does | Suggested macOS hotkey |
| --- | --- | --- |
| **Open navigator** | Opens and reveals the Scene Navigator sidebar. | Use the ribbon icon |
| **Toggle scene comment** | Creates, wraps, or removes a single-line scene marker. | `⇧⌘,` |
| **Copy current scene** | Copies the complete scene containing the cursor. | `⇧⌘S` |
| **Select current scene** | Selects the complete scene containing the cursor. | `⌥⇧⌘S` |

## Features

- Lists every single-line `<!-- HTML comment -->` in document order.
- Shows a native-themed divider before the next scene when the document contains
  a standalone `----` line.
- Creates, wraps, or removes scene comments with the **Toggle scene comment**
  command.
- Opens each comment at its exact editor position.
- Selects, copies, duplicates, or cuts a complete scene from its comment to the
  next one.
- Updates when you switch notes, edit comments, or Obsidian reloads a file.
- Searches scenes from a compact toolbar modeled after Obsidian's Outline view.
- Highlights the scene containing the cursor.
- Optionally keeps the current scene visible with **Auto-scroll to current
  scene**.
- Truncates long sidebar labels while preserving the full text in a tooltip.
- Uses Obsidian's native view system and theme variables.
- Works in either sidebar and on desktop and mobile.

## Usage

1. Open a Markdown note containing single-line HTML comments.
2. On desktop, run **Scene Navigator: Open navigator** from the Command
   Palette. On mobile, use either the Scene Navigator ribbon button or the same
   command.
3. Select a scene to move the editor cursor to that comment.

Run **Scene Navigator: Toggle scene comment** in the Command Palette while
editing a note to create or remove a scene marker:

- With no selection, it inserts `<!--  -->` and places the cursor between the
  spaces.
- With the cursor inside a word, it wraps the whole word.
- With text selected on one line, it wraps that text as an HTML comment.
- With the cursor or selection inside an existing single-line HTML comment, it
  removes the comment markers and preserves the text.

Scene markers must stay on one line. The command refuses multiline selections
because Scene Navigator intentionally ignores multiline HTML comments. To add a
keyboard shortcut, open **Settings → Hotkeys** and search for **Scene Navigator:
Toggle scene comment**. Suggested macOS shortcut: `Shift-Command-,` (`⇧⌘,`).

The magnifying-glass button filters the visible list. The second toolbar button
enables or disables automatic scrolling to the scene at the current cursor
position.

Right-click a scene on desktop, or press and hold it on mobile, to open these
actions:

- **Copy scene** copies everything from the selected HTML comment up to, but not
  including, the next HTML comment.
- **Select scene** selects the complete scene so Obsidian can display selection
  statistics such as its word count.
- **Duplicate scene** inserts an exact copy at the end of that range.
- **Cut scene** copies the same range and then removes it from the note.

For the final scene, the range ends at the end of the file. Duplicate and cut
are ordinary editor changes and can be undone with Obsidian's **Undo** command.

You can drag the view between sidebars using Obsidian's standard pane controls.

### Scene breaks

Scene Navigator recognizes this exact standalone line as a scene break:

```markdown
----
```

Optional surrounding whitespace is ignored. Three or five hyphens are not
treated as scene breaks. The divider is visual and non-interactive; Scene
Navigator never changes the source line.

## Scope

Scene Navigator intentionally:

- reads only single-line HTML comments;
- ignores multiline HTML comments and `%% Obsidian comments %%`;
- reads exact `----` lines only to display scene breaks;
- does not depend on headings;
- changes note content only when you explicitly run **Toggle scene comment** or
  choose **Duplicate scene** or **Cut scene**, using ordinary undoable editor
  operations;
- does not add IDs, tags, frontmatter, block IDs, or other syntax;
- does not create auxiliary vault files or store scenes in a database.

All single-line HTML comments are included in version 1.0.0. The parser has a
separate filtering boundary so an optional convention such as `– v.` can be
added later without changing the file format or navigation model.

## Installation

### Installation with BRAT

1. Install and enable [BRAT](https://github.com/TfTHacker/obsidian42-brat).
2. Open **Settings → BRAT** and choose **Add beta plugin**.
3. Enter `beppepic/scene-navigator` and enable the plugin.

### Community Plugins

Once Scene Navigator is accepted into the Obsidian Community Plugins directory:

1. Open **Settings → Community plugins**.
2. Select **Browse** and search for **Scene Navigator**.
3. Install and enable the plugin.

### Manual installation

Download `main.js`, `manifest.json`, and `styles.css` from the latest GitHub
release. Place them in:

```text
<vault>/.obsidian/plugins/scene-navigator/
```

Reload Obsidian, then enable **Scene Navigator** under **Settings → Community
plugins**.

## Development

Requirements: Node.js 18 or newer and pnpm or npm.

```bash
pnpm install
pnpm test
pnpm lint
pnpm build
```

The production build creates `main.js`. Compiled files are attached to GitHub
releases and are not committed to the repository.

## Privacy and permissions

Scene Navigator works locally. It makes no network requests, collects no
telemetry, and creates no database. It reads the active note to build the
sidebar. Note content changes only when you explicitly choose **Duplicate
scene** or **Cut scene**, or run **Toggle scene comment**.

## License

[MIT](LICENSE)