@camp.dev/bones 0.2.0 → 0.3.0

package/README.md

@@ -32,12 +32,14 @@ import "@camp.dev/bones/css";
 
 ## Entry points
 
-| Import                     | Contents                                                                                                                            |
-| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
-| `@camp.dev/bones/react`    | `createBones`, `readPromise`, `forceBones`, `minMax`, `<Bones>`, `<BonesForce>`                                                     |
-| `@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`, `<Bones>`, `<BonesForce>`                                                                                                                                            |
+| `@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`  | `<bones-boundary>`, a custom element that sets `aria-busy` and `inert` on its subtree with `delay`, `min-duration`, and a crossfade. `precision="measured"` draws pixel-accurate per-line bones measured from the content. |
+| `@camp.dev/bones/server`   | `streamBones` and the wire-protocol primitives: stream a shell with busy boundaries, then flush each region's content out of order as it resolves.                                                                         |
+| `@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 +131,25 @@ 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
+
+`<bones-boundary>` 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
+<script type="module">
+  import "@camp.dev/bones/element";
+</script>
+
+<bones-boundary busy>
+  <h2>Title</h2>
+  <p>Body copy.</p>
+</bones-boundary>
+```
+
+`@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](https://github.com/campdotdev/bones/blob/main/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 `<BonesBoundary>` from `@camp.dev/bones/react`.
+
 ## Development
 
 ```bash

package/dist/css/auto.css

@@ -1090,3 +1090,13 @@
     }
   }
 }
+
+@layer bones-auto {
+  /* precision="measured" hides a boundary's content with inherited
+     visibility from the shadow side. Visibility, unlike display, can be
+     switched back on by a descendant, so the opt-out contract survives
+     measured mode: exempt subtrees stay visible under the overlay. */
+  bones-boundary[data-bones-measured] [data-bones-auto="off"] {
+    visibility: visible;
+  }
+}

package/dist/element/boundary.d.mts

@@ -0,0 +1,26 @@
+//#region src/element/boundary.d.ts
+declare const DEFAULT_DELAY = 200;
+declare const DEFAULT_MIN_DURATION = 400;
+declare const Base: typeof HTMLElement;
+declare class BonesBoundary extends Base {
+  #private;
+  static readonly observedAttributes: string[];
+  get busy(): boolean;
+  set busy(value: boolean);
+  get force(): boolean;
+  set force(value: boolean);
+  get delay(): number;
+  set delay(value: number);
+  get minDuration(): number;
+  set minDuration(value: number);
+  get transition(): "auto" | "none";
+  set transition(value: "auto" | "none");
+  get precision(): "css" | "measured";
+  set precision(value: "css" | "measured");
+  get showing(): boolean;
+  connectedCallback(): void;
+  disconnectedCallback(): void;
+  attributeChangedCallback(name: string): void;
+}
+//#endregion
+export { BonesBoundary, DEFAULT_DELAY, DEFAULT_MIN_DURATION };

package/dist/element/boundary.mjs

@@ -0,0 +1,220 @@
+import { MeasuredOverlay } from "./overlay.mjs";
+//#region src/element/boundary.ts
+const DEFAULT_DELAY = 200;
+const DEFAULT_MIN_DURATION = 400;
+const UPGRADE_PROPERTIES = [
+	"busy",
+	"force",
+	"delay",
+	"minDuration",
+	"transition",
+	"precision"
+];
+const swallow = () => {};
+function parseMs(value, fallback) {
+	if (value === null || value.trim() === "") return fallback;
+	const ms = Number(value);
+	return Number.isFinite(ms) && ms >= 0 ? ms : fallback;
+}
+const Base = typeof HTMLElement === "undefined" ? class {} : HTMLElement;
+var BonesBoundary = class extends Base {
+	static observedAttributes = [
+		"busy",
+		"force",
+		"aria-busy",
+		"inert",
+		"precision"
+	];
+	#state = "idle";
+	#timer;
+	#connected = false;
+	#shownAt = 0;
+	#hideToken = 0;
+	#writingOutput = false;
+	#overlay = new MeasuredOverlay(this);
+	get busy() {
+		return this.hasAttribute("busy");
+	}
+	set busy(value) {
+		this.toggleAttribute("busy", Boolean(value));
+	}
+	get force() {
+		return this.hasAttribute("force");
+	}
+	set force(value) {
+		this.toggleAttribute("force", Boolean(value));
+	}
+	get delay() {
+		return parseMs(this.getAttribute("delay"), 200);
+	}
+	set delay(value) {
+		if (value === null || value === void 0) this.removeAttribute("delay");
+		else this.setAttribute("delay", String(value));
+	}
+	get minDuration() {
+		return parseMs(this.getAttribute("min-duration"), 400);
+	}
+	set minDuration(value) {
+		if (value === null || value === void 0) this.removeAttribute("min-duration");
+		else this.setAttribute("min-duration", String(value));
+	}
+	get transition() {
+		return this.getAttribute("transition") === "none" ? "none" : "auto";
+	}
+	set transition(value) {
+		if (value === "none") this.setAttribute("transition", "none");
+		else this.removeAttribute("transition");
+	}
+	get precision() {
+		return this.getAttribute("precision") === "measured" ? "measured" : "css";
+	}
+	set precision(value) {
+		if (value === "measured") this.setAttribute("precision", "measured");
+		else this.removeAttribute("precision");
+	}
+	get showing() {
+		return this.#state === "showing" || this.#state === "draining" || this.#state === "hiding";
+	}
+	connectedCallback() {
+		for (const name of UPGRADE_PROPERTIES) this.#upgradeProperty(name);
+		this.#connected = true;
+		this.#syncPrecision();
+		if (this.getAttribute("aria-busy") === "true" && !this.showing) {
+			this.#show();
+			if (!this.busy && !this.force) this.#evaluate();
+			return;
+		}
+		this.#evaluate();
+	}
+	disconnectedCallback() {
+		this.#overlay.pause();
+		this.#connected = false;
+		this.#clearTimer();
+		if (this.#state === "pending") this.#state = "idle";
+		else if (this.#state === "hiding") this.#state = "showing";
+	}
+	attributeChangedCallback(name) {
+		if (!this.#connected) return;
+		if (name === "aria-busy" || name === "inert") {
+			this.#defendOutput();
+			return;
+		}
+		if (name === "precision") {
+			this.#syncPrecision();
+			return;
+		}
+		this.#evaluate();
+	}
+	#defendOutput() {
+		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);
+	}
+	#syncPrecision() {
+		if (this.precision === "measured") {
+			this.#overlay.prepare();
+			if (this.showing) this.#overlay.activate();
+		} else this.#overlay.deactivate();
+	}
+	#upgradeProperty(name) {
+		if (!Object.prototype.hasOwnProperty.call(this, name)) return;
+		const self = this;
+		const value = self[name];
+		delete self[name];
+		self[name] = value;
+	}
+	#clearTimer() {
+		if (this.#timer !== void 0) clearTimeout(this.#timer);
+		this.#timer = void 0;
+	}
+	#evaluate() {
+		if (this.force) {
+			if (this.#state === "draining" || this.#state === "hiding") this.#resume();
+			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.#state === "hiding") this.#resume();
+			return;
+		}
+		if (this.#state === "pending") {
+			this.#clearTimer();
+			this.#state = "idle";
+		} else if (this.#state === "showing" || this.#state === "draining") {
+			this.#clearTimer();
+			const remaining = this.#shownAt + this.minDuration - Date.now();
+			if (remaining <= 0) this.#hide();
+			else {
+				this.#state = "draining";
+				this.#timer = setTimeout(() => this.#hide(), remaining);
+			}
+		}
+	}
+	#resume() {
+		this.#clearTimer();
+		this.#state = "showing";
+		this.#writeOutput(true);
+	}
+	#show() {
+		this.#clearTimer();
+		this.#state = "showing";
+		this.#shownAt = Date.now();
+		this.#writeOutput(true);
+		if (this.precision === "measured") this.#overlay.activate();
+		this.dispatchEvent(new CustomEvent("bones:show", {
+			bubbles: true,
+			composed: true
+		}));
+	}
+	#hide() {
+		this.#clearTimer();
+		this.#state = "hiding";
+		const token = ++this.#hideToken;
+		const update = () => {
+			if (this.#state !== "hiding" || token !== this.#hideToken) return;
+			this.#state = "idle";
+			this.#writeOutput(false);
+			this.#overlay.deactivate();
+			this.dispatchEvent(new CustomEvent("bones:hide", {
+				bubbles: true,
+				composed: true
+			}));
+		};
+		if (this.#canTransition()) {
+			const transition = document.startViewTransition(update);
+			transition?.ready?.catch(swallow);
+			transition?.updateCallbackDone?.catch(swallow);
+			transition?.finished?.catch(swallow);
+		} else update();
+	}
+	#writeOutput(shown) {
+		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;
+		}
+	}
+	#canTransition() {
+		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;
+	}
+};
+//#endregion
+export { BonesBoundary, DEFAULT_DELAY, DEFAULT_MIN_DURATION };

package/dist/element/index.d.mts

@@ -0,0 +1,14 @@
+import { BonesBoundary, DEFAULT_DELAY, DEFAULT_MIN_DURATION } from "./boundary.mjs";
+
+//#region src/element/index.d.ts
+declare global {
+  interface HTMLElementTagNameMap {
+    "bones-boundary": BonesBoundary;
+  }
+  interface HTMLElementEventMap {
+    "bones:show": CustomEvent;
+    "bones:hide": CustomEvent;
+  }
+}
+//#endregion
+export { BonesBoundary, DEFAULT_DELAY, DEFAULT_MIN_DURATION };

package/dist/element/index.mjs

@@ -0,0 +1,6 @@
+import { BonesBoundary, DEFAULT_DELAY, DEFAULT_MIN_DURATION } from "./boundary.mjs";
+//#region src/element/index.ts
+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);
+//#endregion
+export { BonesBoundary, DEFAULT_DELAY, DEFAULT_MIN_DURATION };

package/dist/element/measure.mjs

@@ -0,0 +1,99 @@
+//#region src/element/measure.ts
+const BLOCK_TAGS = new Set([
+	"img",
+	"svg",
+	"video",
+	"canvas",
+	"picture",
+	"iframe",
+	"embed",
+	"object",
+	"audio",
+	"button",
+	"input",
+	"select",
+	"textarea",
+	"progress",
+	"meter"
+]);
+const TEXT_BAR_SCALE = .55;
+function verticalOverlap(a, b) {
+	return Math.min(a.top + a.height, b.top + b.height) - Math.max(a.top, b.top);
+}
+function mergeLineRects(rects) {
+	const sorted = [...rects].sort((a, b) => a.top - b.top || a.left - b.left);
+	const merged = [];
+	for (const rect of sorted) {
+		const line = merged.findLast((candidate) => {
+			if (verticalOverlap(candidate, rect) < Math.min(candidate.height, rect.height) / 2) return false;
+			return rect.left - (candidate.left + candidate.width) <= Math.max(candidate.height, rect.height) / 2;
+		});
+		if (line === void 0) {
+			merged.push({ ...rect });
+			continue;
+		}
+		const right = Math.max(line.left + line.width, rect.left + rect.width);
+		const bottom = Math.max(line.top + line.height, rect.top + rect.height);
+		line.left = Math.min(line.left, rect.left);
+		line.top = Math.min(line.top, rect.top);
+		line.width = right - line.left;
+		line.height = bottom - line.top;
+	}
+	return merged;
+}
+function isVisible(rect) {
+	return rect.width > 0 && rect.height > 0;
+}
+function toRect(rect) {
+	return {
+		left: rect.left,
+		top: rect.top,
+		width: rect.width,
+		height: rect.height
+	};
+}
+function measureBones(root) {
+	const doc = root.ownerDocument;
+	const blocks = [];
+	const textRects = [];
+	const visit = (node) => {
+		if (node.nodeType === Node.TEXT_NODE) {
+			if (node.data.trim() === "") return;
+			const range = doc.createRange();
+			range.selectNodeContents(node);
+			if (typeof range.getClientRects !== "function") return;
+			for (const rect of Array.from(range.getClientRects())) {
+				const converted = toRect(rect);
+				if (isVisible(converted)) textRects.push(converted);
+			}
+			return;
+		}
+		if (node.nodeType !== Node.ELEMENT_NODE) return;
+		const el = node;
+		if (el.getAttribute("data-bones-auto") === "off") return;
+		if (BLOCK_TAGS.has(el.localName)) {
+			const rect = toRect(el.getBoundingClientRect());
+			if (isVisible(rect)) blocks.push({
+				kind: "block",
+				...rect
+			});
+			return;
+		}
+		for (const child of node.childNodes) visit(child);
+	};
+	for (const child of root.childNodes) visit(child);
+	const bones = [...blocks];
+	for (const line of mergeLineRects(textRects)) {
+		const height = line.height * TEXT_BAR_SCALE;
+		bones.push({
+			kind: "text",
+			left: line.left,
+			top: line.top + (line.height - height) / 2,
+			width: line.width,
+			height
+		});
+	}
+	return bones;
+}
+//#endregion
+export { measureBones };

package/dist/element/overlay.mjs

@@ -0,0 +1,184 @@
+import { measureBones } from "./measure.mjs";
+//#region src/element/overlay.ts
+const OVERLAY_CSS = `
+:host([precision="measured"]) {
+  display: block;
+  position: relative;
+}
+/* Hidden content still lays out, so re-measurement stays valid. Deliberately
+   not !important: outer-tree rules beat ::slotted, which is what lets the
+   auto.css opt-out rule re-show exempt subtrees (and lets an author
+   visibility rule on a direct child win — a documented edge). */
+:host([data-bones-measured]) ::slotted(*) {
+  visibility: hidden;
+}
+[part~="overlay"] {
+  position: absolute;
+  inset: 0;
+  pointer-events: none;
+}
+[part~="bone"] {
+  position: absolute;
+  background: var(--bone-base, rgba(0, 0, 0, 0.12));
+  border-radius: var(--bone-radius, 4px);
+}
+@keyframes bone-shimmer {
+  0% { background-position: 200% 0; }
+  100% { background-position: -200% 0; }
+}
+@keyframes bone-pulse {
+  0%, 100% { opacity: 1; }
+  50% { opacity: 0.5; }
+}
+[part~="overlay"]:not([data-bone-animate]) [part~="bone"],
+[part~="overlay"][data-bone-animate="shimmer"] [part~="bone"] {
+  animation: bone-shimmer var(--bone-duration, 1.5s) ease-in-out infinite;
+  background: linear-gradient(
+    90deg,
+    var(--bone-base, rgba(0, 0, 0, 0.12)) 25%,
+    var(--bone-highlight, rgba(0, 0, 0, 0.06)) 50%,
+    var(--bone-base, rgba(0, 0, 0, 0.12)) 75%
+  );
+  background-size: 200% 100%;
+}
+[part~="overlay"][data-bone-animate="pulse"] [part~="bone"] {
+  animation: bone-pulse var(--bone-duration, 1.5s) ease-in-out infinite;
+}
+[part~="overlay"][data-bone-animate="none"] [part~="bone"] {
+  animation: none;
+}
+/* Matches the shimmer/pulse selectors above at equal (0,3,0) specificity so
+   this override always wins the cascade instead of losing to source order.
+   data-bone-animate="none" is deliberately excluded: none still means none. */
+@media (prefers-reduced-motion: reduce) {
+  [part~="overlay"]:not([data-bone-animate]) [part~="bone"],
+  [part~="overlay"][data-bone-animate="shimmer"] [part~="bone"],
+  [part~="overlay"][data-bone-animate="pulse"] [part~="bone"] {
+    animation: bone-pulse 2s ease-in-out infinite;
+    background: var(--bone-base, rgba(0, 0, 0, 0.12));
+    background-size: auto;
+  }
+}
+`;
+let sharedSheet;
+function applyStyles(root) {
+	if ("adoptedStyleSheets" in root && typeof CSSStyleSheet !== "undefined" && "replaceSync" in CSSStyleSheet.prototype) {
+		if (sharedSheet === void 0) {
+			sharedSheet = new CSSStyleSheet();
+			sharedSheet.replaceSync(OVERLAY_CSS);
+		}
+		root.adoptedStyleSheets = [...root.adoptedStyleSheets, sharedSheet];
+		return;
+	}
+	const style = root.ownerDocument.createElement("style");
+	style.textContent = OVERLAY_CSS;
+	root.append(style);
+}
+var MeasuredOverlay = class {
+	#host;
+	#container;
+	#observer;
+	#mutations;
+	#active = false;
+	#ownsAutoOff = false;
+	constructor(host) {
+		this.#host = host;
+	}
+	get active() {
+		return this.#active;
+	}
+	prepare() {
+		if (this.#host.shadowRoot) return;
+		const root = this.#host.attachShadow({ mode: "open" });
+		root.append(this.#host.ownerDocument.createElement("slot"));
+		applyStyles(root);
+	}
+	activate() {
+		this.prepare();
+		if (!this.#active) {
+			this.#active = true;
+			if (!this.#host.hasAttribute("data-bones-auto")) {
+				this.#host.setAttribute("data-bones-auto", "off");
+				this.#ownsAutoOff = true;
+			}
+			this.#host.setAttribute("data-bones-measured", "");
+		}
+		if (!this.#renderBars()) {
+			this.deactivate();
+			return;
+		}
+		this.#observe();
+	}
+	deactivate() {
+		this.#unobserve();
+		this.#container?.remove();
+		this.#container = void 0;
+		if (!this.#active) return;
+		this.#active = false;
+		this.#host.removeAttribute("data-bones-measured");
+		if (this.#ownsAutoOff) {
+			this.#host.removeAttribute("data-bones-auto");
+			this.#ownsAutoOff = false;
+		}
+	}
+	pause() {
+		this.#unobserve();
+	}
+	#observe() {
+		if (typeof ResizeObserver !== "undefined" && !this.#observer) {
+			this.#observer = new ResizeObserver(() => this.#invalidate());
+			this.#observer.observe(this.#host);
+		}
+		if (typeof MutationObserver !== "undefined" && !this.#mutations) {
+			this.#mutations = new MutationObserver(() => this.#invalidate());
+			this.#mutations.observe(this.#host, {
+				childList: true,
+				subtree: true,
+				characterData: true
+			});
+		}
+	}
+	#unobserve() {
+		this.#observer?.disconnect();
+		this.#observer = void 0;
+		this.#mutations?.disconnect();
+		this.#mutations = void 0;
+	}
+	#invalidate() {
+		if (this.#active && !this.#renderBars()) this.deactivate();
+	}
+	#renderBars() {
+		const root = this.#host.shadowRoot;
+		if (!root) return false;
+		const bones = measureBones(this.#host);
+		if (bones.length === 0) return false;
+		const doc = this.#host.ownerDocument;
+		if (!this.#container) {
+			this.#container = doc.createElement("div");
+			this.#container.setAttribute("part", "overlay");
+			this.#container.setAttribute("aria-hidden", "true");
+			root.append(this.#container);
+		}
+		const animate = this.#host.closest("[data-bone-animate]")?.getAttribute("data-bone-animate");
+		if (animate) this.#container.setAttribute("data-bone-animate", animate);
+		else this.#container.removeAttribute("data-bone-animate");
+		const origin = this.#container.getBoundingClientRect();
+		const style = getComputedStyle(this.#container);
+		const layoutWidth = Number.parseFloat(style.width);
+		const layoutHeight = Number.parseFloat(style.height);
+		const scaleX = layoutWidth > 0 ? origin.width / layoutWidth : 1;
+		const scaleY = layoutHeight > 0 ? origin.height / layoutHeight : 1;
+		this.#container.replaceChildren(...bones.map((bone) => {
+			const bar = doc.createElement("div");
+			bar.setAttribute("part", `bone bone-${bone.kind}`);
+			bar.style.left = `${(bone.left - origin.left) / scaleX}px`;
+			bar.style.top = `${(bone.top - origin.top) / scaleY}px`;
+			bar.style.width = `${bone.width / scaleX}px`;
+			bar.style.height = `${bone.height / scaleY}px`;
+			return bar;
+		}));
+		return true;
+	}
+};
+//#endregion
+export { MeasuredOverlay };

package/dist/react/boundary.d.mts

@@ -0,0 +1,40 @@
+import { BonesBoundary as BonesBoundary$1 } from "../element/boundary.mjs";
+import { HTMLAttributes, ReactNode, Ref } from "react";
+
+//#region src/react/boundary.d.ts
+interface ElementAttributes extends HTMLAttributes<HTMLElement> {
+  busy?: boolean;
+  force?: boolean;
+  delay?: number;
+  "min-duration"?: number;
+  transition?: "auto" | "none";
+  precision?: "css" | "measured";
+  class?: string;
+  ref?: Ref<BonesBoundary$1>;
+  [dataAttribute: `data-${string}`]: string | number | boolean | undefined;
+}
+declare module "react" {
+  namespace JSX {
+    interface IntrinsicElements {
+      "bones-boundary": ElementAttributes;
+    }
+  }
+}
+interface BonesBoundaryProps extends Omit<ElementAttributes, "min-duration" | "inert" | "aria-busy" | "class"> {
+  minDuration?: number;
+  onShow?: (event: CustomEvent) => void;
+  onHide?: (event: CustomEvent) => void;
+}
+declare function BonesBoundary({
+  busy,
+  force,
+  delay,
+  minDuration,
+  transition,
+  onShow,
+  onHide,
+  children,
+  ...rest
+}: BonesBoundaryProps): ReactNode;
+//#endregion
+export { BonesBoundary, BonesBoundaryProps };

package/dist/react/boundary.mjs

@@ -0,0 +1,21 @@
+import { createElement } from "react";
+//#region src/react/boundary.ts
+function BonesBoundary({ busy, force, delay, minDuration, transition, onShow, onHide, children, ...rest }) {
+	return createElement("bones-boundary", {
+		...rest,
+		busy: busy ? true : void 0,
+		force: force ? true : void 0,
+		delay,
+		"min-duration": minDuration,
+		transition,
+		...force ? {
+			"aria-busy": "true",
+			inert: true
+		} : {},
+		suppressHydrationWarning: true,
+		"onbones:show": onShow,
+		"onbones:hide": onHide
+	}, children);
+}
+//#endregion
+export { BonesBoundary };

package/dist/react/index.d.mts

@@ -1,4 +1,5 @@
 import { BoneOptions, BoneType, MinMax, isMinMax, minMax } from "../core/attributes.mjs";
 import { CreateBonesOptions, CreateBonesReturn, createBones, forceBones, readPromise } from "./create-bones.mjs";
 import { Bones, BonesForce } from "./bones.mjs";
-export { type BoneOptions, type BoneType, Bones, BonesForce, type CreateBonesOptions, type CreateBonesReturn, type MinMax, createBones, forceBones, isMinMax, minMax, readPromise };
+import { BonesBoundary, BonesBoundaryProps } from "./boundary.mjs";
+export { type BoneOptions, type BoneType, Bones, BonesBoundary, type BonesBoundaryProps, BonesForce, type CreateBonesOptions, type CreateBonesReturn, type MinMax, createBones, forceBones, isMinMax, minMax, readPromise };

package/dist/react/index.mjs

@@ -1,4 +1,5 @@
 import { isMinMax, minMax } from "../core/attributes.mjs";
 import { createBones, forceBones, readPromise } from "./create-bones.mjs";
 import { Bones, BonesForce } from "./bones.mjs";
-export { Bones, BonesForce, createBones, forceBones, isMinMax, minMax, readPromise };
+import { BonesBoundary } from "./boundary.mjs";
+export { Bones, BonesBoundary, BonesForce, createBones, forceBones, isMinMax, minMax, readPromise };

package/dist/server/bootstrap.d.mts

@@ -0,0 +1,4 @@
+//#region src/server/bootstrap.d.ts
+declare const BOOTSTRAP_SCRIPT = "<script>function __bonesSwap(e,r){var t=document.querySelector('template[data-bones-chunk=\"'+e+'\"]'),n=document.querySelector('[data-bones-slot=\"'+e+'\"]');n?(t&&(n.replaceChildren(t.content),t.remove()),r&&n.setAttribute(\"data-bones-error\",\"\"),\"boolean\"==typeof n.busy?n.busy=!1:(n.removeAttribute(\"busy\"),n.removeAttribute(\"aria-busy\"),n.removeAttribute(\"inert\"))):t&&t.remove()}</script>";
+//#endregion
+export { BOOTSTRAP_SCRIPT };

package/dist/server/bootstrap.mjs

@@ -0,0 +1,3 @@
+const BOOTSTRAP_SCRIPT = `<script>function __bonesSwap(e,r){var t=document.querySelector('template[data-bones-chunk="'+e+'"]'),n=document.querySelector('[data-bones-slot="'+e+'"]');n?(t&&(n.replaceChildren(t.content),t.remove()),r&&n.setAttribute("data-bones-error",""),"boolean"==typeof n.busy?n.busy=!1:(n.removeAttribute("busy"),n.removeAttribute("aria-busy"),n.removeAttribute("inert"))):t&&t.remove()}<\/script>`;
+//#endregion
+export { BOOTSTRAP_SCRIPT };

package/dist/server/index.d.mts

@@ -0,0 +1,17 @@
+import { BOOTSTRAP_SCRIPT } from "./bootstrap.mjs";
+
+//#region src/server/index.d.ts
+declare function renderBoundary(id: string, fallbackHtml: string, attrs?: string): string;
+declare function renderChunk(id: string, html: string): string;
+declare function renderErrorChunk(id: string, html?: string): string;
+interface StreamBonesOptions {
+  /**
+   * Renders the error HTML for a rejected slot. Returning undefined (and
+   * throwing) falls back to the bare error chunk, which keeps the boundary's
+   * fallback children.
+   */
+  onError?: (id: string, error: unknown) => string | undefined;
+}
+declare function streamBones(shell: string, slots: Record<string, Promise<string>>, options?: StreamBonesOptions): ReadableStream<Uint8Array>;
+//#endregion
+export { BOOTSTRAP_SCRIPT, StreamBonesOptions, renderBoundary, renderChunk, renderErrorChunk, streamBones };

package/dist/server/index.mjs

@@ -0,0 +1,57 @@
+import { BOOTSTRAP_SCRIPT } from "./bootstrap.mjs";
+//#region src/server/index.ts
+const ID_PATTERN = /^[A-Za-z0-9_-]+$/;
+function assertId(id) {
+	if (!ID_PATTERN.test(id)) throw new Error(`bones slot id ${JSON.stringify(id)} must match [A-Za-z0-9_-]+`);
+}
+function renderBoundary(id, fallbackHtml, attrs) {
+	assertId(id);
+	return `<bones-boundary busy aria-busy="true" inert data-bones-slot="${id}"${attrs === void 0 || attrs === "" ? "" : ` ${attrs}`}>${fallbackHtml}</bones-boundary>`;
+}
+function renderChunk(id, html) {
+	assertId(id);
+	return `<template data-bones-chunk="${id}">${html}</template><script>__bonesSwap("${id}")<\/script>`;
+}
+function renderErrorChunk(id, html) {
+	assertId(id);
+	if (html === void 0) return `<script>__bonesSwap("${id}",1)<\/script>`;
+	return `<template data-bones-chunk="${id}">${html}</template><script>__bonesSwap("${id}",1)<\/script>`;
+}
+function streamBones(shell, slots, options = {}) {
+	const ids = Object.keys(slots);
+	for (const id of ids) assertId(id);
+	const encoder = new TextEncoder();
+	let cancelled = false;
+	return new ReadableStream({
+		start(controller) {
+			const send = (html) => {
+				if (!cancelled) controller.enqueue(encoder.encode(html));
+			};
+			send(shell + BOOTSTRAP_SCRIPT);
+			if (ids.length === 0) {
+				controller.close();
+				return;
+			}
+			let pending = ids.length;
+			const settle = (chunk) => {
+				send(chunk);
+				pending -= 1;
+				if (pending === 0 && !cancelled) controller.close();
+			};
+			for (const id of ids) slots[id].then((html) => settle(renderChunk(id, html)), (error) => {
+				let html;
+				try {
+					html = options.onError?.(id, error);
+				} catch {
+					html = void 0;
+				}
+				settle(renderErrorChunk(id, html));
+			});
+		},
+		cancel() {
+			cancelled = true;
+		}
+	});
+}
+//#endregion
+export { BOOTSTRAP_SCRIPT, renderBoundary, renderChunk, renderErrorChunk, streamBones };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camp.dev/bones",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Skeleton loaders designed for React Server Components and streaming.",
   "homepage": "https://github.com/campdotdev/bones#readme",
   "bugs": {
@@ -18,11 +18,14 @@
   ],
   "type": "module",
   "sideEffects": [
-    "*.css"
+    "*.css",
+    "./dist/element/index.mjs"
   ],
   "exports": {
     ".": "./dist/index.mjs",
+    "./element": "./dist/element/index.mjs",
     "./react": "./dist/react/index.mjs",
+    "./server": "./dist/server/index.mjs",
     "./package.json": "./package.json",
     "./css": {
       "style": "./src/css/bones.css",
@@ -45,6 +48,7 @@
     "@typescript/native-preview": "7.0.0-dev.20260328.1",
     "@vitest/coverage-v8": "^4.1.5",
     "jsdom": "^29.0.2",
+    "playwright": "^1.62.1",
     "react": "^19.2.5",
     "typescript": "^6.0.2",
     "vite-plus": "^0.1.14"
@@ -66,6 +70,6 @@
     "dev": "vp pack --watch",
     "test": "vp test",
     "check": "vp check",
-    "health": "vp test --coverage && fallow health --root . --coverage coverage/coverage-final.json --format json --quiet"
+    "health": "vp test --project unit --coverage && fallow health --root . --coverage coverage/coverage-final.json --format json --quiet"
   }
 }

package/src/css/auto.css

@@ -1090,3 +1090,13 @@
     }
   }
 }
+
+@layer bones-auto {
+  /* precision="measured" hides a boundary's content with inherited
+     visibility from the shadow side. Visibility, unlike display, can be
+     switched back on by a descendant, so the opt-out contract survives
+     measured mode: exempt subtrees stay visible under the overlay. */
+  bones-boundary[data-bones-measured] [data-bones-auto="off"] {
+    visibility: visible;
+  }
+}