23. A glossary
The terms a developer meets in this guide and the packages, each in a sentence or two, with where the spec defines it and the chapter that teaches it. The spec's own list is its section 1.1; where a term here is one of those, this is the same meaning, said for building.
| Term | What it is | Spec | Taught in |
|---|---|---|---|
| Ambient pack | A pack every document gets the names of without importing it, at the lowest priority, so a document's own names win. Its names aren't portable: another host doesn't have them (W113 when the host asks). | §6.3 | 9, 21 |
| Binding | How the host contract maps to one framework: plain JavaScript, React or Svelte 5. @compmd/render has react and svelte; a plain module's default export is mount itself. |
§7.6 | 15 |
| Built module | A component file in a pack that is a built ES module, .js, one file with its libraries bundled in but its runtime and its peerDependencies. The sandbox loads it by its place, checked against its file's hash. |
§6.4 | 17, 18 |
| Bundle | Everything a host builds before anyone reads, in one folder: the frames under a hash of their files (frames/<hash>/), each pack's files with its source components compiled beside them (packs/<name>@<version>/), and manifest.json, its one description. @compmd/vite writes it, and buildBundle for a host without Vite; compmd-host reads it in Rust. |
11, 18, 19 | |
| Code renderer | A leaf whose signature renders a language, so it draws that language's code blocks, the block's text as its code param, and is still a leaf. |
§7.7 | 16 |
| Configuration | compmd.config.json, or package.json's compmd key: the app's policy for packs, which only the app sets, never a document or a pack. |
9, 21 | |
| Diagnostic | What the processor, or a renderer, found wrong, by a code from the spec's catalogue: F… an error, W… a warning, with where it is and the stage that found it. |
§10 | 4, 22 |
| Expanded tree | What the processor gives a renderer: the document's content only, every definition, if, each, value and interpolation replaced by what it gives, for one render context. It names host components but holds no code. |
§12.3 | 3, 7 |
| Fallback | What shows where a component can't render: a leaf's or inline component's text in […], a container's slots as plain Markdown, a rendered code block's code. A component gets it as fallback, as its text alternative. |
§4.5 | 8 |
| Frame documents | strict.html and permissive.html, with the frame runtime and the runtimes' modules: the bundle's frames/<hash>/, which a host serves for the sandbox's frames with the serving contract's headers. The bundle's build writes them, and buildFrames for a host that builds its frames itself. |
11, 18 | |
| Frame mode | The sandbox's default: the whole page in one strict frame, for documents from anyone. Permissive and trusted components show their fallbacks there. | 3, 11 | |
| Host | The application whose processor renders documents: it gives the processor everything (files, packs, data, the time), sets each pack's trust in its configuration, and serves the frames. | §1.1 | 3 |
| Host component | A component defined in a host language (js, ts, jsx, tsx, svelte), which a renderer runs. The processor gives each with its code, or its built module's place, and its trust (HostComponent, OpenDocument.components). |
§7.1 | 10 |
| Host contract | How a host component is run, whatever its framework: mount(target, context), with its params, slots, set, fallback, heading level, colour scheme, fail and maybe host, then update and destroy. |
§7.4 | 13, 14 |
| Host mode | The sandbox's other mode, page: "host": the page in the app's page, trusted components inline, every other component in a frame of its own level. For an app with components of its own, or permissive packs. |
10, 11 | |
host |
What the app gives the components of permissive packs it lists with "host": true: calls to its own data or actions. A document can't ask for it. |
§7.4 | 10 |
| Input | A typed value the reader changes, declared in a document's md.inputs, read as md.input.<name>. The host keeps its values and gives them in the request; the page tells the host with set. |
§8.7 | 6 |
| Integrity | The hash a registry publishes for a version's tarball, sha512-…. A document that pins an exact version may write it as its import's integrity, and gets the pack only if the release's matches (F035). Different from a built module's file hash, sha384-…, which the sandbox checks. |
§6.1 | 9, 17 |
| Library definition | What the frames provide component code: the runtimes and the libraries the host offers, each with its version and import names. The bundle's build puts its names and versions in the manifest's policy, the processor's policy.runtimes and policy.libraries; buildFrames gives it to a host that builds its frames itself. |
§7.6 | 18 |
| Library pack | A package that holds one library several packs share, such as three.js, so a sandbox loads one copy: "compmd": { "library": "dist/index.js" }, no document. A pack names it in peerDependencies. |
the companion, §5 | 17 |
| Observer | What the sandbox gives developer tools when the app's page asks, with view.observe: the view's frames, the messages between them, the components mounted and their fallbacks. Nothing a document or a frame sends turns it on. |
12 | |
| Origin | Two things. On an expanded node, when the request asks for origins: the range of the document that made it, with its occurrence, so an editor can keep what it rendered through an edit. And the bundle's origin: where a host serves the bundle, compmd/ under a web app, or a desktop app's own scheme (compmd://localhost), which the app's plugin gives the page as globalThis.__COMPMD__.origin and createSandbox reads. |
§12.3 | 5, 18, 19 |
| Pack | A document, or a published package, that exports components. Published, it is an npm package whose package.json names its document in a compmd field. |
§6 | 9, 13 |
| Place | Where a built module is in its pack: the pack, its version and the file's path (@kit/charts@2.1.0/dist/chart.js). The processor names a module by it, and the sandbox's modules turns it into a URL and a hash, or the file. |
§6.4 | 18 |
| Policy | The processor's form of the configuration, the request's policy: each listed pack's trust, imports, deny, refused, and the runtimes and libraries the host has. policyOf makes it. |
§6.4 | 18 |
| Proxy | The app's own route to its registries, compmd/registry/, so a page fetches packs without telling a registry who reads what. registryProxy is one. |
the companion, §4 | 9, 18 |
| Registry | A server that speaks npm's registry protocol: npm's own, a mirror, a private one, or a proxy. Only the host's configuration names one. | the companion, §1 | 9 |
| Registry pack | A pack published to a registry as an npm package, with a scoped name, the compmd field and the keyword compmd-pack. |
the companion, §2 | 17 |
| Render context | What a render depends on besides the document, its imports and its data: the time, the time zone and the inputs' values. The same context gives the same expanded tree. | §8.5 | 4 |
| Request | Everything the processor needs for one document, since it does no I/O: path and files, packs, ambient, policy, allowedOrigins, remote and host data, now, tz, inputs, origins. virtual:compmd's request holds the app's part. |
3, 4 | |
| Runtime | A binding's framework at a major version, react@19 or svelte@5, which the frames provide, one copy for every component, so component code imports it and never bundles it. |
§7.6 | 15 |
| Sandbox | Where a component's code runs when it isn't trusted: a frame that sees only its contract, with no network unless its pack is permissive. @compmd/sandbox makes them. |
§15 | 8, 11 |
| Serving contract | How every host serves the bundle: only the frames of its hash and the files of its packs, each with the same five headers (CONTRACT_HEADERS: Content-Security-Policy: sandbox allow-scripts, Access-Control-Allow-Origin: *, Access-Control-Expose-Headers: *, X-Content-Type-Options: nosniff, an immutable Cache-Control), and anything else a 404 a page can read. respond in compmd-host is it in Rust; runCheck checks a host keeps it. |
11, 18, 20 | |
| Signature | A component's params, with their types and defaults, and its slots. A host component's is a signature fence, compmd component=<name> signature, which every exported one needs (F029). |
§7.3 | 14 |
| Slot | A named part of a container's body, :: #name; the content before the first is the default slot. The renderer renders slots and gives them to the component. A template slot is rendered once per element of an array param. |
§4.2, §7.5 | 14 |
| Splice | What an edit changed in the expanded tree: top-level nodes from to to replaced by nodes, and how far the rest moved. An editor's preview applies it instead of the whole tree. |
5 | |
| Stage | One step of processing: parse, resolve, validate, load, evaluate (expand), then render. Each needs only what it lists, and finds its own diagnostics. | §11 | 3, 20 |
| Trust level | How far a pack's code is trusted, which the host's configuration sets and a document can never raise. Strict, the default: a sandbox with no network. Permissive: a sandbox of its own, with the network to the origins listed, and host if given. Trusted: the app's own code, in its page, for a folder of the app only. |
§15 | 8 |
virtual:compmd |
The module @compmd/vite gives the app: request for the processor, sandbox for createSandbox (the bundle's frames and modules, and its origin in a web app), and registry for resolvePacks. A host without the plugin makes the same from the bundle's manifest. |
2, 18 |
Next: back to the contents.