@alikhalilll/a-skeleton 1.0.0 → 1.2.0

package/src/composables/useSkeletonCache.ts

@@ -1,24 +1,69 @@
 import type { CSSProperties } from 'vue';
-import type { CachedShape, ShapeNode } from '../types';
+import type {
+  CachedShape,
+  ContainerNode,
+  LeafNode,
+  ShapeNode,
+  StructuralNode,
+  StructuralShape,
+} from '../types';
 
 const memory = new Map<string, CachedShape>();
 const STORAGE_PREFIX = 'a-skeleton:';
 
+/**
+ * Schema version for persisted flat `CachedShape` entries. Bump whenever the
+ * `ShapeNode` / `CachedShape` field set changes so stale localStorage payloads
+ * from older releases get dropped on read instead of rehydrating into a wrong
+ * layout.
+ *
+ * v2 — added advanced surface signals (textRects, bg, border, boxShadow,
+ *      opacity, textAlign).
+ */
+const SCHEMA_VERSION = 2;
+
+/**
+ * Separate in-memory + localStorage namespace for the Recipe 3 structural
+ * shape (`StructuralShape`, `v: 3`). Kept apart from the flat-shape cache so
+ * the two pipelines can't collide on the same `cacheKey` — `<ASkeleton>`'s
+ * legacy cache-replay path and Recipe 3 may both run on the same page with
+ * the same key.
+ */
+const structuralMemory = new Map<string, StructuralShape>();
+const STRUCTURAL_PREFIX = 'a-skeleton:s:';
+const STRUCTURAL_SCHEMA_VERSION = 3 as const;
+
+interface PersistedShape {
+  v: number;
+  width: number;
+  height: number;
+  nodes: Partial<ShapeNode>[];
+  truncated?: boolean;
+}
+
 /**
  * Lookup a captured shape by key. Reads in-memory first, then `localStorage` if
  * `persist` is enabled. SSR-safe — bypasses `window` access on the server.
  * Rehydrates pre-computed styles for shapes deserialized from older sessions
  * (Object.freeze + style/lineStyles don't survive `JSON.stringify` round-trip).
+ * Drops the entry if it was written by a different schema version.
  */
 export function getCached(key: string, persist: boolean): CachedShape | undefined {
   const hit = memory.get(key);
   if (hit) return hit;
   if (!persist || typeof window === 'undefined') return undefined;
   try {
-    const raw = window.localStorage.getItem(STORAGE_PREFIX + key);
+    const storageKey = STORAGE_PREFIX + key;
+    const raw = window.localStorage.getItem(storageKey);
     if (!raw) return undefined;
-    const parsed = JSON.parse(raw) as CachedShape;
-    const rehydrated = rehydrateShape(parsed);
+    const parsed = JSON.parse(raw) as Partial<PersistedShape>;
+    if (parsed.v !== SCHEMA_VERSION) {
+      /* Stale payload from a previous release — purge so the next capture
+       * writes a fresh entry instead of rehydrating into a wrong layout. */
+      window.localStorage.removeItem(storageKey);
+      return undefined;
+    }
+    const rehydrated = rehydrateShape(parsed as PersistedShape);
     memory.set(key, rehydrated);
     return rehydrated;
   } catch {
@@ -32,43 +77,207 @@ export function setCached(key: string, value: CachedShape, persist: boolean): vo
   if (!persist || typeof window === 'undefined') return;
   try {
     /* Only the geometry survives the round-trip; styles get rebuilt on read. */
-    const lean = { width: value.width, height: value.height, nodes: leanNodes(value.nodes) };
+    const lean: PersistedShape = {
+      v: SCHEMA_VERSION,
+      width: value.width,
+      height: value.height,
+      nodes: leanNodes(value.nodes),
+      truncated: value.truncated,
+    };
     window.localStorage.setItem(STORAGE_PREFIX + key, JSON.stringify(lean));
   } catch {
     /* quota exceeded / disabled storage — silently degrade to in-memory only. */
   }
 }
 
-/** Drop a single entry (or all entries when no key). Exposed for tests + manual invalidation. */
+/**
+ * Drop a single entry (or all entries when no key) — wipes both the flat-shape
+ * and the structural-shape namespaces. Exposed for tests + manual invalidation.
+ */
 export function clearCached(key?: string): void {
   if (!key) {
     memory.clear();
+    structuralMemory.clear();
     if (typeof window === 'undefined') return;
     try {
-      for (const k of Object.keys(window.localStorage)) {
-        if (k.startsWith(STORAGE_PREFIX)) window.localStorage.removeItem(k);
+      /* Use Storage's own length + key(i) iteration — `Object.keys()` on a
+       * Storage object isn't reliable across implementations (works in real
+       * browsers via the Storage[Symbol.iterator] hack, but strict polyfills
+       * return only own enumerable properties). */
+      const ls = window.localStorage;
+      const stale: string[] = [];
+      for (let i = 0; i < ls.length; i++) {
+        const k = ls.key(i);
+        if (!k) continue;
+        if (k.startsWith(STORAGE_PREFIX) || k.startsWith(STRUCTURAL_PREFIX)) stale.push(k);
       }
+      /* Remove in a second pass so we don't shift indices mid-iteration. */
+      for (const k of stale) ls.removeItem(k);
     } catch {
       /* ignore */
     }
     return;
   }
   memory.delete(key);
+  structuralMemory.delete(key);
   if (typeof window === 'undefined') return;
   try {
     window.localStorage.removeItem(STORAGE_PREFIX + key);
+    window.localStorage.removeItem(STRUCTURAL_PREFIX + key);
   } catch {
     /* ignore */
   }
 }
 
+/**
+ * Drop a single structural-shape entry (or all when no key). Kept separate
+ * from `clearCached` so callers that only manage structural shapes don't have
+ * to reach across namespaces.
+ */
+export function clearCachedStructural(key?: string): void {
+  if (!key) {
+    structuralMemory.clear();
+    if (typeof window === 'undefined') return;
+    try {
+      const ls = window.localStorage;
+      const stale: string[] = [];
+      for (let i = 0; i < ls.length; i++) {
+        const k = ls.key(i);
+        if (k && k.startsWith(STRUCTURAL_PREFIX)) stale.push(k);
+      }
+      for (const k of stale) ls.removeItem(k);
+    } catch {
+      /* ignore */
+    }
+    return;
+  }
+  structuralMemory.delete(key);
+  if (typeof window === 'undefined') return;
+  try {
+    window.localStorage.removeItem(STRUCTURAL_PREFIX + key);
+  } catch {
+    /* ignore */
+  }
+}
+
+/* ─────────────────────────────────────────────────────────────────────────────
+ * Structural-shape cache — backs Recipe 3 (`useSkeleton()` +
+ * `<ASkeletonLayer>`). The schema-version check auto-purges stale `v: 2`
+ * entries (or any future mismatched version) on read.
+ * ───────────────────────────────────────────────────────────────────────────── */
+
+interface PersistedStructuralShape {
+  v: typeof STRUCTURAL_SCHEMA_VERSION;
+  width: number;
+  height: number;
+  nodes: StructuralNode[];
+  truncated: boolean;
+  capturedAt: number;
+}
+
+/**
+ * Lookup a structural shape by key. Reads in-memory first, then `localStorage`
+ * when `persist` is enabled. Stale schema versions get purged on read.
+ */
+export function getCachedStructural(key: string, persist: boolean): StructuralShape | undefined {
+  const hit = structuralMemory.get(key);
+  if (hit) return hit;
+  if (!persist || typeof window === 'undefined') return undefined;
+  try {
+    const storageKey = STRUCTURAL_PREFIX + key;
+    const raw = window.localStorage.getItem(storageKey);
+    if (!raw) return undefined;
+    const parsed = JSON.parse(raw) as Partial<PersistedStructuralShape>;
+    if (parsed.v !== STRUCTURAL_SCHEMA_VERSION) {
+      window.localStorage.removeItem(storageKey);
+      return undefined;
+    }
+    const rehydrated = rehydrateStructuralShape(parsed as PersistedStructuralShape);
+    structuralMemory.set(key, rehydrated);
+    return rehydrated;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Store a structural shape. `persist=true` mirrors to `localStorage`. */
+export function setCachedStructural(key: string, value: StructuralShape, persist: boolean): void {
+  structuralMemory.set(key, value);
+  if (!persist || typeof window === 'undefined') return;
+  try {
+    const payload: PersistedStructuralShape = {
+      v: STRUCTURAL_SCHEMA_VERSION,
+      width: value.width,
+      height: value.height,
+      nodes: value.nodes.map(leanStructuralNode),
+      truncated: value.truncated,
+      capturedAt: value.capturedAt,
+    };
+    window.localStorage.setItem(STRUCTURAL_PREFIX + key, JSON.stringify(payload));
+  } catch {
+    /* quota / disabled storage — silently degrade to in-memory only. */
+  }
+}
+
+/* JSON-stringify drops `undefined`, but `Object.freeze` survives across the
+ * round-trip only if we re-freeze after parse. The lean transforms keep
+ * payload size predictable (no unexpected enumerable Vue proxies). */
+function leanStructuralNode(node: StructuralNode): StructuralNode {
+  if (node.kind === 'container') {
+    return {
+      kind: 'container',
+      tag: node.tag,
+      className: node.className,
+      style: node.style,
+      children: node.children.map(leanStructuralNode),
+    } as ContainerNode;
+  }
+  return {
+    kind: 'leaf',
+    leafKind: node.leafKind,
+    className: node.className,
+    style: node.style,
+    textLines: node.textLines,
+  } as LeafNode;
+}
+
+function rehydrateStructuralShape(persisted: PersistedStructuralShape): StructuralShape {
+  return Object.freeze({
+    v: STRUCTURAL_SCHEMA_VERSION,
+    width: persisted.width,
+    height: persisted.height,
+    nodes: Object.freeze(persisted.nodes.map(rehydrateStructuralNode)),
+    truncated: persisted.truncated,
+    capturedAt: persisted.capturedAt,
+  }) as StructuralShape;
+}
+
+function rehydrateStructuralNode(node: StructuralNode): StructuralNode {
+  if (node.kind === 'container') {
+    return Object.freeze({
+      kind: 'container',
+      tag: node.tag,
+      className: node.className,
+      style: Object.freeze({ ...node.style }),
+      children: Object.freeze(node.children.map(rehydrateStructuralNode)),
+    }) as ContainerNode;
+  }
+  return Object.freeze({
+    kind: 'leaf',
+    leafKind: node.leafKind,
+    className: node.className ?? '',
+    style: Object.freeze({ ...node.style }),
+    textLines: node.textLines ? Object.freeze([...node.textLines]) : undefined,
+  }) as LeafNode;
+}
+
 /**
  * Rebuild `style` + `lineStyles` for nodes that lost them via serialization.
  * Walks the array in-place where possible and freezes the result so the render
  * path stays allocation-free.
  */
-function rehydrateShape(shape: CachedShape): CachedShape {
-  const nodes = shape.nodes.map((n) => (n.style ? n : freezeNodeStyles(n)));
+function rehydrateShape(shape: PersistedShape): CachedShape {
+  const nodes = shape.nodes.map((n) => freezeNodeStyles(n as ShapeNode));
   return Object.freeze({
     nodes: Object.freeze(nodes),
     width: shape.width,
@@ -90,38 +299,71 @@ function leanNodes(nodes: ReadonlyArray<ShapeNode>): Partial<ShapeNode>[] {
     radius: n.radius,
     lines: n.lines,
     lineHeight: n.lineHeight,
+    textRects: n.textRects
+      ? n.textRects.map((r) => ({ x: r.x, y: r.y, w: r.w, h: r.h }))
+      : undefined,
+    bg: n.bg,
+    border: n.border,
+    boxShadow: n.boxShadow,
+    opacity: n.opacity,
+    textAlign: n.textAlign,
   }));
 }
 
 function freezeNodeStyles(node: ShapeNode): ShapeNode {
-  const style: CSSProperties = Object.freeze({
+  const baseStyle: CSSProperties = {
     left: `${node.x}px`,
     top: `${node.y}px`,
     width: `${node.w}px`,
     height: `${node.h}px`,
     borderRadius: `${node.radius}px`,
-  });
+  };
+  applyVisualSignals(baseStyle, node);
+  const style = Object.freeze(baseStyle);
 
   let lineStyles: ReadonlyArray<Readonly<CSSProperties>> | undefined;
-  if (node.type === 'text' && node.lines && node.lines > 1) {
+
+  if (node.type === 'text' && node.textRects && node.textRects.length > 0) {
+    const radiusStr = `${node.radius}px`;
+    const arr: Readonly<CSSProperties>[] = [];
+    for (const r of node.textRects) {
+      const lineStyle: CSSProperties = {
+        left: `${r.x}px`,
+        top: `${r.y}px`,
+        width: `${r.w}px`,
+        height: `${r.h}px`,
+        borderRadius: radiusStr,
+      };
+      applyVisualSignals(lineStyle, node);
+      arr.push(Object.freeze(lineStyle));
+    }
+    lineStyles = Object.freeze(arr);
+  } else if (node.type === 'text' && node.lines && node.lines > 1) {
     const lh = node.lineHeight ?? Math.round(node.h / node.lines);
     const barHeight = Math.max(8, Math.round(lh * 0.7));
-    const widthFull = `${node.w}px`;
-    const widthLast = `${Math.max(40, Math.round(node.w * 0.7))}px`;
+    const widthFull = node.w;
+    const widthLast = Math.max(40, Math.round(node.w * 0.7));
     const heightStr = `${barHeight}px`;
     const radiusStr = `${node.radius}px`;
     const arr: Readonly<CSSProperties>[] = [];
     for (let i = 1; i <= node.lines; i++) {
       const isLast = i === node.lines;
-      arr.push(
-        Object.freeze<CSSProperties>({
-          left: `${node.x}px`,
-          top: `${node.y + (i - 1) * lh}px`,
-          width: isLast ? widthLast : widthFull,
-          height: heightStr,
-          borderRadius: radiusStr,
-        })
-      );
+      const lineWidth = isLast ? widthLast : widthFull;
+      let leftX = node.x;
+      if (isLast && node.textAlign) {
+        const slack = widthFull - lineWidth;
+        if (node.textAlign === 'center') leftX = node.x + Math.round(slack / 2);
+        else if (node.textAlign === 'right' || node.textAlign === 'end') leftX = node.x + slack;
+      }
+      const lineStyle: CSSProperties = {
+        left: `${leftX}px`,
+        top: `${node.y + (i - 1) * lh}px`,
+        width: `${lineWidth}px`,
+        height: heightStr,
+        borderRadius: radiusStr,
+      };
+      applyVisualSignals(lineStyle, node);
+      arr.push(Object.freeze(lineStyle));
     }
     lineStyles = Object.freeze(arr);
   }
@@ -135,7 +377,23 @@ function freezeNodeStyles(node: ShapeNode): ShapeNode {
     radius: node.radius,
     lines: node.lines,
     lineHeight: node.lineHeight,
+    textRects: node.textRects ? Object.freeze(node.textRects) : undefined,
+    bg: node.bg,
+    border: node.border,
+    boxShadow: node.boxShadow,
+    opacity: node.opacity,
+    textAlign: node.textAlign,
     style,
     lineStyles,
   });
 }
+
+function applyVisualSignals(
+  out: CSSProperties,
+  node: { bg?: string; border?: string; boxShadow?: string; opacity?: number }
+): void {
+  if (node.bg) out.background = node.bg;
+  if (node.border) out.border = node.border;
+  if (node.boxShadow) out.boxShadow = node.boxShadow;
+  if (node.opacity !== undefined) out.opacity = node.opacity;
+}

package/src/index.ts

@@ -2,15 +2,54 @@
 export { default as ASkeleton } from './components/ASkeleton.vue';
 export { default as ASkeletonLayer } from './components/ASkeletonLayer.vue';
 export { default as ASkeletonBlock } from './components/ASkeletonBlock.vue';
+export { default as ASkeletonClone } from './components/ASkeletonClone.vue';
 export { StructuralSkeleton } from './components/StructuralSkeleton';
 
+/* Style-capture engine — public surface for advanced consumers who want to
+ * roll their own capture/replay flow. */
+export { captureSnapshot } from './utils/captureStyles';
+export type {
+  CaptureSnapshot,
+  CapturedNode,
+  TextLineRect,
+  CaptureOptions,
+} from './utils/captureStyles';
+
+/* Variant primitives — Vuetify/shadcn/Flowbite-style preset skeletons.
+ * Use these when auto-detect from a slot isn't right (or when you want a
+ * standalone skeleton without wrapping real content). Each is a thin SFC
+ * on top of `.a-skel` + variant CSS classes. */
+export { default as ASkeletonText } from './components/variants/ASkeletonText.vue';
+export { default as ASkeletonHeading } from './components/variants/ASkeletonHeading.vue';
+export { default as ASkeletonAvatar } from './components/variants/ASkeletonAvatar.vue';
+export { default as ASkeletonImage } from './components/variants/ASkeletonImage.vue';
+export { default as ASkeletonVideo } from './components/variants/ASkeletonVideo.vue';
+export { default as ASkeletonButton } from './components/variants/ASkeletonButton.vue';
+export { default as ASkeletonInput } from './components/variants/ASkeletonInput.vue';
+export { default as ASkeletonListItem } from './components/variants/ASkeletonListItem.vue';
+export { default as ASkeletonCard } from './components/variants/ASkeletonCard.vue';
+export { default as ASkeletonTable } from './components/variants/ASkeletonTable.vue';
+export { default as ASkeletonChart } from './components/variants/ASkeletonChart.vue';
+export { default as ASkeletonForm } from './components/variants/ASkeletonForm.vue';
+export { default as ASkeletonArticle } from './components/variants/ASkeletonArticle.vue';
+export { default as ASkeletonDivider } from './components/variants/ASkeletonDivider.vue';
+export { default as ASkeletonChip } from './components/variants/ASkeletonChip.vue';
+
 /* Composables */
 export { useSkeleton } from './composables/useSkeleton';
 export { useShapeProbe } from './composables/useShapeProbe';
-export { getCached, setCached, clearCached } from './composables/useSkeletonCache';
+export {
+  getCached,
+  setCached,
+  clearCached,
+  getCachedStructural,
+  setCachedStructural,
+  clearCachedStructural,
+} from './composables/useSkeletonCache';
 
 /* Pure utilities — for direct measurement, vnode-walking, default key derivation. */
 export { walkDom } from './utils/walkDom';
+export { walkStructural } from './utils/walkStructural';
 export { buildStructuralSkeleton } from './utils/buildStructuralSkeleton';
 export { fingerprintSlot } from './utils/fingerprint';
 
@@ -25,8 +64,15 @@ export type {
   ShapeNodeType,
   SkeletonAnimation,
   SkeletonFallback,
+  StructuralShape,
+  StructuralNode,
+  ContainerNode,
+  LeafNode,
+  LeafKind,
+  StructuralTextLineRect,
 } from './types';
 export type { UseSkeletonOptions, UseSkeletonReturn } from './composables/useSkeleton';
-export type { ShapeProbeOptions } from './composables/useShapeProbe';
+export type { ShapeProbeOptions, CaptureStrategy, ProbeShape } from './composables/useShapeProbe';
 export type { WalkOptions } from './utils/walkDom';
+export type { WalkStructuralOptions } from './utils/walkStructural';
 export type { BuildOptions } from './utils/buildStructuralSkeleton';

package/src/nuxt/index.ts

@@ -25,6 +25,22 @@ const COMPONENTS: Record<string, string> = {
   ASkeleton: '@alikhalilll/a-skeleton',
   ASkeletonLayer: '@alikhalilll/a-skeleton',
   ASkeletonBlock: '@alikhalilll/a-skeleton',
+  /* Variant primitives */
+  ASkeletonText: '@alikhalilll/a-skeleton',
+  ASkeletonHeading: '@alikhalilll/a-skeleton',
+  ASkeletonAvatar: '@alikhalilll/a-skeleton',
+  ASkeletonImage: '@alikhalilll/a-skeleton',
+  ASkeletonVideo: '@alikhalilll/a-skeleton',
+  ASkeletonButton: '@alikhalilll/a-skeleton',
+  ASkeletonInput: '@alikhalilll/a-skeleton',
+  ASkeletonListItem: '@alikhalilll/a-skeleton',
+  ASkeletonCard: '@alikhalilll/a-skeleton',
+  ASkeletonTable: '@alikhalilll/a-skeleton',
+  ASkeletonChart: '@alikhalilll/a-skeleton',
+  ASkeletonForm: '@alikhalilll/a-skeleton',
+  ASkeletonArticle: '@alikhalilll/a-skeleton',
+  ASkeletonDivider: '@alikhalilll/a-skeleton',
+  ASkeletonChip: '@alikhalilll/a-skeleton',
 };
 
 const module: NuxtModule<ModuleOptions> = defineNuxtModule<ModuleOptions>({

package/src/resolver/index.ts

@@ -20,6 +20,22 @@ const COMPONENT_TO_ENTRY: Record<string, string> = {
   ASkeleton: '@alikhalilll/a-skeleton',
   ASkeletonLayer: '@alikhalilll/a-skeleton',
   ASkeletonBlock: '@alikhalilll/a-skeleton',
+  /* Variant primitives */
+  ASkeletonText: '@alikhalilll/a-skeleton',
+  ASkeletonHeading: '@alikhalilll/a-skeleton',
+  ASkeletonAvatar: '@alikhalilll/a-skeleton',
+  ASkeletonImage: '@alikhalilll/a-skeleton',
+  ASkeletonVideo: '@alikhalilll/a-skeleton',
+  ASkeletonButton: '@alikhalilll/a-skeleton',
+  ASkeletonInput: '@alikhalilll/a-skeleton',
+  ASkeletonListItem: '@alikhalilll/a-skeleton',
+  ASkeletonCard: '@alikhalilll/a-skeleton',
+  ASkeletonTable: '@alikhalilll/a-skeleton',
+  ASkeletonChart: '@alikhalilll/a-skeleton',
+  ASkeletonForm: '@alikhalilll/a-skeleton',
+  ASkeletonArticle: '@alikhalilll/a-skeleton',
+  ASkeletonDivider: '@alikhalilll/a-skeleton',
+  ASkeletonChip: '@alikhalilll/a-skeleton',
 };
 
 export default function ASkeletonResolver(opts: ResolverOptions = {}): ComponentResolver {

package/src/types.ts

@@ -2,6 +2,14 @@ import type { CSSProperties, HTMLAttributes } from 'vue';
 
 export type ShapeNodeType = 'block' | 'text' | 'image' | 'circle';
 
+/** A single per-line text rect captured via the `Range` API — root-relative. */
+export interface TextLineRect {
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+}
+
 /** A single shimmer block in a captured skeleton — positioned absolutely inside the layer. */
 export interface ShapeNode {
   type: ShapeNodeType;
@@ -14,6 +22,23 @@ export interface ShapeNode {
   lines?: number;
   /** Line-height used when expanding `lines` into stacked bars. */
   lineHeight?: number;
+  /**
+   * Per-line text rects captured via `Range.getClientRects()` — when present, each
+   * rendered text line gets its own bar at the exact position and width of the
+   * actual rendered text, so wrapped/centered/RTL/short-last-line all replay correctly
+   * without heuristics. Supersedes `lines` + `lineHeight` for text nodes.
+   */
+  textRects?: ReadonlyArray<TextLineRect>;
+  /** Background colour captured via `getComputedStyle()` — applied inline so e.g. a white button stays white. */
+  bg?: string;
+  /** Shorthand border (`"<width>px solid <color>"`) — captured when the element has a visible border. */
+  border?: string;
+  /** Box-shadow captured verbatim when non-trivial — preserves elevation on cards. */
+  boxShadow?: string;
+  /** Element opacity when < 1 — captured so semi-transparent surfaces replay correctly. */
+  opacity?: number;
+  /** Resolved `text-align` (only meaningful for `type='text'`). */
+  textAlign?: 'left' | 'right' | 'center' | 'justify' | 'start' | 'end';
   /**
    * Pre-computed (and frozen) inline style for the block. Built once during
    * capture so the render path never allocates a style object per node per
@@ -35,16 +60,104 @@ export interface CachedShape {
   truncated?: boolean;
 }
 
+/* ─────────────────────────────────────────────────────────────────────────────
+ * Structural skeleton — tree-shaped capture used by Recipe 3
+ * (`useSkeleton()` + `<ASkeletonLayer>`).
+ *
+ * Differs from `CachedShape` in two ways: the output is a *tree* rather than a
+ * flat list, and each container preserves its original `class` + a captured
+ * subset of layout-affecting CSS so the skeleton flows through the real DOM's
+ * flex/grid/spacing rules instead of being absolutely positioned to fixed
+ * coordinates.
+ *
+ * Leaves carry their own width/height/border-radius + visual signals inline
+ * and render as `<div class="a-skel">` placeholders that sit in whatever space
+ * their parent's layout reserves for them.
+ * ───────────────────────────────────────────────────────────────────────────── */
+
+/** Per-line text rect on a text leaf — coordinates are leaf-relative. */
+export interface StructuralTextLineRect {
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+}
+
+export type StructuralNode = ContainerNode | LeafNode;
+
+export interface ContainerNode {
+  kind: 'container';
+  /** Lowercased tag — preserved so semantic CSS / a11y still applies. */
+  tag: string;
+  /** Original `class` attribute, verbatim. Empty string when the element has no class. */
+  className: string;
+  /** Captured layout + visual CSS (frozen). Layout props belong on containers; visual signals optional. */
+  style: Readonly<CSSProperties>;
+  children: ReadonlyArray<StructuralNode>;
+}
+
+export type LeafKind = 'block' | 'text' | 'image' | 'media';
+
+export interface LeafNode {
+  kind: 'leaf';
+  leafKind: LeafKind;
+  /** Original `class` attribute of the real element, verbatim. Empty string when absent. */
+  className: string;
+  /**
+   * Captured inline style: width, height, plus the same comprehensive
+   * layout + visual capture used on containers (display, margin, padding,
+   * border, background, transform, …). Frozen.
+   */
+  style: Readonly<CSSProperties>;
+  /**
+   * Per-line rects for text leaves (`leafKind === 'text'`), captured via
+   * `Range.getClientRects()`. Coordinates are relative to the leaf's own box,
+   * so the renderer can lay them out with `position: absolute` inside a
+   * normal-flow text host.
+   */
+  textLines?: ReadonlyArray<StructuralTextLineRect>;
+}
+
+export interface StructuralShape {
+  /** Captured root rect — used by consumers for sanity checks; not for replay sizing. */
+  width: number;
+  height: number;
+  nodes: ReadonlyArray<StructuralNode>;
+  /** Was the walk cut short by `maxNodes`? */
+  truncated: boolean;
+  /** ms since epoch — useful for cache invalidation policies. */
+  capturedAt: number;
+  /** Persisted-shape schema version. Currently 3. */
+  v: 3;
+}
+
 export type SkeletonAnimation = 'shimmer' | 'pulse' | 'none';
 export type SkeletonFallback = 'shimmer' | 'block';
 
+export type ASkeletonMode = 'mirror' | 'clone';
+
 export interface ASkeletonProps {
   /** When true, render the captured skeleton (or `fallback` slot) instead of the default slot. */
   loading: boolean;
   /**
-   * Identifier used to look up + persist the captured shape. Falls back to the
-   * slot's first child component name, then `'anonymous'`. Pass explicitly when
-   * the same component renders different shapes depending on props.
+   * Rendering strategy. Default `'mirror'`.
+   *   - `'mirror'`: walks the slot's vnode tree and preserves every element
+   *     with its real class / inline style. Pure-Vue, SSR-safe, no DOM read.
+   *   - `'clone'`: mounts the slot off-screen once, takes a comprehensive
+   *     `getComputedStyle()` snapshot of every leaf, then replays the
+   *     snapshot as positioned divs carrying every captured CSS property.
+   *     Pixel-identical to the real render, regardless of styling system
+   *     (Tailwind, CSS-in-JS, DaisyUI, computed inline styles). Requires
+   *     a DOM (client-side only).
+   */
+  mode?: ASkeletonMode;
+  /**
+   * Identifier used to look up + persist the captured shape. Defaults to
+   * `"<slot-fingerprint>:<useId()>"` so every `<ASkeleton>` instance gets its
+   * own cache slot automatically — two `<ASkeleton><UserCard/></ASkeleton>` on
+   * the same page never collide. Pass explicitly when you *want* multiple
+   * instances to share a captured shape (e.g. a list of identical cards), or
+   * when one instance renders different shapes depending on a prop.
    */
   cacheKey?: string;
   /** Max recursion depth during shape capture. Default 6. */
@@ -79,8 +192,14 @@ export interface ASkeletonSlots {
 }
 
 export interface ASkeletonLayerProps {
-  /** Shape captured by `walkDom` / `useSkeleton`. Renders nothing when undefined. */
-  shape?: CachedShape;
+  /**
+   * Structural shape captured by `useSkeleton()` (Recipe 3) or `walkStructural()`
+   * directly. Renders nothing when `undefined`. The layer drops into the
+   * consumer's container as a transparent shell — captured containers preserve
+   * their tag/class/layout so the skeleton flows naturally inside the
+   * surrounding layout rather than being absolutely positioned.
+   */
+  shape?: StructuralShape;
   /** Animation variant. Default `'shimmer'`. */
   animation?: SkeletonAnimation;
   /** Class on the layer wrapper. */