viteboard 0.1.1 → 0.1.3

package/bin/viteboard.mjs

@@ -4,6 +4,7 @@ import { createServer } from "vite";
 import { fileURLToPath } from "node:url";
 import path from "node:path";
 import fs from "node:fs";
+import { createContentApiPlugin } from "./content-api-plugin.mjs";
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const packageRoot = path.resolve(__dirname, "..");
@@ -29,15 +30,10 @@ async function main() {
     await server.listen();
     server.printUrls();
   } else if (hasDist) {
-    // Installed as a package — serve the pre-built dist with the API plugin
-    // We need to dynamically import the config since it may be .ts
-    const { default: configFn } = await import(path.join(packageRoot, "vite.config.ts"));
-    const config = typeof configFn === "function" ? configFn({}) : configFn;
-    const plugins = Array.isArray(config.plugins) ? config.plugins : [];
-
+    // Installed as a package — serve the pre-built dist with the runtime JS plugin.
     const server = await createServer({
       root: path.join(packageRoot, "dist"),
-      plugins,
+      plugins: [createContentApiPlugin()],
       server: { port, host, open: true },
     });
     await server.listen();

package/content/docs/index.md

@@ -25,7 +25,7 @@ ViteBoard discovers `docs/` folders inside your projects and gives you a workspa
 ## Keyboard Shortcuts
 
 | Shortcut | Action |
-|----------|--------|
+| --- | --- |
 | `Cmd/Ctrl K` | Open search |
 | `Escape` | Close modals and search |
 

package/content/docs/product-roadmap.board.json

@@ -3,11 +3,11 @@
   "id": "product-roadmap",
   "title": "Product Roadmap",
   "createdAt": 1718000000000,
-  "updatedAt": 1784600810590,
+  "updatedAt": 1785447846332,
   "viewport": {
-    "offsetX": -3547.7083035349933,
-    "offsetY": -2049.683417968947,
-    "scale": 0.7351121006160558
+    "offsetX": -2867.916693773289,
+    "offsetY": -1155.98783153076,
+    "scale": 0.6195352130520436
   },
   "theme": "light",
   "elements": [

package/content/machine/board-v1.schema.json

@@ -0,0 +1,138 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://viteboard.local/board-v1.schema.json",
+  "title": "ViteBoard Board v1",
+  "type": "object",
+  "required": [
+    "version",
+    "id",
+    "title",
+    "createdAt",
+    "updatedAt",
+    "viewport",
+    "theme",
+    "elements",
+    "assetIds"
+  ],
+  "properties": {
+    "$schema": {
+      "type": "string"
+    },
+    "version": {
+      "const": 1
+    },
+    "id": {
+      "type": "string",
+      "minLength": 1
+    },
+    "title": {
+      "type": "string"
+    },
+    "createdAt": {
+      "type": "number"
+    },
+    "updatedAt": {
+      "type": "number"
+    },
+    "viewport": {
+      "type": "object",
+      "required": ["offsetX", "offsetY", "scale"],
+      "properties": {
+        "offsetX": { "type": "number" },
+        "offsetY": { "type": "number" },
+        "scale": { "type": "number" }
+      },
+      "additionalProperties": false
+    },
+    "theme": {
+      "enum": ["light", "dark"]
+    },
+    "elements": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/element" }
+    },
+    "assetIds": {
+      "type": "array",
+      "items": { "type": "string" }
+    }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "elementStyle": {
+      "type": "object",
+      "properties": {
+        "fill": { "type": "string" },
+        "stroke": { "type": "string" },
+        "strokeWidth": { "type": "number" },
+        "opacity": { "type": "number" },
+        "borderRadius": { "type": "number" },
+        "shadow": { "type": "boolean" },
+        "fontSize": { "type": "number" },
+        "fontFamily": { "type": "string" },
+        "fontWeight": { "type": "string" },
+        "textColor": { "type": "string" },
+        "arrowStart": { "type": "boolean" },
+        "arrowEnd": { "type": "boolean" },
+        "strokeDash": {
+          "type": "array",
+          "items": { "type": "number" }
+        }
+      },
+      "additionalProperties": true
+    },
+    "element": {
+      "type": "object",
+      "required": [
+        "id",
+        "type",
+        "x",
+        "y",
+        "width",
+        "height",
+        "rotation",
+        "zIndex",
+        "locked",
+        "hidden",
+        "createdAt",
+        "updatedAt",
+        "style",
+        "data"
+      ],
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "type": {
+          "enum": [
+            "sticky",
+            "task",
+            "rectangle",
+            "ellipse",
+            "text",
+            "line",
+            "arrow",
+            "connector",
+            "image",
+            "screenshot",
+            "frame",
+            "templateGroup"
+          ]
+        },
+        "x": { "type": "number" },
+        "y": { "type": "number" },
+        "width": { "type": "number" },
+        "height": { "type": "number" },
+        "rotation": { "type": "number" },
+        "zIndex": { "type": "number" },
+        "locked": { "type": "boolean" },
+        "hidden": { "type": "boolean" },
+        "createdAt": { "type": "number" },
+        "updatedAt": { "type": "number" },
+        "style": { "$ref": "#/$defs/elementStyle" },
+        "data": {
+          "type": "object",
+          "additionalProperties": true
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}

package/content/machine/example.board.json

@@ -0,0 +1,217 @@
+{
+  "$schema": "/board-v1.schema.json",
+  "version": 1,
+  "id": "examples/system-flow",
+  "title": "System Flow Example",
+  "createdAt": 1784635200000,
+  "updatedAt": 1784635200000,
+  "viewport": {
+    "offsetX": 80,
+    "offsetY": 80,
+    "scale": 0.58
+  },
+  "theme": "light",
+  "elements": [
+    {
+      "id": "frame-example",
+      "type": "frame",
+      "x": 0,
+      "y": 0,
+      "width": 1240,
+      "height": 840,
+      "rotation": 0,
+      "zIndex": 1,
+      "locked": false,
+      "hidden": false,
+      "createdAt": 1784635200000,
+      "updatedAt": 1784635200000,
+      "style": {
+        "fill": "#ffffff",
+        "stroke": "#e5e7eb",
+        "strokeWidth": 1.5,
+        "borderRadius": 20,
+        "shadow": true
+      },
+      "data": {
+        "text": "",
+        "shapeKind": "rectangle"
+      }
+    },
+    {
+      "id": "title-example",
+      "type": "text",
+      "x": 40,
+      "y": 50,
+      "width": 500,
+      "height": 40,
+      "rotation": 0,
+      "zIndex": 2,
+      "locked": false,
+      "hidden": false,
+      "createdAt": 1784635200000,
+      "updatedAt": 1784635200000,
+      "style": {
+        "fontSize": 24,
+        "fontWeight": "700",
+        "textColor": "#1f2933"
+      },
+      "data": {
+        "text": "System flow"
+      }
+    },
+    {
+      "id": "actor-user",
+      "type": "ellipse",
+      "x": 120,
+      "y": 320,
+      "width": 190,
+      "height": 110,
+      "rotation": 0,
+      "zIndex": 3,
+      "locked": false,
+      "hidden": false,
+      "createdAt": 1784635200000,
+      "updatedAt": 1784635200000,
+      "style": {
+        "fill": "#dcfce7",
+        "stroke": "#16a34a",
+        "strokeWidth": 1.5,
+        "shadow": true,
+        "fontSize": 14,
+        "fontWeight": "650",
+        "textColor": "#1f2933"
+      },
+      "data": {
+        "text": "User"
+      }
+    },
+    {
+      "id": "surface-ui",
+      "type": "rectangle",
+      "x": 430,
+      "y": 330,
+      "width": 220,
+      "height": 90,
+      "rotation": 0,
+      "zIndex": 4,
+      "locked": false,
+      "hidden": false,
+      "createdAt": 1784635200000,
+      "updatedAt": 1784635200000,
+      "style": {
+        "fill": "#4dabf7",
+        "stroke": "#1d4ed8",
+        "strokeWidth": 1.5,
+        "borderRadius": 999,
+        "shadow": true,
+        "fontSize": 14,
+        "fontWeight": "650",
+        "textColor": "#ffffff"
+      },
+      "data": {
+        "text": "ViteBoard UI",
+        "shapeKind": "pill"
+      }
+    },
+    {
+      "id": "store-docs",
+      "type": "rectangle",
+      "x": 840,
+      "y": 320,
+      "width": 220,
+      "height": 110,
+      "rotation": 0,
+      "zIndex": 5,
+      "locked": false,
+      "hidden": false,
+      "createdAt": 1784635200000,
+      "updatedAt": 1784635200000,
+      "style": {
+        "fill": "#86efac",
+        "stroke": "#15803d",
+        "strokeWidth": 1.5,
+        "shadow": true,
+        "fontSize": 14,
+        "fontWeight": "650",
+        "textColor": "#1f2933"
+      },
+      "data": {
+        "text": "Docs root\nfiles on disk",
+        "shapeKind": "cylinder"
+      }
+    },
+    {
+      "id": "edge-user-ui",
+      "type": "arrow",
+      "x": 310,
+      "y": 375,
+      "width": 120,
+      "height": 0,
+      "rotation": 0,
+      "zIndex": 6,
+      "locked": false,
+      "hidden": false,
+      "createdAt": 1784635200000,
+      "updatedAt": 1784635200000,
+      "style": {
+        "stroke": "#64748b",
+        "strokeWidth": 2,
+        "arrowEnd": true,
+        "arrowStart": false
+      },
+      "data": {
+        "text": "edits",
+        "labelPosition": "center"
+      }
+    },
+    {
+      "id": "edge-ui-store",
+      "type": "arrow",
+      "x": 650,
+      "y": 375,
+      "width": 190,
+      "height": 0,
+      "rotation": 0,
+      "zIndex": 7,
+      "locked": false,
+      "hidden": false,
+      "createdAt": 1784635200000,
+      "updatedAt": 1784635200000,
+      "style": {
+        "stroke": "#64748b",
+        "strokeWidth": 2,
+        "arrowEnd": true,
+        "arrowStart": false
+      },
+      "data": {
+        "text": "persists",
+        "labelPosition": "center"
+      }
+    },
+    {
+      "id": "note-example",
+      "type": "sticky",
+      "x": 140,
+      "y": 650,
+      "width": 360,
+      "height": 90,
+      "rotation": 0,
+      "zIndex": 8,
+      "locked": false,
+      "hidden": false,
+      "createdAt": 1784635200000,
+      "updatedAt": 1784635200000,
+      "style": {
+        "fill": "#fef3c7",
+        "borderRadius": 12,
+        "shadow": true,
+        "fontSize": 11,
+        "textColor": "#1f2933"
+      },
+      "data": {
+        "text": "Keep embed crops inside the frame and leave enough space around labeled arrows."
+      }
+    }
+  ],
+  "assetIds": []
+}

package/content/machine/guide.md

@@ -0,0 +1,270 @@
+# ViteBoard Authoring Guide
+
+ViteBoard is a local-first documentation workspace. Humans browse it through the web UI. Machines can use the same origin to discover how the app is structured, then use normal filesystem tools to create and update the underlying files.
+
+This guide is read-only. It explains how to work with ViteBoard content and how to cooperate with a human who may be using the app at the same time.
+
+## Connection rule
+
+When a user gives you a ViteBoard URL, keep using that exact origin.
+
+Example:
+
+- if the user says `http://localhost:5173`, keep using `http://localhost:5173`
+- do not replace it with `http://127.0.0.1:5173`
+
+Some local ViteBoard sessions bind only one loopback interface, so `localhost` and `127.0.0.1` are not always equivalent.
+
+## 1. Workspace model
+
+- Projects are registered in the local workspace.
+- Every descendant directory named `docs` becomes a docs root.
+- Markdown documents, capabilities, boards, and assets live inside a docs root.
+
+Important discovery endpoints:
+
+- `GET /__api/workspace`
+- `GET /__api/project-tree?projectId={projectId}`
+- `GET /__api/tree?rootId={rootId}`
+
+The machine can navigate the same app surfaces a human uses:
+
+- workspace home: `#/`
+- project wiki: `#/project/{projectId}`
+- project board index: `#/project/{projectId}/boards`
+- document view: `#/root/{rootId}/docs/{path}`
+- root board list: `#/root/{rootId}/boards`
+- board editor: `#/root/{rootId}/boards/{boardId}`
+- capability index: `#/root/{rootId}/capabilities`
+- capability document: `#/root/{rootId}/capabilities/{path}`
+- directory wiki: `#/root/{rootId}/directory/{path}`
+
+Open these routes directly when you want the human UI to focus a specific page, document, board, or wiki surface.
+
+If a target project is not in the workspace yet, register it with:
+
+```http
+POST /__api/workspace/project
+Content-Type: application/json
+
+{
+  "rootPath": "/absolute/project/path",
+  "label": "optional label"
+}
+```
+
+If the project has no docs root yet, create one with:
+
+```http
+POST /__api/workspace/project/docs-root
+Content-Type: application/json
+
+{ "projectId": "project-..." }
+```
+
+## 2. Files and IDs
+
+### Markdown documents
+
+- Stored as `*.md` beneath a docs root.
+- Read and write them directly as normal Markdown files.
+
+### Boards
+
+- Stored as `*.board.json` anywhere beneath a docs root.
+- Board ID = path relative to the docs root, without `.board.json`.
+
+Example:
+
+```text
+docs/architecture/system-overview.board.json
+```
+
+Board ID:
+
+```text
+architecture/system-overview
+```
+
+### Capabilities
+
+- Stored as managed directory branches beneath `capabilities/` inside a docs root.
+- A capability branch is the unit, not just one markdown file.
+- Human entrypoint: `index.md`
+- Machine entrypoint: `llms.txt`
+
+Example:
+
+```text
+docs/capabilities/automation/docs-refresh/
+  index.md
+  llms.txt
+  scripts/
+```
+
+Capability route path:
+
+```text
+automation/docs-refresh
+```
+
+Machines should treat the whole branch as the capability context and use `llms.txt` as the first machine-facing file when it exists.
+
+## 3. Markdown board embeds
+
+Use fenced `board` blocks inside Markdown:
+
+````markdown
+```board
+src: ./system-overview
+region: 20, 20, 1200, 760
+height: 500
+title: System overview
+```
+````
+
+Fields:
+
+- `src` required
+- `region` optional, `x, y, width, height`
+- `height` optional, minimum `120`, default `360`
+- `title` optional
+
+Relative `src` paths resolve from the Markdown document directory.
+
+## 4. Board document model
+
+Every board should contain:
+
+- `version: 1`
+- `id`
+- `title`
+- `createdAt`
+- `updatedAt`
+- `viewport`
+- `theme`
+- `elements`
+- `assetIds`
+
+Preferred form:
+
+```json
+{
+  "$schema": "/board-v1.schema.json",
+  "version": 1,
+  "id": "architecture/system-overview",
+  "title": "System Overview",
+  "createdAt": 1784635200000,
+  "updatedAt": 1784635200000,
+  "viewport": { "offsetX": 80, "offsetY": 80, "scale": 0.24 },
+  "theme": "light",
+  "elements": [],
+  "assetIds": []
+}
+```
+
+Use the schema at `/board-v1.schema.json` for the full contract.
+
+## 5. Element families
+
+Supported element types:
+
+- `sticky`
+- `task`
+- `rectangle`
+- `ellipse`
+- `text`
+- `line`
+- `arrow`
+- `connector`
+- `image`
+- `screenshot`
+- `frame`
+- `templateGroup`
+
+Important shape semantics:
+
+- Rectangle: general system or concept
+- Ellipse: actor or user group
+- Diamond: decision or routing question
+- Pill: stable platform or product identity
+- Parallelogram: interface or input/output boundary
+- Hexagon: platform or partner capability
+- Cylinder: authoritative data store
+- Sticky: caveat or interpretation
+
+Non-ellipse graphic shapes usually use:
+
+```json
+{
+  "type": "rectangle",
+  "data": { "shapeKind": "diamond" }
+}
+```
+
+## 6. Diagram composition
+
+- One board should answer one coherent family of questions.
+- One white frame should contain one diagram or visual cluster.
+- Choose one dominant reading direction.
+- Keep enough whitespace above and below the main node bounds.
+- Use dashed arrows for optional or weaker relationships.
+- Remove arrow labels when the relationship is already obvious.
+- Keep Markdown embed crops fully inside a white frame.
+
+## 7. Updating existing content
+
+When changing a hand-edited board:
+
+1. Preserve the board ID.
+2. Preserve unrelated elements.
+3. Preserve `createdAt`.
+4. Update `updatedAt`.
+5. Keep stable element IDs where possible.
+6. Recalculate arrow geometry if nodes moved.
+7. Adjust any embed crop if the layout changed.
+
+When changing a Markdown document:
+
+1. Preserve unrelated sections.
+2. Preserve semantic frontmatter such as `title`, `summary`, and `tags`.
+3. Update fenced `board` embeds if board location or crop changes.
+
+## 8. Cooperative live use
+
+If you want the app to reflect that an agent is connected and editing:
+
+1. Register an actor session.
+2. Heartbeat while active.
+3. Acquire a lock before writing a board or Markdown file.
+4. Write your file changes.
+5. Release the lock.
+
+Actor sessions can include the current route, current doc or board target, and for boards the currently selected element IDs. That makes prompts like “update the section I have selected” possible when the actor and the app are cooperating on the same live session.
+
+The lock protocol is cooperative. While your lock is active, the human UI becomes read-only for that target.
+
+Session endpoints:
+
+- `POST /__api/actors/session`
+- `POST /__api/actors/heartbeat`
+- `DELETE /__api/actors/session?actorId=...`
+
+Lock endpoints:
+
+- `POST /__api/locks/acquire`
+- `POST /__api/locks/release`
+
+Live events:
+
+- `GET /__api/events`
+
+## 9. Completion checklist
+
+- Board JSON parses.
+- Board ID matches its path from the docs root.
+- Element IDs are unique.
+- Geometry is finite.
+- Embeds resolve by relative path.
+- Embed crops stay inside the intended frame.
+- The resulting layout is readable to a human.