Canonical short definitions live in _index.md §0.8. This file expands them with code references and adds terms that emerged after consolidation.

Last reviewed: 2026-05-24

Conventions

• Term — short definition (one sentence).
• Code: where in the repo the concept is defined / serialised.
• See: related ADRs, runbooks, or spec sections.

Core product model

Project

Top-level container owned by a user. Holds one workflow + many screens + optional connected git repo + shared library.

• Code: packages/db/src/schema.ts (opens in a new tab) → project
• API: POST /api/v1/projects, GET /api/v1/me/projects — see docs/api/rest.md (opens in a new tab)

Workflow

Directed graph of screens connected by edges. Live-synced via Yjs (Liveblocks Storage room project:${id}).

• Code: packages/db/src/schema.ts (opens in a new tab) → workflow; node/edge types in packages/shared/src/workflow.ts (opens in a new tab)
• Sync: Liveblocks Storage channel — see master spec §I.2.2
• See: ADR 0002

Screen

A composition of component instances. Node in the workflow graph.

• Code: ScreenData in packages/shared/src/workflow.ts (opens in a new tab)
• Storage: screen_composition table, one row per (projectId, screenId)

Edge

A connection between two screens, triggered by an interactive element. May reference a specific instance + event (navigate action).

• Code: WorkflowEdgeData in packages/shared/src/workflow.ts (opens in a new tab)

Component spec

Markdown file describing a component's contract — props, slots, events, structural sections. Source of truth for the component's interface.

• Format: YAML frontmatter + fenced <!-- arno:props v1 --> / <!-- arno:slots v1 --> blocks
• Code: parseComponentMd in packages/editor/src/md-parser.ts (opens in a new tab) → returns ParsedComponent
• Storage: raw MD in component_md_raw, immutable versions in component_md_versions

Component instance

A placement of a component within a screen, with concrete prop values and (optionally) children inserted into named slots.

• Code: ComponentInstance, findInstance, insertIntoSlot, removeById, updateProp in packages/shared/src/composition.ts (opens in a new tab)

Composition

The full tree of instances for one screen. Tree, not list — instances can hold children inside slots.

• Code: ScreenComposition in packages/shared/src/composition.ts (opens in a new tab)
• Store: CompositionStore class in packages/editor/src/composition-store.ts (opens in a new tab)

Slot

A named insertion point within a component, declared in its spec. Children of an instance live in instance.children[slotName] = [...].

• Code: insertIntoSlot in packages/shared/src/composition.ts (opens in a new tab)

Library

The set of component specs available to a project — either resolved from the connected git repo's design-system or from a built-in fallback.

• Code: LibraryStore in packages/editor/src/library-store.ts (opens in a new tab) — state machine fallback → cache → fetched
• See: ADR 0003

Prop schema

Typed declaration of a single prop on a component spec — string with textEditable flag, or enum with allowed values.

• Code: PropSchema, PropSchemaString, PropSchemaEnum in packages/shared/src/index.ts (opens in a new tab)

textEditable prop

Marker on a string prop indicating the Editor role may modify its value (without touching layout or component choice).

• See: master spec §I.1.2 (permission enforcement)

Rendering

Render adapter

The postMessage protocol + iframe bridge that lets a project's real React components render inside ARNO's preview pane without ARNO importing the bundle.

• Protocol: packages/render-adapter/src/ — ARNORenderMessage, ARNOReadyMessage, ARNONavigateMessage, PROTOCOL_VERSION
• See: ADR 0004

Bundle

The compiled output of a project's design system, hosted as a JS file the render adapter iframe loads. Each connected repo ships its own arno.entry.tsx.

• Convention: .github/workflows/arno-build.yml builds and publishes; URL configured per-project in connected_repo.bundle_hosting

Bundle proxy

ARNO backend route that serves bundles from private repos using the user's GitHub installation token (so private DS code doesn't leak to public CDN).

• See: master spec §I.3 ("Source of truth"), bundle hosting section

arno.entry.tsx

The entry file in a connected repo that registers the design-system components for the render adapter. Lives at repo root.

• Convention: documented in master spec §I.2.3

Live collaboration

Session-branch

Per-Maker working git branch (arno/{user-handle}). Where in-flight Yjs edits are eventually snapshotted to.

• Code: session_branch_state table in packages/db/src/schema.ts (opens in a new tab)

CRDT

Conflict-free Replicated Data Type. ARNO uses Yjs (via Liveblocks Storage) for workflow + presence. Component spec edits use REST + versioned storage, not CRDT.

• See: master spec §0.3 principle 10

Snapshot

A git-committed state derived from the live Yjs document. Activity-based: triggered after edit-quiescence, not on a fixed schedule.

• See: master spec §0.3 principle 5

Soft snapshot

In-memory cache of component versions captured at screen-edit-session start, so the screen renders consistently even if the underlying spec changes mid-edit.

• See: master spec §0.8

Quality & sync

Drift

A divergence between an MD component spec and the actual TSX implementation in the connected repo. Detected by .github/workflows/arno-check.yml and surfaced in ARNO UI.

• Code: component_drift table; sync logic in apps/api/src/sync.ts (opens in a new tab) and apps/api/src/github.ts (opens in a new tab)
• Storage: one row per (projectId, filePath), status enum
• See: master spec §0.3 principle 8

check_run

GitHub Check Run created by arno-check.yml reporting drift / lint / UUID-validity status against a commit SHA. ARNO reads these via the GitHub App webhook (check_run event) and via /debug/github/sync-check-runs backfill.

• Code: apps/api/src/github.ts (opens in a new tab), apps/api/src/webhooks.ts (opens in a new tab)

Pre-edit impact analysis

Synchronous check before a structural change to a component spec: surfaces every screen / instance that will be affected so the Maker can confirm.

• See: master spec §0.3 principle 9

Branch-aware view

Each Maker sees their own session-branch edits live; other Makers see main until a snapshot lands.

• See: master spec §0.8

Composition propagation

The killer feature: editing a component spec instantly updates every screen / instance using it across every project, because instances reference specs by UUID.

• See: master spec §0.1 ("Vision"), §0.3 principle 3 ("Identity ≠ name")

URL-import feature (master spec v1.3, §V unparked)

URL-import

The small-business onboarding flow: user provides a URL, ARNO extracts a working React component set (TSX + types + tokens + stories) covering all observed states, viewports, and themes.

• Spec: docs/url_import_spec.md
• ADRs: 0007 – 0018

Atom

A self-contained UI fragment extracted from a target page — e.g. a button, a card, a nav item. The building block the URL-import pipeline operates on before composing components.

• Code: packages/atom-poc/src/, packages/url-import-extractor/src/decompose.ts (opens in a new tab)
• Embedding: E5-small text embeddings, not visual — see ADR 0018

Staging area

V1 holding pen for imported components: ARNO writes to Modal Volume + Backblaze B2, not directly to the user's git repo. Promotes to PR in V2.

• Code: staged_component table
• See: ADR 0016

Shadow data

Anonymised extraction artifacts kept for the data flywheel (cost-decrease loop). Disclosed in ToS; opt-out via privacy settings (default ON).

• See: ADR 0017, PATCH /api/v1/me/settings

Completeness matrix

Empirical acceptance check for URL-import output: matrix of (state × viewport × theme) combinations actually exercised, not a single pointwise score.

• See: ADR 0009, ADR 0010

Reactive vision

VLM (Vision Language Model) is called only when the code-first pipeline fails or its result fails completeness — not predictively up-front.

• See: ADR 0011

Legal-clean distillation

URL-import LoRA teacher is Qwen (Apache 2.0), explicitly not Anthropic / OpenAI APIs, to keep redistribution rights clean.

• See: ADR 0014, ADR 0015

Operational

Runbook

Operational playbook for a paging alert. Lives in docs/runbooks/, one file per alert.

• Convention: master spec §II.9 — every PAGE alert must have a runbook

ADR

Architecture Decision Record. Captures why a decision was made, with context + alternatives + consequences. Immutable once Accepted (Deprecated / Superseded markers preserve history).

• Index: docs/adr/_index.md — auto-generated by pnpm docs:adr-index
• Template: docs/adr/README.md

docs-autogen

CI job that regenerates docs/api/** and docs/adr/_index.md from source on each push to main, then commits drift back.

• Code: .github/workflows/docs-autogen.yml (opens in a new tab)
• Scripts: scripts/gen-*.ts

INTERNALS.md

Per-package deep-dive documentation: how the module works inside, lifecycle, invariants, non-obvious behaviour. Distinct from _index.md (catalog) and README.md (intro).

• Enforcement: dangerfile.ts posts a warning when source under a package changes without the matching INTERNALS.md being touched.

Studio (editor tooling) — cross-tool vocabulary

Terms used by two or more tools under apps/web/src/dev-tools/studio/. The canonical definition lives here; each tool's docs/<tool>/glossary.md defers to this section for the shared terms and only adds tool-private terms.

LayoutNode

The unit of the rendered tree. A discriminated union: RowNode | ColumnNode | ComponentNode. Every node has an id, a type discriminator, and either children (containers) or a component ref + props (leaves).

• Code: apps/web/src/dev-tools/studio/types.ts
• Consumers: Layers, Canvas, Punta, dito, passo — everything that operates on the tree.
• See: ADR 0061 for the LayerType taxonomy derived from LayoutNode.

layerTypeOf

The single dispatch function that classifies a LayoutNode into a LayerType (box | text | component). The authority — no tool inlines the check; every consumer imports the function from the shared kernel.

• Code: apps/web/src/dev-tools/studio/layer-type.ts
• Consumers: Punta (sidebar variant), dito (action list), passo (overlay flavour — planned).
• See: ADR 0061.

studio-bus

The shared module-level state — active tree handle, pick state, hover state, request-pick channel. Every Studio tool that needs to coordinate on the active document reads from / writes to this single channel.

• Code: apps/web/src/dev-tools/studio/studio-bus.ts
• Consumers: every Studio tool — Layers / Punta / Canvas / dito / passo / tela (read-only).
• See: docs/kernel/ for the full kernel reference.

studio-events

The shared telemetry emitter + queue. Every Studio tool routes events through this single transport; the server-side STUDIO_EVENT_TYPES allowlist gates the accepted event types.

• Code: apps/web/src/dev-tools/studio/studio-events.ts
• Storage: sorgente.studio_event table.
• See: docs/kernel/.

tree-ops

Pure tree mutation functions (moveNodeAt, insertFromPaletteAt, removeNode, duplicateNode, containsNode, …). Shared between every tool that edits the tree.

• Code: apps/web/src/dev-tools/studio/tree-ops.ts
• Consumers: Layers (DnD), Punta (property edits), dito (row actions), palette (insert), Canvas (DnD onDragEnd).

useStudioTree

The React hook that owns per-surface tree state — current tree, undo stack, debounced persistence to sorgente.composition_instance, telemetry emission.

• Code: apps/web/src/dev-tools/studio/useStudioTree.ts
• Surface: one hook call per editor surface (e.g. /app/sorgente).

registry (component factory map)

The LayoutNode.ref → React-component mapping. Used by StudioRenderer to dispatch component leaves to their React renderers. Shared across surfaces.

• Code: apps/web/src/dev-tools/studio/registry.tsx
• Contract: every registered component must forward the carrier attributes (data-arno-box-id, data-layer-type) to its root DOM element.
• See: ADR 0062.

Carrier (data-arno-box-id)

The single positioning anchor attribute on every rendered DOM element. Sets the cross-tool addressing convention — any tool that needs to resolve a node id to a DOM element uses document.querySelector('[data-arno-box-id="<id>"]').

• Code: apps/web/src/dev-tools/studio/canvas/Carrier.ts (the helper); StudioRenderer.tsx (the emit point).
• Consumers: Layers magnet pick, dito anchor, passo measurement, Canvas selection ring.
• See: ADR 0062.

StudioRenderer

The recursive React component that walks LayoutNode trees and emits DOM with carriers. Owned by Canvas; consumed wherever a tree is rendered (Canvas itself, Storybook preview, Foundation catalogue).

• Code: apps/web/src/dev-tools/studio/canvas/StudioRenderer.tsx (target location post-migration from studio/render/).
• See: docs/canvas/contract.md §"Required: renderer ownership".

StudioDndShell

The single DndContext (dnd-kit) wrapping the rendered tree. Owned by Canvas; consumed by Layers (drop-tracker) and Palette (drag-to-insert).

• Code: apps/web/src/dev-tools/studio/canvas/StudioDndShell.tsx (target location post-migration).
• See: docs/canvas/contract.md §"Required: DnD shell ownership".

Pure module

A file with pure functions and frozen data — no React, no DOM, no side effects. Every Studio tool has a "pure modules" coverage gate at 95% lines / 90% branches / 100% functions.

• Examples: tree-ops.ts, layer-type.ts, every tool's *-registry.ts.
• See: testing-standard.md §"L1 Unit".

Carrier sentinel (render_anomaly)

The Canvas telemetry event fired when the rendered carrier count drifts from the tree node count. The cheapest reliable signal that the renderer (or a registered component) regressed.

• Code: Canvas's anomaly probe.
• See: ADR 0062 §Enforcement.

Italian / Renaissance chord

The product-wide naming convention. Every Studio tool and product surface picks an Italian noun from Renaissance-craft vocabulary as its canonical name.

• Live names: punta (tip), dito (finger), passo (step), tela (canvas/cloth), Sorgente (source), Foundation (Vasari).
• See: ADR 0059.

Acronyms