Document Context for the DOM

Physical DOM nesting is the scope hierarchy — no virtual container trees, no leaked listeners.

@sandlada/document-context is a function-first IoC container and reactive state library hosted on HTMLElement and physical DOM nodes. Independent bundles — Astro islands, micro-frontends, Web Components — share services and state through the DOM tree itself, using the W3C Context Protocol.

Getting startedInstall the package and mount your first DOM-anchored session.

Core conceptsThe two-phase blueprint model and data-last curried verbs.

API referenceEvery export of the published subpaths, generated from the source JSDoc.

W3C protocolHow inject requests cross Shadow DOM and bundle boundaries.

Why anchor to the DOM?

Space is scope. Resolving a dependency walks up parentElement, so nested UI naturally inherits parent services with no manual child containers.
Zero-leak by construction. Sessions live and die with their host node; disconnects are confirmed in a microtask and subscriptions are torn down automatically.
State is the view. withBridge projects reactive state onto dataset, style, aria-*, and form values with loop guards and cursor preservation.
One bus for every framework. React, Vue, Svelte, and vanilla scripts meet at native HTMLElement and context-request events — no shared heap reference required.

A complete example

import { createContext, pipe, withBridge, withStorage, mount, update } from '@sandlada/document-context'

const themeBlueprint = pipe(
    createContext({ isDark: false }),
    withBridge({ properties: { isDark: 'dataset.themeDark' } }),
    withStorage({ adapter: 'localStorage', key: 'app-theme' })
)

const session = mount(themeBlueprint)(document.documentElement)
const toggle = update<{ isDark: boolean }>((s) => ({ isDark: !s.isDark }))
toggle(session)

isDark flows to data-theme-dark, persists across reloads, and any island holding the session — or a child node resolving through it — sees the same state.

What ships

5 focused subpaths — core, bridge, storage, dom, signals, so tree-shaking stays total.
Two-phase purity — Phase 1 blueprint composition has zero DOM, zero I/O, zero listeners.
W3C-native DI — inject, injectAsync, injectAll over composed context-request events.
Four-dimension lifecycles — DOM host, session machine, services, and state/bridge/storage coordinated.

Install

npm i @sandlada/document-context