keeps nodes by key keeps your listeners keeps what users typed patches attributes in place awaits its transition
df$ selects real elements with native CSS selectors and returns them as a real Array. Content writes such as html(), text() and empty() go through the defuss-morph engine, which diffs the new content against the live DOM and patches it in place. Events and forms stay native: addEventListener and FormData.
Built by Aron Homberg (kyr0) (opens in a new tab). Open source (MIT (opens in a new tab))
<script type="module" src="https://cdn.jsdelivr.net/npm/defuss-morph@latest/dist/all.min.js"></script><script type="module" src="https://cdn.jsdelivr.net/npm/defuss-query@latest/dist/all.min.js"></script><script type="module"> // html() runs defuss-morph, not innerHTML: the list is // patched in place, both <li> are kept and reordered df$("#list").html('<li key="b">B</li><li key="a">A</li>'); df$("#list li") .addClass("ready") .on("click", (e) => { df$(e.currentTarget).text("Saved"); });</script>df$Call it to select: CSS selectors, markup, VNodes, elements or collections. Read it as a namespace: df$.morph() and every other morph export sit on the same function.
Content writes are diffed against the live DOM. Keyed and id-matched nodes are moved, not recreated, so their listeners and typed values survive, and focus stays on an element that keeps its place.
A selection is an Array subclass: map, some and for...of just work. Its members are fixed when it is created; traversal returns a new selection, setters return the same one.
on() is addEventListener on each target, so stopPropagation(), non-bubbling events and currentTarget behave as usual. When morph removes an element, its listeners go with it.
form() returns the browser's own FormData with duplicate names, files and the submitter; serialize() URL-encodes its string entries. No hand-rolled form walker.
The CDN bundle is 4.2 kB gzipped, imports nothing and does not embed morph. The npm entry writes no global and reads no document on import.
Every change renders the whole list again as VNodes with df$("#tasks").morph(rows). Shuffle, sort or reverse it: the number on each row names its DOM element and does not change, because morph moves the keyed rows instead of rebuilding them. The inspector counts the elements each render kept, created and removed. The frame runs the bundles this site serves, with shadcn styles and no other script.
Try a reorder with the fade transition: morph() returns a Promise when you pass transition.
Each snippet runs on this page's df$ against a fresh copy of the sandbox below. The report lists what the snippet returned and which sandbox elements survived, were created or were removed. Compare the morph reorder with the innerHTML one.
Snippets
Pick a snippet.defuss-query adds no second reconciler and no second event system. It selects with the platform, writes content through defuss-morph and does the exact inserts and removals morph has no primitive for. The design rationale is in ARCH.md (opens in a new tab).
df$ to selectEvery call returns a DfQuery: an Array subclass, deduplicated, in encounter order.
df$(".card") // querySelectorAlldf$("button", dialog) // with a context rootdf$("<li>New</li>") // parse markup into nodesdf$({ type: "b", children: ["x"] }) // render a VNodedf$(element) / df$(nodeList) // wrap targetsdf$(() => start()) // run when the DOM is readydf$ as a namespaceThe morph API is copied onto the function, plus three reserved slots.
df$.morph(el, "<p>Hi</p>") // the engine itselfdf$.renderMarkup(vnode) // any other morph exportdf$.fn // DfQuery.prototypedf$.dom // the structural adapterdf$.queryVersion // the package version stringhtml()A markup string becomes VNodes through morph's parser; standalone <tr>, <td> or <option> get their table or select context. VNodes and DOM nodes are snapshotted as VNodes.
morph() compares the VNodes with each element's live children. Nodes matched by key or id are moved; attributes are patched in place.
Elements morph removes run its cleanup, and a hook defuss-query registers removes their on() listeners. Matched elements keep theirs.
Without transition the call is synchronous and returns the selection for chaining. With one it returns a Promise of the selection, after every element's transition settled.
| Entry | For | Contract |
|---|---|---|
dist/all.min.js | CDN, module script | Upgrades the morph global window.df$ into the callable. No imports, morph not embedded. |
dist/global.min.js | Classic script | The same installation as a classic script, for loaders that need deterministic execution. |
defuss-query | npm, bundlers, servers | Imports the defuss-morph peer, writes no global, reads no document on import. ESM and CommonJS. |
defuss-query/core | Your own morph | createDf$(morph) builds a df$ around the morph instance you pass. |
Load morph before query. The other order works with morph 0.1.1 or later: selectors work at once, content writes once morph has loaded.
The declarations ship in the package (dist/index.d.ts); the agent-facing reference is SKILL.md (opens in a new tab), which ships in the npm package too.
A string starting with < (after whitespace) is markup; any other string is a selector. Collections must contain EventTargets; anything else throws a TypeError.
| Call | Returns | Semantics |
|---|---|---|
df$(selector, context?) | DfQuery<Element> | querySelectorAll on context (Document, Element or DocumentFragment), default the document. Tag names give precise types: df$("button") is DfQuery<HTMLButtonElement>. |
df$("<markup>"), df$(vnode) | DfQuery<Node> | New detached nodes; several roots allowed. |
df$(target | targets) | DfQuery<T> | Wraps an EventTarget (element, document, window) or an iterable or array-like of them. |
df$(fn) | DfQuery<Document> | Runs fn(df$) on DOMContentLoaded, or in a microtask when the document is already parsed. |
df$(), df$(null) | DfQuery | An empty selection. |
[i], .length, .get(i?), .toArray() | item or array | Array access; get() and toArray() return copies, get(-1) counts from the end. |
.eq(i), .first(), .last() | new selection | One item; negative indices count from the end. |
.each(fn) | this | jQuery order (index, element) with this bound to the element; returning false stops. |
.find(css), .filter(css | fn), .is(css) | selection, boolean | Descendants, matching subset, any match. .find(fn) keeps the native Array behavior. |
.parent(), .children(css?), .closest(css), .next(), .prev() | new selection | Element traversal, deduplicated in encounter order. |
.map(), .slice(), .flat() | plain Array | Species-based Array methods return ordinary arrays. |
Getters read the first element; setters write every element and return the selection. Non-element targets are skipped where a method needs an element.
| Method | Semantics |
|---|---|
.attr(name, value?) | A missing attribute reads null, an empty selection undefined. Setting null removes it. |
.prop(name, value?) | Native JS properties. innerHTML, outerHTML, textContent and innerText writes throw: use the content methods. |
.data(name, value?) | dataset with camelCase keys; values are strings, null deletes. No cache, no JSON coercion. |
.css(name | map, value?) | Getters read the computed style, setters write inline style. camelCase and custom properties work; no implicit px. |
.addClass(), .removeClass(), .toggleClass(names, force?), .hasClass() | Whitespace strings or string arrays. removeClass() without arguments clears the attribute. |
.val(value?) | Control values; a multiple select reads and writes string arrays, an array on checkboxes and radios sets checked by value. Dispatches no input or change. |
Content methods accept markup strings, VNodes, nodes, NodeLists and fragments. With several targets, nodes are cloned for all but the last target, which receives the originals.
| Method | Returns | Semantics |
|---|---|---|
.morph(content, options?) | this or Promise<this> | Morphs the content into every element. Passing transition makes it async, even { type: "none" }. |
.html(content?, options?) | string or as morph() | Without arguments: the first element's innerHTML (its open shadow root's for normal elements). With content: morph(). |
.text(value?) | string or this | Reads the concatenated text. Writes literal text, never parsed as HTML; Text and CDATA nodes keep their identity. |
.empty() | this | Morphs an empty list into every element. |
.append(), .prepend(), .before(), .after() | this | Exact inserts with insertBefore. A batch that would insert an ancestor into its descendant throws before any write. |
.replaceWith(content) | this | Inserts the content before each target, then removes the target. |
.appendTo(target) | inserted nodes | Appends this selection to a selector, root or collection and selects the inserted nodes. |
.remove() | this | Detaches every node after running morph's cleanup, which also removes on() listeners. |
| Method | Semantics |
|---|---|
.on(types, handler, capture?) | addEventListener on each target; space-separated types; this is the target. Only capture is accepted (true or { capture: true }); other option keys throw. For elements it needs morph loaded. |
.off(types?, handler?) | Removes listeners that on() added: by handler, by type, or all. Native and VNode listeners stay. |
.trigger(type, detail?) | Dispatches a CustomEvent built in the target's realm: bubbles and cancelable true, composed false. Not trusted input, no default actions. |
.form(submitter?) | The native FormData of a selection that is exactly one form, built with the form's own realm; otherwise throws. A submitter adds its entry. |
.serialize(submitter?) | URL-encoded string entries of form(); file entries are skipped. |
| Name | Semantics |
|---|---|
df$.<morph export> | Every own export of the morph API, with its identity: df$.morph, df$.renderMarkup, df$.queueCallback and the rest. |
df$.fn | DfQuery.prototype, for adding your own chain methods. |
df$.dom | The structural adapter: create, insert, replace, remove, morph, text. |
df$.queryVersion | The package version string. |
createDf$(morphApi) | From defuss-query/core: a new df$ around the given morph API. |
installGlobal(target?) | The CDN installation: reuses an installed query df$, upgrades the morph object, throws on an unrelated df$ function. |
Sizes are make metrics output for the 0.2.0 build, which this page and the demo load from assets/. The release gate (scripts/verify.ts) fails when a browser bundle gzips above 4,608 bytes, imports a module or embeds the morph engine.
all.min.jsdefuss-morph; the CDN bundle does not embed itmake metricsall.js 30219 bytes 8638 gzip 7453 brotliall.min.js 11342 bytes 4203 gzip 3714 brotliglobal.min.js 11078 bytes 4112 gzip 3626 brotlizlib gzip level 9 and Brotli defaults; stats.json holds the same numbers.Two script tags for a page, or the npm package with its defuss-morph peer for a build. Or hand one prompt to your coding agent.
Load morph first, then query. Module scripts run in document order, so the application script after them sees df$.
<script type="module" src="https://cdn.jsdelivr.net/npm/defuss-morph@latest/dist/all.min.js"></script><script type="module" src="https://cdn.jsdelivr.net/npm/defuss-query@latest/dist/all.min.js"></script><script type="module"> df$("#app").html("<p>Hello</p>");</script><script type="module"> await import("https://cdn.jsdelivr.net/npm/defuss-morph@latest/dist/all.min.js"); const { df$ } = await import("https://cdn.jsdelivr.net/npm/defuss-query@latest/dist/all.min.js"); df$("#app").html("<p>Hello</p>");</script>The npm entry imports the defuss-morph peer (^0.2.0) and has no side effects on import, so server-side imports are safe.
bun add defuss-query defuss-morphimport df$, { type DfQuery } from "defuss-query";const buttons: DfQuery<HTMLButtonElement> = df$("button");buttons.prop("disabled", false).on("click", function (event) { console.log(this.disabled, event.clientX);});Paste this prompt into your coding agent. The package ships SKILL.md, the API reference written for agents.
Use defuss-query for the DOM code in this app: https://github.com/kyr0/defuss-queryInstall defuss-query and defuss-morph, then read node_modules/defuss-query/SKILL.md and follow it.Write content with html(), text() or morph() instead of innerHTML, render lists as keyed VNodes, and put user input only into text() or VNode text.Use on() and off() for listeners and form() for form data.sendGive your agent the defuss-vae skills too: it then plans, tests and reviews against a verifier instead of declaring itself done. In Claude Code, the plugin adds the commit and Stop-hook gate. Needs python3 3.9 or later, git and make.
npx skills add kyr0/defuss-vae --skill '*'claude plugin marketplace add kyr0/defuss-vaeclaude plugin install defuss-vae@defuss-vae
Build more consistent agents with defuss-vae (opens in a new tab), Aron's verification-first skill set: plans, tests and reviews run against a verifier.
For a remote training or mentoring session for you or your engineering team.
Native selectors, real Arrays, native events and forms, and content writes that patch the DOM instead of replacing it.
MIT licensed · 0.2.0 · one peer dependency