Engine Deep Dive

How the engine works

Take the engine apart phase by phase. For every step you get the real code that runs, the DOM before and after, the engine’s state and the cost — as if you were debugging it live.

<Skeletonizer :enabled="true">
  <UserProfile />
</Skeletonizer>

Live engine

Skeleton

Ada Lovelace

Principal engineer · enjoys skeletons that never shift the layout.

Live scan

Bones0

Ignored0

Hosts0

Last scan0.00 ms

Pipeline · 15 phases

1 / 15

Acquisition · step 1

Subtree acquisition & root container

On mount, the host grabs its rendered subtree and asks the engine to render an overlay for it.

Each <Skeletonizer> renders a positioned wrapper element (it becomes position:relative while active so it can host an absolutely-positioned SVG overlay) and keeps a template ref to it. On mount it registers a host controller with the global store and, when active, calls store.engine.renderHost(root, meta). The real DOM produced by your component is the engine’s input — there is no virtual copy and nothing is ever mutated.

Cost: O(1) — a single ref read and one controller registration per host.

components/Skeletonizer.vue

const root = ref<HTMLElement | null>(null)

onMounted(() => {
  if (!root.value || !store) return
  controller = { id: store._nextId(), scan: doScan, restore, report }
  store._register(controller)
  if (active.value) nextTick(() => doScan())   // doScan() → store.engine.renderHost(root.value, meta)
})

Engine architecture

Component

<Skeletonizer>
Skeleton* primitives

Composable / Store

useSkeletonizer()
per-app reactive store
stats & hosts

Engine

Scan layer
SVG renderer
CLS guard
DebouncedObserver

Theme / Animations

CSS variables
5 keyframe animations

Complete lifecycle

mount

bind engine, register host

enable

nextTick → render

render

scan → SVG → inject overlay

observe

debounced MutationObserver

mutate

coalesced re-render (cache-aware)

disable

remove overlay + restore

unmount

restore + unregister

Scan flow chart

             ┌─────────────────────────┐
             │  enable / DOM mutation  │
             └────────────┬────────────┘
                          ▼
              fingerprint(route, viewport, uid)
                          ▼
                 blueprint cached?  ── yes ─► replay SvgBlueprint  (cache hit)
                          │ no                          │
                          ▼                             │
                 ┌──────────────────┐                  │
                 │  pop element     │◄──────────┐      │
                 │  from DFS stack  │           │      │
                 └────────┬─────────┘           │      │
                          ▼                     │      │
                 getComputedStyle(el)           │      │
                          ▼                     │      │
                   ┌─────────────┐              │      │
                   │ classify()  │              │      │
                   └──┬───┬───┬──┘              │      │
        skip ◄────────┘   │   └──► shimmer node │      │
         │                ▼                     │      │
   ignored++     ┌────────────────┐             │      │
                 │   container?   │── yes ─► push children ─┘  │
                 └───────┬────────┘                            │
                         │ no (leaf)                           │
                         ▼                                     │
        measure → push ScannedNode { kind, rect, radius }      │
                         ▼                                     │
              SvgRenderer → one <svg> + shared gradient  │
                         ▼                                     │
              CLS guard: clamp viewBox → inject overlay ◄──────┘
                         ▼
   report { bones, ignored, timings, blueprint } → store._recompute()

Adaptive engine · SVG pipeline

The adaptive SVG engine

Everything above feeds one render backend: SVG. The host routes through the SkeletonEngine — a modular pipeline (Scan → SVG Renderer → CLS Guard → DOM Injection) that adapts the shimmer animation and tier to the live device load, so the interface stays fluid even on enterprise-scale pages. It is fully additive: with the default config there is zero extra overhead.

A 5-layer modular pipeline

1 · Scan Layer

measure subtree → ScannedNode[]

2 · SVG Renderer

one <svg> overlay + shared gradient

3 · CLS Guard

clamp viewBox to host bounding box

4 · DOM Injection

absolute overlay, content hidden in place

5 · Telemetry

metrics + cache + Explain feedback

Live SVG overlay & Blueprint Inspector

svg

Skeleton

Ada Lovelace

Principal engineer · enjoys skeletons that never shift the layout.

Live adaptive signals

Render modesvg

Score100/100

FPS—

Animation tierfull

SVG shapes0

Cache hit0%

One SVG pipeline, stage by stage

Scan Layer

+0 nodes

Read-only measurement

Walks the subtree and measures each leaf into a ScannedNode (kind, DOMRect, radius) — the source DOM is never mutated.

SVG Renderer

+1 nodes

Any density

Maps ScannedNode[] to one <svg> overlay: a <rect> per box, a <circle> per avatar — one element regardless of node count.

Shared Gradient

0 nodes

Animated shimmer

One namespaced <linearGradient> reused by every shape, swept by a single <animateTransform>.

CLS Guard

+0 nodes

Zero layout shift

Clamps the viewBox to the host bounding box and hides the real content in place — the page never shifts.

Eight subsystems

Adaptive Performance

FPS/CPU score, animation auto-degradation and shimmer auto-disable, driven by a runtime policy that watches the live signals.

config.adaptive · minFps

SVG Renderer

The single render backend: ScannedNode[] → one <svg> overlay (a <rect>/<circle> per node) with rounded coordinates.

config.renderMode · svgPrecision

Shared Gradient

One namespaced <linearGradient> reused by every shape, animated by a single <animateTransform> sweep — no per-node JS.

config.svgSharedGradient

Blueprint Cache

A layout fingerprint hash(route + viewport + UID) caches the SvgBlueprint in memory or session; a hit replays it and skips the scan.

config.layoutCache

Animation Intelligence

Microcontroller degrades wave → pulse → static under load; the CLS guard clamps the viewBox so the overlay is pixel-stable.

tiers · cls-guard

Telemetry & Off-thread

Per-stage timings, FPS, memory, cache ratio — with heavy compute (fingerprint, analysis) offloaded to a Web Worker / requestIdleCallback.

config.telemetry · offThread

DevTools (DX)

Blueprint Inspector (the generated SVG), Explain Mode (natural-language decisions) and a bottleneck ranking of the slowest hosts.

useSkeletonPerformance()

Layered Pipeline

A modular engine: Scan → SVG Renderer → CLS Guard → DOM Injection, where each layer is decoupled and individually testable.

SkeletonEngine

See it under load

The Performance Lab runs this SVG pipeline and the adaptive controls against enterprise-scale scenarios — with live telemetry, a cold-scan vs cache-hit comparison and Explain Mode.