From a30894eee396d9c2aeb7a85807f2c96a63d1c895 Mon Sep 17 00:00:00 2001 From: Hunter Garrett Date: Sat, 22 Aug 2026 12:46:12 -0400 Subject: [PATCH 01/12] feat: add the bones-boundary element with delay and reflected properties --- packages/bones/src/element/boundary.ts | 144 +++++++++++++++++++++++++ packages/bones/src/element/index.ts | 24 +++++ packages/bones/tests/boundary.test.ts | 139 ++++++++++++++++++++++++ 3 files changed, 307 insertions(+) create mode 100644 packages/bones/src/element/boundary.ts create mode 100644 packages/bones/src/element/index.ts create mode 100644 packages/bones/tests/boundary.test.ts diff --git a/packages/bones/src/element/boundary.ts b/packages/bones/src/element/boundary.ts new file mode 100644 index 0000000..4ab31fa --- /dev/null +++ b/packages/bones/src/element/boundary.ts @@ -0,0 +1,144 @@ +// --------------------------------------------------------------------------- +// — owns the loading state of its subtree +// +// The element draws nothing. bones.css and auto.css key on aria-busy="true", +// so the element's whole job is to set aria-busy and inert at the right time: +// after `delay` so fast loads never flash a skeleton, and for at least +// `min-duration` so slow ones never strobe. `busy` and `force` are the inputs +// an author controls; aria-busy and inert are outputs the element controls. +// --------------------------------------------------------------------------- + +export const DEFAULT_DELAY = 200; +export const DEFAULT_MIN_DURATION = 400; + +type State = "idle" | "pending" | "showing" | "draining"; + +function parseMs(value: string | null, fallback: number): number { + if (value === null || value.trim() === "") return fallback; + const ms = Number(value); + return Number.isFinite(ms) && ms >= 0 ? ms : fallback; +} + +// `extends HTMLElement` evaluates HTMLElement when the module loads. Node has +// none, and a Next.js client module still runs on the server during SSR, so +// the base class falls back to an empty class there. Registration is skipped +// in that case anyway (see index.ts). +const Base: typeof HTMLElement = + typeof HTMLElement === "undefined" ? (class {} as unknown as typeof HTMLElement) : HTMLElement; + +export class BonesBoundary extends Base { + static readonly observedAttributes = ["busy", "force"]; + + #state: State = "idle"; + #timer: ReturnType | undefined; + #connected = false; + + get busy(): boolean { + return this.hasAttribute("busy"); + } + + set busy(value: boolean) { + this.toggleAttribute("busy", Boolean(value)); + } + + get force(): boolean { + return this.hasAttribute("force"); + } + + set force(value: boolean) { + this.toggleAttribute("force", Boolean(value)); + } + + get delay(): number { + return parseMs(this.getAttribute("delay"), DEFAULT_DELAY); + } + + set delay(value: number) { + if (value === null || value === undefined) this.removeAttribute("delay"); + else this.setAttribute("delay", String(value)); + } + + get minDuration(): number { + return parseMs(this.getAttribute("min-duration"), DEFAULT_MIN_DURATION); + } + + set minDuration(value: number) { + if (value === null || value === undefined) this.removeAttribute("min-duration"); + else this.setAttribute("min-duration", String(value)); + } + + get transition(): "auto" | "none" { + return this.getAttribute("transition") === "none" ? "none" : "auto"; + } + + set transition(value: "auto" | "none") { + if (value === "none") this.setAttribute("transition", "none"); + else this.removeAttribute("transition"); + } + + get showing(): boolean { + return this.#state === "showing" || this.#state === "draining"; + } + + connectedCallback(): void { + this.#connected = true; + this.#evaluate(); + } + + disconnectedCallback(): void { + this.#connected = false; + this.#clearTimer(); + } + + attributeChangedCallback(): void { + // Attributes parsed from markup fire this before connectedCallback; the + // connect path evaluates once for all of them. + if (this.#connected) this.#evaluate(); + } + + #clearTimer(): void { + if (this.#timer !== undefined) clearTimeout(this.#timer); + this.#timer = undefined; + } + + #evaluate(): void { + if (this.force) { + if (this.#state === "draining") { + this.#clearTimer(); + this.#state = "showing"; + } else if (this.#state !== "showing") { + this.#show(); + } + return; + } + + if (this.busy) { + if (this.#state === "idle") { + const delay = this.delay; + if (delay === 0) { + this.#show(); + } else { + this.#state = "pending"; + this.#timer = setTimeout(() => this.#show(), delay); + } + } else if (this.#state === "draining") { + this.#clearTimer(); + this.#state = "showing"; + } + return; + } + + if (this.#state === "pending") { + this.#clearTimer(); + this.#state = "idle"; + } + } + + #show(): void { + this.#clearTimer(); + this.#state = "showing"; + this.setAttribute("aria-busy", "true"); + this.toggleAttribute("inert", true); + this.dispatchEvent(new CustomEvent("bones:show", { bubbles: true, composed: true })); + } +} diff --git a/packages/bones/src/element/index.ts b/packages/bones/src/element/index.ts new file mode 100644 index 0000000..ded6410 --- /dev/null +++ b/packages/bones/src/element/index.ts @@ -0,0 +1,24 @@ +import { BonesBoundary } from "./boundary.ts"; + +export { BonesBoundary, DEFAULT_DELAY, DEFAULT_MIN_DURATION } from "./boundary.ts"; + +declare global { + interface HTMLElementTagNameMap { + "bones-boundary": BonesBoundary; + } + interface HTMLElementEventMap { + "bones:show": CustomEvent; + "bones:hide": CustomEvent; + } +} + +// --------------------------------------------------------------------------- +// Registration on import +// +// `import "@camp.dev/bones/element"` is the whole setup. The guard keeps the +// module importable in Node (no customElements) and safe to import twice. +// --------------------------------------------------------------------------- + +if (typeof customElements !== "undefined" && !customElements.get("bones-boundary")) { + customElements.define("bones-boundary", BonesBoundary); +} diff --git a/packages/bones/tests/boundary.test.ts b/packages/bones/tests/boundary.test.ts new file mode 100644 index 0000000..abca420 --- /dev/null +++ b/packages/bones/tests/boundary.test.ts @@ -0,0 +1,139 @@ +import { afterEach, beforeEach, describe, expect, test, vi } from "vite-plus/test"; +import { BonesBoundary } from "../src/element/index.ts"; + +// --------------------------------------------------------------------------- +// state machine +// +// The element sets aria-busy and inert as output; busy and force are input. +// Fake timers drive delay and min-duration, and Date.now() is faked with them, +// so shownAt math is deterministic. +// --------------------------------------------------------------------------- + +function mount(attrs: Record = {}): BonesBoundary { + const el = document.createElement("bones-boundary"); + for (const [name, value] of Object.entries(attrs)) el.setAttribute(name, value); + el.innerHTML = "

copy

"; + document.body.append(el); + return el; +} + +function events(el: HTMLElement): string[] { + const log: string[] = []; + el.addEventListener("bones:show", () => log.push("show")); + el.addEventListener("bones:hide", () => log.push("hide")); + return log; +} + +function shown(el: HTMLElement): boolean { + return el.getAttribute("aria-busy") === "true" && el.hasAttribute("inert"); +} + +beforeEach(() => { + vi.useFakeTimers(); +}); + +afterEach(() => { + document.body.innerHTML = ""; + vi.useRealTimers(); +}); + +describe("registration and reflection", () => { + test("importing the module registers bones-boundary", () => { + expect(customElements.get("bones-boundary")).toBe(BonesBoundary); + expect(mount()).toBeInstanceOf(BonesBoundary); + }); + + test("boolean properties reflect to attributes", () => { + const el = mount(); + el.busy = true; + expect(el.hasAttribute("busy")).toBe(true); + el.busy = false; + expect(el.hasAttribute("busy")).toBe(false); + el.force = true; + expect(el.hasAttribute("force")).toBe(true); + el.force = false; + expect(el.hasAttribute("force")).toBe(false); + // React 19 assigns null when a prop is removed. + el.busy = null as unknown as boolean; + expect(el.hasAttribute("busy")).toBe(false); + }); + + test("numeric properties parse attributes and fall back to defaults", () => { + const el = mount(); + expect(el.delay).toBe(200); + expect(el.minDuration).toBe(400); + el.setAttribute("delay", "50"); + expect(el.delay).toBe(50); + el.minDuration = 10; + expect(el.getAttribute("min-duration")).toBe("10"); + expect(el.minDuration).toBe(10); + for (const bad of ["abc", "-1", "Infinity", ""]) { + el.setAttribute("delay", bad); + expect(el.delay).toBe(200); + } + el.delay = null as unknown as number; + expect(el.hasAttribute("delay")).toBe(false); + expect(el.delay).toBe(200); + }); + + test("transition reads auto unless the attribute is none", () => { + const el = mount(); + expect(el.transition).toBe("auto"); + el.setAttribute("transition", "anything"); + expect(el.transition).toBe("auto"); + el.transition = "none"; + expect(el.getAttribute("transition")).toBe("none"); + el.transition = "auto"; + expect(el.hasAttribute("transition")).toBe(false); + }); +}); + +describe("delay", () => { + test("busy shows bones after the delay with aria-busy, inert, and one bones:show", () => { + const el = mount(); + const log = events(el); + el.busy = true; + expect(shown(el)).toBe(false); + expect(el.showing).toBe(false); + vi.advanceTimersByTime(199); + expect(shown(el)).toBe(false); + vi.advanceTimersByTime(1); + expect(shown(el)).toBe(true); + expect(el.showing).toBe(true); + expect(log).toEqual(["show"]); + }); + + test("busy cleared during the delay never shows and fires nothing", () => { + const el = mount(); + const log = events(el); + el.busy = true; + vi.advanceTimersByTime(100); + el.busy = false; + vi.advanceTimersByTime(1000); + expect(shown(el)).toBe(false); + expect(log).toEqual([]); + }); + + test("a busy attribute present at connect starts the delay from connect", () => { + const el = mount({ busy: "" }); + vi.advanceTimersByTime(199); + expect(shown(el)).toBe(false); + vi.advanceTimersByTime(1); + expect(shown(el)).toBe(true); + }); + + test("a custom delay attribute is honored", () => { + const el = mount({ delay: "50" }); + el.busy = true; + vi.advanceTimersByTime(49); + expect(shown(el)).toBe(false); + vi.advanceTimersByTime(1); + expect(shown(el)).toBe(true); + }); + + test("delay=0 shows synchronously", () => { + const el = mount({ delay: "0" }); + el.busy = true; + expect(shown(el)).toBe(true); + }); +}); From 4ec686bd4c25f8ccd64f05b91222dade387acf24 Mon Sep 17 00:00:00 2001 From: Hunter Garrett Date: Sat, 22 Aug 2026 12:51:44 -0400 Subject: [PATCH 02/12] feat: hold bones for min-duration and add force to bones-boundary --- packages/bones/src/element/boundary.ts | 18 +++++ packages/bones/tests/boundary.test.ts | 102 +++++++++++++++++++++++++ 2 files changed, 120 insertions(+) diff --git a/packages/bones/src/element/boundary.ts b/packages/bones/src/element/boundary.ts index 4ab31fa..e552212 100644 --- a/packages/bones/src/element/boundary.ts +++ b/packages/bones/src/element/boundary.ts @@ -32,6 +32,7 @@ export class BonesBoundary extends Base { #state: State = "idle"; #timer: ReturnType | undefined; #connected = false; + #shownAt = 0; get busy(): boolean { return this.hasAttribute("busy"); @@ -131,14 +132,31 @@ export class BonesBoundary extends Base { if (this.#state === "pending") { this.#clearTimer(); this.#state = "idle"; + } else if (this.#state === "showing") { + const remaining = this.#shownAt + this.minDuration - Date.now(); + if (remaining <= 0) { + this.#hide(); + } else { + this.#state = "draining"; + this.#timer = setTimeout(() => this.#hide(), remaining); + } } } #show(): void { this.#clearTimer(); this.#state = "showing"; + this.#shownAt = Date.now(); this.setAttribute("aria-busy", "true"); this.toggleAttribute("inert", true); this.dispatchEvent(new CustomEvent("bones:show", { bubbles: true, composed: true })); } + + #hide(): void { + this.#clearTimer(); + this.#state = "idle"; + this.removeAttribute("aria-busy"); + this.removeAttribute("inert"); + this.dispatchEvent(new CustomEvent("bones:hide", { bubbles: true, composed: true })); + } } diff --git a/packages/bones/tests/boundary.test.ts b/packages/bones/tests/boundary.test.ts index abca420..a81639c 100644 --- a/packages/bones/tests/boundary.test.ts +++ b/packages/bones/tests/boundary.test.ts @@ -137,3 +137,105 @@ describe("delay", () => { expect(shown(el)).toBe(true); }); }); + +describe("min-duration", () => { + test("bones stay until min-duration has elapsed, then bones:hide fires", () => { + const el = mount(); + const log = events(el); + el.busy = true; + vi.advanceTimersByTime(200); + expect(shown(el)).toBe(true); + vi.advanceTimersByTime(100); + el.busy = false; + expect(shown(el)).toBe(true); + expect(el.showing).toBe(true); + vi.advanceTimersByTime(299); + expect(shown(el)).toBe(true); + vi.advanceTimersByTime(1); + expect(shown(el)).toBe(false); + expect(el.getAttribute("aria-busy")).toBeNull(); + expect(el.hasAttribute("inert")).toBe(false); + expect(el.showing).toBe(false); + expect(log).toEqual(["show", "hide"]); + }); + + test("clearing busy after min-duration hides at once", () => { + const el = mount(); + const log = events(el); + el.busy = true; + vi.advanceTimersByTime(200 + 400); + el.busy = false; + expect(shown(el)).toBe(false); + expect(log).toEqual(["show", "hide"]); + }); + + test("busy set again while draining cancels the hide without a second show", () => { + const el = mount(); + const log = events(el); + el.busy = true; + vi.advanceTimersByTime(200); + el.busy = false; + vi.advanceTimersByTime(100); + el.busy = true; + vi.advanceTimersByTime(1000); + expect(shown(el)).toBe(true); + expect(log).toEqual(["show"]); + }); + + test("min-duration=0 hides at once", () => { + const el = mount({ "min-duration": "0" }); + el.busy = true; + vi.advanceTimersByTime(200); + el.busy = false; + expect(shown(el)).toBe(false); + }); +}); + +describe("force", () => { + test("force shows at once and ignores delay", () => { + const el = mount(); + const log = events(el); + el.force = true; + expect(shown(el)).toBe(true); + expect(log).toEqual(["show"]); + }); + + test("force in markup shows at connect", () => { + const el = mount({ force: "" }); + expect(shown(el)).toBe(true); + }); + + test("force set while draining keeps bones showing", () => { + const el = mount(); + const log = events(el); + el.busy = true; + vi.advanceTimersByTime(200); + el.busy = false; + el.force = true; + vi.advanceTimersByTime(1000); + expect(shown(el)).toBe(true); + expect(log).toEqual(["show"]); + }); + + test("clearing force with busy absent hides after min-duration counted from the force", () => { + const el = mount(); + el.force = true; + vi.advanceTimersByTime(100); + el.force = false; + expect(shown(el)).toBe(true); + vi.advanceTimersByTime(299); + expect(shown(el)).toBe(true); + vi.advanceTimersByTime(1); + expect(shown(el)).toBe(false); + }); + + test("clearing force with busy set keeps showing", () => { + const el = mount(); + el.busy = true; + el.force = true; + vi.advanceTimersByTime(1000); + el.force = false; + vi.advanceTimersByTime(1000); + expect(shown(el)).toBe(true); + }); +}); From f1c373491f85dea3f8e12b06567e6d92bbad1acc Mon Sep 17 00:00:00 2001 From: Hunter Garrett Date: Sat, 22 Aug 2026 12:59:51 -0400 Subject: [PATCH 03/12] feat: animate the bones-boundary swap and adopt server-rendered state --- packages/bones/src/element/boundary.ts | 43 ++++- packages/bones/tests/boundary.test.ts | 209 +++++++++++++++++++++++++ 2 files changed, 249 insertions(+), 3 deletions(-) diff --git a/packages/bones/src/element/boundary.ts b/packages/bones/src/element/boundary.ts index e552212..b90424c 100644 --- a/packages/bones/src/element/boundary.ts +++ b/packages/bones/src/element/boundary.ts @@ -83,12 +83,27 @@ export class BonesBoundary extends Base { connectedCallback(): void { this.#connected = true; + // Server-rendered markup can carry aria-busy="true" so the CSS paints + // bones before this script runs. Adopt that as "showing" rather than + // re-running the delay; min-duration counts from now. + if (this.getAttribute("aria-busy") === "true" && !this.showing) { + this.#show(); + if (!this.busy && !this.force) this.#evaluate(); + return; + } this.#evaluate(); } disconnectedCallback(): void { this.#connected = false; this.#clearTimer(); + // A pending element that gets reparented (moved with appendChild, busy + // unchanged) must restart its delay rather than get stuck: without this, + // connectedCallback's #evaluate sees busy=true and state="pending" (not + // idle or draining) and does nothing. A showing element keeps its + // aria-busy/inert attributes across the move, so connectedCallback's + // adoption path above re-adopts it as showing instead of resetting it. + this.#state = "idle"; } attributeChangedCallback(): void { @@ -155,8 +170,30 @@ export class BonesBoundary extends Base { #hide(): void { this.#clearTimer(); this.#state = "idle"; - this.removeAttribute("aria-busy"); - this.removeAttribute("inert"); - this.dispatchEvent(new CustomEvent("bones:hide", { bubbles: true, composed: true })); + const update = (): void => { + this.removeAttribute("aria-busy"); + this.removeAttribute("inert"); + this.dispatchEvent(new CustomEvent("bones:hide", { bubbles: true, composed: true })); + }; + if (this.#canTransition()) { + document.startViewTransition(update); + } else { + update(); + } + } + + // Showing never animates: a crossfade into a skeleton only delays the + // loading state. Hiding animates when the page allows it. + #canTransition(): boolean { + if (this.transition === "none") return false; + if (typeof document.startViewTransition !== "function") return false; + if ( + typeof window !== "undefined" && + typeof window.matchMedia === "function" && + window.matchMedia("(prefers-reduced-motion: reduce)").matches + ) { + return false; + } + return true; } } diff --git a/packages/bones/tests/boundary.test.ts b/packages/bones/tests/boundary.test.ts index a81639c..3dccc39 100644 --- a/packages/bones/tests/boundary.test.ts +++ b/packages/bones/tests/boundary.test.ts @@ -239,3 +239,212 @@ describe("force", () => { expect(shown(el)).toBe(true); }); }); + +// --------------------------------------------------------------------------- +// View transitions. jsdom has neither startViewTransition nor matchMedia, so +// each test installs what it needs and the afterEach removes it. +// --------------------------------------------------------------------------- + +// Omit + intersect rather than plain intersect: this lib's DOM types already +// declare startViewTransition/matchMedia with stricter, non-optional +// signatures, so a plain intersection would merge the real property type +// with the mock's and reject the mock as unassignable. +type TransitionDoc = Omit & { + startViewTransition?: (update: () => void) => unknown; +}; +type MediaWindow = Omit & { + matchMedia?: (query: string) => { matches: boolean }; +}; + +function stubTransition() { + const fn = vi.fn((update: () => void) => { + update(); + return {}; + }); + (document as TransitionDoc).startViewTransition = fn; + return fn; +} + +function stubReducedMotion(matches: boolean) { + (window as MediaWindow).matchMedia = vi.fn(() => ({ matches })); +} + +describe("view transitions", () => { + afterEach(() => { + delete (document as TransitionDoc).startViewTransition; + delete (window as MediaWindow).matchMedia; + }); + + test("hide runs inside startViewTransition and show does not", () => { + const fn = stubTransition(); + const el = mount(); + const log = events(el); + el.busy = true; + vi.advanceTimersByTime(200); + expect(fn).not.toHaveBeenCalled(); + vi.advanceTimersByTime(400); + el.busy = false; + expect(fn).toHaveBeenCalledTimes(1); + expect(shown(el)).toBe(false); + expect(log).toEqual(["show", "hide"]); + }); + + test("bones:hide fires inside the update callback", () => { + const order: string[] = []; + const fn = vi.fn((update: () => void) => { + order.push("before"); + update(); + order.push("after"); + return {}; + }); + (document as TransitionDoc).startViewTransition = fn; + const el = mount({ delay: "0", "min-duration": "0" }); + el.addEventListener("bones:hide", () => order.push("hide")); + el.busy = true; + el.busy = false; + expect(order).toEqual(["before", "hide", "after"]); + }); + + test("transition=none skips startViewTransition", () => { + const fn = stubTransition(); + const el = mount({ delay: "0", "min-duration": "0", transition: "none" }); + el.busy = true; + el.busy = false; + expect(fn).not.toHaveBeenCalled(); + expect(shown(el)).toBe(false); + }); + + test("reduced motion skips startViewTransition", () => { + const fn = stubTransition(); + stubReducedMotion(true); + const el = mount({ delay: "0", "min-duration": "0" }); + el.busy = true; + el.busy = false; + expect(fn).not.toHaveBeenCalled(); + expect(shown(el)).toBe(false); + }); + + test("a matchMedia that does not match still allows the transition", () => { + const fn = stubTransition(); + stubReducedMotion(false); + const el = mount({ delay: "0", "min-duration": "0" }); + el.busy = true; + el.busy = false; + expect(fn).toHaveBeenCalledTimes(1); + }); + + test("hide completes when startViewTransition is absent", () => { + const el = mount({ delay: "0", "min-duration": "0" }); + const log = events(el); + el.busy = true; + el.busy = false; + expect(shown(el)).toBe(false); + expect(log).toEqual(["show", "hide"]); + }); +}); + +describe("server-rendered state", () => { + test("an element connected with aria-busy=true adopts showing", () => { + const el = document.createElement("bones-boundary"); + el.setAttribute("busy", ""); + el.setAttribute("aria-busy", "true"); + el.setAttribute("inert", ""); + document.body.append(el); + expect(el.showing).toBe(true); + expect(shown(el)).toBe(true); + }); + + test("min-duration counts from connect for adopted state", () => { + const el = document.createElement("bones-boundary"); + el.setAttribute("busy", ""); + el.setAttribute("aria-busy", "true"); + document.body.append(el); + el.busy = false; + expect(shown(el)).toBe(true); + vi.advanceTimersByTime(399); + expect(shown(el)).toBe(true); + vi.advanceTimersByTime(1); + expect(shown(el)).toBe(false); + }); + + test("aria-busy without busy or force still adopts, then hides after min-duration", () => { + const el = document.createElement("bones-boundary"); + el.setAttribute("aria-busy", "true"); + document.body.append(el); + expect(el.showing).toBe(true); + vi.advanceTimersByTime(400); + expect(shown(el)).toBe(false); + }); +}); + +describe("disconnect", () => { + test("removing the element clears timers and fires nothing", () => { + const el = mount(); + const log = events(el); + el.busy = true; + el.remove(); + vi.advanceTimersByTime(1000); + expect(shown(el)).toBe(false); + expect(log).toEqual([]); + }); + + test("removing a draining element leaves its attributes alone and fires nothing more", () => { + const el = mount(); + const log = events(el); + el.busy = true; + vi.advanceTimersByTime(200); + el.busy = false; + el.remove(); + vi.advanceTimersByTime(1000); + expect(log).toEqual(["show"]); + }); + + test("an element moved while pending restarts its delay", () => { + const el = mount(); + el.busy = true; + vi.advanceTimersByTime(100); + const other = document.createElement("div"); + document.body.append(other); + other.append(el); + vi.advanceTimersByTime(199); + expect(shown(el)).toBe(false); + vi.advanceTimersByTime(1); + expect(shown(el)).toBe(true); + }); + + test("a showing element that is moved keeps its bones and still hides", () => { + const el = mount(); + el.busy = true; + vi.advanceTimersByTime(200); + const other = document.createElement("div"); + document.body.append(other); + other.append(el); + expect(shown(el)).toBe(true); + expect(el.showing).toBe(true); + el.busy = false; + vi.advanceTimersByTime(399); + expect(shown(el)).toBe(true); + vi.advanceTimersByTime(1); + expect(shown(el)).toBe(false); + }); +}); + +describe("auto.css contract", () => { + test("a leaf inside a showing boundary matches the auto.css text-leaf selector", async () => { + const { readFileSync } = await import("node:fs"); + const { join } = await import("node:path"); + const css = readFileSync(join(import.meta.dirname, "../src/css/auto.css"), "utf8"); + // Search past the file's header comment: its prose mentions the literal + // text `[aria-busy="true"]` before the first real rule does. + const layerStart = css.indexOf("@layer bones-auto"); + const start = css.indexOf('[aria-busy="true"]', layerStart); + const selector = css.slice(start, css.indexOf("{", start)).replace(/\s+/g, " ").trim(); + const el = mount({ delay: "0", "min-duration": "0" }); + const leaf = el.querySelector("p")!; + expect(leaf.matches(selector)).toBe(false); + el.busy = true; + expect(leaf.matches(selector)).toBe(true); + el.busy = false; + expect(leaf.matches(selector)).toBe(false); + }); +}); From 0a6c49b75af6c1413a56381a98e28775a6c05635 Mon Sep 17 00:00:00 2001 From: Hunter Garrett Date: Sat, 22 Aug 2026 13:09:52 -0400 Subject: [PATCH 04/12] fix: keep a moved bones-boundary on its original schedule --- packages/bones/src/element/boundary.ts | 16 +++++++++---- packages/bones/tests/boundary.test.ts | 33 ++++++++++++++++++++++---- 2 files changed, 39 insertions(+), 10 deletions(-) diff --git a/packages/bones/src/element/boundary.ts b/packages/bones/src/element/boundary.ts index b90424c..ac01a68 100644 --- a/packages/bones/src/element/boundary.ts +++ b/packages/bones/src/element/boundary.ts @@ -100,10 +100,12 @@ export class BonesBoundary extends Base { // A pending element that gets reparented (moved with appendChild, busy // unchanged) must restart its delay rather than get stuck: without this, // connectedCallback's #evaluate sees busy=true and state="pending" (not - // idle or draining) and does nothing. A showing element keeps its - // aria-busy/inert attributes across the move, so connectedCallback's - // adoption path above re-adopts it as showing instead of resetting it. - this.#state = "idle"; + // idle or draining) and does nothing. A showing or draining element keeps + // its state (and its aria-busy/inert attributes) across the move: it + // already has a live skeleton on screen and must keep its original + // min-duration clock rather than re-fire bones:show and restart the + // window from the reconnect time. + if (this.#state === "pending") this.#state = "idle"; } attributeChangedCallback(): void { @@ -147,7 +149,11 @@ export class BonesBoundary extends Base { if (this.#state === "pending") { this.#clearTimer(); this.#state = "idle"; - } else if (this.#state === "showing") { + } else if (this.showing) { + // Covers both "showing" and "draining": a reconnected draining element + // (its timer was cleared by disconnectedCallback) reschedules the + // remainder of its original min-duration window rather than a fresh one. + this.#clearTimer(); const remaining = this.#shownAt + this.minDuration - Date.now(); if (remaining <= 0) { this.#hide(); diff --git a/packages/bones/tests/boundary.test.ts b/packages/bones/tests/boundary.test.ts index 3dccc39..2067b39 100644 --- a/packages/bones/tests/boundary.test.ts +++ b/packages/bones/tests/boundary.test.ts @@ -397,6 +397,8 @@ describe("disconnect", () => { el.remove(); vi.advanceTimersByTime(1000); expect(log).toEqual(["show"]); + expect(el.getAttribute("aria-busy")).toBe("true"); + expect(el.hasAttribute("inert")).toBe(true); }); test("an element moved while pending restarts its delay", () => { @@ -414,18 +416,39 @@ describe("disconnect", () => { test("a showing element that is moved keeps its bones and still hides", () => { const el = mount(); + const log = events(el); el.busy = true; - vi.advanceTimersByTime(200); + vi.advanceTimersByTime(200); // shows at t=200, shownAt=200 + vi.advanceTimersByTime(100); // t=300, still showing (busy), 100ms since show const other = document.createElement("div"); document.body.append(other); other.append(el); + // The move must not re-fire bones:show or reset the min-duration clock. expect(shown(el)).toBe(true); - expect(el.showing).toBe(true); - el.busy = false; - vi.advanceTimersByTime(399); + expect(log).toEqual(["show"]); + el.busy = false; // t=300: 300ms remain until 400ms since the original show + vi.advanceTimersByTime(299); // t=599, still short of t=600 expect(shown(el)).toBe(true); - vi.advanceTimersByTime(1); + vi.advanceTimersByTime(1); // t=600 = 400ms after the ORIGINAL show at t=200 expect(shown(el)).toBe(false); + expect(log).toEqual(["show", "hide"]); + }); + + test("a draining element that is moved hides on its original schedule", () => { + const el = mount(); + const log = events(el); + el.busy = true; + vi.advanceTimersByTime(200); // shows at t=200, shownAt=200 + el.busy = false; // draining starts at t=200, scheduled to hide at t=600 + vi.advanceTimersByTime(350); // t=550, still draining, 50ms left + const other = document.createElement("div"); + document.body.append(other); + other.append(el); + vi.advanceTimersByTime(49); // t=599, still short of t=600 + expect(shown(el)).toBe(true); + vi.advanceTimersByTime(1); // t=600 = 400ms after the original show at t=200 + expect(shown(el)).toBe(false); + expect(log).toEqual(["show", "hide"]); }); }); From 4292aa10251646f5665b09ce60ab1d853cbd58de Mon Sep 17 00:00:00 2001 From: Hunter Garrett Date: Sat, 22 Aug 2026 13:14:49 -0400 Subject: [PATCH 05/12] feat: publish @camp.dev/bones/element --- packages/bones/package.json | 4 +++- packages/bones/vite.config.ts | 2 +- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/packages/bones/package.json b/packages/bones/package.json index a9bb593..cd8485d 100644 --- a/packages/bones/package.json +++ b/packages/bones/package.json @@ -18,10 +18,12 @@ ], "type": "module", "sideEffects": [ - "*.css" + "*.css", + "./dist/element/index.mjs" ], "exports": { ".": "./dist/index.mjs", + "./element": "./dist/element/index.mjs", "./react": "./dist/react/index.mjs", "./package.json": "./package.json", "./css": { diff --git a/packages/bones/vite.config.ts b/packages/bones/vite.config.ts index e0c1f0e..8f41a84 100644 --- a/packages/bones/vite.config.ts +++ b/packages/bones/vite.config.ts @@ -5,7 +5,7 @@ export default defineConfig({ "*": "vp check --fix", }, pack: { - entry: ["src/index.ts", "src/react/index.ts"], + entry: ["src/index.ts", "src/react/index.ts", "src/element/index.ts"], unbundle: true, copy: "src/css", dts: { From 15b12ae6d5edc6ff2449f3b233be03cce051da7b Mon Sep 17 00:00:00 2001 From: Hunter Garrett Date: Sat, 22 Aug 2026 13:18:45 -0400 Subject: [PATCH 06/12] feat: add the BonesBoundary React wrapper Hook-free wrapper around for src/react/index.ts. onbones:show/onbones:hide bound as React 19 custom-element event listeners and were called in tests as expected, so no ref-based fallback was needed. --- packages/bones/src/react/boundary.ts | 75 ++++++++++++++ packages/bones/src/react/index.ts | 2 + packages/bones/tests/boundary-react.test.tsx | 101 +++++++++++++++++++ 3 files changed, 178 insertions(+) create mode 100644 packages/bones/src/react/boundary.ts create mode 100644 packages/bones/tests/boundary-react.test.tsx diff --git a/packages/bones/src/react/boundary.ts b/packages/bones/src/react/boundary.ts new file mode 100644 index 0000000..db02e48 --- /dev/null +++ b/packages/bones/src/react/boundary.ts @@ -0,0 +1,75 @@ +import { createElement, type CSSProperties, type ReactNode, type Ref } from "react"; + +// --------------------------------------------------------------------------- +// — typed wrapper for the element +// +// No hooks, so it renders inside server components like does. The +// attribute names are spelled out because React 19 serializes unknown props +// on a custom element by their prop name, and the element observes +// `min-duration`, not `minDuration`. Event props use React 19's rule for +// custom elements: an `on*` prop becomes addEventListener with the rest of +// the name as the event type. The element is registered by importing +// `@camp.dev/bones/element` once in a client entry; this file does not do it. +// --------------------------------------------------------------------------- + +type ElementAttributes = { + busy?: boolean; + force?: boolean; + delay?: number; + "min-duration"?: number; + transition?: "auto" | "none"; + inert?: boolean; + "aria-busy"?: "true" | "false"; + class?: string; + className?: string; + style?: CSSProperties; + id?: string; + children?: ReactNode; + ref?: Ref; + [dataAttribute: `data-${string}`]: string | number | boolean | undefined; +}; + +declare module "react" { + namespace JSX { + interface IntrinsicElements { + "bones-boundary": ElementAttributes; + } + } +} + +export interface BonesBoundaryProps extends Omit< + ElementAttributes, + "min-duration" | "inert" | "aria-busy" | "class" +> { + minDuration?: number; + onShow?: (event: CustomEvent) => void; + onHide?: (event: CustomEvent) => void; +} + +export function BonesBoundary({ + busy, + force, + delay, + minDuration, + transition, + onShow, + onHide, + children, + ...rest +}: BonesBoundaryProps): ReactNode { + return createElement( + "bones-boundary", + { + ...rest, + busy: busy ? true : undefined, + force: force ? true : undefined, + delay, + "min-duration": minDuration, + transition, + ...(force ? { "aria-busy": "true", inert: true } : {}), + "onbones:show": onShow, + "onbones:hide": onHide, + }, + children, + ); +} diff --git a/packages/bones/src/react/index.ts b/packages/bones/src/react/index.ts index 69026b6..a072296 100644 --- a/packages/bones/src/react/index.ts +++ b/packages/bones/src/react/index.ts @@ -1,5 +1,7 @@ export { createBones, readPromise, forceBones, minMax, isMinMax } from "./create-bones.ts"; export { Bones, BonesForce } from "./bones.ts"; +export { BonesBoundary } from "./boundary.ts"; +export type { BonesBoundaryProps } from "./boundary.ts"; export type { BoneType, BoneOptions, diff --git a/packages/bones/tests/boundary-react.test.tsx b/packages/bones/tests/boundary-react.test.tsx new file mode 100644 index 0000000..07f9718 --- /dev/null +++ b/packages/bones/tests/boundary-react.test.tsx @@ -0,0 +1,101 @@ +import { act, cleanup, render } from "@testing-library/react"; +import { renderToString } from "react-dom/server"; +import { afterEach, describe, expect, test, vi } from "vite-plus/test"; +import "../src/element/index.ts"; +import { BonesBoundary } from "../src/react/index.ts"; + +// --------------------------------------------------------------------------- +// is a hook-free wrapper. It maps camelCase props to the +// element's attribute names so server output drives the element before +// hydration, and relies on React 19's custom-element handling for the rest. +// --------------------------------------------------------------------------- + +afterEach(() => { + cleanup(); + vi.useRealTimers(); +}); + +describe("server rendering", () => { + test("maps props to attribute names", () => { + const html = renderToString( + +

copy

+ , + ); + expect(html).toContain("copy

"); + }); + + test("busy=false emits no busy attribute", () => { + const html = renderToString(x); + expect(html).not.toContain("busy"); + }); + + test("force emits aria-busy and inert so the server paints bones", () => { + const html = renderToString(x); + expect(html).toContain('force=""'); + expect(html).toContain('aria-busy="true"'); + expect(html).toContain('inert=""'); + }); + + test("className and data attributes pass through", () => { + const html = renderToString( + + x + , + ); + expect(html).toContain('class="card"'); + expect(html).toContain('data-testid="b"'); + }); + + test("raw type-checks with the augmented intrinsic element", () => { + const html = renderToString( + + x + , + ); + expect(html).toContain('min-duration="0"'); + }); +}); + +describe("client rendering", () => { + test("busy drives the element and onShow/onHide receive the events", () => { + vi.useFakeTimers(); + const onShow = vi.fn(); + const onHide = vi.fn(); + const { container, rerender } = render( + +

copy

+ , + ); + const el = container.querySelector("bones-boundary")!; + expect(el.busy).toBe(true); + expect(el.getAttribute("aria-busy")).toBeNull(); + act(() => { + vi.advanceTimersByTime(10); + }); + expect(el.getAttribute("aria-busy")).toBe("true"); + expect(onShow).toHaveBeenCalledTimes(1); + expect(onShow.mock.calls[0][0]).toBeInstanceOf(CustomEvent); + rerender( + +

copy

+ , + ); + expect(el.getAttribute("aria-busy")).toBeNull(); + expect(onHide).toHaveBeenCalledTimes(1); + }); + + test("minDuration reaches the element as the min-duration attribute", () => { + const { container } = render(x); + const el = container.querySelector("bones-boundary")!; + expect(el.getAttribute("min-duration")).toBe("25"); + expect(el.minDuration).toBe(25); + }); +}); From c5d7e5473ab7455fa80f2c9506a26fab45b0c733 Mon Sep 17 00:00:00 2001 From: Hunter Garrett Date: Sat, 22 Aug 2026 13:24:08 -0400 Subject: [PATCH 07/12] docs: document bones-boundary and add its sandbox page --- .changeset/bones-boundary-element.md | 5 + README.md | 30 ++++- apps/docs/content/docs/api/bones-boundary.mdx | 119 ++++++++++++++++++ apps/docs/content/docs/api/meta.json | 2 +- packages/bones/README.md | 30 ++++- packages/bones/sandbox/boundary.html | 86 +++++++++++++ 6 files changed, 259 insertions(+), 13 deletions(-) create mode 100644 .changeset/bones-boundary-element.md create mode 100644 apps/docs/content/docs/api/bones-boundary.mdx create mode 100644 packages/bones/sandbox/boundary.html diff --git a/.changeset/bones-boundary-element.md b/.changeset/bones-boundary-element.md new file mode 100644 index 0000000..530ec2c --- /dev/null +++ b/.changeset/bones-boundary-element.md @@ -0,0 +1,5 @@ +--- +"@camp.dev/bones": minor +--- + +Add `@camp.dev/bones/element`, a `` custom element that owns the loading state of its subtree. Set `busy` and the element sets `aria-busy="true"` and `inert` after a `delay` (200 ms), keeps them for at least `min-duration` (400 ms), and removes them inside a view transition where the browser supports one. It fires `bones:show` and `bones:hide`, honors `force` for demos, and adopts server-rendered `aria-busy` on upgrade. `@camp.dev/bones/react` gains a hook-free `` wrapper. diff --git a/README.md b/README.md index 62da87b..8b15826 100644 --- a/README.md +++ b/README.md @@ -32,12 +32,13 @@ import "@camp.dev/bones/css"; ## Entry points -| Import | Contents | -| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | -| `@camp.dev/bones/react` | `createBones`, `readPromise`, `forceBones`, `minMax`, ``, `` | -| `@camp.dev/bones/css` | The skeleton stylesheet. Import once in your root layout. | -| `@camp.dev/bones/auto.css` | Skeletonizes unmarked leaves under `aria-busy="true"`. Imports the base stylesheet itself, so a separate `/css` import is optional. | -| `@camp.dev/bones` | The framework-agnostic core (`boneAttributes`, `minMax`). You only need this to build your own renderer or adapter. | +| Import | Contents | +| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | +| `@camp.dev/bones/react` | `createBones`, `readPromise`, `forceBones`, `minMax`, ``, `` | +| `@camp.dev/bones/css` | The skeleton stylesheet. Import once in your root layout. | +| `@camp.dev/bones/auto.css` | Skeletonizes unmarked leaves under `aria-busy="true"`. Imports the base stylesheet itself, so a separate `/css` import is optional. | +| `@camp.dev/bones/element` | ``, a custom element that sets `aria-busy` and `inert` on its subtree with `delay`, `min-duration`, and a crossfade. | +| `@camp.dev/bones` | The framework-agnostic core (`boneAttributes`, `minMax`). You only need this to build your own renderer or adapter. | React is an optional peer dependency: installing the package without React is supported and only the `/react` entry requires it. @@ -129,6 +130,23 @@ Set `aria-busy="true"` on the loading region and every unmarked leaf inside it b Auto rules live in `@layer bones-auto`, so any page CSS that sets `color` on an element outranks the bone's transparent text, and that text stays visible over its skeleton bar. `data-bone-animate` also has to sit on an ancestor of the `aria-busy` element — set directly on it, it has no effect. The `data-bone-animate` overrides rely on `@scope`. In a browser without `@scope`, auto bones always shimmer, and `data-bone-animate="pulse"` and `"none"` cannot change that. The `prefers-reduced-motion` fallback to pulse still applies. +## Without React + +`` manages the loading state for any stack. Set `busy` when a request starts and clear it when the response lands. The element waits 200 ms before showing bones and keeps them for at least 400 ms, then crossfades to content with the View Transitions API where available. + +```html + + + +

Title

+

Body copy.

+ +``` + +Pair it with `auto.css` for zero-markup skeletons, or with `data-bone` markup from `boneAttributes`. The element is also exported for React as `` from `@camp.dev/bones/react`. + ## Development ```bash diff --git a/apps/docs/content/docs/api/bones-boundary.mdx b/apps/docs/content/docs/api/bones-boundary.mdx new file mode 100644 index 0000000..fb6911a --- /dev/null +++ b/apps/docs/content/docs/api/bones-boundary.mdx @@ -0,0 +1,119 @@ +--- +title: bones-boundary +description: A custom element that manages the loading state of its subtree. +--- + +```ts +import "@camp.dev/bones/element"; +``` + +`` sets `aria-busy="true"` and `inert` on itself while its subtree is loading, and removes them when it is not. It draws nothing. `@camp.dev/bones/css` styles `data-bone` markup and `@camp.dev/bones/auto.css` styles unmarked leaves, and both key on `aria-busy="true"`. + +Set `busy` when loading starts and remove it when loading ends. The element waits `delay` before it shows bones, so a fast response never flashes a skeleton, and it keeps bones for at least `min-duration`, so a slow one never strobes. + +## Usage + +```html + + + + +

Loading profile

+

Three lines of copy become three bones while busy.

+ + + +``` + +## Attributes + +| Attribute | Property | Type | Default | Description | +| -------------- | ------------- | -------------------- | -------- | ------------------------------------------------------------------ | +| `busy` | `busy` | boolean | absent | The subtree is loading. | +| `force` | `force` | boolean | absent | Show bones now and keep them until removed. Skips both timers. | +| `delay` | `delay` | number (ms) | `200` | How long `busy` must stay set before bones show. | +| `min-duration` | `minDuration` | number (ms) | `400` | Once shown, bones stay at least this long. | +| `transition` | `transition` | `"auto"` or `"none"` | `"auto"` | Whether hiding bones runs inside `document.startViewTransition()`. | + +Every property reflects to its attribute. A `delay` or `min-duration` that is missing, negative, or not a number falls back to the default. The read-only `showing` property is `true` while bones are visible. + +## Output attributes + +While bones show, the element carries `aria-busy="true"` and `inert`. `inert` removes the subtree from the tab order and from assistive technology, and ignores pointer events. Do not set these two attributes yourself on the client. Setting them on the server is how you render the loading state before JavaScript runs (see below). + +## Events + +| Event | When | +| ------------ | --------------------------------------------------------------- | +| `bones:show` | After `aria-busy` and `inert` are set. | +| `bones:hide` | After they are removed. A view transition may still be playing. | + +Both bubble and cross shadow roots. Neither is cancelable. + +```js +boundary.addEventListener("bones:hide", () => console.log("content visible")); +``` + +## The swap + +When `busy` is removed and `min-duration` has elapsed, the element removes its output attributes inside `document.startViewTransition()`, which crossfades bones into content. The call is skipped when `transition="none"` is set, when the browser has no `startViewTransition`, or when `prefers-reduced-motion: reduce` matches. In every case the content appears. + +Two limits of the View Transitions API apply: + +- The API snapshots the whole document. If two boundaries hide within the same crossfade, the browser skips the first transition and runs the second. +- The page does not respond to input for the length of the crossfade. Set `transition="none"` on boundaries where that matters. + +## Server rendering + +Render the output attributes yourself when you know a region is loading at request time: + +```html +… +``` + +The stylesheet paints bones and the subtree is inert before the element upgrades. On upgrade the element adopts the showing state, and `min-duration` counts from that moment. + +## React + +`@camp.dev/bones/react` exports a typed wrapper. Import the element once in a client entry so the tag is registered. + +```tsx +import "@camp.dev/bones/element"; +import { BonesBoundary } from "@camp.dev/bones/react"; + +function Profile({ loading, user }: { loading: boolean; user?: User }) { + return ( + track("profile:visible")}> +

{user?.name ?? "Loading"}

+

{user?.bio ?? "Three lines of copy become three bones while busy."}

+ + ); +} +``` + +| Prop | Maps to | Notes | +| ------------- | -------------- | ------------------------------------------------------------------------------------ | +| `busy` | `busy` | | +| `force` | `force` | Also renders `aria-busy="true"` and `inert` on the server. | +| `delay` | `delay` | | +| `minDuration` | `min-duration` | | +| `transition` | `transition` | | +| `onShow` | `bones:show` | Listener. Passing a function from a server component is an error, as with `onClick`. | +| `onHide` | `bones:hide` | Same. | + +The wrapper uses no hooks, so it renders inside server components. `` and Suspense do not need it: the Suspense fallback renders `data-bone` markup that the stylesheet styles on its own. + +## Browser support + +Custom elements, `inert` (Chrome 102, Safari 15.5, Firefox 112), and the `:has()` selector that `auto.css` already needs. View Transitions are detected at runtime. diff --git a/apps/docs/content/docs/api/meta.json b/apps/docs/content/docs/api/meta.json index 7bcf1d8..1ade7af 100644 --- a/apps/docs/content/docs/api/meta.json +++ b/apps/docs/content/docs/api/meta.json @@ -1,4 +1,4 @@ { "title": "API Reference", - "pages": ["create-bones", "bones-component", "bones-force", "force-bones"] + "pages": ["create-bones", "bones-component", "bones-force", "force-bones", "bones-boundary"] } diff --git a/packages/bones/README.md b/packages/bones/README.md index 64b4a73..7c08650 100644 --- a/packages/bones/README.md +++ b/packages/bones/README.md @@ -32,12 +32,13 @@ import "@camp.dev/bones/css"; ## Entry points -| Import | Contents | -| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | -| `@camp.dev/bones/react` | `createBones`, `readPromise`, `forceBones`, `minMax`, ``, `` | -| `@camp.dev/bones/css` | The skeleton stylesheet. Import once in your root layout. | -| `@camp.dev/bones/auto.css` | Skeletonizes unmarked leaves under `aria-busy="true"`. Imports the base stylesheet itself, so a separate `/css` import is optional. | -| `@camp.dev/bones` | The framework-agnostic core (`boneAttributes`, `minMax`). You only need this to build your own renderer or adapter. | +| Import | Contents | +| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | +| `@camp.dev/bones/react` | `createBones`, `readPromise`, `forceBones`, `minMax`, ``, `` | +| `@camp.dev/bones/css` | The skeleton stylesheet. Import once in your root layout. | +| `@camp.dev/bones/auto.css` | Skeletonizes unmarked leaves under `aria-busy="true"`. Imports the base stylesheet itself, so a separate `/css` import is optional. | +| `@camp.dev/bones/element` | ``, a custom element that sets `aria-busy` and `inert` on its subtree with `delay`, `min-duration`, and a crossfade. | +| `@camp.dev/bones` | The framework-agnostic core (`boneAttributes`, `minMax`). You only need this to build your own renderer or adapter. | React is an optional peer dependency: installing the package without React is supported and only the `/react` entry requires it. @@ -129,6 +130,23 @@ Set `aria-busy="true"` on the loading region and every unmarked leaf inside it b Auto rules live in `@layer bones-auto`, so any page CSS that sets `color` on an element outranks the bone's transparent text, and that text stays visible over its skeleton bar. `data-bone-animate` also has to sit on an ancestor of the `aria-busy` element — set directly on it, it has no effect. The `data-bone-animate` overrides rely on `@scope`. In a browser without `@scope`, auto bones always shimmer, and `data-bone-animate="pulse"` and `"none"` cannot change that. The `prefers-reduced-motion` fallback to pulse still applies. +## Without React + +`` manages the loading state for any stack. Set `busy` when a request starts and clear it when the response lands. The element waits 200 ms before showing bones and keeps them for at least 400 ms, then crossfades to content with the View Transitions API where available. + +```html + + + +

Title

+

Body copy.

+ +``` + +Pair it with `auto.css` for zero-markup skeletons, or with `data-bone` markup from `boneAttributes`. The element is also exported for React as `` from `@camp.dev/bones/react`. + ## Development ```bash diff --git a/packages/bones/sandbox/boundary.html b/packages/bones/sandbox/boundary.html new file mode 100644 index 0000000..9859998 --- /dev/null +++ b/packages/bones/sandbox/boundary.html @@ -0,0 +1,86 @@ + + + + + + bones-boundary sandbox + + + + + + +
+ + + + + +
+ + +

Article title

+

First paragraph with a couple of lines of copy to show the bar geometry.

+

Second paragraph, shorter.

+ avatar + + + + 

+
+    
+  
+

From ce3538a69432a748075f74841b419114d2beb4ce Mon Sep 17 00:00:00 2001
From: Hunter Garrett 
Date: Sat, 22 Aug 2026 14:14:12 -0400
Subject: [PATCH 08/12] fix: defend bones-boundary output attributes and add
 the hiding state

React 19 owns any prop it renders. A  that goes from `force`
to `busy` makes React delete the aria-busy and inert it wrote for `force`,
and the element had no way to notice: it ended up showing with no skeleton
and an interactive subtree. The element now observes both output attributes
and writes them back while it is showing or draining. It leaves them alone
when it is idle, and its own hide is not something it fights.

A view transition runs its update callback a frame or more later, so #hide
setting the state to idle up front left a window where busy or force could
show bones again and then have the queued update strip them anyway. #hide now
moves to a fifth state, "hiding", and the update bails unless the element is
still in it. busy and force during that window go back to showing with no
second bones:show, and an element removed during it fires nothing.

Two smaller fixes ride along. connectedCallback replays own properties left
behind by a script that ran before the module loaded, so `boundary.busy` set
early no longer shadows the accessor for good. A tag name that is already
taken now warns instead of registering nothing in silence.
---
 packages/bones/src/element/boundary.ts | 122 +++++++++++++++++++-----
 packages/bones/src/element/index.ts    |  11 ++-
 packages/bones/tests/boundary.test.ts  | 125 +++++++++++++++++++++++++
 3 files changed, 234 insertions(+), 24 deletions(-)

diff --git a/packages/bones/src/element/boundary.ts b/packages/bones/src/element/boundary.ts
index ac01a68..2c839b4 100644
--- a/packages/bones/src/element/boundary.ts
+++ b/packages/bones/src/element/boundary.ts
@@ -11,7 +11,14 @@
 export const DEFAULT_DELAY = 200;
 export const DEFAULT_MIN_DURATION = 400;
 
-type State = "idle" | "pending" | "showing" | "draining";
+const UPGRADE_PROPERTIES = ["busy", "force", "delay", "minDuration", "transition"] as const;
+type UpgradeProperty = (typeof UPGRADE_PROPERTIES)[number];
+
+// "hiding" is the window a view transition leaves open: #hide has decided to
+// remove the output attributes, but the browser runs the update callback on a
+// later frame. Bones are still on screen, and busy or force arriving in that
+// window must cancel the hide rather than race it.
+type State = "idle" | "pending" | "showing" | "draining" | "hiding";
 
 function parseMs(value: string | null, fallback: number): number {
   if (value === null || value.trim() === "") return fallback;
@@ -27,12 +34,15 @@ const Base: typeof HTMLElement =
   typeof HTMLElement === "undefined" ? (class {} as unknown as typeof HTMLElement) : HTMLElement;
 
 export class BonesBoundary extends Base {
-  static readonly observedAttributes = ["busy", "force"];
+  // aria-busy and inert are outputs, observed only so the element can put
+  // them back when something else strips them. See attributeChangedCallback.
+  static readonly observedAttributes = ["busy", "force", "aria-busy", "inert"];
 
   #state: State = "idle";
   #timer: ReturnType | undefined;
   #connected = false;
   #shownAt = 0;
+  #writingOutput = false;
 
   get busy(): boolean {
     return this.hasAttribute("busy");
@@ -78,10 +88,11 @@ export class BonesBoundary extends Base {
   }
 
   get showing(): boolean {
-    return this.#state === "showing" || this.#state === "draining";
+    return this.#state === "showing" || this.#state === "draining" || this.#state === "hiding";
   }
 
   connectedCallback(): void {
+    for (const name of UPGRADE_PROPERTIES) this.#upgradeProperty(name);
     this.#connected = true;
     // Server-rendered markup can carry aria-busy="true" so the CSS paints
     // bones before this script runs. Adopt that as "showing" rather than
@@ -104,14 +115,49 @@ export class BonesBoundary extends Base {
     // its state (and its aria-busy/inert attributes) across the move: it
     // already has a live skeleton on screen and must keep its original
     // min-duration clock rather than re-fire bones:show and restart the
-    // window from the reconnect time.
-    if (this.#state === "pending") this.#state = "idle";
+    // window from the reconnect time. A hiding element resets too, so the
+    // view transition's queued update finds a state it no longer owns and
+    // bails: a removed element fires no events.
+    if (this.#state === "pending" || this.#state === "hiding") this.#state = "idle";
   }
 
-  attributeChangedCallback(): void {
+  attributeChangedCallback(name: string): void {
     // Attributes parsed from markup fire this before connectedCallback; the
     // connect path evaluates once for all of them.
-    if (this.#connected) this.#evaluate();
+    if (!this.#connected) return;
+    if (name === "aria-busy" || name === "inert") {
+      this.#defendOutput();
+      return;
+    }
+    this.#evaluate();
+  }
+
+  // React 19 owns every prop it renders, so a  that drops
+  // `force` makes React delete the aria-busy and inert it wrote alongside it,
+  // mid-update, while the element still means to show bones. Put them back.
+  // Only in the two states that mean "bones are on screen and staying there":
+  // #hide leaves "showing" and "draining" for "hiding" before it removes
+  // anything, so the element never fights its own hide, and #writingOutput
+  // keeps the reaction from its own setAttribute out of here entirely. An
+  // idle element leaves both attributes alone; they are the author's then.
+  #defendOutput(): void {
+    if (this.#writingOutput) return;
+    if (this.#state !== "showing" && this.#state !== "draining") return;
+    if (this.getAttribute("aria-busy") === "true" && this.hasAttribute("inert")) return;
+    this.#writeOutput(true);
+  }
+
+  // A page that assigns boundary.busy = false before this module loads writes
+  // an own data property onto the element. Upgrading does not remove it, and
+  // it shadows the prototype accessor from then on, so the setter never runs
+  // and the element never reads the attribute again. Replay the value through
+  // the accessor and delete the shadow.
+  #upgradeProperty(name: UpgradeProperty): void {
+    if (!Object.prototype.hasOwnProperty.call(this, name)) return;
+    const self = this as unknown as Partial>;
+    const value = self[name];
+    delete self[name];
+    self[name] = value;
   }
 
   #clearTimer(): void {
@@ -121,9 +167,8 @@ export class BonesBoundary extends Base {
 
   #evaluate(): void {
     if (this.force) {
-      if (this.#state === "draining") {
-        this.#clearTimer();
-        this.#state = "showing";
+      if (this.#state === "draining" || this.#state === "hiding") {
+        this.#resume();
       } else if (this.#state !== "showing") {
         this.#show();
       }
@@ -139,9 +184,8 @@ export class BonesBoundary extends Base {
           this.#state = "pending";
           this.#timer = setTimeout(() => this.#show(), delay);
         }
-      } else if (this.#state === "draining") {
-        this.#clearTimer();
-        this.#state = "showing";
+      } else if (this.#state === "draining" || this.#state === "hiding") {
+        this.#resume();
       }
       return;
     }
@@ -149,10 +193,11 @@ export class BonesBoundary extends Base {
     if (this.#state === "pending") {
       this.#clearTimer();
       this.#state = "idle";
-    } else if (this.showing) {
-      // Covers both "showing" and "draining": a reconnected draining element
-      // (its timer was cleared by disconnectedCallback) reschedules the
-      // remainder of its original min-duration window rather than a fresh one.
+    } else if (this.#state === "showing" || this.#state === "draining") {
+      // A reconnected draining element (its timer was cleared by
+      // disconnectedCallback) reschedules the remainder of its original
+      // min-duration window rather than a fresh one. "hiding" is left out of
+      // this branch on purpose: that hide is already in flight.
       this.#clearTimer();
       const remaining = this.#shownAt + this.minDuration - Date.now();
       if (remaining <= 0) {
@@ -164,21 +209,36 @@ export class BonesBoundary extends Base {
     }
   }
 
+  // Bones never left the screen, so this is not a fresh show: no bones:show,
+  // and shownAt keeps its original value so min-duration still counts from
+  // the first show. The output attributes are written again because whatever
+  // stripped them (React, see attributeChangedCallback) can have run while
+  // the state was "hiding", where the element does not defend them.
+  #resume(): void {
+    this.#clearTimer();
+    this.#state = "showing";
+    this.#writeOutput(true);
+  }
+
   #show(): void {
     this.#clearTimer();
     this.#state = "showing";
     this.#shownAt = Date.now();
-    this.setAttribute("aria-busy", "true");
-    this.toggleAttribute("inert", true);
+    this.#writeOutput(true);
     this.dispatchEvent(new CustomEvent("bones:show", { bubbles: true, composed: true }));
   }
 
   #hide(): void {
     this.#clearTimer();
-    this.#state = "idle";
+    this.#state = "hiding";
     const update = (): void => {
-      this.removeAttribute("aria-busy");
-      this.removeAttribute("inert");
+      // A real startViewTransition runs this a frame or more later. Anything
+      // that happened in between (busy set again, the element removed) has
+      // already moved the state off "hiding", and this stale update must not
+      // undo it.
+      if (this.#state !== "hiding") return;
+      this.#state = "idle";
+      this.#writeOutput(false);
       this.dispatchEvent(new CustomEvent("bones:hide", { bubbles: true, composed: true }));
     };
     if (this.#canTransition()) {
@@ -188,6 +248,24 @@ export class BonesBoundary extends Base {
     }
   }
 
+  // The element's own writes to its output attributes, flagged while they run
+  // so the attributeChangedCallback that defends those attributes ignores
+  // them and cannot recurse into itself.
+  #writeOutput(shown: boolean): void {
+    this.#writingOutput = true;
+    try {
+      if (shown) {
+        this.setAttribute("aria-busy", "true");
+        this.toggleAttribute("inert", true);
+      } else {
+        this.removeAttribute("aria-busy");
+        this.removeAttribute("inert");
+      }
+    } finally {
+      this.#writingOutput = false;
+    }
+  }
+
   // Showing never animates: a crossfade into a skeleton only delays the
   // loading state. Hiding animates when the page allows it.
   #canTransition(): boolean {
diff --git a/packages/bones/src/element/index.ts b/packages/bones/src/element/index.ts
index ded6410..eb083ff 100644
--- a/packages/bones/src/element/index.ts
+++ b/packages/bones/src/element/index.ts
@@ -17,8 +17,15 @@ declare global {
 //
 // `import "@camp.dev/bones/element"` is the whole setup. The guard keeps the
 // module importable in Node (no customElements) and safe to import twice.
+// A tag that is already taken means two copies of this package on the page,
+// or someone else's element under the same name, and the boundaries in the
+// losing copy silently do nothing. That is worth a line in the console.
 // ---------------------------------------------------------------------------
 
-if (typeof customElements !== "undefined" && !customElements.get("bones-boundary")) {
-  customElements.define("bones-boundary", BonesBoundary);
+if (typeof customElements !== "undefined") {
+  if (customElements.get("bones-boundary")) {
+    console.warn("bones-boundary is already defined; @camp.dev/bones/element did not register");
+  } else {
+    customElements.define("bones-boundary", BonesBoundary);
+  }
 }
diff --git a/packages/bones/tests/boundary.test.ts b/packages/bones/tests/boundary.test.ts
index 2067b39..7f752bd 100644
--- a/packages/bones/tests/boundary.test.ts
+++ b/packages/bones/tests/boundary.test.ts
@@ -76,6 +76,25 @@ describe("registration and reflection", () => {
     expect(el.delay).toBe(200);
   });
 
+  test("a property assigned before upgrade is replayed through the setter", () => {
+    const el = document.createElement("bones-boundary");
+    // What `boundary.busy = true` leaves behind when the page runs it before
+    // the element module loads: an own data property that shadows the
+    // prototype accessor for good once the element upgrades.
+    Object.defineProperty(el, "busy", {
+      value: true,
+      writable: true,
+      configurable: true,
+      enumerable: true,
+    });
+    document.body.append(el);
+    expect(Object.prototype.hasOwnProperty.call(el, "busy")).toBe(false);
+    expect(el.hasAttribute("busy")).toBe(true);
+    expect(el.busy).toBe(true);
+    vi.advanceTimersByTime(200);
+    expect(shown(el)).toBe(true);
+  });
+
   test("transition reads auto unless the attribute is none", () => {
     const el = mount();
     expect(el.transition).toBe("auto");
@@ -205,6 +224,19 @@ describe("force", () => {
     expect(shown(el)).toBe(true);
   });
 
+  test("force set during the delay cancels the timer and fires one bones:show", () => {
+    const el = mount();
+    const log = events(el);
+    el.busy = true;
+    vi.advanceTimersByTime(100);
+    el.force = true;
+    expect(shown(el)).toBe(true);
+    // The delay timer would have fired at t=200 and shown a second time.
+    vi.advanceTimersByTime(1000);
+    expect(shown(el)).toBe(true);
+    expect(log).toEqual(["show"]);
+  });
+
   test("force set while draining keeps bones showing", () => {
     const el = mount();
     const log = events(el);
@@ -240,6 +272,46 @@ describe("force", () => {
   });
 });
 
+describe("output attribute defense", () => {
+  test("attributes stripped while bones show are put back", () => {
+    const el = mount({ delay: "0" });
+    const log = events(el);
+    el.busy = true;
+    el.removeAttribute("aria-busy");
+    expect(el.getAttribute("aria-busy")).toBe("true");
+    el.removeAttribute("inert");
+    expect(shown(el)).toBe(true);
+    // Draining counts as on screen too: the bones are still painted.
+    el.busy = false;
+    expect(el.showing).toBe(true);
+    el.removeAttribute("aria-busy");
+    el.removeAttribute("inert");
+    expect(shown(el)).toBe(true);
+    vi.advanceTimersByTime(400);
+    expect(shown(el)).toBe(false);
+    expect(log).toEqual(["show", "hide"]);
+  });
+
+  test("the element leaves alone attributes it did not set", () => {
+    const el = mount({ delay: "0", "min-duration": "0" });
+    // Idle: the author owns these attributes, so neither setting nor
+    // removing them by hand pulls the element into a showing state.
+    el.setAttribute("aria-busy", "true");
+    el.toggleAttribute("inert", true);
+    expect(el.showing).toBe(false);
+    el.removeAttribute("aria-busy");
+    el.removeAttribute("inert");
+    expect(el.hasAttribute("aria-busy")).toBe(false);
+    expect(el.hasAttribute("inert")).toBe(false);
+    // And the element's own hide is not something it defends against.
+    el.busy = true;
+    expect(shown(el)).toBe(true);
+    el.busy = false;
+    expect(shown(el)).toBe(false);
+    expect(el.showing).toBe(false);
+  });
+});
+
 // ---------------------------------------------------------------------------
 // View transitions. jsdom has neither startViewTransition nor matchMedia, so
 // each test installs what it needs and the afterEach removes it.
@@ -269,6 +341,18 @@ function stubReducedMotion(matches: boolean) {
   (window as MediaWindow).matchMedia = vi.fn(() => ({ matches }));
 }
 
+// A real startViewTransition runs its update callback on a later frame. This
+// stub captures the callback instead of running it, so a test can act inside
+// that window and then let the stale update run.
+function captureTransition(): () => void {
+  let captured = (): void => {};
+  (document as TransitionDoc).startViewTransition = (update: () => void) => {
+    captured = update;
+    return {};
+  };
+  return () => captured();
+}
+
 describe("view transitions", () => {
   afterEach(() => {
     delete (document as TransitionDoc).startViewTransition;
@@ -333,6 +417,47 @@ describe("view transitions", () => {
     expect(fn).toHaveBeenCalledTimes(1);
   });
 
+  test("busy set again before the update runs keeps bones and fires no second show", () => {
+    const run = captureTransition();
+    const el = mount({ delay: "0", "min-duration": "0" });
+    const log = events(el);
+    el.busy = true;
+    el.busy = false;
+    expect(el.showing).toBe(true);
+    expect(shown(el)).toBe(true);
+    el.busy = true;
+    run();
+    expect(shown(el)).toBe(true);
+    expect(el.showing).toBe(true);
+    expect(log).toEqual(["show"]);
+  });
+
+  test("an element removed before the update runs fires no bones:hide", () => {
+    const run = captureTransition();
+    const el = mount({ delay: "0", "min-duration": "0" });
+    const log = events(el);
+    el.busy = true;
+    el.busy = false;
+    el.remove();
+    run();
+    expect(log).toEqual(["show"]);
+    expect(el.getAttribute("aria-busy")).toBe("true");
+    expect(el.hasAttribute("inert")).toBe(true);
+  });
+
+  test("an uninterrupted update still hides and fires bones:hide", () => {
+    const run = captureTransition();
+    const el = mount({ delay: "0", "min-duration": "0" });
+    const log = events(el);
+    el.busy = true;
+    el.busy = false;
+    expect(shown(el)).toBe(true);
+    run();
+    expect(shown(el)).toBe(false);
+    expect(el.showing).toBe(false);
+    expect(log).toEqual(["show", "hide"]);
+  });
+
   test("hide completes when startViewTransition is absent", () => {
     const el = mount({ delay: "0", "min-duration": "0" });
     const log = events(el);

From b5af6e6d5428cdc6d83cec0e506df6a0f32ae969 Mon Sep 17 00:00:00 2001
From: Hunter Garrett 
Date: Sat, 22 Aug 2026 14:17:01 -0400
Subject: [PATCH 09/12] fix: widen BonesBoundary props and suppress hydration
 diffing

BonesBoundaryProps allowed id, className, style, ref, children, and data-*,
and nothing else. `role`, `hidden`, `tabIndex`, `title`, `onClick`, and every
aria-* attribute were type errors on an element whose whole job is to wrap
real content. ElementAttributes now extends HTMLAttributes and
keeps the element's own attributes on top.

The wrapper also sets suppressHydrationWarning. When hydration lands later
than `delay`, which is what selective hydration inside a streaming Suspense
boundary does, the element has already written aria-busy and inert, and React
reports the extra attributes as a mismatch. They are the element's to write,
so React has no business diffing them.

`ref` is now typed as Ref through a type-only import of the
element class. Types are erased at build time, so dist/react/index.mjs still
imports nothing but react.
---
 packages/bones/src/react/boundary.ts         | 27 +++++++----
 packages/bones/tests/boundary-react.test.tsx | 51 ++++++++++++++++++++
 2 files changed, 68 insertions(+), 10 deletions(-)

diff --git a/packages/bones/src/react/boundary.ts b/packages/bones/src/react/boundary.ts
index db02e48..2d45d8b 100644
--- a/packages/bones/src/react/boundary.ts
+++ b/packages/bones/src/react/boundary.ts
@@ -1,4 +1,8 @@
-import { createElement, type CSSProperties, type ReactNode, type Ref } from "react";
+import { createElement, type HTMLAttributes, type ReactNode, type Ref } from "react";
+// A type-only import: it is erased at build time, so the rule that src/react
+// never depends on src/element at runtime still holds. The element module is
+// what registers the tag, and this file must not pull it into a bundle.
+import type { BonesBoundary as BonesBoundaryElement } from "../element/boundary.ts";
 
 // ---------------------------------------------------------------------------
 //  — typed wrapper for the  element
@@ -12,22 +16,21 @@ import { createElement, type CSSProperties, type ReactNode, type Ref } from "rea
 // `@camp.dev/bones/element` once in a client entry; this file does not do it.
 // ---------------------------------------------------------------------------
 
-type ElementAttributes = {
+// Everything a plain 
 accepts, plus the element's own attributes. A
+// boundary wraps real content, so `role`, `hidden`, `tabIndex`, `onClick`, and
+// the rest of the aria-* set all have reasons to appear on it.
+interface ElementAttributes extends HTMLAttributes {
   busy?: boolean;
   force?: boolean;
   delay?: number;
   "min-duration"?: number;
   transition?: "auto" | "none";
-  inert?: boolean;
-  "aria-busy"?: "true" | "false";
+  // React maps `className` to class on custom elements too, but a raw
+  //  written by hand reads better with the HTML name.
   class?: string;
-  className?: string;
-  style?: CSSProperties;
-  id?: string;
-  children?: ReactNode;
-  ref?: Ref;
+  ref?: Ref;
   [dataAttribute: `data-${string}`]: string | number | boolean | undefined;
-};
+}
 
 declare module "react" {
   namespace JSX {
@@ -67,6 +70,10 @@ export function BonesBoundary({
       "min-duration": minDuration,
       transition,
       ...(force ? { "aria-busy": "true", inert: true } : {}),
+      // The element writes aria-busy and inert itself, and it can have done so
+      // before hydration reaches this subtree. React must not treat those
+      // attributes as a mismatch against the server HTML and warn about them.
+      suppressHydrationWarning: true,
       "onbones:show": onShow,
       "onbones:hide": onHide,
     },
diff --git a/packages/bones/tests/boundary-react.test.tsx b/packages/bones/tests/boundary-react.test.tsx
index 07f9718..7a17bd6 100644
--- a/packages/bones/tests/boundary-react.test.tsx
+++ b/packages/bones/tests/boundary-react.test.tsx
@@ -54,6 +54,21 @@ describe("server rendering", () => {
     expect(html).toContain('data-testid="b"');
   });
 
+  test("standard HTML and ARIA props type-check and reach the element", () => {
+    const html = renderToString(
+       {}}>
+        x
+      ,
+    );
+    expect(html).toContain('role="status"');
+    expect(html).toContain('aria-label="Loading"');
+  });
+
+  test("suppressHydrationWarning never reaches the markup", () => {
+    const html = renderToString(x);
+    expect(html.toLowerCase()).not.toContain("suppresshydrationwarning");
+  });
+
   test("raw  type-checks with the augmented intrinsic element", () => {
     const html = renderToString(
       
@@ -92,6 +107,42 @@ describe("client rendering", () => {
     expect(onHide).toHaveBeenCalledTimes(1);
   });
 
+  test("the output attributes survive a force to busy rerender", () => {
+    vi.useFakeTimers();
+    const onHide = vi.fn();
+    const { container, rerender } = render(
+      
+        
copy

+      ,
+    );
+    const el = container.querySelector("bones-boundary")!;
+    expect(el.getAttribute("aria-busy")).toBe("true");
+    expect(el.hasAttribute("inert")).toBe(true);
+    // React deletes the aria-busy and inert it rendered for `force` before it
+    // applies `busy`, so the element has to put them back.
+    rerender(
+      
+        
copy

+      ,
+    );
+    expect(el.getAttribute("aria-busy")).toBe("true");
+    expect(el.hasAttribute("inert")).toBe(true);
+    expect(el.showing).toBe(true);
+    expect(onHide).not.toHaveBeenCalled();
+    rerender(
+      
+        
copy

+      ,
+    );
+    act(() => {
+      vi.advanceTimersByTime(400);
+    });
+    expect(el.getAttribute("aria-busy")).toBeNull();
+    expect(el.hasAttribute("inert")).toBe(false);
+    expect(el.showing).toBe(false);
+    expect(onHide).toHaveBeenCalledTimes(1);
+  });
+
   test("minDuration reaches the element as the min-duration attribute", () => {
     const { container } = render(x);
     const el = container.querySelector("bones-boundary")!;

From 6177594c92e01b43eff93b9aed5a0ca33efab529 Mon Sep 17 00:00:00 2001
From: Hunter Garrett 
Date: Sat, 22 Aug 2026 14:19:48 -0400
Subject: [PATCH 10/12] docs: note bones-boundary upgrade, focus, and hydration
 behavior

The usage snippet drove the boundary from a classic inline script, which runs
before the deferred module import above it and touches an element that has
not upgraded. It is a module script now, and it awaits
customElements.whenDefined() before it reads or writes anything.

The rest of the page fills gaps the review found: a new delay or min-duration
applies to the next transition rather than the one running, inert blurs
focus inside the boundary and nothing restores it, bones:show also fires when
an element upgrades with server-rendered aria-busy, React does not own the
attributes the element writes, and a project with its own bones-boundary
declaration in JSX.IntrinsicElements will hit a conflict.

Both READMEs now say that the bare specifier in the "Without React" snippet
needs a bundler or an import map, and where to find the CDN form.
---
 README.md                                     |  2 ++
 apps/docs/content/docs/api/bones-boundary.mdx | 29 +++++++++++++------
 packages/bones/README.md                      |  2 ++
 3 files changed, 24 insertions(+), 9 deletions(-)

diff --git a/README.md b/README.md
index 8b15826..305480c 100644
--- a/README.md
+++ b/README.md
@@ -145,6 +145,8 @@ Auto rules live in `@layer bones-auto`, so any page CSS that sets `color` on an
 
 ```
 
+`@camp.dev/bones/element` is a bare specifier. A browser cannot resolve it on its own, so this snippet needs a bundler or an import map. To load the element straight from a CDN in a plain HTML file, see the URL form on the [bones-boundary docs page](apps/docs/content/docs/api/bones-boundary.mdx).
+
 Pair it with `auto.css` for zero-markup skeletons, or with `data-bone` markup from `boneAttributes`. The element is also exported for React as `` from `@camp.dev/bones/react`.
 
 ## Development
diff --git a/apps/docs/content/docs/api/bones-boundary.mdx b/apps/docs/content/docs/api/bones-boundary.mdx
index fb6911a..2e6e046 100644
--- a/apps/docs/content/docs/api/bones-boundary.mdx
+++ b/apps/docs/content/docs/api/bones-boundary.mdx
@@ -24,18 +24,19 @@ Set `busy` when loading starts and remove it when loading ends. The element wait
   
Three lines of copy become three bones while busy.

 
 
-
 ```
 
+The second script waits for the definition instead of trusting script order. A classic `