Vellum

draft 1.0.0
  status stable
  title Vellum Specification
  date 2026-04-15
  license All Rights Reserved

---

spec vellum

  section purpose
    title Purpose
    level 1

    prose
      value
        Vellum is a minimal, DOM-centric mod loader kernel for web
        applications. Page composition is expressed as DOM markup;
        Vellum coordinates discovery, dependency resolution, and
        lifecycle for each mod.

  section primitives
    title Primitives
    level 2

    prose
      value
        Vellum provides two custom elements. The host element
        coordinates the mods within it; the mod element is a
        declarative marker for a loadable module. Either element
        may be registered under any name; the spec uses
        vellum-host and vellum-mod as the conventional names.

    requirement V-001
      level MUST
      value
        A host element MUST discover its child mod elements at
        connectedCallback time and at any DOM mutation that adds
        or removes mod children.

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

  section dependencies
    title Dependency resolution
    level 3

    prose
      value
        Vellum supports hard dependencies via the require
        attribute and soft dependencies via the after attribute.
        Cycles are detected and reported via the failed state on
        the affected mod elements.

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

    requirement V-011
      level SHOULD
      value
        Mods SHOULD honour after dependencies for ordering when no
        require cycle is present, but a missing after dependency
        SHOULD NOT block mount.

  section bundle-registration
    title Bundle Registration
    level 4

    prose
      value
        When mods are statically bundled into a single artifact,
        each mod's module can call host.register(name, factory) at
        load time to make it discoverable by name. Mod elements
        with ref=name resolve from the registry instead of loading
        via src.