viteboard 0.1.0 → 0.1.1

package/README.md

@@ -1,8 +1,10 @@
 # ViteBoard
 
-A local-first documentation workspace and infinite-canvas whiteboard. Markdown docs, boards, and structured capability specs — all plain files on disk, tracked by git.
+A local-first documentation workspace and infinite-canvas whiteboard.
 
-**Zero runtime dependencies.** Built entirely in vanilla TypeScript with Vite.
+Write markdown docs, create visual boards, and manage structured capability specs -- all stored as plain files on disk, tracked by git. No database, no cloud, no vendor lock-in.
+
+Built entirely in vanilla TypeScript with Vite. Zero runtime framework dependencies.
 
 ## Install
 
@@ -20,117 +22,164 @@ Or run without installing:
 
 ```bash
 npx viteboard
+# or
+pnpm dlx viteboard
 ```
 
-Or with pnpm:
+ViteBoard opens in your browser at `http://localhost:5173`.
 
-```bash
-pnpm dlx viteboard
-```
+## Getting Started
 
-ViteBoard opens in your browser. Click **Add Repo** in the sidebar, pick any local project directory, and ViteBoard discovers all `docs/` folders and mounts them in the sidebar.
+1. Click **Add Repo** in the sidebar
+2. Pick any local project directory
+3. ViteBoard scans for `docs/` folders and mounts them in the sidebar
+4. Start writing
 
-## Development
+If your project doesn't have a `docs/` folder yet, select **View: Raw** from the project menu, then right-click the target directory and choose **Create docs folder here**.
 
-To work on ViteBoard itself:
+## Features
 
-```bash
-git clone https://gitlab.com/ajsib/viteboard.git
-cd viteboard
-npm install
-npm run dev
+### Markdown Docs
+
+Write and edit markdown files inside any `docs/` directory. Full rendering support for headings, lists, tables, code blocks, blockquotes, images, and links. Inline editor with live preview.
+
+### Infinite-Canvas Boards
+
+Visual whiteboards saved as `.board.json` files alongside your docs. Elements include sticky notes, shapes, arrows, text, images, tasks, and frames. Boards are small JSON files that diff cleanly in git.
+
+Board regions can be embedded directly into markdown:
+
+````md
+```board
+src: architecture
+region: 100, 50, 1200, 700
+height: 360
+title: System Architecture
 ```
+````
 
-## What It Does
+### Capability Specs
 
-ViteBoard is a local documentation tool that runs alongside your codebase. Point it at a project directory and it finds every `docs/` folder, giving you a workspace to write, organize, and browse documentation — all stored as plain files that git tracks naturally.
+Structured markdown documents with YAML frontmatter (`title`, `summary`, `tags`). Designed for building AI prompts -- add specs to a cart and copy them as a combined prompt.
 
-### Docs
+### Full-Text Search
 
-Write markdown files inside any `docs/` directory. ViteBoard renders them with full markdown support: headings, lists, tables, code blocks, images, and links. Edit inline or in an integrated editor.
+Search across every doc and capability in every registered project. Open with `Cmd/Ctrl K` from anywhere. Results are ranked by title, path, headings, and body text.
 
-### Boards
+### Sidebar Navigation
 
-Infinite-canvas whiteboards saved as `.board.json` files next to your docs. Create sticky notes, shapes, arrows, text, images, tasks, and frames. Boards are small, diffable, and git-native.
+The sidebar has two projections of one project-relative tree. **View: Docs** shows docs roots and the folder paths leading to them. **View: Raw** adds muted project folders and files for discovery. Discovered `docs/` folders stay in their physical location in both views.
 
-Board regions can be embedded directly into markdown documents using fenced code blocks.
+Other sidebar features:
 
-### Capabilities
+- Right-click files and directories for contextual actions (new doc, rename, delete, etc.)
+- Drag and drop to reorganize files between directories
+- Inline rename and creation (VS Code style)
+- Full breadcrumb navigation with wiki pages at every directory level
 
-Structured markdown specs with YAML frontmatter (title, summary, tags). Build a cart of specs and copy them as a combined prompt for AI workflows.
+## How It Works
 
-### Search
+ViteBoard uses a custom Vite plugin as its backend. The dev server reads and writes files directly to your project's `docs/` folders. There is no separate database -- your filesystem is the source of truth.
 
-Full-text search across every doc and capability in every registered project. `Cmd/Ctrl K` to open from anywhere.
+### Directory Convention
 
-## Project Structure
+Any folder named `docs/` inside a registered project is automatically discovered and mounted:
 
 ```
 your-project/
   frontend/
     src/
-    docs/                  <- ViteBoard discovers this
+    docs/                  <- Discovered
       index.md
       guides/
         getting-started.md
-      boards/
-        architecture.board.json
       capabilities/
         auth-flow.md
       assets/
         screenshot.png
   api/
-    docs/                  <- And this
+    docs/                  <- Discovered
       endpoints.md
-  backend/                 <- No docs/ yet (create one via View: Raw)
+      boards/
+        api-flow.board.json
+  backend/                 <- No docs/ yet
 ```
 
-Each `docs/` folder becomes a content root. ViteBoard reads and writes files directly to disk. Git in your project is the source of truth.
-
-## Navigation
+Each `docs/` folder becomes a self-contained content root with its own docs, boards, capabilities, and assets.
 
-### View: Docs (default)
+### Workspace
 
-The sidebar shows only your `docs/` folders and their contents. Clean, focused, no noise from the rest of the project filesystem.
+ViteBoard stores which projects you've registered in `.workspace/workspace.json`. This file is local to your machine and should be gitignored -- it contains only absolute paths to project roots.
 
-### View: Raw
+## Development
 
-Toggle via the three-dot menu on any project header. Shows the full directory tree with non-docs directories subtly muted. Right-click any directory to create a `docs/` folder inside it. Once created, toggle back to Docs view and the new root appears immediately.
+```bash
+git clone https://gitlab.com/ajsib/viteboard.git
+cd viteboard
+npm install
+npm run dev
+```
 
-### Breadcrumbs
+### Scripts
 
-Every page shows its full path as clickable breadcrumbs. Each directory segment links to a wiki page showing the contents of that level — docs, boards, capabilities, and subdirectories.
+| Command | Description |
+|---------|-------------|
+| `npm run dev` | Start development server |
+| `npm run build` | Type-check and bundle to `dist/` |
+| `npm run preview` | Preview the production build |
+| `npm start` | Run via the CLI entry point |
 
-### Shared Links
+### Project Structure
 
-Copy any URL from the address bar. Links are stable and resolve correctly when the same project is registered in the workspace.
+```
+src/
+  app/          Application controller, keyboard shortcuts, board state
+  board/        Board service (CRUD operations for .board.json files)
+  canvas/       Canvas renderer, viewport, hit testing, image cache
+  content/      Content API client, markdown parser, markdown renderer
+  editor/       Inline document editor
+  elements/     Board element types and rendering
+  shell/        Shell (routing, topbar) and Sidebar (navigation tree)
+  storage/      Asset store, board serialization, IndexedDB fallback
+  templates/    Board templates (journey map, persona, system diagram, etc.)
+  testing/      Stress test utilities
+  tools/        Board tools (select, pan, sticky, shape, arrow, text, image)
+  ui/           UI components (modal, toolbar, top controls, overlays)
+  styles.css    All application styles
+vite.config.ts  Vite plugin (backend API server)
+index.html      Entry point
+```
 
-## Sidebar Actions
+### Tech Stack
 
-- **Right-click a directory** inside `docs/` to create docs, boards, capabilities, or subdirectories
-- **Right-click a file** to open, edit, rename, or delete
-- **Drag and drop** files and directories to reorganize
-- **Three-dot menu** on project headers for View: Raw/Docs toggle, wiki, and project actions
+- **Vite** -- Dev server and bundler
+- **TypeScript** -- All source code, zero JavaScript files
+- **Canvas API** -- Board rendering (no canvas libraries)
+- **Custom Vite plugin** -- Backend API for file I/O and workspace management
+- **Hash-based routing** -- Client-side navigation, works as static files
 
-## Workspace
+## API Reference
 
-Developer-specific workspace settings (which projects are registered) live in `.workspace/` and should be gitignored. The workspace file stores only absolute paths to project roots.
+ViteBoard exposes a local REST API at `/__api/` during development:
 
-## Building
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/workspace` | GET | List all projects and their docs roots |
+| `/workspace/pick-project` | POST | Open native folder picker to add a project |
+| `/workspace/project` | DELETE | Remove a project from workspace |
+| `/tree` | GET | Get file tree for a docs root |
+| `/project-tree` | GET | Get full directory tree for a project |
+| `/file` | GET/PUT/PATCH/DELETE | Read, write, rename, or delete files |
+| `/directory` | PUT | Create a directory |
+| `/board` | GET/PUT/DELETE | Read, write, or delete board documents |
+| `/asset` | GET/POST | Serve or upload assets |
 
-```bash
-npm run build     # Type-check + bundle to dist/
-npm run preview   # Preview the production build
-```
+All file operations are scoped to registered docs roots and reject paths that escape the root directory.
 
-## Tech
+## Contributing
 
-- **Vite** — dev server and build tool
-- **TypeScript** — all source code, zero JavaScript
-- **Canvas API** — infinite-canvas board rendering (no libraries)
-- **Custom Vite plugin** — serves as the backend, handling file I/O and workspace management
-- **Hash-based routing** — works as static files, no page reloads
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development guidelines.
 
 ## License
 
-MIT
+[MIT](LICENSE)

package/content/docs/guide/boards-in-markdown.md

@@ -1,48 +1,50 @@
 ---
-title: Boards in markdown
-order: 2
+title: Embedding Boards in Docs
 ---
 
-# Boards in markdown
+# Embedding Boards in Docs
 
-You can embed any board into a doc and **frame exactly the region you want to show**.
+You can embed a region of any board directly into a markdown document using a fenced code block.
 
-## The directive
+## Syntax
 
+````md
 ```board
-src: ../product-roadmap
-region: -393, -16, 1259, 663
+src: architecture
+region: 100, 50, 1200, 700
 height: 360
-title: Product Roadmap
+title: System Overview
 ```
+````
 
-`src` is required — it's the board file name without `.board.json`.
+### Parameters
 
-- `region` is four numbers in **world coordinates**: `x, y, width, height`. Omit it to fit the whole board.
-- The preview is **read-only** and rendered with the same drawing engine as the editor, so it looks identical — just cropped and static.
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `src` | Yes | Board ID (filename without `.board.json`) |
+| `region` | No | Viewport region: `x, y, width, height` |
+| `height` | No | Display height in pixels (default: 300) |
+| `title` | No | Caption shown below the embed |
 
-## How to get a region without doing math
+## Getting the Embed Snippet
 
-1. Open the board from the Boards section for the active docs root and click **Edit**.
-2. Pan/zoom until the area you want fills the screen.
-3. Click **Copy embed** in the top bar.
-4. Paste the snippet into any markdown file. The current visible rectangle becomes the `region`
+The easiest way to create an embed:
 
-\`\`\`board
+1. Open the board in the editor
+2. Navigate to the region you want to embed
+3. Click **Copy embed** in the toolbar
+4. Paste the snippet into your markdown document
 
-src: product-roadmap
+The copied snippet includes the exact viewport coordinates for the current view.
 
-region: 4958, 3057, 1273, 789
+## How It Works
 
-height: 360
+When a markdown document is rendered, board embeds are replaced with a live canvas preview showing the specified region. The preview is read-only -- click it to open the full board editor.
 
-title: Product Roadmap
+## Relative Paths
 
-\`\`\`
+Board paths are resolved relative to the current document. If your document is at `docs/guides/setup.md` and the board is at `docs/boards/flow.board.json`, use:
 
 ```board
-src: ../product-roadmap
-region: 4958, 3057, 1273, 789
-height: 360
-title: Product Roadmap
+src: ../boards/flow
 ```

package/content/docs/guide/boards.md

@@ -4,89 +4,51 @@ title: Boards
 
 # Boards
 
-Boards are infinite-canvas files stored as JSON alongside your docs. They open in a full-screen editor, close back to the doc view, and commit to git like any other file.
-
-## Creating a board
-
-Three ways:
-
-1. Right-click a directory in the sidebar → **New Board**
-2. Click **All Boards** for a project → **+ New board** button on the page
-3. Click the board page button in the top-right of the boards list page
-
-Give the board a title. The file is created at `<docs-root>/boards/<slug>.board.json`.
-
-## Editing a board
-
-Click any board in the sidebar or on the All Boards page. The board opens full-screen. The shell layout is hidden while the editor is active — close with the **×** button in the top-right to return.
-
-### Canvas controls
-
-| Input | Action |
-| --- | --- |
-| Scroll | Pan vertically |
-| Shift + scroll | Pan horizontally |
-| Cmd/Ctrl + scroll | Zoom in / out |
-| Click element | Select |
-| Click + drag empty area | Pan |
-| Double-click element | Edit text |
-| Delete / Backspace | Remove selected |
-
-### Toolbar elements
-
-The bottom toolbar contains every element type:
-
-- **Select** — move, resize, multi-select
-- **Pan** — drag canvas
-- **Sticky** — colour-coded sticky notes
-- **Task** — checkbox task items
-- **Text** — free text at any size
-- **Shapes** — rectangles, ellipses, and more with fill/stroke
-- **Arrow / Connector** — lines between elements
-- **Image** — paste or drag an image file; stored in `assets/`
-- **Frame** — group elements into a named region
-- **Templates** — pre-built layout starters
-
-### Renaming and deleting
-
-Right-click any board link in the sidebar:
-
-- **Rename** — updates the board's title (the `.board.json` filename stays the same)
-- **Delete** — removes the file after confirmation
-
-## Embedding a board in a doc
-
-A board region can be embedded inline in any markdown doc using a fenced `board` block:
-
-````
-```board
-src: my-board
-region: 100, 200, 800, 400
-height: 320
-title: Sprint overview
+Boards are infinite-canvas whiteboards saved as `.board.json` files inside your `docs/` folders.
+
+## Creating a Board
+
+Right-click any directory in the sidebar and select **New Board**. Enter a name and the board opens immediately in full-screen editing mode.
+
+## Elements
+
+| Element | Shortcut | Description |
+|---------|----------|-------------|
+| Sticky Note | `S` | Color-coded notes with text |
+| Shape | `R` | Rectangles, ellipses, diamonds, and more |
+| Text | `T` | Free-form text labels |
+| Arrow | `A` | Connectors between elements |
+| Image | `I` | Drag or paste images onto the canvas |
+| Task | `O` | Checklist items with completion state |
+
+## Navigation
+
+| Action | Input |
+|--------|-------|
+| Pan | Click and drag on empty space, or Shift + scroll |
+| Zoom | Cmd/Ctrl + scroll, or pinch on trackpad |
+| Select | Click an element, or drag to select multiple |
+| Move | Drag a selected element |
+| Resize | Drag the handles on a selected element |
+| Delete | Select and press Backspace/Delete |
+
+## File Format
+
+Boards are stored as JSON:
+
+```json
+{
+  "id": "architecture",
+  "title": "System Architecture",
+  "elements": [...],
+  "viewport": { "x": 0, "y": 0, "zoom": 1 },
+  "createdAt": 1700000000000,
+  "updatedAt": 1700000000000
+}
 ```
-````
-
-- `src` — the board filename without `.board.json` (**required**)
-- `region` — four world-space coordinates: `x, y, width, height` (optional — omit to fit the whole board)
-- `height` — height of the embed in pixels (optional, defaults to 360)
-- `title` — caption shown below the embed (optional)
 
-The embed is **read-only** and rendered with the same drawing engine as the editor.
+These files are small, diffable, and work naturally with git.
 
-## Getting a region without doing the maths
-
-1. Open the board and click **Edit** to enter the canvas editor.
-2. Pan and zoom until the area you want to show fills the screen.
-3. Click **Copy embed** in the top-right toolbar.
-4. Paste the snippet anywhere in a markdown doc.
-
-The `region` coordinates are calculated from whatever is currently visible on screen.
-
-## Board files are git-native
-
-Each board is a single JSON file. `git diff` shows exactly which elements changed. Board files are small — a board with 50 elements is typically under 20 KB.
-
----
+## Exiting the Board Editor
 
-**Next:** [Capabilities](capabilities.md) — writing reusable specs and building LLM prompts.
+Click the back arrow in the top-left corner to return to the documentation view. Your board is saved automatically.

package/content/docs/guide/getting-started.md

@@ -1,71 +1,59 @@
 ---
-title: Getting started
+title: Getting Started
 ---
 
-# Getting started
+# Getting Started
 
-## Install and run
+## Adding a Project
 
-```bash
-pnpm install
-pnpm dev
-```
-
-Open the URL printed in the terminal. You'll see the home page with an empty workspace.
-
-## Add a project
-
-Click **+ Add Repo** on the home page or at the bottom of the sidebar. A native folder picker opens — select the root of any project you want to document.
+Click **Add Repo** in the sidebar footer. A native folder picker opens -- select your project's root directory. ViteBoard scans for `docs/` folders and mounts each one in the sidebar.
 
-The tool scans the selected directory recursively for folders named `docs/`. Every `docs/` folder that contains at least one `.md` or `.board.json` file becomes a **docs root** and appears in the sidebar.
+You can add multiple projects. Each appears as a collapsible section in the sidebar.
 
-> The tool only records the path. It never copies, uploads, or modifies your project files.
+## Creating Documentation
 
-## What the sidebar shows
+Right-click any directory in the sidebar to create:
 
-After adding a project you'll see it as a collapsible section in the sidebar. Click to expand. Inside you'll find the path tree leading to each discovered `docs/` root.
+- **New Doc** -- A markdown file
+- **New Board** -- An infinite-canvas whiteboard
+- **New Directory** -- A subdirectory for organizing content
+- **New Capability** -- A structured spec with YAML frontmatter
 
-- Each docs root shows its relative path (e.g. `backend/api/docs`)
-- Right-click any directory to create a new doc, board, or capability inside it
-- **All Boards** and **All Capabilities** appear at the bottom of each project
+## The docs/ Convention
 
-## The folder model
-
-The tool expects this layout inside each `docs/` root:
+ViteBoard looks for folders named `docs/` inside your project. This is a convention -- documentation lives alongside the code it describes:
 
 ```
-docs/
-  index.md          → shows as "Overview" in the sidebar
-  any-subdir/       → becomes a collapsible group
-    my-doc.md
-  boards/           → board files; excluded from the doc tree
-    my-board.board.json
-  capabilities/     → capability specs; shown via All Capabilities
-    auth-flow.md
-  assets/           → images; excluded from the doc tree
-    screenshot.png
+my-project/
+  frontend/
+    src/
+    docs/           <- ViteBoard finds this
+      index.md
+      guides/
+  api/
+    docs/           <- And this
+      endpoints.md
 ```
 
-`boards/`, `capabilities/`, and `assets/` are special directories — the tool recognises them and surfaces their contents through dedicated views rather than as doc tree nodes.
+### Creating a docs/ Folder
 
-## Your first doc
+If a directory doesn't have a `docs/` folder yet:
 
-1. Right-click a directory in the sidebar.
-2. Choose **New Doc**.
-3. Type a name — it becomes the filename (`my-doc.md`) and the page title.
-4. The doc opens immediately. Click **Edit** in the top bar to write in it.
+1. Open the project menu and select **View: Raw**
+2. Right-click the directory where you want documentation
+3. Select **Create docs folder here**
+4. Switch back to **View: Docs** when you want the focused docs-only view
 
-## Your first board
+## Editing
 
-1. Right-click a directory or click **All Boards** → **+ New board**.
-2. Give it a title.
-3. The board opens in full-screen canvas mode.
-4. Draw, add stickies, shapes, tasks. Close with the × button when done.
+Click any doc in the sidebar to view it. Click the **Edit** button in the topbar (or right-click the doc and select **Edit**) to open the inline editor.
 
-## Removing a project
+Changes are saved directly to the file on disk.
 
-Right-click the project name in the sidebar → **Remove from workspace**. The project is unregistered. Nothing on disk is deleted.
+## Search
 
----
+Press `Cmd/Ctrl K` to open the command palette. Search across all docs and capabilities in every registered project. Use arrow keys to navigate results and Enter to open.
+
+## Workspace
 
-**Next:** [Docs](docs.md) — writing and managing markdown content.
+Your registered projects are stored in `.workspace/workspace.json` in the ViteBoard directory. This file is local to your machine -- add it to `.gitignore`.

package/content/docs/index.md

@@ -4,44 +4,33 @@ title: Overview
 
 # ViteBoard
 
-A local-first documentation workspace for development teams. Markdown docs, infinite-canvas boards, and structured capability specs — all plain files on disk, committed to git alongside your source code.
+A local-first documentation workspace and infinite-canvas whiteboard.
 
-There is no cloud service, no database, no account. The Vite dev-server plugin reads and writes files directly. Every change you make is immediately a git diff.
+ViteBoard discovers `docs/` folders inside your projects and gives you a workspace to write, organize, and browse documentation. Everything is stored as plain files on disk -- markdown, board JSON, and assets -- tracked by your project's git history.
 
----
-
-## What's in here
-
-**[Getting started](guide/getting-started.md)** — add your first project, understand the folder model, make your first doc and board.
-
-**[Docs](guide/docs.md)** — writing and managing markdown documents, the sidebar tree, right-click actions, full-text search.
+## Quick Start
 
-**[Boards](guide/boards.md)** — creating and editing infinite-canvas boards, embedding board regions into docs, the Copy embed workflow.
-
-**[Capabilities](guide/capabilities.md)** — writing capability specs, the component cart, building and copying LLM prompts.
-
-**[Workspace](guide/workspace.md)** — managing multiple projects, the project wiki, keyboard shortcuts, removing projects.
-
----
+1. Click **Add Repo** in the sidebar
+2. Pick any local project directory
+3. ViteBoard scans for `docs/` folders and mounts them
+4. Start writing
 
-## The short version
+## Content Types
 
-1. Run `pnpm dev` in this directory.
-2. Click **Add Repo** in the sidebar and pick any project root.
-3. The sidebar discovers every `docs/` folder under that root.
-4. Right-click any directory in the sidebar to create a doc, board, or capability.
-5. Everything saves to disk. Commit with git as normal.
+- **Docs** -- Markdown files with full rendering support
+- **Boards** -- Infinite-canvas whiteboards saved as `.board.json`
+- **Capabilities** -- Structured specs with YAML frontmatter for AI prompt building
+- **Assets** -- Images stored alongside your docs
 
-**Note:** These built-in docs ship with ViteBoard. To remove them, delete the `content/docs/` folder from the ViteBoard directory and restart the dev server.
+## Keyboard Shortcuts
 
-## How it stores things
+| Shortcut | Action |
+|----------|--------|
+| `Cmd/Ctrl K` | Open search |
+| `Escape` | Close modals and search |
 
-| Action | What happens on disk |
-| --- | --- |
-| Create / edit a doc | Writes `<docs-root>/<path>.md` |
-| Create / save a board | Writes `<docs-root>/boards/<id>.board.json` |
-| Paste image on board | Writes `<docs-root>/assets/<filename>` |
-| Create a capability | Writes `<docs-root>/capabilities/<name>.md` |
-| Add a project | Records path in `.workspace/workspace.json` |
+## Learn More
 
-Nothing leaves your machine.
+- [Getting Started](guide/getting-started.md) -- First steps with ViteBoard
+- [Boards](guide/boards.md) -- Working with the infinite canvas
+- [Embedding Boards](guide/boards-in-markdown.md) -- Embed board regions in docs