Making plugins

A plugin is a .f8 file: a ZIP archive containing a manifest.json and a JavaScript entry file. The entry runs inside a hidden iframe with sandbox="allow-scripts" and no allow-same-origin, so it loads at an opaque origin with no cookies, no localStorage, no parent DOM, and no access to your cloud tokens. Everything it can do arrives through one global object, f8xt, which forwards each call to the host over postMessage. The host checks a permission allowlist before any call runs. Start a new one from the plugin template generator.

The manifest

manifest.json describes the plugin. The id is a reverse-DNS package identifier; updates are matched on it, so keep it stable across versions.

{
  "id": "com.example.my-plugin",
  "name": "My Plugin",
  "version": "1.0.0",
  "author": "You",
  "description": "What it does.",
  "entry": "main.js",
  "permissions": ["notes:read", "ui:add"],
  "minAppVersion": "0.2.0",
  "settings": [
    { "key": "greeting", "type": "text", "label": "Greeting", "default": "hi" }
  ]
}

settings is optional. Each entry renders a native control under your plugin in the settings dropdown. Supported types are text, toggle, number, and select (with an options array). Read values with f8xt.settings.get(key) and write them with f8xt.settings.set(key, value). When a user edits a setting, the plugin restarts, so read your settings at startup.

Permissions

Request only what you need. Each permission you list is shown to the user at install; if a later version adds new permissions, the user must re-approve before updating. Network access is separate from reading notes, so a plugin cannot both read your notes and send them somewhere without you seeing both grants.

dom:unsandboxed and administrator let a plugin reach outside the sandbox. dom:unsandboxed skips HTML sanitization in f8xt.ui.html; the page CSP still blocks script execution in that markup. administrator short-circuits the permission check on every method. Only grant them to plugins you trust.

How a call reaches the host

Each f8xt.* method is a thin wrapper around postMessage. It assigns a request id, stores a resolver, posts { t: "req", id, method, args } to the parent window, and returns a Promise. The host looks up the method in METHOD_PERMISSIONS. If the entry is undefined, it rejects with UNKNOWN_METHOD. If the entry is a permission string and the plugin lacks it (and is not administrator), it rejects with PERMISSION_DENIED. Otherwise it runs the handler and posts the result back. Calls that need no result still return a Promise so you can await confirmation that they ran. Host-to-plugin calls (commands firing, editor typing events, cloud provider operations) use the same envelope in the other direction and time out after 10 seconds.

// Rejects with an Error whose .code is 'PERMISSION_DENIED'
// if the manifest did not list notes:read.
const note = await f8xt.notes.current();

API reference

The 24 methods below are every call a plugin can make. Grouped by namespace. Each entry lists the signature, the permission it needs, what it returns, and the one behavior worth knowing. none means no permission is checked; the method is still sandboxed and rate-limited by the host.

f8xt.plugin

none. A string, not a call. The host passes it in at boot; it is the id from your manifest. Useful for namespacing keys in storage or logging.

f8xt.notes

Read and mutate the note store. path arguments are forward-slash paths into the active storage engine (the same paths the sidebar shows). Writes go to disk through the storage bridge; if the path matches the currently open note, the editor content updates in place.

f8xt.editor

All three methods act on whichever editor holds focus: the CodeMirror live-preview or the raw textarea. They no-op and return null or false when no editor is active. Offsets are absolute character offsets into the document, not line/column pairs.

f8xt.commands

The command palette (Ctrl+P) is populated by plugins and the app alike. Registered commands survive until the plugin stops.

f8xt.ui

f8xt.css

Injected stylesheets are scoped to a <style data-f8xt-plugin="groupId"> element in the document head. One sheet per plugin group; a second inject replaces the first.

f8xt.settings and f8xt.storage

Two key-value stores, both permission-free because they are scoped to your plugin. settings is the user-facing one: its keys are declared in the manifest and edited through the settings dropdown. storage is the private one: arbitrary keys your plugin uses for caches, tokens, last-seen timestamps. Both live in the plugin's settings record on disk; storage nests under a __kv sub-object so it never collides with declared settings.

f8xt.net

f8xt.cloud

A plugin with cloud:provider can register a storage backend the app treats as a first-class cloud option. Once the user picks it from the provider list, every note read and write routes back into the plugin through provider.* calls. Credentials stay inside the plugin's storage; the app's OAuth tokens are in a separate store the plugin cannot reach.

engine = {
  listFiles(path):            Promise<CloudFile[]>,   // { name, path, modified, size? }
  readFile(path):             Promise<string>,         // file body as text
  writeFile(path, content):   Promise<void>,
  deleteFile(path):           Promise<void>,
  createFolder(path):         Promise<void>,
  checkStorageQuota():        Promise<{ used, limit }> // bytes
}

Two plugins, end to end

A keyword expander that turns _now into a timestamp as you type, and a command that appends to the current note.

// manifest.json
{
  "id": "com.example.expander",
  "name": "Expander",
  "version": "1.0.0",
  "entry": "main.js",
  "permissions": ["notes:read", "notes:write"]
}

// main.js
f8xt.editor.onType((e) => {
  if (e.word === '_now') {
    f8xt.editor.replaceRange(e.from, e.to,
      new Date().toISOString().slice(0, 10));
  }
});

// manifest.json
{
  "id": "com.example.stamp",
  "name": "Stamp",
  "version": "1.0.0",
  "entry": "main.js",
  "permissions": ["notes:read", "notes:write", "ui:add"]
}

// main.js
f8xt.commands.register('stamp', 'Add timestamp', async () => {
  const note = await f8xt.notes.current();
  if (!note) { f8xt.ui.toast('open a note first', { variant: 'destructive' }); return; }
  await f8xt.notes.write(note.path, note.content + '\n\n' + new Date().toISOString());
  f8xt.ui.toast('stamped');
});

Packaging

A .f8 is a plain ZIP with manifest.json and your entry file at the top level. Optional siblings are styles.css (injected automatically on start) and icon.png (shown in the settings dropdown). The template generator builds a valid, ready-to-edit .f8 from a short form, or you can zip the files yourself and rename the archive to .f8.