Glossary
The terms Sparkles coins, or uses in a narrower sense than usual. Shared vocabulary — the kind a capable engineer from outside the project already knows — is not repeated here; pages link it to its own authority instead.
Each entry is defined once, in docs/.vitepress/glossary.json, and every page that uses a term links to its anchor here. A library's own terms are also listed in the Terminology section of its specification. The rules for adding an entry are in Writing Specification Prose.
Shared terms
grapheme cluster
Also: grapheme, graphemes, grapheme clusters
The extended grapheme cluster of Unicode Standard Annex #29. It is not a shaping cluster and not a glyph: one grapheme can shape into several glyphs, and one ligature can cover several graphemes.
Regular type
Also: Regular
A type whose copy, assignment and equality behave as they do for int: a copy compares equal to its original, and changing one never affects the other. Sparkles requires it of events and identifiers so tests can compare and replay them; see local reasoning.
sans-I/O
A protocol or state-machine implementation that never reads, writes, sleeps or consults a clock. Its caller feeds it input and carries out the effects it requests, which makes the core deterministic and testable without sockets or timers. Writing Specification Docs asks for this separation wherever the domain permits.
sparkles:base
generational handle
Also: generational id, generational index
A slot index paired with the slot's generation at issue time. Removing the occupant advances the generation, so every handle issued before the removal stops resolving. Sparkles' form is sparkles.base.pool's Handle; see its specification.
grid cell
Also: grid cells
The unit of terminal cell text. A grapheme occupies a whole number of grid cells under the active width profile, and cells never become pixels implicitly. The UI toolkit's own layout unit is the cell.
width profile
Also: width profiles
sparkles:base measures, fits, wraps and hit-tests cell text under exactly one width profile. terminalKitty gives each grapheme cluster its leading scalar's width; terminalUnclustered measures the same and differs only in what it emits, so a terminal without grapheme clustering still moves its cursor as layout assumed.
sparkles:core-cli
command graph
In sparkles:core-cli, the compile-time tree of a CLI's commands. A command's children are its nested @(Command) structs and the types it registers with mixin addSubCommand, in compiler member order, or the variants of an explicit @Subcommands field when it has one.
command group
In sparkles:core-cli, a command with at least one child in the command graph. Its parse-tree node holds the selected child's node, and selecting the group without naming a child is an incorrect call unless the group declares default handling.
sparkles:dman
command schema
In sparkles:dman, the struct-with-UDAs model of a command: the same declaration parses argv into a struct for dman's own CLI and renders a struct into argv for third-party tools such as git, jj and gh, whose output a return-type-driven collector then decodes. Its option attributes are aliases over the sparkles:wired policy vocabulary, so one schema governs both the command line and JSON.
sparkles:dmd-fmt
offset oracle
Also: start-offset oracle
The facts the formatter takes from DMD's parser: the start offsets of declarations, statements and expressions, collected in one parse-only pass and stored in sorted arrays. Layout consults them by binary search and never walks the tree; when the input does not parse, the oracle is empty and grouping falls back to bracket matching.
rewrite tier
The second of the formatter's two tiers. The layout tier changes only whitespace and is verified by token equality; a rewrite breaks token equality by construction, so each one ships with a verifier of its own and is opt-in, apart from trailing commas on broken lists. Rewrites whose safety needs resolved types are codemods, not part of this tier.
token spine
Also: spine
The sequence of tokens produced by DMD's lexer in its trivia configuration, which emits whitespace and comments as tokens, plus explicit entries for directives, a leading byte-order mark and the __EOF__ tail. Concatenating the entries reproduces the input byte for byte, so the formatter can never lose text the way a tree-based printer can.
sparkles:dmd-lsp
sample
The unit a Twoslash-style D analysis reads when no project is involved: one buffer whose only context is the runtime import path plus whatever its own // @import: and // @dflags: annotations declare. A file from a real project needs its dub project context instead, or every sibling import becomes an error.
target profile
Also: profile
A setting of a sparkles:dmd-lsp analysis that makes the DMD frontend see code as a particular compiler would: dmd (the default), ldc, or ldcDevice for the dcompute LDC's device compile of @compute shader modules. A -mdcompute-targets= flag selects ldcDevice on its own.
sparkles:docs
flow mode
Also: flow-mode emission
A third HTML mode of sparkles:ui: a designated subtree emits semantic elements with class-based styling and no fixed cell widths, and composes with cell-grid subtrees on one page. It is the path by which documentation chrome becomes toolkit widgets without giving up proportional prose.
link-driven discovery
The page-selection rule of sparkles:docs: a file gets a source-listing page only when the docs link to it, and a linked directory expands to its renderable subtree. The outcome, including every file skipped on purpose, is recorded in a manifest the site build reads instead of deciding again.
sparkles:dql
DQL path
Also: query path
A dotted address that names one field, getter or index reachable from a queried D type, such as pointer.logicalPosition.x. The alternatives of a SumType field are transparent: their fields join the path of the field that holds the union, so keyboard.action reads the keyboard alternative's action.
DQL schema
The table of every DQL path a D type offers, with each path's type, category and documentation, generated at compile time through the reflection kernel. The parser rejects a query naming a path outside it, and the help protocol prints it.
sparkles:event-horizon
ambient authority
In the capability VFS, the one function that resolves a path from the process root or current directory requires an AmbientAuthority token obtained from ambientAuthority(), so every place that exercises ambient authority can be found by searching for that name.
attenuation
Also: attenuate
In the capability VFS, attenuate!(R) yields a borrowed directory handle whose rights are R, and compiles only when R is a subset of the source's rights. A program hands a helper an attenuated handle so the helper can do only what it needs.
beneath
The containment property the capability VFS guarantees. It is defined by the handles a program held, never by a path string, so a directory moved away after it was opened stays beneath its root for operations through the handle already held.
capability row
Also: effect row
In sparkles:event-horizon, a Ctx struct holding one handler per uniquely labeled capability; a function that needs several services takes a row, one that needs one takes it bare. Swapping a handler means passing a value of a different type, so tests substitute virtual time or a simulated network with no run-time dispatch. It is a testability and least-authority convention, not a security boundary.
component walk
The portable resolver of the capability VFS, used wherever the kernel has no resolver that gives the same answer. It never opens .. through the file system; an in-scope .. returns to a handle the walk still holds.
directory capability
In the capability VFS, a Dir value: an open directory handle together with the operations its rights permit and the policy its walks follow for symbolic links, .. and mount points. Every file the program reaches through it is named relative to the handle, so holding the capability is what grants access. Unlike a capability row, it is an enforcement boundary.
sparkles:font
cell metrics
In sparkles:font, the cell width and height, baseline, and underline and strikeout positions and thicknesses derived from a face at a size, rounded to whole device pixels by one documented rule. The cell width is the advance of the digit zero.
coverage
Also: pixel coverage
In sparkles:font, the 8-bit per-pixel value a rasterizer writes for a glyph: 0 where the outline leaves the pixel empty, 255 where it covers it. The set of characters a face maps through its cmap table is called character coverage.
face
Also: font face
In sparkles:font, one font inside a byte buffer, read in place and never changed after it opens. A single-font file holds one face; an OpenType collection holds several, picked by index.
face record
In sparkles:font, the catalog's description of one face: names, style, width, weight, spacing and character coverage, read by the library's own parser and cached on disk against the file's size and modification time.
fallback chain
In sparkles:font, an ordered list of face records beginning with the matched face and keeping only faces that add character coverage. A face opens on first use, and each character's answer is remembered.
font catalog
In sparkles:font, the set of face records built from all font sources. Platforms differ only in which files they list; matching and fallback rules over the catalog are the same everywhere. Distinct from a collection index, which picks a face inside one file.
font source
An input to the font catalog: explicit files, a directory, the font directory Sparkles bundles, or the files the platform lists as installed. A platform source only lists files; the library's own parser describes them.
glyph key
In sparkles:font, the face identity, glyph, size, variation coordinates, subpixel offset and render flags of one rasterization. Equal keys produce byte-identical output, which is what makes glyph caches separate values instead of state inside a face.
instance
Also: font instance
In sparkles:font, a copyable value combining a face, a size in pixels per em, one vector of normalized variation coordinates and a synthesis. It is the only place variation coordinates are stored, so shaping, metrics, outlines and rasterization all read the same ones. Not to be confused with an OpenType named instance.
synthesis
In sparkles:font, the value a match returns alongside the chosen face, saying how to approximate what the face lacks: embolden by an amount, skew by an angle, or set an axis. Shaping and rasterization both consume it, so faked bold and italic look the same everywhere.
sparkles:font-explorer
cell-grid audit
In the font explorer, the check that tells which text in a programming font a terminal may place one glyph per cell: glyphs whose advance differs from the face's cell metrics, and ligatures that change the glyph count, each with the characters involved. Text that fails it is still drawn correctly, from its shaped positions.
specimen
In the font explorer, a block of sample text or glyphs rendered in the font being examined. Every specimen is one bitmap the font library rasterizes, shown as an image in a window or over the kitty graphics protocol in a terminal, never drawn in the terminal's own font.
width class
In the font explorer, the layout chosen by width measured in interface cells, so one rule serves a window and a terminal: wide at 150 cells or more shows every pane, medium folds the sources into the family list, and narrow below 100 shows only the specimens with the other panes as overlays.
sparkles:fuzzy
admission
Also: admit, admitted
In sparkles:fuzzy, a query part admits a candidate when the part, after deleting at most its typo budget of characters, occurs in order within the candidate. Admission alone decides which candidates match and what is highlighted; ranking only orders the admitted ones.
canonical witness
Also: witness
Of all the ways an admitted query part can be found in a candidate, the one with the fewest deleted query characters, then the earliest final character, then the earliest positions. It supplies both the highlighted ranges and the window the ranking score is computed over.
sparkles:hue
content kind
The category a document gets when hue loads a target, chosen from its content rather than from a command-line mode. Each kind produces one sparkles:ui widget tree that every backend paints, and kinds compose: a markdown document may embed a code block of another kind.
interaction tier
A classification of hue's viewer requirements by what they need from a backend, not by which backend paints them: passive (static output), interactive (a live event loop) and precise (sub-cell positions or continuous time). Where a backend cannot reach a tier, the requirement states the degradation; any other difference between backends is a defect.
sparse overlay
Also: layer
Layers of sparse overlays resolve from lowest to highest: compiled defaults, then files, then command-line flags. A setting present in a layer wins even when it equals the default, so a user can pin a value against a lower layer.
sparkles:packaging
artifact receipt
Also: receipt
The machine-readable output of a successful sparkles:packaging run for one target: resolved identity, stage inventory, final artifact sizes and SHA-256 digests, encoder or tool versions, and signing status. It is evidence for later publishing tools, not an SBOM or a provenance attestation.
stage tree
The format-neutral input to sparkles:packaging: an ordered tree of regular files, directories and symbolic links with logical /-separated paths and honest metadata. Every artifact format is produced from it, and its paths are validated before any host path is joined.
sparkles:release
pull-request-atomic unit
Also: PR-atomic unit
The indivisible element of a split mode backlog. A unit ends at the first commit where every pull request opened so far has closed, so interleaved pull requests merge into one wider unit; release boundaries fall only between units.
split mode
Also: --split
The release --split mode of sparkles:release. It matches commits to the pull requests that introduced them, groups them into pull-request-atomic units, asks a command-line agent for release boundaries and themes, validates and approves the plan, and tags each slice oldest first. Its counterpart, classic mode, makes a single release.
sparkles:shaders
device configuration
In sparkles:shaders, a dub configuration whose dflags contain -mdcompute-targets=; shaders is the conventional name. The build step and editor analysis both read a package's device compilation from it, so it is declared once and never restated per shader.
fragment entry point
Also: @fragment function
In sparkles:shaders, a function marked @fragment in a @compute module. The compiler synthesises the shader interface from its signature: @input parameters become located varyings, @uniform parameters named uniforms, Sampler2D parameters bound images, and the return value the finalColor output. The fragment stage is an extension of LDC's dcompute, which upstream compiles only compute kernels.
freshness stamp
Also: stamp
In sparkles:shaders, the .stamp file in a build step's output directory: the SHA-256 of each module of the shader unit and each contributing build recipe, and the files produced. While it still matches, a build needs neither dub nor the device compiler; a stamp reading prebuilt marks output a packager supplied.
shader unit
In sparkles:shaders, the set of modules marked @compute among the source files of a package's device configuration and all its dependencies. It is discovered from the modules' own declarations, never listed, and compiled in one invocation because a SPIR-V module has no linker.
shader vocabulary
In sparkles:shaders, the types vec2, vec3 and vec4, their constructors and component access, and GLSL's built-in functions with GLSL's definitions. It is plain D on the host and SPIR-V on the device; a vec3's layout differs between the two, which is why one never crosses a shader interface.
single-source shader
Also: single-source effect
In sparkles:shaders, a per-pixel effect whose only definition is one D function over the shader vocabulary. The host compilation calls it directly, for example once per terminal cell; the device compilation wraps it in a fragment entry point and emits GLSL. Neither side is written separately.
sparkles:syntax
highlight event stream
Also: highlight events
The single seam of sparkles:syntax: engines emit source(start, end), push(label) and pop events in position order with every push matched by a pop, and renderers fold that sequence into ANSI, HTML or styled runs. The stream is infallible; engine failures surface before it, never inside it. The event model follows tree-sitter's reference highlighter.
highlight label
A name from the canonical, TextMate-scope-compatible vocabulary of sparkles:syntax, interned to a numeric id at configure time. Themes and capture names both resolve by longest dotted prefix, so keyword.control.import falls back to keyword.control and then keyword; capture names additionally consult an alias table that reconciles other grammar dialects.
totality law
Unlike a parser, a highlighter must render whatever it is given. In sparkles:syntax an engine failure is reported before any event stream reaches a renderer, the caller then shows the plain source, and an unevaluable query pattern disables only itself; no degradation is sticky.
sparkles:terminal
development environment
A terminal execution context with a stable identity, storage namespace, readiness checks and lifecycle authority. Multiple profiles and panes can use the same environment; externally provisioned resources retain their external owner.
exit prompt
Shown at the bottom of a pane whose program exited, over its last screen: the exit status or signal, the command, and Enter to re-run, Esc for a shell, Ctrl+C to close. Modelled on zellij's command panes.
extra-keys row
Also: extra keys, MENU key
The row Termux introduced and the Sparkles terminal keeps, in Termux's extra-keys layout syntax. Ctrl and Alt latch for the next key; a MENU key opens the key guide.
leader
Also: leader key, leader chord
The chord the Sparkles terminal reserves to reach its own commands: pressed, it opens the key guide, and the next keys pick a command from it. Ctrl+Shift+Space on the desktop and Ctrl+Alt+Space on Android by default; configurable as lantern.leader.
one-off command
A pane command supplied as explicit argv outside the profile's ordinary entry recipe, using the selected environment. Workspace restoration retains an inactive record; only an explicit execution action may run it again.
opener
Also: pill, rail
The pill suits a phone held upright; the rail suits landscape, tablets and the desktop. Both also carry a button that opens the key guide on a touch screen. Chosen by ui.tabsOpener.
pane
Also: terminal pane, viewer pane, panes
A terminal pane runs one program on its own pseudo-terminal; a viewer pane shows a file through the embedded document viewer. Both take part in tabs, splits, focus, zoom and restore alike.
surface
Also: surfaces, page, sheet, anchored card
The Sparkles terminal keeps its surfaces in one stack that receives input before the panes. A page fills the window, a sheet rises from the bottom edge, an anchored card sits next to its subject without covering it, and a panel slides out beside the opener.
terminal profile
A configuration object with a stable identity and an environment reference that supplies a pane's launch recipe. A running pane captures resolved settings; restoration resolves the saved profile identity against loaded configuration.
sparkles:test-runner
metric class
Also: quantitative metric, diagnostic metric
Every metric in the test runner's catalog is either quantitative, with near-zero perturbation and the only class a reported or gated number may read, or diagnostic, which perturbs the measurement and is rendered separately, never blended into a headline.
reported absence
Also: capability absence
Each measurement source opens through a run-time probe and reports what it can measure. A missing capability is recorded as an absence with a human-readable reason; its columns are omitted or render as unavailable, never as zero or an unlabeled estimate.
workload window
A @workload test is measured as a window rather than per iteration: each source is read once at the window's opening and closing edges, and the runner reports the deltas, including a split of elapsed time into on-CPU and off-CPU components. The body is never re-run for counting.
sparkles:text-layout
shaped flow
Also: shapedFlow
One of text-layout's two placement modes. A shaped-flow paragraph is measured in layout units with contextual shaping, and painting, hit-testing and selection all use its one cluster result; the other mode places text on grid cells.
typography profile
Also: typography profiles
Text-layout's bounded choices for microtypography, script-aware justification and related publication features. A profile is requested explicitly; the paragraph engine never infers one.
sparkles:tui
cell-diff compositor
Also: cell diff, cell-diff
The sparkles:tui renderer: it retains the last rendered grid, compares the next one cell by cell, and emits one cursor move plus the styled text for each run of changed cells, so repainting a whole frame costs only its differences. Its retained grid reuses its storage, so a steady render loop allocates nothing.
packed cell
Also: compact packed cell
The cell representation of the sparkles:tui frame grid: a packed code point plus a flat style, with graphemes too long to pack spilled to out-of-line storage, after the Notcurses and libvaxis inline packing. The render-core benchmark found that it lets a D renderer match a C one on the common workload.
sparkles:twoslash
below-line block
The part of a Twoslash overlay that adds rows under a line of code: error messages, ^? query results, completion lists, and // @tag lines. The overlay planner sorts them by line, and every backend flushes them at the line's end.
inline decoration
The part of a Twoslash overlay that marks a span inside one line of code: hovers, highlights, and errors. The overlay planner sorts inline decorations so an enclosing span opens before a nested one; they never cross a line break.
sparkles:ui
capability profile
Also: capability profiles
A named bundle of the design system's capability flags. A profile narrows what the toolkit uses, so a preview shows what a less capable target would draw; it never widens beyond what the target declares.
cell
Also: cells
Every coordinate and extent in sparkles:ui layout is a whole number of cells; no floating-point value enters layout. Mapping cells to pixels or CSS lengths is the canvas's job, so pixel backends may still position content more finely.
design token
Also: token, tokens, design tokens
In the Sparkles design system every token sits on one of three tiers: a primitive holds a raw value, a semantic token names a role, and a component token names a part of one component; each tier aliases the one below, and the alias graph must be acyclic. A theme assigns values to tokens.
display list
In sparkles:ui, the display list is the last backend-neutral stage: each operation carries its slot, its resolved appearance and its clip state, so a backend paints it without consulting the theme or the widget tree. Tests inspect it through a recording canvas.
font role
Also: font roles
A theme token whose value is a font request, a fallback chain and code-point routes, in the font library's terms. The design system owns the roles; the font library resolves requests and has no notion of a role.
glyph channel
The part of a theme that chooses chrome glyphs per capability, separate from the text a widget shows. Its glyphs occupy one cell under every width profile, including one that makes ambiguous-width characters wide.
interaction state
Also: interaction states
Slot resolution in sparkles:ui takes the set of active interaction states as a second argument. A theme overrides a state sparsely; where no active state has an override the resting appearance is used, and among several active states the highest-precedence override wins.
key guide
Also: guide, lantern, touch guide
The sparkles:ui lantern: after a prefix key such as the leader, it shows the next keys and what they do, and descends into groups. Its touch form adds breadcrumbs, tappable rows and a search across every command.
projection
In the Sparkles design system a metric finer than a cell is typed in device pixels and carries a projection onto cell targets; each target declares per metric whether it honours or projects it, so no value is silently dropped. Glyphs and borders are projected the same way.
slot
Also: semantic slot, slots
In sparkles:ui, a widget names a slot rather than a color or style; the theme's palette resolves each slot to a concrete appearance (colors, attributes, border, font role) while the display list is built, so one theme restyles every target.
sparkles:ui-app
application host
Also: host
sparkles:ui-app is the application host: a sibling of the UI toolkit that owns backend selection, the shared window and font options, and the frame loop, so an application supplies only a present and a handle function and never names a backend.
recording target
The recording target is the third backend of sparkles:ui-app, beside the terminal and the window. It opens no window and no terminal, so a whole application session can be asserted in an ordinary unit test; it extends the toolkit's recording canvas from one frame to a session.
render level
Also: render levels
At the widget level the host lays out and paints a tree; at the display-list level the application appends drawing operations the host replays; at the direct level the application drives the backend's canvas itself, as a terminal emulator's per-cell renderer does.
sparkles:versions
version scheme
A plain struct that is at once the version value for one ecosystem (SemVer, PEP 440, Debian, …) and the handle carrying its parser and Package URL type. It satisfies the version concept, a total order plus text rendering, and the scheme concept; every further capability is optional and detected at compile time.
sparkles:wired
configuration definition
One value supplied by a source for a particular configuration option, together with its priority and ordering information. Explicitly setting an option creates a definition even when its value equals the built-in default; leaving it out creates none.
configuration option
A setting declared by a configuration schema and identified by its schema path, with a type, built-in default value, and rules for resolving supplied definitions. Sections group options; a collection element is not automatically a separate option.
configuration source
An origin identified by the application that can supply definitions for configuration options. A source's kind describes where values come from; each definition's priority determines precedence.
configuration submodule
A typed configuration section using submodule policy to distribute supplied-member presence and inherited metadata to child options. It can be a direct section or a repeated list/map value; container eligibility is settled before child resolution in a repeated instance.
definition priority
A number used to select definitions for an option: only definitions with the smallest number participate in resolution. Those selected definitions merge or conflict under the option's rules; their merge order is specified separately.
definition projection
A view identified by its parent definition and original branch locator. It carries supplied-member presence, inherited metadata, and branch disposition; its identity is independent of where that branch lands in an effective concatenated list.
option pattern
A pattern made from original schema member names and repeated list/map segments, distinct from a runtime property address. Its canonical text uses [<index>] and [<key>]; actual instances use indices or quoted keys, and ordinary collection data is not automatically a declared option.
resolution snapshot
A result that keeps all accepted definitions together with each option's resolved value or failure and the definitions that contributed or were overridden. Failed and successful options can be inspected together, but a complete configuration is available only when every option resolves successfully.
source branch locator
An original-source route used with a parent definition identity to locate a supplied payload and presence. It is not an effective list index, a source file path, or a documentation anchor; projections keep it while reports separately use canonical active addresses.