KVG Stencil Libraries

proposal-v0.1

Stack-level system of reusable KVG object libraries ("stencils"): themed banks of parametric `kdef` primitives (BPMN, UML, ER, floor plans, furniture, civil/ mechanical/electrical/electronic, PCB/IC, signage, characters, devices, …) that any KVG editor inserts into a document. Promotes the per-Dok catalog (format.kmd §11.5) to a versioned, Hub-distributable, multi-tenant registry.

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 *opies

    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