@0xgf/boneyard 1.0.0

package/dist/layout.js

@@ -0,0 +1,256 @@
+/**
+ * Layout engine — uses @chenglou/pretext for exact text measurement.
+ *
+ * Takes a SkeletonDescriptor (developer-defined component structure) and a
+ * width, then computes pixel-perfect bone positions using pretext for text
+ * and box-model arithmetic for containers.
+ *
+ * No DOM, no puppeteer, no build step. Describe your component, get bones.
+ */
+import { prepare, layout as pretextLayout } from '@chenglou/pretext';
+function resolveSides(v) {
+    if (v === undefined)
+        return { top: 0, right: 0, bottom: 0, left: 0 };
+    if (typeof v === 'number')
+        return { top: v, right: v, bottom: v, left: v };
+    return { top: v.top ?? 0, right: v.right ?? 0, bottom: v.bottom ?? 0, left: v.left ?? 0 };
+}
+/**
+ * Compute skeleton bones from a descriptor at a given width.
+ * Uses pretext for all text measurement — no DOM needed.
+ */
+export function computeLayout(desc, width, name = 'component') {
+    const bones = [];
+    layoutNode(desc, 0, 0, width, bones);
+    let maxBottom = 0;
+    for (const b of bones) {
+        const bottom = b.y + b.h;
+        if (bottom > maxBottom)
+            maxBottom = bottom;
+    }
+    return {
+        name,
+        viewportWidth: width,
+        width,
+        height: round(maxBottom),
+        bones,
+    };
+}
+/**
+ * Recursively layout a node and its children, producing bones.
+ * Returns the height consumed (including margin).
+ */
+function layoutNode(desc, offsetX, offsetY, availableWidth, bones) {
+    const pad = resolveSides(desc.padding);
+    const mar = resolveSides(desc.margin);
+    const nodeX = offsetX + mar.left;
+    const nodeY = offsetY + mar.top;
+    const nodeWidth = clampWidth(desc.width !== undefined ? Math.min(desc.width, availableWidth) : availableWidth, desc.maxWidth, availableWidth);
+    const contentX = nodeX + pad.left;
+    const contentY = nodeY + pad.top;
+    const contentWidth = Math.max(0, nodeWidth - pad.left - pad.right);
+    if (isLeaf(desc)) {
+        const contentHeight = resolveLeafHeight(desc, contentWidth, pad);
+        const totalHeight = contentHeight + pad.top + pad.bottom;
+        // For single-line text, use intrinsic text width instead of full container width
+        let boneWidth = nodeWidth;
+        if (desc.text && desc.font && desc.lineHeight && contentHeight < desc.lineHeight * 1.5) {
+            const intrinsic = getIntrinsicWidth(desc, contentWidth);
+            boneWidth = Math.min(intrinsic, nodeWidth);
+        }
+        bones.push({
+            x: round(nodeX),
+            y: round(nodeY),
+            w: round(boneWidth),
+            h: round(totalHeight),
+            r: desc.borderRadius ?? 8,
+        });
+        return totalHeight + mar.top + mar.bottom;
+    }
+    const children = desc.children ?? [];
+    let innerHeight;
+    const display = desc.display ?? 'block';
+    const direction = desc.flexDirection ?? 'row';
+    if (display === 'flex' && direction === 'row') {
+        innerHeight = layoutFlexRow(desc, children, contentX, contentY, contentWidth, bones);
+    }
+    else if (display === 'flex' && direction === 'column') {
+        innerHeight = layoutFlexColumn(desc, children, contentX, contentY, contentWidth, bones);
+    }
+    else {
+        // Block layout with CSS margin collapsing
+        let y = 0;
+        let prevMarBottom = 0;
+        for (let i = 0; i < children.length; i++) {
+            const childMar = resolveSides(children[i].margin);
+            if (i > 0) {
+                // CSS collapses adjacent margins: gap = max(prev bottom, current top)
+                y -= Math.min(prevMarBottom, childMar.top);
+            }
+            y += layoutNode(children[i], contentX, contentY + y, contentWidth, bones);
+            prevMarBottom = childMar.bottom;
+        }
+        innerHeight = y;
+    }
+    const totalHeight = innerHeight + pad.top + pad.bottom;
+    return totalHeight + mar.top + mar.bottom;
+}
+/** Flex column: children stack vertically with gap */
+function layoutFlexColumn(parent, children, contentX, contentY, contentWidth, bones) {
+    const gap = parent.rowGap ?? parent.gap ?? 0;
+    let y = 0;
+    for (let i = 0; i < children.length; i++) {
+        const h = layoutNode(children[i], contentX, contentY + y, contentWidth, bones);
+        y += h;
+        if (i < children.length - 1 && h > 0)
+            y += gap;
+    }
+    return y;
+}
+/** Flex row: two-pass layout with alignment */
+function layoutFlexRow(parent, children, contentX, contentY, contentWidth, bones) {
+    if (children.length === 0)
+        return 0;
+    const gap = parent.columnGap ?? parent.gap ?? 0;
+    const justify = parent.justifyContent ?? 'flex-start';
+    const align = parent.alignItems ?? 'stretch';
+    // Phase 1: compute child widths
+    const childWidths = [];
+    let totalFixed = 0;
+    let flexCount = 0;
+    for (const child of children) {
+        if (child.width !== undefined) {
+            const w = clampWidth(child.width, child.maxWidth, contentWidth);
+            childWidths.push(w);
+            totalFixed += w;
+        }
+        else if (isContentSized(child)) {
+            let w = getIntrinsicWidth(child, contentWidth);
+            w = clampWidth(w, child.maxWidth, contentWidth);
+            childWidths.push(w);
+            totalFixed += w;
+        }
+        else {
+            childWidths.push(-1);
+            flexCount++;
+        }
+    }
+    const totalGaps = Math.max(0, children.length - 1) * gap;
+    const remaining = Math.max(0, contentWidth - totalFixed - totalGaps);
+    const flexWidth = flexCount > 0 ? remaining / flexCount : 0;
+    for (let i = 0; i < childWidths.length; i++) {
+        if (childWidths[i] < 0) {
+            childWidths[i] = clampWidth(flexWidth, children[i].maxWidth, contentWidth);
+        }
+    }
+    // Phase 2: measure heights
+    const childHeights = [];
+    for (let i = 0; i < children.length; i++) {
+        const temp = [];
+        childHeights.push(layoutNode(children[i], 0, 0, childWidths[i], temp));
+    }
+    const maxHeight = Math.max(...childHeights, 0);
+    // Phase 3: justify-content
+    const totalUsed = childWidths.reduce((s, w) => s + w, 0) + totalGaps;
+    let xStart = 0;
+    let extraGap = 0;
+    if (justify === 'flex-end') {
+        xStart = Math.max(0, contentWidth - totalUsed);
+    }
+    else if (justify === 'center') {
+        xStart = Math.max(0, (contentWidth - totalUsed) / 2);
+    }
+    else if (justify === 'space-between' && children.length > 1) {
+        const totalChildWidth = childWidths.reduce((s, w) => s + w, 0);
+        extraGap = Math.max(0, (contentWidth - totalChildWidth) / (children.length - 1)) - gap;
+    }
+    // Phase 4: position with alignment
+    let x = xStart;
+    for (let i = 0; i < children.length; i++) {
+        let yOff = 0;
+        if (align === 'center')
+            yOff = Math.max(0, (maxHeight - childHeights[i]) / 2);
+        else if (align === 'flex-end')
+            yOff = Math.max(0, maxHeight - childHeights[i]);
+        layoutNode(children[i], contentX + x, contentY + yOff, childWidths[i], bones);
+        x += childWidths[i];
+        if (i < children.length - 1)
+            x += gap + extraGap;
+    }
+    return maxHeight;
+}
+/** Is this a leaf that produces a bone? */
+function isLeaf(desc) {
+    if (desc.leaf === true)
+        return true;
+    if (desc.text !== undefined)
+        return true;
+    if (desc.height !== undefined && (!desc.children || desc.children.length === 0))
+        return true;
+    if (desc.aspectRatio !== undefined && (!desc.children || desc.children.length === 0))
+        return true;
+    if (!desc.children || desc.children.length === 0)
+        return false;
+    return false;
+}
+function isContentSized(child) {
+    if (child.width !== undefined)
+        return false;
+    return child.text !== undefined || child.leaf === true;
+}
+function getIntrinsicWidth(child, maxAvailable) {
+    if (child.text && child.font && child.lineHeight) {
+        try {
+            const pad = resolveSides(child.padding);
+            const prepared = prepare(child.text, child.font);
+            const singleLine = child.lineHeight * 1.5; // tolerance for font metric differences
+            // Binary search for minimum width that keeps text on one line
+            let lo = 1, hi = maxAvailable;
+            while (hi - lo > 0.5) {
+                const mid = (lo + hi) / 2;
+                const r = pretextLayout(prepared, mid, child.lineHeight);
+                if (r.height <= singleLine)
+                    hi = mid;
+                else
+                    lo = mid;
+            }
+            return Math.ceil(hi) + 1 + pad.left + pad.right;
+        }
+        catch {
+            return maxAvailable;
+        }
+    }
+    if (child.width !== undefined)
+        return child.width;
+    return maxAvailable;
+}
+/** Compute leaf height — pretext for text, arithmetic for everything else */
+function resolveLeafHeight(desc, contentWidth, pad) {
+    if (desc.text && desc.font && desc.lineHeight) {
+        try {
+            const prepared = prepare(desc.text, desc.font);
+            const result = pretextLayout(prepared, contentWidth, desc.lineHeight);
+            return result.height;
+        }
+        catch {
+            return desc.lineHeight ?? 20;
+        }
+    }
+    if (desc.height !== undefined) {
+        return Math.max(0, desc.height - pad.top - pad.bottom);
+    }
+    if (desc.aspectRatio && desc.aspectRatio > 0 && isFinite(desc.aspectRatio)) {
+        return contentWidth / desc.aspectRatio;
+    }
+    return 20;
+}
+function clampWidth(width, maxWidth, parentWidth) {
+    if (maxWidth === undefined)
+        return width;
+    return Math.min(width, maxWidth);
+}
+function round(n) {
+    if (!isFinite(n))
+        return 0;
+    return Math.round(n * 100) / 100;
+}

package/dist/react.d.ts

@@ -0,0 +1,107 @@
+import { type ReactNode } from 'react';
+import type { SkeletonResult, ResponsiveBones, SnapshotConfig } from './types.js';
+/**
+ * Register pre-generated bones so `<Skeleton name="...">` can auto-resolve them.
+ *
+ * Called by the generated `registry.js` file (created by `npx boneyard build`).
+ * Import it once in your app entry point:
+ *
+ * ```ts
+ * import './bones/registry'
+ * ```
+ *
+ * Then every `<Skeleton name="blog-card">` automatically gets its bones — no
+ * `initialBones` prop needed.
+ */
+export declare function registerBones(map: Record<string, SkeletonResult | ResponsiveBones>): void;
+export interface SkeletonProps {
+    /** When true, shows the skeleton. When false, shows children and extracts layout. */
+    loading: boolean;
+    /** Your component — rendered when not loading. The skeleton is extracted from it. */
+    children: ReactNode;
+    /**
+     * Name this skeleton. When provided:
+     * - After each snapshot, bones are registered to `window.__PRESKEL_BONES[name]`
+     * - The `boneyard build` CLI reads this registry to generate bones JSON files
+     *
+     * @example
+     * <Skeleton name="blog-card" loading={isLoading}>
+     *   <BlogCard />
+     * </Skeleton>
+     *
+     * Then run: npx boneyard capture http://localhost:3000 --out ./src/bones
+     * Which writes: ./src/bones/blog-card.bones.json
+     */
+    name?: string;
+    /**
+     * Pre-generated bones for zero first-load flash.
+     * Accepts a single `SkeletonResult` or a `ResponsiveBones` map (from `boneyard build`).
+     *
+     * - Single: used regardless of viewport width
+     * - Responsive: boneyard picks the nearest breakpoint match for the current container width
+     *
+     * After the first real render, live `snapshotBones` measurements replace the initial bones.
+     *
+     * @example
+     * import blogBones from './src/bones/blog-card.bones.json'
+     * <Skeleton loading={isLoading} initialBones={blogBones}>
+     *   <BlogCard />
+     * </Skeleton>
+     */
+    initialBones?: SkeletonResult | ResponsiveBones;
+    /** Bone color (default: '#e0e0e0') */
+    color?: string;
+    /** Enable pulse animation (default: true) */
+    animate?: boolean;
+    /** Additional className for the container */
+    className?: string;
+    /**
+     * Shown on the very first load if no cached bones and no initialBones.
+     * Unnecessary when initialBones is provided.
+     */
+    fallback?: ReactNode;
+    /**
+     * Controls how boneyard extracts bones from your component's DOM.
+     * Override the default extraction rules to match your design system.
+     *
+     * @example
+     * // Treat <Card> root divs as leaves, skip icons and footers
+     * snapshotConfig={{
+     *   leafTags: ['p', 'h1', 'h2', 'h3', 'li'],
+     *   excludeSelectors: ['.icon', '[data-no-skeleton]', 'footer'],
+     * }}
+     */
+    snapshotConfig?: SnapshotConfig;
+}
+/**
+ * Wrap any component to get automatic skeleton loading screens.
+ *
+ * How it works:
+ * 1. When loading=false, your children render normally.
+ *    After paint, boneyard snapshots the exact bone positions from the DOM.
+ * 2. When loading=true, the cached bones are replayed as a skeleton overlay.
+ * 3. On the very first load (no cache yet):
+ *    - With `initialBones`: shows pre-generated bones immediately, no flash
+ *    - Without: shows the `fallback` prop
+ *
+ * For zero first-load flash, run `npx boneyard capture` to generate initialBones.
+ *
+ * @example Basic
+ * ```tsx
+ * import { Skeleton } from '@0xgf/boneyard/react'
+ *
+ * <Skeleton name="blog-card" loading={isLoading}>
+ *   <BlogCard data={data} />
+ * </Skeleton>
+ * ```
+ *
+ * @example With pre-generated responsive bones (zero flash)
+ * ```tsx
+ * import blogBones from './src/bones/blog-card.bones.json'
+ *
+ * <Skeleton name="blog-card" loading={isLoading} initialBones={blogBones}>
+ *   <BlogCard data={data} />
+ * </Skeleton>
+ * ```
+ */
+export declare function Skeleton({ loading, children, name, initialBones, color, animate, className, fallback, snapshotConfig, }: SkeletonProps): import("react/jsx-runtime").JSX.Element;

package/dist/react.js

@@ -0,0 +1,146 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useRef, useState, useEffect } from 'react';
+import { snapshotBones } from './extract.js';
+// ── Bones registry ──────────────────────────────────────────────────────────
+// Module-level registry populated by registerBones() from the generated registry file.
+// This lets <Skeleton name="x"> auto-resolve bones without an explicit initialBones prop.
+const bonesRegistry = new Map();
+/**
+ * Register pre-generated bones so `<Skeleton name="...">` can auto-resolve them.
+ *
+ * Called by the generated `registry.js` file (created by `npx boneyard build`).
+ * Import it once in your app entry point:
+ *
+ * ```ts
+ * import './bones/registry'
+ * ```
+ *
+ * Then every `<Skeleton name="blog-card">` automatically gets its bones — no
+ * `initialBones` prop needed.
+ */
+export function registerBones(map) {
+    for (const [name, bones] of Object.entries(map)) {
+        bonesRegistry.set(name, bones);
+    }
+}
+/** Pick the right SkeletonResult from a responsive set for the current width */
+function resolveResponsive(bones, width) {
+    if (!('breakpoints' in bones))
+        return bones;
+    const bps = Object.keys(bones.breakpoints).map(Number).sort((a, b) => a - b);
+    if (bps.length === 0)
+        return null;
+    // Largest breakpoint that fits (same logic as CSS min-width media queries)
+    const match = [...bps].reverse().find(bp => width >= bp) ?? bps[0];
+    return bones.breakpoints[match] ?? null;
+}
+/** Mix a hex color toward white by `amount` (0–1). */
+function lightenHex(hex, amount) {
+    const r = parseInt(hex.slice(1, 3), 16);
+    const g = parseInt(hex.slice(3, 5), 16);
+    const b = parseInt(hex.slice(5, 7), 16);
+    const nr = Math.round(r + (255 - r) * amount);
+    const ng = Math.round(g + (255 - g) * amount);
+    const nb = Math.round(b + (255 - b) * amount);
+    return `#${nr.toString(16).padStart(2, '0')}${ng.toString(16).padStart(2, '0')}${nb.toString(16).padStart(2, '0')}`;
+}
+/**
+ * Wrap any component to get automatic skeleton loading screens.
+ *
+ * How it works:
+ * 1. When loading=false, your children render normally.
+ *    After paint, boneyard snapshots the exact bone positions from the DOM.
+ * 2. When loading=true, the cached bones are replayed as a skeleton overlay.
+ * 3. On the very first load (no cache yet):
+ *    - With `initialBones`: shows pre-generated bones immediately, no flash
+ *    - Without: shows the `fallback` prop
+ *
+ * For zero first-load flash, run `npx boneyard capture` to generate initialBones.
+ *
+ * @example Basic
+ * ```tsx
+ * import { Skeleton } from '@0xgf/boneyard/react'
+ *
+ * <Skeleton name="blog-card" loading={isLoading}>
+ *   <BlogCard data={data} />
+ * </Skeleton>
+ * ```
+ *
+ * @example With pre-generated responsive bones (zero flash)
+ * ```tsx
+ * import blogBones from './src/bones/blog-card.bones.json'
+ *
+ * <Skeleton name="blog-card" loading={isLoading} initialBones={blogBones}>
+ *   <BlogCard data={data} />
+ * </Skeleton>
+ * ```
+ */
+export function Skeleton({ loading, children, name, initialBones, color = '#e0e0e0', animate = true, className, fallback, snapshotConfig, }) {
+    const containerRef = useRef(null);
+    const [cachedBones, setCachedBones] = useState(null);
+    const [containerWidth, setContainerWidth] = useState(0);
+    // Track container width so responsive initialBones picks the right breakpoint
+    useEffect(() => {
+        const el = containerRef.current;
+        if (!el)
+            return;
+        const ro = new ResizeObserver(entries => {
+            setContainerWidth(Math.round(entries[0]?.contentRect.width ?? 0));
+        });
+        ro.observe(el);
+        setContainerWidth(Math.round(el.getBoundingClientRect().width));
+        return () => ro.disconnect();
+    }, []);
+    // After every non-loading render, snapshot the DOM and update the cache
+    useEffect(() => {
+        if (loading || !containerRef.current)
+            return;
+        let raf1, raf2;
+        raf1 = requestAnimationFrame(() => {
+            raf2 = requestAnimationFrame(() => {
+                const el = containerRef.current;
+                if (!el)
+                    return;
+                const firstChild = el.firstElementChild;
+                if (!firstChild)
+                    return;
+                try {
+                    const result = snapshotBones(firstChild, name ?? 'component', snapshotConfig);
+                    setCachedBones(result);
+                    // Register to global so `boneyard build` CLI can read it
+                    if (name && typeof window !== 'undefined') {
+                        const w = window;
+                        w.__BONEYARD_BONES = w.__BONEYARD_BONES ?? {};
+                        w.__BONEYARD_BONES[name] = result;
+                    }
+                }
+                catch {
+                    // keep existing cache on error
+                }
+            });
+        });
+        return () => {
+            cancelAnimationFrame(raf1);
+            cancelAnimationFrame(raf2);
+        };
+    }, [loading, name]);
+    // Active bones: live cache > explicit initialBones > registry lookup
+    const effectiveInitialBones = initialBones ?? (name ? bonesRegistry.get(name) : undefined);
+    const resolved = !cachedBones && effectiveInitialBones && containerWidth > 0
+        ? resolveResponsive(effectiveInitialBones, containerWidth)
+        : null;
+    const activeBones = cachedBones ?? resolved;
+    const showSkeleton = loading && activeBones;
+    const showFallback = loading && !activeBones;
+    return (_jsxs("div", { ref: containerRef, className: className, style: { position: 'relative' }, children: [_jsx("div", { style: showSkeleton ? { visibility: 'hidden' } : undefined, children: showFallback ? fallback : children }), showSkeleton && (_jsx("div", { style: { position: 'absolute', inset: 0 }, children: _jsxs("div", { style: { position: 'relative', width: '100%', height: activeBones.height }, children: [activeBones.bones.map((b, i) => (_jsx("div", { style: {
+                                position: 'absolute',
+                                left: b.x,
+                                top: b.y,
+                                width: b.w,
+                                height: b.h,
+                                borderRadius: typeof b.r === 'string' ? b.r : `${b.r}px`,
+                                // Container bones are rendered lighter so children stand out on top
+                                backgroundColor: b.c ? lightenHex(color, 0.45) : color,
+                                animation: animate ? 'boneyard-pulse 1.8s ease-in-out infinite' : undefined,
+                            } }, i))), animate && (_jsx("style", { children: `@keyframes boneyard-pulse{0%,100%{background-color:${color}}50%{background-color:${lightenHex(color, 0.3)}}}` }))] }) }))] }));
+}

package/dist/responsive.d.ts

@@ -0,0 +1,34 @@
+import type { ResponsiveDescriptor } from './types.js';
+/**
+ * Extract a responsive descriptor from a rendered DOM element at multiple widths.
+ *
+ * Resizes the element's container to each breakpoint width, extracts the
+ * skeleton descriptor, and returns a ResponsiveDescriptor mapping.
+ *
+ * Use this at build time, in a test, or in a dev tool to pre-generate
+ * descriptors that work at every breakpoint. Ship the result as JSON.
+ *
+ * @example Browser dev tool / test:
+ * ```ts
+ * import { extractResponsive } from '@0xgf/boneyard'
+ *
+ * // Render your component, then:
+ * const el = document.querySelector('.blog-post')!
+ * const descriptor = extractResponsive(el, [0, 768, 1024])
+ * console.log(JSON.stringify(descriptor, null, 2))
+ * // Save as blog-post-skeleton.json
+ * ```
+ *
+ * @example Playwright / build script:
+ * ```ts
+ * for (const width of [375, 768, 1280]) {
+ *   await page.setViewportSize({ width, height: 800 })
+ *   await page.waitForTimeout(100)
+ *   const desc = await page.evaluate(() => {
+ *     const { extractResponsive } = require('boneyard')
+ *     return extractResponsive(document.querySelector('.card')!)
+ *   })
+ * }
+ * ```
+ */
+export declare function extractResponsive(el: Element, breakpoints?: number[]): ResponsiveDescriptor;

package/dist/responsive.js

@@ -0,0 +1,67 @@
+import { fromElement } from './extract.js';
+/** Default breakpoints: mobile, tablet, desktop */
+const DEFAULT_BREAKPOINTS = [0, 768, 1024];
+/**
+ * Extract a responsive descriptor from a rendered DOM element at multiple widths.
+ *
+ * Resizes the element's container to each breakpoint width, extracts the
+ * skeleton descriptor, and returns a ResponsiveDescriptor mapping.
+ *
+ * Use this at build time, in a test, or in a dev tool to pre-generate
+ * descriptors that work at every breakpoint. Ship the result as JSON.
+ *
+ * @example Browser dev tool / test:
+ * ```ts
+ * import { extractResponsive } from '@0xgf/boneyard'
+ *
+ * // Render your component, then:
+ * const el = document.querySelector('.blog-post')!
+ * const descriptor = extractResponsive(el, [0, 768, 1024])
+ * console.log(JSON.stringify(descriptor, null, 2))
+ * // Save as blog-post-skeleton.json
+ * ```
+ *
+ * @example Playwright / build script:
+ * ```ts
+ * for (const width of [375, 768, 1280]) {
+ *   await page.setViewportSize({ width, height: 800 })
+ *   await page.waitForTimeout(100)
+ *   const desc = await page.evaluate(() => {
+ *     const { extractResponsive } = require('boneyard')
+ *     return extractResponsive(document.querySelector('.card')!)
+ *   })
+ * }
+ * ```
+ */
+export function extractResponsive(el, breakpoints = DEFAULT_BREAKPOINTS) {
+    const container = el.parentElement;
+    if (!container) {
+        throw new Error('boneyard: element must have a parent to extract responsive descriptors');
+    }
+    // Save original styles
+    const originalWidth = container.style.width;
+    const originalOverflow = container.style.overflow;
+    const result = {};
+    // Prevent layout from overflowing during resize
+    container.style.overflow = 'hidden';
+    const sorted = [...breakpoints].sort((a, b) => a - b);
+    for (const bp of sorted) {
+        const targetWidth = bp === 0 ? 375 : bp;
+        // Resize container to simulate breakpoint
+        container.style.width = `${targetWidth}px`;
+        // Force synchronous layout recalc
+        void container.offsetHeight;
+        try {
+            result[bp] = fromElement(el);
+        }
+        catch {
+            // Skip breakpoints that fail to extract
+        }
+    }
+    // Restore original styles
+    container.style.width = originalWidth;
+    container.style.overflow = originalOverflow;
+    // Force layout to settle back
+    void container.offsetHeight;
+    return result;
+}

package/dist/runtime.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Runtime — renders skeleton bones to HTML.
+ *
+ * Usage:
+ *   import { computeLayout, renderBones } from '@0xgf/boneyard'
+ *
+ *   const skeleton = computeLayout(myDescriptor, containerWidth)
+ *   element.innerHTML = renderBones(skeleton)
+ */
+import type { Bone, SkeletonResult } from './types.js';
+export type { Bone, SkeletonResult };
+export type { SkeletonDescriptor } from './types.js';
+/**
+ * Render bones to an HTML string.
+ * Use for SSR, innerHTML, or any HTML-based rendering.
+ */
+export declare function renderBones(skel: SkeletonResult, color?: string, animate?: boolean): string;

package/dist/runtime.js

@@ -0,0 +1,38 @@
+/**
+ * Runtime — renders skeleton bones to HTML.
+ *
+ * Usage:
+ *   import { computeLayout, renderBones } from '@0xgf/boneyard'
+ *
+ *   const skeleton = computeLayout(myDescriptor, containerWidth)
+ *   element.innerHTML = renderBones(skeleton)
+ */
+/** Mix a hex color toward white by `amount` (0–1). */
+function lightenHex(hex, amount) {
+    const r = parseInt(hex.slice(1, 3), 16);
+    const g = parseInt(hex.slice(3, 5), 16);
+    const b = parseInt(hex.slice(5, 7), 16);
+    const nr = Math.round(r + (255 - r) * amount);
+    const ng = Math.round(g + (255 - g) * amount);
+    const nb = Math.round(b + (255 - b) * amount);
+    return `#${nr.toString(16).padStart(2, '0')}${ng.toString(16).padStart(2, '0')}${nb.toString(16).padStart(2, '0')}`;
+}
+/**
+ * Render bones to an HTML string.
+ * Use for SSR, innerHTML, or any HTML-based rendering.
+ */
+export function renderBones(skel, color, animate) {
+    const c = color ?? '#e0e0e0';
+    const shouldAnimate = animate !== false;
+    const lighter = lightenHex(c, 0.3);
+    const keyframes = shouldAnimate
+        ? `<style>.boneyard-bone{animation:boneyard-pulse 1.8s ease-in-out infinite}@keyframes boneyard-pulse{0%,100%{background-color:${c}}50%{background-color:${lighter}}}</style>`
+        : '';
+    let html = `${keyframes}<div class="boneyard" style="position:relative;width:100%;height:${skel.height}px">`;
+    for (const b of skel.bones) {
+        const radius = typeof b.r === 'string' ? b.r : `${b.r}px`;
+        html += `<div class="boneyard-bone" style="position:absolute;left:${b.x}px;top:${b.y}px;width:${b.w}px;height:${b.h}px;border-radius:${radius};background-color:${c}"></div>`;
+    }
+    html += '</div>';
+    return html;
+}