In this guide +
New to extensions? Start with the counter. Already building? Jump to the SDK or the contribution you need.
REFERENCE / 01
Quick start
Start with a small panel that saves a different counter for each project. Download the working starter ZIP, then open Plugins → Add → From ZIP file in Daevu. Review the storage permission and install it. Open Project counter from the installed plugins.
The ZIP contains three files at its root:
project-counter/
manifest.json
index.html
main.js
You can also extract the ZIP and install the folder. Choose the folder containing manifest.json, not its parent. Open the panel inside a project, add one, close it and reopen: the saved count should return. Another project has its own counter.
The starter uses window.workspacePlugin; opening its HTML in an ordinary browser does not provide that SDK.
The manifest
{
"apiVersion": 1,
"id": "project-counter",
"name": "Project counter",
"version": "1.0.0",
"description": "A counter saved separately for each project.",
"permissions": ["storage"],
"panels": [
{
"id": "main",
"title": "Project counter",
"type": "html",
"entry": "index.html"
}
]
}
Connect your code
Load your JavaScript with <script type="module" src="main.js"></script>. Wait for the host before calling the SDK. This is the core of the starter; the download also includes loading states, an increment button and error handling.
const sdk = window.workspacePlugin;
const { project, theme } = await sdk.ready();
const saved = await sdk.storage.get("count");
const count = Number.isSafeInteger(saved) ? saved : 0;
await sdk.storage.set("count", count + 1);
REFERENCE / 02
Manifest reference
manifest.json belongs at the package root. Declare only the permissions and contributions your plugin uses.
| Field | Contract |
|---|---|
apiVersion |
The number 1 in Daevu 2.0.5. |
id |
Unique lowercase ID, 2–60 characters: starts with a letter, then letters, digits or hyphens. Keep it stable for updates. |
name |
Non-empty display name, at most 80 characters. |
version |
A semantic version such as 1.0.0 or 1.1.0-beta.1. |
description, author |
Optional display information. |
permissions |
An array of supported permission names, without duplicates. Use [] when none are needed. |
panels |
Up to eight panels. Use [] for a contribution-only plugin. A plugin needs at least one panel or contribution. |
contributes |
Optional boards, fileEditors, sheetFunctions, themes and browser entries. |
HTML panel IDs start with a lowercase letter, contain letters, digits or hyphens, and are at most 50 characters. Every panel needs a unique id, a non-empty title (up to 80 characters), type: "html" and a local entry path. Do not use absolute paths, .., or symlinks.
The host also supports web-chat, web-app and browser-assistant panels. Those use native web or assistant surfaces; the HTML SDK examples here apply to html panels and contribution pages.
REFERENCE / 03
Working with the SDK
The SDK is injected into a plugin's HTML page. Calls return promises. Catch errors in the UI and wait for successful writes before displaying success.
const sdk = window.workspacePlugin;
const { plugin, project, theme } = await sdk.ready();
// Requires project:read. A project must be selected.
const current = await sdk.project();
console.log(current.name, current.notes, current.kpis);
// Refresh a view when project data changes.
const stop = sdk.onChange(async () => {
try {
const latest = await sdk.project();
render(latest); // your rendering function
} catch (error) {
showError(error.message); // your error UI
}
});
// Call stop() when your view no longer needs the subscription.
ready() returns the plugin manifest, a small selected-project summary (or null) and the theme. project() requires project:read and returns the selected project's description, notes and KPIs as well as its ID and name. A plugin cannot pass a different project ID to switch the SDK's scope.
onChange is a notification to refresh your data, not a replacement project payload. Avoid writing back on every change notification: that can create an update loop.
REFERENCE / 04
Permissions
Permissions appear in the install/update review. Adding a method call to your code does not grant its permission.
| Permission | What it enables |
|---|---|
storage |
storage.get(key) and storage.set(key, value): device-local, project-scoped plugin state. |
project:read |
project(): the selected project's notes, overview and KPIs. |
files:read |
files.list() and files.read(id): selected-project files; reads return { name, base64 }. |
files:write |
files.save(name, base64): add a file to the selected project. |
files:edit |
files.update(id, base64): replace an existing file's bytes. |
database:read |
db.schema() and db.query(sql, params): read the project's database within the host's query limits. |
database:write |
db.create(name, properties) and db.write({ op, table, rowId, values }): typed table operations. |
agents:read |
agents.list() and agents.messages(): assigned public profiles and project conversation messages. |
agents:run |
agents.send(agentId, text, chatId): run an assigned agent using its configured provider allowance. |
browser:read |
Share visible browser-tab context with a browser assistant. |
browser:modify |
Browser styles and request-blocking contributions. |
browser:scripts |
Scripts and toolbar tools that run on browser pages. |
web-chat |
Native signed-in AI website panels and user-requested sends. |
Storage keys use 1–80 letters, digits, underscores or hyphens; reserved prototype keys are rejected. Total saved plugin state is limited to 2 MB per plugin. It stays on this device. With no project, storage uses a global scope; project-dependent APIs need a selected project.
File reads and SDK writes accept up to 12 MB of decoded file data. File writes take base64, not a data URL. files:write adds files; files:edit changes existing ones. Database read and write permissions are separate. Agent calls expose public profile fields, not provider credentials, and retain the workspace's agent policies.
The sandbox boundary
HTML plugins run in an opaque sandbox without Node/Electron, direct host filesystem access, external networking or access to the parent page's DOM. Use the SDK for workspace data. Package dependencies and assets locally rather than fetching them from a CDN.
Native website panels have their own browsing context and provider sessions. Browser script contributions run on matching research-browser pages under their declared permission. Those surfaces differ from an HTML panel's sandbox.
REFERENCE / 05
Board and chart types
Add up to 16 board types under contributes.boards. A board page receives the host's selected spreadsheet range or document table, so your renderer can focus on drawing it.
Merge this contribution into a valid manifest. For a contribution-only plugin, keep panels: [].
{
"boards": [
{
"id": "flow",
"name": "Flow diagram",
"hint": "See how values move",
"group": "other",
"entry": "flow.html",
"sample": "From,To,Value\nResearch,Design,8\nDesign,Launch,5"
}
]
}
Groups are basic, stats, business, science and other. A contribution ID starts with a lowercase letter and uses lowercase letters, digits or hyphens, up to 40 characters. entry must be a packaged HTML page. Boards appear in the board picker, on the canvas and in document insertion menus.
const sdk = window.workspacePlugin;
await sdk.ready();
async function refresh() {
const { title, editable, state, table } = await sdk.board.get();
// table: { rows, label, error }
// Handle table.error and empty data before drawing.
renderChart({ title, rows: table.rows, error: table.error, state });
}
await refresh();
const stop = sdk.onChange(refresh);
// Only call this from an editable board context.
const board = await sdk.board.get();
if (board.editable) await sdk.board.set({ selectedSeries: "Revenue" });
renderChart is your implementation. board.set saves the board's own JSON state (up to 200 KB); it does not rewrite its source spreadsheet. A read-only embed rejects state writes. Disabling a plugin leaves its boards in the project with a missing-plugin message until it is enabled again.
REFERENCE / 06
File editors
A file editor adds an Edit action for selected extensions. The editor page needs both files:read and files:edit; this permission is shown because the plugin can replace existing content.
{
"fileEditors": [
{ "id": "text", "name": "Text workshop", "extensions": ["txt", "md"], "entry": "editor.html" }
]
}
const sdk = window.workspacePlugin;
await sdk.ready();
const { id, name } = await sdk.file.get();
const { base64 } = await sdk.files.read(id);
// Decode, edit, then encode your result as base64.
// newBase64 must contain the complete replacement file.
await sdk.files.update(id, newBase64);
newBase64 is supplied by your editor. Offer an explicit save action and surface errors. Each plugin can add up to eight editors; each editor accepts up to 12 extension names (lowercase letters/digits, no leading dot, up to eight characters each).
REFERENCE / 07
Spreadsheet functions
Declare formulas as expressions over named arguments. They need no JavaScript page or additional permission. Built-in formula names take precedence.
{
"sheetFunctions": [
{
"name": "MARKUP",
"args": ["price", "pct"],
"expr": "price*(1+pct/100)",
"hint": "Price plus a percentage"
}
]
}
After installation, =MARKUP(200,10) returns 220. Expressions use the host's mathematical expression language, not arbitrary JavaScript. Use only your declared argument names and supported math functions/constants. Disable the plugin to remove its functions from evaluation.
REFERENCE / 08
Appearance themes
Themes extend a light or dark base through CSS custom properties. They appear in Settings → Appearance.
{
"themes": [
{
"id": "dusk",
"name": "Dusk",
"mode": "dark",
"vars": { "--accent": "#7c5cff", "--bg": "#14121c" }
}
]
}
The theme validator permits supported custom-property names and plain colour/length values. URLs and arbitrary CSS rules are refused. A theme contribution changes the host's appearance; panel styling still belongs to your packaged HTML/CSS.
REFERENCE / 09
Research browser extensions
Declare additions under contributes.browser. Choose specific match patterns where possible. Omitted matches means every site.
{
"browser": {
"styles": [
{
"id": "reading",
"name": "Reading width",
"matches": ["https://*.example.com/*"],
"css": "article { max-width: 70ch !important; margin-inline: auto !important; }"
}
],
"blocks": ["*://ads.example.net/*"],
"tools": [
{
"id": "words",
"name": "Count words",
"icon": "Search",
"matches": ["https://*.example.com/*"],
"code": "document.body.innerText.trim().split(/\\s+/).length + ' words'"
}
]
}
}
This example requires browser:modify for styles and blocks, and browser:scripts for the tool. A scripts entry has the same id, name, matches and code structure as a tool; it runs after a page loads instead of from a toolbar button. Styles also apply after page load. Blocks stop matching requests before they are sent. Tools run on demand and display their returned value.
Use inline css/code, or a file path to a packaged text file. Each source is limited to 20 KB. There can be up to eight styles, eight scripts, eight tools and 100 block patterns.
REFERENCE / 10
React and bundled libraries
HTML pages can use module scripts, relative imports and packaged CSS/JSON. Daevu bundles react, react-dom, three, three/addons/... and phaser for plugin pages. .mjs, .jsx and .css modules are supported.
import React from "react";
import { createRoot } from "react-dom/client";
const sdk = window.workspacePlugin;
const { project } = await sdk.ready();
createRoot(document.querySelector("#root")).render(
<main><h1>{project?.name ?? "My workspace"}</h1></main>
);
Save that as a local .jsx module and load it from your HTML's module script. Other dependencies must be included in your package as browser-compatible local code. No package manager or install script runs during installation. Do not ship node_modules, a server, or code requiring Node built-ins.
REFERENCE / 11
Package, install and update
From a checkout of Open-Daevu, use its packaging command with Node.js 24:
node scripts/package-plugin.cjs path/to/project-counter project-counter.zip
The command validates the folder, writes a ZIP, then validates the ZIP. Installation also checks that HTML entry pages compile before showing the permission review.
| Limit | Maximum |
|---|---|
| Files | 128, including the root manifest |
| Individual file | 2 MB |
| Total uncompressed source/assets | 12 MB |
| Input ZIP | 16 MB |
Keep manifest.json at the ZIP root. Path traversal, symlinks, encrypted ZIPs, duplicate case-insensitive paths and invalid checksums are rejected. Binary assets are packaged locally and converted to data URLs by the installer.
Install from a folder or ZIP through Plugins → Add. You can also choose Install from GitHub, supply a public https://github.com/owner/repository URL, and select Download & review. That repository needs a plugin manifest at its root; an arbitrary repository is not a plugin. The installer uses its default branch. Private repositories and automatic plugin updates are not supported in this version.
To update, keep the plugin id, bump version and reinstall the package. The host asks for review again and preserves plugin settings/state. Place in lets standalone panels live in the sidebar, project tab bar or pull-out. Browser assistants stay integrated with the research browser.
Installation, provider sessions and storage are device-local. Install the plugin on each device. Project files and database data use the workspace's normal persistence and Drive behaviour. Uninstalling removes the package and plugin settings while leaving project files/database records.
REFERENCE / 12
Troubleshooting
| Symptom | Check |
|---|---|
workspacePlugin is missing |
Run the page inside an installed HTML plugin, not an ordinary browser or a native website panel. |
| Missing permission | Add the exact permission to the manifest, repackage and review the update. |
| Project not available | Select a project; project files, database and agents require that scope. |
| Missing entry / manifest | Check letter case, relative paths and that the manifest is at the package root. |
| Package fails to compile | Use module scripts, packaged browser-compatible imports and supported bundled libraries. Remove remote imports and Node built-ins. |
| State vanished on another computer | Local storage does not sync. Use project files or the project database for data that must follow the workspace. |
| Chart is unavailable | Install and enable the plugin that owns its board type. |
board.set is refused |
Check editable from board.get(); a read-only embed cannot save board state. |
| Website controls stopped working | Provider websites change. Open the native website controls and complete the action manually. |
REFERENCE / 13
Version and source
This guide targets Daevu 2.0.5 / plugin API 1, checked on 23 October 2026. Examples and limits were checked against the local app's manifest validator, packaging code, plugin host and SDK bridge.
For implementation details, see the plugin guide, manifest validation, the SDK host and the package command. Treat these versioned sources as the authority when a later app release changes the contract.
