The component contract

Version 0.2. This document is the whole idea: if you can write a file that follows it, any host that implements it can run your component, and any model that reads SKILL.md can write one.

1. What a component is

A component is one self-contained file that draws one piece of UI into a box it is given, and cleans up after itself when the box goes away.

There are two kinds:

A module component looks like this:

export const meta = {
  name: "Clock",
  version: "1.0.0",
  description: "Current time, updating every second.",
  settings: { seconds: true },
};

export default function clock(ctx) {
  const time = ctx.h("div", { class: "clock-time" });
  ctx.host.append(time);
  ctx.css(`.clock-time { font-size: 2em; color: var(--text-normal); }`);

  const tick = () => {
    time.textContent = new Date().toLocaleTimeString([], {
      timeStyle: ctx.settings.seconds ? "medium" : "short",
    });
  };
  tick();
  ctx.interval(tick, 1000);
}

That is the entire format: an optional meta export and a default-exported function that receives ctx. The function may be async. It may return a cleanup function, although registering cleanup through ctx is preferred.

A component file:

• has no imports. Everything it needs comes from ctx or the platform (DOM, Intl, Math, Date, crypto.randomUUID, canvas).
• uses no globals: not window.* state, not document.body, not localStorage, not app directly.
• keeps data out of code. Anything a user might change goes in meta.settings and is read from ctx.settings.

2. meta

All fields are optional. Hosts show name and description wherever a component is picked or trusted.

3. The ctx object

Every member is optional for a host to enhance, but every member listed here must exist, so a component never has to feature-test.

Drawing

Theme

In CSS, prefer the host's own variables directly (var(--text-normal), var(--background-secondary), var(--interactive-accent)). They update with no code at all. ctx.palette is for the places CSS cannot reach, mainly canvas.

Lifecycle

Everything registered here is undone automatically on teardown, in reverse order.

Data

A Note is:

{
  path: string;          // "Journal/2026-03-04.md"
  name: string;          // "2026-03-04"
  folder: string;        // "Journal"
  tags: string[];        // ["journal", "health"], no leading "#"
  frontmatter: object;   // plain values, dates left as strings
  created: Date;
  modified: Date;
  day: string | null;    // "2026-03-04" when the name starts with a date, else null
  size: number;          // bytes
}

Plain arrays and Date objects, on purpose. No proxy arrays, no library date types.

Host

4. Lifecycle

1. Mount. The host creates an empty ctx.host, builds ctx, and calls the default export once.
2. Re-render. Some hosts re-run components when data changes, and a component cannot know when. DataviewJS, for example, re-runs every visible block a few seconds after any note in the vault changes, not only the note the block is in, and it does so without unloading the previous run. Whatever the host's runtime does, the host must make a re-render a full teardown followed by a fresh mount with a new ctx.host. That is the host's job, so a component never needs to detect a re-render. ctx.state carries over; nothing else does.
3. Teardown. Everything registered through ctx is undone, then any function the component returned is called.

The one test every component must pass: mounted twice on the same page and re-rendered in the middle of an animation, nothing leaks and nothing collides. No timers left running, no listeners left behind, no element ids shared between the two copies, no style bleeding from one into the other.

5. html components

An html component is a complete HTML document (or fragment) run inside an iframe with sandbox="allow-scripts" and a content security policy that blocks all network access. It cannot see the vault, the host page, cookies or storage.

Before the file runs, the host defines window.cf:

The host also sets the same CSS variables used in the host application (--text-normal, --background-primary, --interactive-accent and so on) on the iframe's root element, keeps them in sync, and sizes the iframe to its content.

This is the kind to use for code from a model or a person you do not trust, and it is how a pasted AI-generated HTML artifact becomes a component.

An html component is its own document, so the rules that protect a shared page do not apply inside it: ids and px are fine. The rules about the theme do: use the CSS variables, so it looks right in both themes. And it cannot use the network.

6. Trust

A module component runs with the same privileges as the host page. In Obsidian that means it can read and write any file in the vault. meta.needs states intent; it does not limit anything. The rules below exist because of that.

Hosts must:

1. Never run a component the user has not explicitly mounted.
2. Make the source one step away from the rendered component.
3. Run html components sandboxed as described in section 5.

Hosts should:

4. Support pinning: the user records a hash of the file they reviewed, and the host refuses to run it if the file changes, showing the new hash and the source instead. This matters most in synced vaults, where a file can change without you touching it.
5. Show meta.needs and a plain "runs JavaScript with access to your vault" notice for module components.

Users should read a component before mounting it, or have an AI read it for them with a prompt such as: "Review this component for anything that reads or writes files, touches the network, runs shell commands, or uses globals. List every such line."

7. What a host provides

A host is anything that can give a component a box and a ctx: a DataviewJS block, a web page, an Obsidian plugin with a layout grid. To conform to contract 0.2, a host:

• implements every member in section 3 (members it cannot support return empty values rather than being absent),
• follows the lifecycle in section 4,
• scopes ctx.css to the host element,
• follows the trust rules in section 6,
• supports html components as described in section 5, or refuses them clearly.

Two hosts exist so far, both in cf.js: a DataviewJS host for Obsidian (mount), and the generic run and runHtml that the article page uses to run the examples.

8. File conventions

• One component per file. Name the file after the component: clock.js, heatmap.js.
• A folder is fine when a component has an example or a README beside it: clock/clock.js.
• Keep components small. Past about 300 lines, split the idea into two components.
• Settings that hold lists or records are better kept in the host note's frontmatter and passed in, so the data lives with your notes and not in code.

Changes

• 0.2 (2026-10-15). Added ctx.query.url for images and other files, and em in ctx.onResize. Stated that the host's height comes from its content, and that resizing the host inside ctx.onResize loops. Said which rules apply inside html components. A 0.1 component runs unchanged on a 0.2 host. These changes came from having a model write fourteen components from this document alone: it got stuck on images, two components grew without limit or redrew forever, and it had to read cf.js to learn what this page left out.