vellum

draft 1.0.0
  status draft
  title vellum — runtime composer
  date 2026-05-24
  license Open

---

spec vellum

  section purpose
    title Purpose
    level 1

    prose
      value
        vellum is the runtime composer. A small kernel coordinates
        the loading and lifecycle of modular pieces (mods) declared
        as DOM markup. Composition is expressed by what is in the
        document; everything else is loading order.

  section primitives
    title Primitives
    level 1

    requirement V-001
      level MUST
      value
        A host element MUST discover its child mod elements when it
        connects to the document and on every relevant DOM mutation.

    requirement V-002
      level MUST
      value
        A mod element MUST publish its load state via a DOM
        attribute, with values drawn from a fixed set covering
        loading, loaded, failed, unloading.

  section dependencies
    title Dependency resolution
    level 1

    prose
      value
        Hard dependencies (require) block mount; soft dependencies
        (after) order loads without blocking. Cycles in hard
        dependencies are detected and reported via the failed state.

    requirement V-010
      level MUST
      value
        A mod MUST NOT mount until all its require dependencies
        report state=loaded.