From c9ce9191c29b1fbd0d369003268aae052a66f112 Mon Sep 17 00:00:00 2001 From: Ivan Banov Date: Mon, 16 Nov 2026 11:18:23 +0100 Subject: [PATCH 1/3] docs: center the README diagram and show every DOM host Co-Authored-By: Claude Opus 5.5 --- README.md | 47 ++++++++++++++++++++++------------------------- 1 file changed, 22 insertions(+), 25 deletions(-) diff --git a/README.md b/README.md index 51c3a18..2dbb31d 100644 --- a/README.md +++ b/README.md @@ -17,31 +17,28 @@ host environment puts it on screen. Add a substrate and every primitive shows up there with the same behavior and the same a11y. ``` - +---------------------------+ - | core/ | the behavior - | states . events . a11y | framework-free, no DOM - +-------------+-------------+ - | - connect() -> logical bindings - (onPress, role, data-state, ...) - | - +----------------+----------------+ - | | - v | - +------------------------+ | - | dom/components/ | the DOM half | - | document listeners, | shared by every | - | focus/stack sequence | DOM host | - +-----+------------+-----+ | - | ^ | - | | dom/utils/* | - | | focus-trap, overlay, | - | | scroll-lock, ... | - v v - +-----------+ +-----------+ +-----------+ - | react | | solid | | native | - +-----------+ +-----------+ +-----------+ - render + host lifecycle only + +---------------------------+ + | core/ | the behavior + | states . events . a11y | framework-free, no DOM + +-------------+-------------+ + | + connect() -> logical bindings + (onPress, role, data-state, ...) + | + +-------+---------------------------------+ + v | ++--------------+ +------------------------+ | +| dom/utils/* | | dom/components/ | | +| focus-trap, +->| document listeners, | the DOM half, shared | +| overlay, ... | | focus/stack sequence | by every DOM host | ++--------------+ +------------+-----------+ | + | | + +------------+------------+------------+------------+ | + v v v v v v ++---------+ +---------+ +---------+ +---------+ +---------+ +---------+ +| react | | solid | | vue | | svelte | | others | | native | ++---------+ +---------+ +---------+ +---------+ +---------+ +---------+ + render + host lifecycle only ``` The engine that runs the core machines lives in its own repo: From b5748753063de362abde680d45b5cd2b3c8cac1d Mon Sep 17 00:00:00 2001 From: Ivan Banov Date: Mon, 16 Nov 2026 11:30:18 +0100 Subject: [PATCH 2/3] docs: redraw the README diagram as agnostic, platform, and substrate layers Co-Authored-By: Claude Opus 5.5 --- README.md | 47 +++++++++++++++++++++++++---------------------- 1 file changed, 25 insertions(+), 22 deletions(-) diff --git a/README.md b/README.md index 2dbb31d..e556ba3 100644 --- a/README.md +++ b/README.md @@ -17,28 +17,31 @@ host environment puts it on screen. Add a substrate and every primitive shows up there with the same behavior and the same a11y. ``` - +---------------------------+ - | core/ | the behavior - | states . events . a11y | framework-free, no DOM - +-------------+-------------+ - | - connect() -> logical bindings - (onPress, role, data-state, ...) - | - +-------+---------------------------------+ - v | -+--------------+ +------------------------+ | -| dom/utils/* | | dom/components/ | | -| focus-trap, +->| document listeners, | the DOM half, shared | -| overlay, ... | | focus/stack sequence | by every DOM host | -+--------------+ +------------+-----------+ | - | | - +------------+------------+------------+------------+ | - v v v v v v -+---------+ +---------+ +---------+ +---------+ +---------+ +---------+ -| react | | solid | | vue | | svelte | | others | | native | -+---------+ +---------+ +---------+ +---------+ +---------+ +---------+ - render + host lifecycle only + +-------------------------+ +-------------------------+ + | core/ | | utilities | + | | | | + | state machine per | | focus-trap, viewport, | + | primitive: states, | | scroll-spy, overlay, | + | events, a11y | | scroll-lock, ... | + +------------+------------+ +------------+------------+ + | | + +------------------+------------------+ + | + agnostic: no env assumptions, no framework + | + +------------------+------------------+ + v v + +-------------+ platform-specific +-------------+ + | dom | implementation of the | native | + +------+------+ agnostic core + utils +------+------+ + | | + +----------+----------+----------+----------+ | + v v v v v v ++--------+ +--------+ +--------+ +--------+ +--------+ +--------------+ +| react | | solid | | vue | | svelte | | others | | react-native | ++--------+ +--------+ +--------+ +--------+ +--------+ +--------------+ + substrates: glue code, thin connectors to each host + ``` The engine that runs the core machines lives in its own repo: From 528fc82e9d8005b86c892dce24f02b70b1fb2d8a Mon Sep 17 00:00:00 2001 From: Ivan Banov Date: Mon, 16 Nov 2026 11:40:10 +0100 Subject: [PATCH 3/3] docs: document the agnostic core utils and fix the import rules The core and DOM util import rules missed real edges: core/dialog imports controllable, and dom-overlay builds on the agnostic overlay stack. The layers diagram now shows the core utils and the DOM layer, and native's direct path from core to substrate. Co-Authored-By: Claude Opus 5.5 --- AGENTS.md | 5 ++- ARCHITECTURE.md | 101 ++++++++++++++++++++++++++++++------------------ README.md | 7 +++- 3 files changed, 72 insertions(+), 41 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index ae55113..dac625b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -56,8 +56,9 @@ architecture: (`@dunky.dev/state-machine` + `@dunky.dev/state-machine-bindings`), and the machine utils under `core/utils`. A machine util imports only the runtime; a DOM util imports nothing from this repo except a smaller DOM util (a - predicate two utils must agree on, never a peer that imports it back); a DOM - component imports its core counterpart and the DOM utils, never a framework; + predicate two utils must agree on, never a peer that imports it back) and + the core util it extends for the DOM (`dom-overlay` builds on `overlay`); a + DOM component imports its core counterpart and the DOM utils, never a framework; a substrate hook imports only the DOM util it wraps. - **DOM behavior is written once too.** Logic that is DOM-specific but not framework-specific — a document listener, an ordered focus/stack sequence — diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index 0d5e090..2970d38 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -19,8 +19,9 @@ inside it. packages/ | +- core/ substrate-free behavior, one package per primitive -| +- utils/ machine utilities shared across primitives +| +- utils/ agnostic utilities shared across primitives | | +- controllable/ @dunky.dev/controllable +| | +- overlay/ @dunky.dev/overlay | | +- ... | +- dialog/ @dunky.dev/dialog | +- tooltip/ @dunky.dev/tooltip @@ -70,11 +71,15 @@ framework-free. The split matters as substrates multiply: React and Solid differ in how they schedule an effect, not in what the effect does, so the what is written once and each binding contributes only its lifecycle. -Machine logic that several primitives need — the controlled/uncontrolled -machinery (`@dunky.dev/controllable`) — lives the same way under -`core/utils/`: substrate-free helpers a core machine composes into its -transition table, so every primitive encodes the same contract instead of -hand-rolling it. +Agnostic logic that several primitives need lives the same way under +`core/utils/`: no env assumptions, no framework. The controlled/uncontrolled +machinery (`@dunky.dev/controllable`) is a helper a core machine composes into +its transition table, so every primitive encodes the same contract instead of +hand-rolling it. The overlay-layer stack (`@dunky.dev/overlay`) tracks the open +layers and resolves the topmost one, so every overlay primitive agrees on who +owns Escape and the focus trap. A platform util extends an agnostic one for its +host: `@dunky.dev/dom-overlay` adds the DOM element and containment on top of +`@dunky.dev/overlay`. Each substrate directory is itself a private workspace package (`@dunky-dev/`) that owns the substrate's infrastructure — the dev @@ -85,32 +90,50 @@ level down. Internal infra uses the `@dunky-dev` scope; published packages use ## Layers and dependency direction ``` -+-----------------------------------------------------------+ -| machine runtime @dunky.dev/state-machine | -| (external dependency) | -+-----------------------------------------------------------+ - | - v -+-----------------------------------------------------------+ -| core primitive packages/core/ | -| @dunky.dev/ | -| | -| the behavior: states, transitions, guards, callback | -| ordering — no DOM, no framework, no host assumptions | -+-----------------------------------------------------------+ - | - v -+-----------------------------------------------------------+ -| substrate binding packages// | -| @dunky.dev/- | -| | -| owns the host wiring: element/listener lifecycle, | -| translating host events into machine events, re-syncing | -| options each render so fresh callbacks land | -+-----------------------------------------------------------+ - | - v - consumer code ++-------------------------------------------------------------+ +| machine runtime @dunky.dev/state-machine | +| (external dependency) | ++-------------------------------------------------------------+ + | + v ++-------------------------------------------------------------+ +| core primitive packages/core/ | +| @dunky.dev/ | +| agnostic utils packages/core/utils/ | +| @dunky.dev/ | +| | +| the behavior: states, transitions, guards, callback | +| ordering, plus the logic every host shares (controlled | +| state, the overlay stack) - no DOM, no framework, no env | +| assumptions +----+ ++-------------------------------------------------------------+ | + | | + v | native ++-------------------------------------------------------------+ | +| DOM component packages/dom/components/ | | +| @dunky.dev/dom- | | +| DOM utils packages/dom/utils/ | | +| @dunky.dev/dom- | | +| | | +| the platform-specific implementation of the agnostic | | +| core and utils: document listeners, focus/stack | | +| sequences, focus trap, scroll lock - no framework | | ++-------------------------------------------------------------+ | + | | + v | ++-------------------------------------------------------------+ | +| substrate binding packages// <----+ +| @dunky.dev/- | +| substrate hooks packages//hooks/use- | +| @dunky.dev/-use- | +| | +| owns the host wiring: element/listener lifecycle, | +| translating host events into machine events, re-syncing | +| options each render so fresh callbacks land | ++-------------------------------------------------------------+ + | + v + consumer code ``` The rules, stated as imports: @@ -119,13 +142,15 @@ The rules, stated as imports: state-machine adapter, its own hooks, the DOM utils, and — for a DOM substrate — its primitive's `dom/components` package. Nothing else from this repo. -- A core package imports only the state-machine runtime and the agnostic - bindings vocabulary. +- A core package imports only the state-machine runtime, the agnostic + bindings vocabulary, and the agnostic utils under `core/utils/`. An agnostic + util imports at most the state-machine runtime. - A DOM util imports nothing from this repo except another DOM util — and only - a smaller one, never a peer that would import it back. A shared predicate - (`isRendered`) is one package so its callers can't drift; the direction of - such an edge is a design decision, recorded in the importing package's - `SPEC.md`. A substrate hook imports only the DOM util it wraps. + a smaller one, never a peer that would import it back — and the agnostic + util it extends for the DOM. A shared predicate (`isRendered`) is one + package so its callers can't drift; the direction of such an edge is a + design decision, recorded in the importing package's `SPEC.md`. A substrate + hook imports only the DOM util it wraps. - A `dom/components` package imports its core counterpart and the DOM utils — never a framework, and never another primitive. - Primitives are independent of each other. If two need to share logic, that diff --git a/README.md b/README.md index e556ba3..6056e6b 100644 --- a/README.md +++ b/README.md @@ -55,6 +55,11 @@ renders, not how machines execute. - **`core/`** — the behavior. One package per primitive: a framework-free state machine. No DOM, no framework. Published as `@dunky.dev/`. +- **`core/utils/`** — agnostic utilities shared across primitives: the logic + every host needs but no host owns (controlled/uncontrolled state, the + overlay-layer stack). No env assumptions, no framework. A platform layer + extends them for its host (`dom/utils/overlay` builds on `core/utils/overlay`). + Published as `@dunky.dev/`. - **`dom/utils/`** — framework-free DOM utilities shared across primitives and substrates (focus trap, scroll lock, overlay stacking). Published as `@dunky.dev/dom-`. @@ -66,7 +71,7 @@ renders, not how machines execute. `solid/`, `native/`) that wires the machine to real elements. Published as `@dunky.dev/-` (e.g. `@dunky.dev/react-dialog`). -The dependency direction is one-way: `substrate -> dom -> core`. A binding +The layers build one way: `core -> dom -> substrate`. A binding adds no behavior of its own — if a decision is needed, it moves into the core machine so every substrate inherits it. The deep reference is [ARCHITECTURE.md](./ARCHITECTURE.md).