KVG Stencil Libraries

Version: 0.1 — Proposal Status: Pre-normative — depends on specs/kvg/format.kmd (also proposal-v0.1)

0. Why

KVG's extension mechanism is [[kdef]] — a reusable custom primitive expanded to base primitives at load time (format.kmd §11). The format spec already imagines a catalog of common kdefs (spring, gear, bezier-arrow, …) but assigns ownership to one product: "O Koder Dok mantém um catálogo de kdefs comuns … quando o autor insere uma do catálogo, o Dok copia a definição para dentro do arquivo" (format.kmd §11.5).

That ownership is wrong for the Stack (D1 — correct contract; D10 — reuse). A visual KVG editor, Craft, Cine, kicon, and Dok all need the same themed object banks. A "Dok-owned" catalog is invisible to the others. This spec promotes the catalog to a Stack-level stencil registry: domain-organized kdef packs, versioned, distributed through the Koder Hub, and inserted identically by any editor. No change to the kdef mechanism itself — a stencil is a kdef.

1. Definitions

• Stencil — one parametric kdef representing a domain object (e.g. a BPMN task, a door, a resistor, an office-chair). May target any KVG profile: a Core 2D shape, a Solid 3D mesh, or (with kvg-RFC-001) an Interact-bearing object (e.g. a light-switch that toggles a bound lamp).
• Stencil pack — a versioned bundle of stencils for one domain, plus metadata and thumbnails. Distributed as a Hub bundle.
• Stencil registry — the Stack-level index of published packs.
• Insertion — placing a stencil into a target document: the editor copies the kdef definition into the document (the file stays self-sufficient per format.kmd §11.5) and adds one instance node.

2. Pack layout (R1)

A pack is a directory (publishable as a .kpkg Hub bundle, specs/kpkg/format.kmd):

stencils/<domain>/
├── pack.kvgs.toml         # manifest (R2)
├── defs/*.kvg             # kdef definitions, one domain object per def (or grouped)
├── thumbs/*.png           # generated previews (kicon rasterizes defs/)
└── README.kmd

• R1.1 A pack MUST declare exactly one domain (§4) and MUST NOT mix domains.
• R1.2 defs/ MUST contain only [[kdef]] blocks + supporting [[kgen]]; no top-level scene content (a pack is a library, not a document).
• R1.3 Thumbnails MUST be generated, never hand-drawn (kicon rasterizes each def at a canonical size), mirroring the icon-generation rule.

3. Manifest (pack.kvgs.toml) (R2)

[pack]
domain      = "floorplan"
title       = "Floor Plans & Furnishing"
version     = "1.2.0"            # semver; breaking kdef param change = major
profile_max = "Spatial"         # highest KVG profile any stencil here needs
license     = "self-hosted"     # no external asset refs (R5)

[[stencil]]
id      = "floorplan/door-single"
title   = "Single Door"
kdef    = "door-single"         # the [[kdef]] name in defs/
params  = ["width", "swing", "hinge"]
profile = "Core"                # this stencil's own profile floor
tags    = ["opening", "door"]

• R2.1 Every stencil's id is "<domain>/<name>", globally unique within the registry (naming authority: the stencil registry, §6).
• R2.2 kdef names inside defs/ are namespaced on insertion to <domain>__<name> to prevent collisions when a document mixes packs.
• R2.3 profile per stencil + profile_max per pack let an editor filter to what its renderer supports (profile_doc ⊆ profile_renderer, format.kmd §3).

4. Domain taxonomy (R3)

Initial closed set of domains (extensible by registry PR). Each maps to one pack:

• R3.1 A domain not in this table requires a registry entry (§6) before a pack may claim it — no ad-hoc domains (prevents fragmentation; D10).
• R3.2 Domains are slugs (lowercase, hyphenated), stable once published.

5. Self-hosted-first (R5)

• R5.1 A stencil MUST be fully self-contained KVG — no external CDN, font, or asset reference (format.kmd §0 premise; policies/self-hosted-first.kmd).
• R5.2 Heavy 3D meshes ship inside the pack (KVG Solid mesh), or are generated by a [[kgen]] in the pack; a stencil never fetches a mesh at runtime.
• R5.3 A pack passes the same kvg validator as any document before publish.

6. Registry & distribution (R6)

• R6.1 The Stack-level index lives at meta/docs/stack/registries/kvg-stencils.md (source of truth: domain → pack → version → Hub coordinates), analogous to other Stack registries.
• R6.2 Packs publish to the Koder Hub as bundles (hub.koder.dev/bundles/<domain>-stencils); editors discover and install from there (specs/landing-pages/packages.kmd for the Hub page).
• R6.3 First-party packs are authored in-monorepo under engines/lang/kvg/stencils/<domain>/ and released via the standard tag flow (policies/releases.kmd).
• R6.4 Versioning is semver; a breaking change to any stencil's params (rename/remove/retype) is a major bump (documents pin the pack major they were authored against; insertion already copies the def, so existing documents are unaffected — pinning governs re-insertion and update prompts).

7. Multi-tenant user stencils (R7)

Beyond first-party packs, a user can save their own objects as stencils.

• R7.1 User stencils are tenant-scoped by the host editor product per policies/multi-tenant-by-default.kmd: keyed by koder_user_id / workspace_id, tenant resolved by auth (never client-supplied), isolated at storage (RLS / key-prefix), cross-tenant access → 404.
• R7.2 A user stencil uses a reserved domain prefix user/<workspace>/… and never collides with the first-party namespace.
• R7.3 Sharing a user stencil across tenants reuses the Drive/Tribus ACL grant model (out of scope here; deferred to the product).

8. Insertion contract (R8)

• R8.1 On insert, the editor copies the stencil's kdef (and any kdef it extends or references via use of=/extrude of=, transitively) into the target document under the namespaced name (R2.2), then adds one use of=#<domain>__<name> instance node, carrying the stencil's params as overrides. use is the engine's instancing substrate (KVG-097 / RFC-004 C4): it resolves a kdef extends=-chain to a base primitive and places it, so a placed stencil renders and is extrude-able for the 2D→3D pipeline (KAD-004) with no per-instance geometry duplicated. (A procedural/composite kdef with an expand body — format.kmd §11 — is a forward extension that renders once the engine implements §11 type-named expansion; use of= is the substrate that renders today.)
• R8.2 The saved document is self-sufficient — it never references the pack at render time (format.kmd §11.5). The pack is an authoring-time convenience.
• R8.3 Re-inserting the same stencil reuses the already-copied kdef (no duplicate definitions); kvg fmt dedupes on save.
• R8.4 The editor SHOULD surface @param-marked params (kvg-RFC-001 §3.4) as instance knobs so a placed object is immediately tunable.

9. Relation to existing components

• products/horizontal/dok — its catalog (format.kmd §11.5) becomes the textual-editor client of this registry (autocomplete + copy-on-insert), not the owner.
• The visual KVG editor (kvg-RFC-002, forthcoming) — the primary client: a domain palette backed by the registry, drag-to-insert per R8.
• products/dev/kicon — rasterizes defs/ to thumbnails (R1.3).
• products/dev/hub — distribution surface (R6.2).

10. Open questions

• Q1 Do BPMN/UML/circuit stencils carry semantic connection rules (a BPMN gateway has typed in/out flows) here, or does that live in the editor's diagram-logic layer? Leaning: connection anchors (named ports) live on the stencil; validation of legal connections lives in the editor.
• Q2 Granularity: one pack per domain, or sub-packs (e.g. electrical/iec vs electrical/ansi symbol standards)? Standards-divergent domains likely need sub-packs keyed by standard.
• Q3 Who curates the first-party domain set's visual style for cross-domain consistency (one designer pass vs per-domain)? Ties to specs/themes/verge.kmd.