​

Render Runtime Contract

​

Short Version

• Your plugin class runs in the plugin backend/runtime.
• Your plugin UI runs in a sandboxed iframe host managed by FDO.
• render() returns UI source for the FDO iframe pipeline.
• That output is not the same thing as raw innerHTML inserted directly into the host page.
• SDK DOM helpers generate raw HTML strings intended for that iframe-hosted render pipeline.

​

Two Runtimes

​

Backend Runtime

• init()
• handler registration
• storage access
• logging
• filesystem or process-side work
• error handling outside the iframe UI

​

Iframe UI Runtime

• browser DOM access
• window.createBackendReq(...)
• window.waitForElement(...)
• window.executeInjectedScript(...)
• window.addGlobalEventListener(...)
• window.removeGlobalEventListener(...)
• window.applyClassToSelector(...)
• injected UI libraries such as goober, ACE, Highlight.js, Notyf, FontAwesome, and Split Grid

​

What render() Really Means

1. requests plugin render output
2. prepares and validates the payload
3. wraps the render content for the iframe host
4. transforms it for the plugin page runtime
5. mounts it inside a React-hosted sandboxed iframe

• “plain HTML string” is an incomplete mental model
• “React component source” is also not quite right from the plugin author’s perspective
• the safest description is: JSX-like UI strings for the FDO iframe host pipeline

• helper APIs may accept compatibility aliases like className, htmlFor, and readOnly
• emitted helper output should still use raw HTML attribute names like class, for, and readonly
• when both forms are supplied, the native HTML form wins explicitly so output does not depend on object key iteration order

​

JSX-Compatibility Rules For render()

• raw void tags such as <br> instead of <br />
• raw <style> blocks inside render()
• literal JavaScript/object syntax inside <code> blocks without escaping JSX-sensitive characters
• other raw text that contains unescaped { / } in JSX-visible positions
• display-only strings that match host fail-fast guard patterns, for example sensitive runtime tokens such as process. or other blocked runtime-access markers
• raw JSON or object-literal content embedded directly into JSX-visible markup, especially inside <pre> blocks

• prefer JSX-safe void tags such as <br />
• avoid inline <style> blocks in render(); prefer DOM helpers plus renderHTML(...), host CSS classes, or inline element styles when needed
• if you show code samples in <code> or <pre> blocks, escape literal braces as { and }
• avoid embedding raw guard-sensitive runtime tokens in display text when a plain-language description is enough
• if you want to show structured JSON results, render a safe placeholder first and populate the result panel after iframe initialization through backend/UI calls
• do not assume “browser HTML parsing would accept this” means the FDO host transform will accept it

render(): string {
  return `
    <div>
      <strong>Status</strong><br />
      Ready
    </div>
  `;
}

render(): string {
  return `
    <pre><code class="language-javascript">function greet(name) &#123;
  return "Hello";
&#125;</code></pre>
  `;
}

render(): string {
  return `
    <style>
      .demo { padding: 20px; }
    </style>
    <pre><code>function greet(name) { return "Hello"; }</code></pre>
  `;
}

render(): string {
  return `
    <p>Declared capabilities: broad host tool execution plus the narrow Docker CLI scope.</p>
  `;
}

render(): string {
  return `
    <p><code>["system.process.exec", "system.process.scope.docker-cli"]</code></p>
  `;
}

render(): string {
  return `
    <pre id="result-box">Snapshot will load after initialization...</pre>
  `;
}

renderOnLoad(): string {
  return `
    (() => {
      const output = document.getElementById("result-box");
      // fetch data through UI_MESSAGE and then:
      output.textContent = JSON.stringify({ ok: true }, null, 2);
    })();
  `;
}

render(): string {
  return `
    <pre>{ "ok": true }</pre>
  `;
}

• render() returns the plugin’s UI string
• renderOnLoad() optionally returns:
  • source string
  • function (() => void)
  • defineRenderOnLoad(...) module
• serialization for the host transport is handled by explicit SDK methods rather than by mutating plugin lifecycle methods at construction time

​

Supported Lifecycle Contract

• init() performs plugin setup
• render() synchronously returns a string
• renderOnLoad() optionally synchronously returns a string, function, or defineRenderOnLoad(...) module
• serializeRender() and serializeRenderOnLoad() are transport helpers used by the SDK/host boundary

import { defineRenderOnLoad } from "@anikitenko/fdo-sdk";

renderOnLoad() {
  return defineRenderOnLoad(() => {
    const button = document.getElementById("run");
    button?.addEventListener("click", async () => {
      await window.createBackendReq("UI_MESSAGE", {
        handler: "plugin.run",
        content: {},
      });
    });
  }, {
    language: "typescript",
    description: "typed on-load handler",
  });
}

import { defineRenderOnLoadActions } from "@anikitenko/fdo-sdk";

const onLoadModule = defineRenderOnLoadActions({
  setup: () => {
    // optional setup hook before listeners attach
  },
  handlers: {
    runInspect: async () => {
      await window.createBackendReq("UI_MESSAGE", {
        handler: "plugin.inspect",
        content: {},
      });
    },
  },
  bindings: [
    { selector: "#inspect-button", event: "click", handler: "runInspect", preventDefault: true },
  ],
  language: "typescript",
  strict: true,
});

• listRenderOnLoadTemplates(...)
• getRenderOnLoadTemplate(id)

(() => {
  const marker = { invoked: false };
  const run = () => {
    marker.invoked = true;
  };
  run();
  if (!marker.invoked) {
    throw new Error("runtime marker was not invoked");
  }
})();

• init()
• render()
• optionally renderOnLoad()

​

Plugin Metadata Contract

• metadata is part of the host-facing contract, not just plugin-internal data.
• metadata.icon must be a valid BlueprintJS v6 icon name because the FDO host uses BlueprintJS v6.
• Keep metadata values deterministic and serializable.

​

What The SDK DOM Helpers Do

• helpers for the FDO UI render pipeline
• not proof that the host inserts raw HTML directly
• not proof that every browser/runtime feature is available everywhere

• helper-composed styled output: return helper.renderHTML(content)
• plain manual JSX-like markup with no helper-generated styling: return the markup directly

​

Trusted Markup vs Safe Text

• trusted markup composition: generic helpers like DOM.createElement(...) accept children as already-formed JSX-like fragments
• safe text composition: DOMText APIs escape JSX-sensitive characters for text-node contexts

• use DOMText.createText(...) and related DOMText methods for user-provided or untrusted text
• use raw children in generic DOM helpers only for trusted plugin-authored markup fragments

​

Runtime Safety Rules

​

Safe Backend Assumptions

• registering handlers in init()
• reading or writing store data
• logging and diagnostics
• backend error handling

​

Safe Iframe/UI Assumptions

• DOM interaction
• event listeners on window or document
• window.createBackendReq(...)
• goober styling used by rendered UI behavior
• UI-only injected libraries

​

Third-Party Imports In UI Runtime

• Do not assume arbitrary third-party import/require works in iframe UI code.
• Use only host-injected globals and helpers documented by FDO/SDK.
• If a new UI library is needed, it must be added by FDO host injection policy first, then documented.

​

Unsafe Assumption To Avoid

• plugin constructors
• class field initializers
• backend/bootstrap paths
• backend render-error fallbacks
• non-UI utility modules unless the current workspace explicitly proves that runtime

​

Error Handling Guidance

• keep it runtime-safe
• avoid depending on iframe-only helpers unless you know the fallback runs in the iframe UI path
• prefer simple fallback UI over brittle styling dependencies

​

Practical Authoring Guidance

• Use init() for setup and handler registration.
• Use render() to provide UI for the iframe host pipeline.
• Use injected window.* helpers only from UI-facing code paths.
• Use SDK DOM helpers when they match the existing workspace style.
• When DOM helpers generate styled output, call renderHTML(...) on the final helper markup before returning from render().
• Do not move UI-runtime assumptions into backend/bootstrap code.

​

Guidance For AI Tools

• do not describe the plugin UI as only “plain HTML”
• do not claim unrestricted React/Electron/Node access from UI code
• preserve the current workspace’s render convention
• distinguish backend runtime from iframe runtime explicitly