viteboard 0.1.0 → 0.1.2

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.

package/content/machine/llms.txt

@@ -0,0 +1,31 @@
+# ViteBoard
+
+> Local-first documentation workspace and infinite-canvas board system. The source of truth is plain files on disk.
+
+Use your normal filesystem tools to read and write project files. Use ViteBoard's HTTP surface to discover workspace roots, understand board/document grammar, and coordinate live editing with locks and presence.
+
+Always reuse the exact origin the user gives you, for example `http://localhost:5173`. Do not silently swap it for `127.0.0.1`, another hostname, or another port because the running ViteBoard instance may only be bound on one loopback interface.
+
+## Core machine docs
+
+- [ViteBoard authoring guide](/viteboard-guide.md): How docs roots, boards, embeds, visual layout, locks, and live coordination work.
+- [Board schema v1](/board-v1.schema.json): JSON Schema for `.board.json` files.
+- [Example board](/viteboard-example.board.json): One complete valid ViteBoard board.
+
+## Capability model
+
+- Capabilities are managed directory branches under `capabilities/` inside a docs root.
+- Human entrypoint: `index.md`
+- Machine entrypoint: `llms.txt`
+- The rest of the branch may contain markdown, scripts, helpers, assets, examples, and nested directories.
+
+## App discovery
+
+- [Workspace listing](/__api/workspace): Registered projects and docs roots.
+- [Machine manifest](/.well-known/viteboard.json): Route templates and coordination endpoints.
+
+The machine can also open the same wiki, document, board, capability, and directory routes a human uses. See the guide for the exact route templates.
+
+## Optional
+
+- [Machine guide source](https://gitlab.com/ajsib/viteboard): Project repository homepage.