# Wrengle local plugin authoring instructions for LLMs

Use this text when a user asks you to create a Wrengle plugin.

Wrengle plugin support is currently a local developer-preview feature. The
safest default for non-technical users is a view-only plugin: a local folder
with a plugin.toml manifest and one self-contained HTML file rendered by
Wrengle in a sandboxed iframe tab.

Local plugin code remains trusted local code. Do not imply marketplace
availability, remote installation, or public stability. Capability declarations
are not grants; grants are local to the user's app install. View-only plugin
JavaScript can make direct network requests, and those direct requests are not
controlled by the httpHosts capability. httpHosts applies only to Wrengle
host-bridge HTTP used by WASM action plugins.

Do not design or describe marketplace distribution, remote installation,
process plugins, terminal access, arbitrary shell commands, arbitrary local file
access, or direct access to Wrengle internals. Those are not available in the
current local plugin surface.

Plugin Builder currently supports static custom views and offline feature apps
with plugin-scoped JSON state. Builder-created apps are offline and cannot read
or write Wrengle workspace content. Workspace-aware generated plugins are future
work.

Builder-created offline apps can use `window.wrengle.state.get`,
`window.wrengle.state.set`, and `window.wrengle.state.delete` for
plugin-scoped local JSON state. Builder drafts declare expected state keys and
generated code is checked against that draft contract before Apply. Installed
app state remains scoped to the plugin. They do not receive `state.list` or
`state.clear`; reset is a Wrengle-owned action from Plugin Builder.
Resetting app state removes the app's local saved data only; it does not remove
plugin files, prompt history, or conversations. Deleting a Builder-created app
removes its managed plugin files, approved prompt history, rollback points,
linked Builder conversations, and installed app state.
For stateful edits, edit-preview state is temporary; preview interactions test
the draft only, and applying an edit preserves installed app state.

In the app, Plugin Builder is a minimal chat-and-preview workspace. Chat remains
visible beside the generated preview, build progress appears as concise chat
status cards, and installed-plugin lifecycle actions live in the project header
instead of a permanent controls rail. Open and History stay visible in the
header; edit, Reset app state for stateful apps, enable or disable, and delete
stay in the actions menu.

For supported static custom-view create prompts with clear static/sample/mock UI intent, Plugin Builder may recover from malformed provider JSON, invalid draft specs, or policy-blocked static HTML by discarding the provider output and synthesizing a safe local static starter draft. The recovered draft still runs local checks and smoke preview before install. Recovery does not apply to unsupported prompts, network/API/remote-service prompts, live/real/actual/production data requests, workspace data prompts, edit drafts, provider connection/auth/rate-limit failures, or local write, metadata, or fingerprint failures.

Generated Builder views have no network, secrets, shell, filesystem, or Tauri
IPC access. Plugin Builder creates local offline custom views and stateful
offline feature apps. It does not create networked plugins, workspace readers,
workspace writers, marketplace listings, or generated WASM tools in this
release.

Default output
==============

Create a view-only plugin with this folder layout:

my-plugin/
  plugin.toml
  ui/
    index.html

The final answer to the user must include:

1. The folder tree.
2. The full contents of plugin.toml.
3. The full contents of ui/index.html.
4. Short load and test steps for Wrengle Settings -> Plugins.

If the user asks for a WASM action plugin, do not generate it from this file
alone. Ask the user to provide Wrengle's WASM action plugin documentation first.

plugin.toml requirements
========================

For a view-only plugin, plugin.toml must include top-level metadata and at least
one [[views]] block.

Use this shape:

id = "plugin.my-tool"
name = "My Tool"
version = "0.1.0"
schema_version = 1
description = "Short description of what the plugin does."

[[views]]
id = "plugin.my-tool.view"
label = "My Tool"
entry = "ui/index.html"

If the plugin should receive selected note text, add these fields to the same
[[views]] block:

accepts_selection = true
selection_label = "Send to My Tool"

Rules:

- The top-level plugin id must start with plugin.
- The rest of the top-level id should be lowercase ASCII. A safe pattern is
  plugin.<short-name>.
- The view id must start with the plugin id plus a dot.
- Use lowercase ASCII ids with letters, digits, dots, and hyphens only.
- Do not use consecutive dots in ids.
- entry must be relative to the plugin folder.
- entry must point to an HTML file that exists in the generated folder.
- Use accepts_selection = true only when the view should receive selected note
  text from the editor Actions menu.
- Add a clear selection_label when accepts_selection = true.
- Do not include a [runtime] block for a view-only plugin.
- Do not include plugin.wasm for a view-only plugin.
- Do not require Rust, WASM, Node, npm, a bundler, or a build step for the
  default view-only plugin.

ui/index.html requirements
==========================

The entry file must be one self-contained HTML file.

Rules:

- Inline all CSS and JavaScript.
- Do not use external script files.
- Do not use external stylesheet files.
- Do not use src attributes for local companion JavaScript files.
- Keep the file under 5 MB.
- Use Wrengle theme CSS variables for colors, borders, shadows, and surfaces.
- Do not define an independent hard-coded light or dark color palette.
- Support active theme updates by handling wrengle:init and wrengle:theme.
- Build a complete, usable interface for the user's requested plugin idea.
- If selected note text is supported, handle wrengle:selection messages.
- Do not use network requests by default.
- If the user explicitly asks for network requests, list the exact destination
  hosts, explain what data is sent, and make each send action user-triggered.
- Never send selected note text or pasted user content to a remote service
  automatically.
- Do not claim httpHosts grants control direct fetch or XMLHttpRequest calls
  from view JavaScript.

Required bridge protocol
========================

Wrengle sends messages to the view over window.postMessage. The view must send
wrengle:ready after it is ready to receive messages.

Include this bridge inside a <script> element in ui/index.html and adapt the
wrengle:selection branch to the user's plugin:

window.addEventListener("message", (event) => {
  if (event.source !== window.parent) return;
  const msg = event.data;
  if (!msg || typeof msg !== "object") return;

  if (msg.type === "wrengle:init" || msg.type === "wrengle:theme") {
    document.documentElement.dataset.theme =
      msg.theme === "dark" ? "dark" : "light";

    if (msg.themeTokens && typeof msg.themeTokens === "object") {
      for (const [name, value] of Object.entries(msg.themeTokens)) {
        if (/^--[A-Za-z0-9_-]+$/.test(name) && typeof value === "string" && value.length > 0) {
          document.documentElement.style.setProperty(name, value);
        }
      }
    }
  } else if (msg.type === "wrengle:selection" && typeof msg.text === "string") {
    // Use msg.text as the selected note text.
  }
});

parent.postMessage({ type: "wrengle:ready" }, "*");

The view should respond to these host messages:

- wrengle:init with { theme: "light" | "dark", themeTokens: Record<string, string> }
- wrengle:theme with { theme: "light" | "dark", themeTokens: Record<string, string> }
- wrengle:selection with { text: string }

Builder-created offline feature app drafts declare expected plugin-scoped JSON
state keys, and generated code is checked against that draft contract before
Apply. Manual local plugin views cannot use these generated helpers yet.
Generated offline feature apps should use the injected helpers instead of direct
parent-window access: `window.wrengle.state.get`, `window.wrengle.state.set`,
and `window.wrengle.state.delete`. Installed app state remains scoped to the
plugin. Builder-created apps do not receive dashboard, note, block, workflow,
file, settings, network, secret, shell, generated WASM, `state.list`, or
`state.clear` helpers. Resetting state is owned by Wrengle from Plugin Builder.

Wrengle injects active CSS variables before first paint. Use variables such as
var(--background), var(--foreground), var(--card), var(--card-foreground),
var(--muted), var(--muted-foreground), var(--border), var(--primary), and
var(--primary-foreground) in the view CSS.

Loading and testing instructions to include
===========================================

Tell the user to:

1. Create the plugin folder and files exactly as shown.
2. Open Wrengle.
3. Open Settings -> Plugins.
4. Add the absolute path to the plugin folder under Developer plugins.
5. Click Reload.
6. Confirm the plugin appears under Loaded plugins.
7. Open the command palette with Cmd+K on macOS or Ctrl+K on other platforms.
8. Run Open <label>, where <label> is the view label in plugin.toml.

If accepts_selection = true, also tell the user to:

1. Open a note.
2. Select text.
3. Open the floating toolbar's Actions menu.
4. Choose the plugin's selection_label.
5. Confirm the selected text appears in the plugin view.

Troubleshooting guidance
========================

If the plugin does not load, tell the user to open Settings -> Plugins ->
Diagnostics and paste the diagnostic back to you.

Common fixes:

- If the view is missing from the command palette, check that plugin.toml has a
  valid [[views]] block and that the user clicked Reload.
- If the tab is blank, check that entry = "ui/index.html" and the file exists.
- If the selection action is missing, check accepts_selection = true and
  selection_label.
- If the theme looks wrong, check that CSS uses Wrengle variables and that
  wrengle:init / wrengle:theme apply themeTokens.

Advanced note
=============

Wrengle also supports local WASM action plugins, but those need a WASM runtime
entry and a built plugin.wasm. This raw file is intentionally scoped to
view-only plugins. If the user needs a WASM action plugin, ask for Wrengle's
WASM action plugin documentation before generating files.