CompMD Developer's Guide. Written for the @compmd packages at 0.5.0, and following them as they change. Download the book as PDF

22. 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, 20
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
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, 20
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, 21
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, which a host serves (under compmd/) for the sandbox's frames, with Access-Control-Allow-Origin: * and, for the documents, Content-Security-Policy: sandbox allow-scripts. buildFrames writes them. 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. buildFrames gives it; its names and versions are the processor's policy.runtimes and policy.libraries. §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 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. §12.3 5
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
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, 19
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, and registry for resolvePacks. A host without the plugin makes the same by hand. 2, 18

Next: back to the contents.