@alikhalilll/a-skeleton 1.0.0 → 1.2.0

package/dist/index.d.cts

@@ -2,6 +2,13 @@ import { CSSProperties, HTMLAttributes, PropType, Ref, VNode, VNodeArrayChildren
 
 //#region src/types.d.ts
 type ShapeNodeType = 'block' | 'text' | 'image' | 'circle';
+/** A single per-line text rect captured via the `Range` API — root-relative. */
+interface TextLineRect$1 {
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+}
 /** A single shimmer block in a captured skeleton — positioned absolutely inside the layer. */
 interface ShapeNode {
   type: ShapeNodeType;
@@ -14,6 +21,23 @@ 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$1>;
+  /** 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
@@ -33,15 +57,81 @@ interface CachedShape {
   /** Was the walk cut short by `maxNodes`? Surface so consumers can tune the budget. */
   truncated?: boolean;
 }
+/** Per-line text rect on a text leaf — coordinates are leaf-relative. */
+interface StructuralTextLineRect {
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+}
+type StructuralNode = ContainerNode | LeafNode;
+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>;
+}
+type LeafKind = 'block' | 'text' | 'image' | 'media';
+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>;
+}
+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;
+}
 type SkeletonAnimation = 'shimmer' | 'pulse' | 'none';
 type SkeletonFallback = 'shimmer' | 'block';
+type ASkeletonMode = 'mirror' | 'clone';
 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. */
@@ -74,8 +164,14 @@ interface ASkeletonSlots {
   fallback?: () => unknown;
 }
 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. */
@@ -105,28 +201,131 @@ interface ASkeletonBlockProps {
 type __VLS_Slots = ASkeletonSlots;
 declare const __VLS_base: import("vue").DefineComponent<ASkeletonProps, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<ASkeletonProps> & Readonly<{}>, {
   animation: SkeletonAnimation;
+  mode: ASkeletonMode;
   maxDepth: number;
   maxNodes: number;
   minNodeSize: number;
   persist: boolean;
   fallback: SkeletonFallback;
 }, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
-declare const __VLS_export$2: typeof __VLS_base;
-declare const _default: typeof __VLS_export$2;
+declare const __VLS_export$18: typeof __VLS_base;
+declare const _default: typeof __VLS_export$18;
 //#endregion
 //#region src/components/ASkeletonLayer.vue.d.ts
-declare const __VLS_export$1: import("vue").DefineComponent<ASkeletonLayerProps, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<ASkeletonLayerProps> & Readonly<{}>, {
+declare const __VLS_export$17: import("vue").DefineComponent<ASkeletonLayerProps, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<ASkeletonLayerProps> & Readonly<{}>, {
   animation: SkeletonAnimation;
 }, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
-declare const _default$2: typeof __VLS_export$1;
+declare const _default$14: typeof __VLS_export$17;
 //#endregion
 //#region src/components/ASkeletonBlock.vue.d.ts
-declare const __VLS_export: import("vue").DefineComponent<ASkeletonBlockProps, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<ASkeletonBlockProps> & Readonly<{}>, {
+declare const __VLS_export$16: import("vue").DefineComponent<ASkeletonBlockProps, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<ASkeletonBlockProps> & Readonly<{}>, {
   type: ShapeNodeType;
   lines: number;
   animation: SkeletonAnimation;
 }, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
-declare const _default$1: typeof __VLS_export;
+declare const _default$3: typeof __VLS_export$16;
+//#endregion
+//#region src/utils/domRead.d.ts
+/**
+ * Shared DOM-read helpers used by both capture strategies:
+ *   - `captureStyles.ts` (clone-mode comprehensive style snapshot)
+ *   - `walkStructural.ts` (Recipe 3 tree-shaped capture)
+ *
+ * One source of truth for "what counts as a default CSS value", how to read a
+ * computed-style subset into a frozen camelCased object, and how to measure
+ * per-line text rectangles. Keeping both walkers behind these helpers prevents
+ * silent drift between the two pipelines.
+ */
+/** A single rendered text-line rectangle, expressed in root-relative pixels. */
+interface TextLineRect {
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+}
+//#endregion
+//#region src/utils/captureStyles.d.ts
+/** A captured element — geometry + comprehensive style snapshot + children. */
+interface CapturedNode {
+  /** Tag name lowercased — used by the replay to decide content-type treatment. */
+  tag: string;
+  /** Root-relative position + size in CSS pixels. */
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+  /**
+   * Frozen, ready-to-apply `style` object. Only non-default visual
+   * properties are included — the snapshot for a default `<div>` is tiny.
+   */
+  style: Readonly<Record<string, string>>;
+  /**
+   * Content classification — drives how `<ASkeletonClone>` renders the leaf:
+   *   - `text`     → shimmer text bar (optionally with per-line rects)
+   *   - `image`    → solid surface with image-placeholder icon
+   *   - `video`    → solid surface with play-icon
+   *   - `media`    → atomic block (svg/canvas/iframe — no icon)
+   *   - `block`    → opaque shimmer block (default for unrecognised leaves)
+   *   - `container` → has children; rendered as a positioned wrapper
+   */
+  kind: 'text' | 'image' | 'video' | 'media' | 'block' | 'container';
+  /**
+   * Per-line text rects (only set when `kind === 'text'`). Replaces the
+   * single-rect bar with one bar per rendered text line at the exact width
+   * of that line — handles wrapping, RTL, centered headings 1:1.
+   */
+  textLines?: ReadonlyArray<TextLineRect>;
+  /** Children (only set when `kind === 'container'`). */
+  children?: ReadonlyArray<CapturedNode>;
+}
+interface CaptureSnapshot {
+  /** Overall bounding box. */
+  width: number;
+  height: number;
+  /** Top-level captured nodes (siblings of the root's direct children). */
+  nodes: ReadonlyArray<CapturedNode>;
+  /** True if `maxNodes` was hit and the walk bailed out early. */
+  truncated: boolean;
+  /** When the snapshot was taken (ms since epoch). For cache invalidation policies. */
+  capturedAt: number;
+}
+interface CaptureOptions {
+  /** Max recursion depth. Default 12. */
+  maxDepth?: number;
+  /** Hard cap on captured nodes. Default 800. */
+  maxNodes?: number;
+  /** Skip elements smaller than this many CSS pixels (either axis). Default 4. */
+  minSize?: number;
+  /**
+   * When true, capture child elements even inside leaves that we'd normally
+   * treat atomically. Default false (atomic = single block).
+   */
+  walkAtomic?: boolean;
+}
+/**
+ * Snapshot the rendered DOM under `root`, returning a frozen tree of every
+ * visible element + its computed visual styles. Replaying the snapshot
+ * produces a surface visually identical to `root`.
+ */
+declare function captureSnapshot(root: HTMLElement, options?: CaptureOptions): CaptureSnapshot;
+//#endregion
+//#region src/components/ASkeletonClone.vue.d.ts
+/**
+ * `<ASkeletonClone>` — replays a `CaptureSnapshot` produced by
+ * `captureSnapshot()` as a tree of positioned divs each carrying its
+ * captured inline style. Pure render component; the recursive per-node
+ * rendering lives in `CloneNode` to keep the strategy table isolated from
+ * the layer-level concerns (sizing, animation, a11y).
+ */
+interface Props$15 {
+  shape: CaptureSnapshot;
+  animation?: 'pulse' | 'shimmer' | 'wave' | 'none';
+  class?: string | string[] | Record<string, boolean>;
+}
+declare const __VLS_export$15: import("vue").DefineComponent<Props$15, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<Props$15> & Readonly<{}>, {
+  animation: "pulse" | "shimmer" | "wave" | "none";
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default$8: typeof __VLS_export$15;
 //#endregion
 //#region src/components/StructuralSkeleton.d.ts
 /**
@@ -178,6 +377,232 @@ declare const StructuralSkeleton: import("vue").DefineComponent<import("vue").Ex
   maxNodes: number;
 }, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
 //#endregion
+//#region src/components/variants/ASkeletonText.vue.d.ts
+interface Props$14 {
+  lines?: number;
+  width?: number | string;
+  /** Animation variant. Default `'pulse'`. */
+  animation?: 'pulse' | 'shimmer' | 'wave' | 'none';
+  class?: HTMLAttributes['class'];
+}
+declare const __VLS_export$14: import("vue").DefineComponent<Props$14, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<Props$14> & Readonly<{}>, {
+  lines: number;
+  animation: "pulse" | "shimmer" | "wave" | "none";
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default$17: typeof __VLS_export$14;
+//#endregion
+//#region src/components/variants/ASkeletonHeading.vue.d.ts
+interface Props$13 {
+  level?: 1 | 2 | 3 | 4 | 5 | 6;
+  width?: number | string;
+  animation?: 'pulse' | 'shimmer' | 'wave' | 'none';
+  class?: HTMLAttributes['class'];
+}
+declare const __VLS_export$13: import("vue").DefineComponent<Props$13, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<Props$13> & Readonly<{}>, {
+  animation: "pulse" | "shimmer" | "wave" | "none";
+  level: 1 | 2 | 3 | 4 | 5 | 6;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default$11: typeof __VLS_export$13;
+//#endregion
+//#region src/components/variants/ASkeletonAvatar.vue.d.ts
+interface Props$12 {
+  size?: number | string;
+  shape?: 'circle' | 'square' | 'rounded';
+  animation?: 'pulse' | 'shimmer' | 'wave' | 'none';
+  class?: HTMLAttributes['class'];
+}
+declare const __VLS_export$12: import("vue").DefineComponent<Props$12, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<Props$12> & Readonly<{}>, {
+  animation: "pulse" | "shimmer" | "wave" | "none";
+  shape: "circle" | "square" | "rounded";
+  size: number | string;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default$2: typeof __VLS_export$12;
+//#endregion
+//#region src/components/variants/ASkeletonImage.vue.d.ts
+interface Props$11 {
+  ratio?: string;
+  width?: number | string;
+  height?: number | string;
+  showIcon?: boolean;
+  animation?: 'pulse' | 'shimmer' | 'wave' | 'none';
+  class?: HTMLAttributes['class'];
+}
+declare const __VLS_export$11: import("vue").DefineComponent<Props$11, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<Props$11> & Readonly<{}>, {
+  animation: "pulse" | "shimmer" | "wave" | "none";
+  ratio: string;
+  showIcon: boolean;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default$12: typeof __VLS_export$11;
+//#endregion
+//#region src/components/variants/ASkeletonVideo.vue.d.ts
+interface Props$10 {
+  ratio?: string;
+  width?: number | string;
+  height?: number | string;
+  showIcon?: boolean;
+  animation?: 'pulse' | 'shimmer' | 'wave' | 'none';
+  class?: HTMLAttributes['class'];
+}
+declare const __VLS_export$10: import("vue").DefineComponent<Props$10, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<Props$10> & Readonly<{}>, {
+  animation: "pulse" | "shimmer" | "wave" | "none";
+  ratio: string;
+  showIcon: boolean;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default$18: typeof __VLS_export$10;
+//#endregion
+//#region src/components/variants/ASkeletonButton.vue.d.ts
+interface Props$9 {
+  width?: number | string;
+  height?: number | string;
+  outlined?: boolean;
+  animation?: 'pulse' | 'shimmer' | 'wave' | 'none';
+  class?: HTMLAttributes['class'];
+}
+declare const __VLS_export$9: import("vue").DefineComponent<Props$9, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<Props$9> & Readonly<{}>, {
+  animation: "pulse" | "shimmer" | "wave" | "none";
+  width: number | string;
+  height: number | string;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default$4: typeof __VLS_export$9;
+//#endregion
+//#region src/components/variants/ASkeletonInput.vue.d.ts
+interface Props$8 {
+  width?: number | string;
+  height?: number | string;
+  animation?: 'pulse' | 'shimmer' | 'wave' | 'none';
+  class?: HTMLAttributes['class'];
+}
+declare const __VLS_export$8: import("vue").DefineComponent<Props$8, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<Props$8> & Readonly<{}>, {
+  animation: "pulse" | "shimmer" | "wave" | "none";
+  width: number | string;
+  height: number | string;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default$13: typeof __VLS_export$8;
+//#endregion
+//#region src/components/variants/ASkeletonListItem.vue.d.ts
+interface Props$7 {
+  avatar?: boolean;
+  lines?: 1 | 2 | 3;
+  trailing?: boolean;
+  animation?: 'pulse' | 'shimmer' | 'wave' | 'none';
+  class?: HTMLAttributes['class'];
+}
+declare const __VLS_export$7: import("vue").DefineComponent<Props$7, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<Props$7> & Readonly<{}>, {
+  lines: 1 | 2 | 3;
+  animation: "pulse" | "shimmer" | "wave" | "none";
+  avatar: boolean;
+  trailing: boolean;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default$15: typeof __VLS_export$7;
+//#endregion
+//#region src/components/variants/ASkeletonCard.vue.d.ts
+interface Props$6 {
+  media?: boolean;
+  heading?: boolean;
+  lines?: number;
+  actions?: boolean;
+  footerAvatar?: boolean;
+  animation?: 'pulse' | 'shimmer' | 'wave' | 'none';
+  class?: HTMLAttributes['class'];
+}
+declare const __VLS_export$6: import("vue").DefineComponent<Props$6, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<Props$6> & Readonly<{}>, {
+  lines: number;
+  animation: "pulse" | "shimmer" | "wave" | "none";
+  media: boolean;
+  heading: boolean;
+  actions: boolean;
+  footerAvatar: boolean;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default$5: typeof __VLS_export$6;
+//#endregion
+//#region src/components/variants/ASkeletonTable.vue.d.ts
+interface Props$5 {
+  rows?: number;
+  columns?: number;
+  showHeader?: boolean;
+  animation?: 'pulse' | 'shimmer' | 'wave' | 'none';
+  class?: HTMLAttributes['class'];
+}
+declare const __VLS_export$5: import("vue").DefineComponent<Props$5, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<Props$5> & Readonly<{}>, {
+  animation: "pulse" | "shimmer" | "wave" | "none";
+  rows: number;
+  columns: number;
+  showHeader: boolean;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default$16: typeof __VLS_export$5;
+//#endregion
+//#region src/components/variants/ASkeletonChart.vue.d.ts
+interface Props$4 {
+  bars?: number;
+  height?: number | string;
+  showHeader?: boolean;
+  animation?: 'pulse' | 'shimmer' | 'wave' | 'none';
+  class?: HTMLAttributes['class'];
+}
+declare const __VLS_export$4: import("vue").DefineComponent<Props$4, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<Props$4> & Readonly<{}>, {
+  animation: "pulse" | "shimmer" | "wave" | "none";
+  height: number | string;
+  showHeader: boolean;
+  bars: number;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default$6: typeof __VLS_export$4;
+//#endregion
+//#region src/components/variants/ASkeletonForm.vue.d.ts
+interface Props$3 {
+  fields?: number;
+  showSubmit?: boolean;
+  animation?: 'pulse' | 'shimmer' | 'wave' | 'none';
+  class?: HTMLAttributes['class'];
+}
+declare const __VLS_export$3: import("vue").DefineComponent<Props$3, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<Props$3> & Readonly<{}>, {
+  animation: "pulse" | "shimmer" | "wave" | "none";
+  fields: number;
+  showSubmit: boolean;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default$10: typeof __VLS_export$3;
+//#endregion
+//#region src/components/variants/ASkeletonArticle.vue.d.ts
+interface Props$2 {
+  media?: boolean;
+  paragraphs?: number;
+  linesPerParagraph?: number;
+  animation?: 'pulse' | 'shimmer' | 'wave' | 'none';
+  class?: HTMLAttributes['class'];
+}
+declare const __VLS_export$2: import("vue").DefineComponent<Props$2, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<Props$2> & Readonly<{}>, {
+  animation: "pulse" | "shimmer" | "wave" | "none";
+  media: boolean;
+  paragraphs: number;
+  linesPerParagraph: number;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default$1: typeof __VLS_export$2;
+//#endregion
+//#region src/components/variants/ASkeletonDivider.vue.d.ts
+interface Props$1 {
+  thickness?: number;
+  animation?: 'pulse' | 'shimmer' | 'wave' | 'none';
+  class?: HTMLAttributes['class'];
+}
+declare const __VLS_export$1: import("vue").DefineComponent<Props$1, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<Props$1> & Readonly<{}>, {
+  animation: "pulse" | "shimmer" | "wave" | "none";
+  thickness: number;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default$9: typeof __VLS_export$1;
+//#endregion
+//#region src/components/variants/ASkeletonChip.vue.d.ts
+interface Props {
+  width?: number | string;
+  height?: number | string;
+  animation?: 'pulse' | 'shimmer' | 'wave' | 'none';
+  class?: HTMLAttributes['class'];
+}
+declare const __VLS_export: import("vue").DefineComponent<Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<Props> & Readonly<{}>, {
+  animation: "pulse" | "shimmer" | "wave" | "none";
+  width: number | string;
+  height: number | string;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default$7: typeof __VLS_export;
+//#endregion
 //#region src/composables/useSkeleton.d.ts
 interface UseSkeletonOptions {
   /**
@@ -197,31 +622,33 @@ interface UseSkeletonOptions {
   target?: () => HTMLElement | null;
   /** Persist to `localStorage` so first-paint after reload skips the cold start. Default false. */
   persist?: boolean;
-  /** Forwarded to `walkDom`. Default 6. */
+  /** Forwarded to `walkStructural`. Default 12. */
   maxDepth?: number;
-  /** Forwarded to `walkDom`. Default 500. */
+  /** Forwarded to `walkStructural`. Default 500. */
   maxNodes?: number;
-  /** Forwarded to `walkDom`. Default 4. */
+  /** Forwarded to `walkStructural`. Default 4. */
   minSize?: number;
   /** Forwarded to `useShapeProbe`. Default 150 ms. */
   resizeDebounceMs?: number;
 }
 interface UseSkeletonReturn {
-  /** Reactive captured shape — `undefined` on cache miss. Replace your skeleton render path. */
-  shape: Readonly<Ref<CachedShape | undefined>>;
+  /** Reactive captured shape — `undefined` on cache miss. Feed it to `<ASkeletonLayer>`. */
+  shape: Readonly<Ref<StructuralShape | undefined>>;
   /**
    * Synchronously measure the current target and write to cache. Returns the
    * captured shape, or `undefined` if the target wasn't available / nothing
    * worth measuring was rendered. Use when you want to force a capture outside
    * the automatic `ResizeObserver` flow (e.g. after an animation settles).
    */
-  captureNow: () => CachedShape | undefined;
+  captureNow: () => StructuralShape | undefined;
   /** Drop the cache entry for this `cacheKey`. The reactive `shape` flips to `undefined`. */
   clear: () => void;
 }
 /**
- * High-level building block for custom skeleton UIs. Wires up the probe + cache
- * + reactivity so the consumer just renders something using the reactive shape:
+ * High-level building block for Recipe 3 — wires the structural capture +
+ * cache + reactivity around a target element. The reactive `shape` is fed to
+ * `<ASkeletonLayer>` which renders it in normal flow inside the consumer's
+ * container.
  *
  * ```ts
  * const containerRef = ref<HTMLElement | null>(null);
@@ -238,17 +665,29 @@ interface UseSkeletonReturn {
  * </div>
  * ```
  *
- * For more control, drop down to `useShapeProbe` + `getCached`/`setCached` and
- * compose your own.
+ * For more control, drop down to `useShapeProbe` (pass `walkStructural` as the
+ * capture strategy) + `getCachedStructural` / `setCachedStructural` and compose
+ * your own orchestration.
  */
 declare function useSkeleton(options: UseSkeletonOptions): UseSkeletonReturn;
 //#endregion
 //#region src/composables/useShapeProbe.d.ts
-interface ShapeProbeOptions {
+type ProbeShape = CachedShape | StructuralShape;
+/**
+ * Pluggable capture strategy. `walkDom` is the default (flat, absolute-
+ * positioned `CachedShape`). Recipe 3 passes `walkStructural` to produce a
+ * tree-shaped `StructuralShape` instead.
+ */
+type CaptureStrategy<S extends ProbeShape> = (el: HTMLElement, options: {
+  maxDepth: number;
+  maxNodes?: number;
+  minSize?: number;
+}) => S;
+interface ShapeProbeOptions<S extends ProbeShape = CachedShape> {
   maxDepth: number;
-  /** Forwarded to `walkDom`. Default 500. */
+  /** Forwarded to the capture strategy. Default 500. */
   maxNodes?: number;
-  /** Forwarded to `walkDom`. Default 4. */
+  /** Forwarded to the capture strategy. Default 4. */
   minSize?: number;
   /**
    * Debounce window for `ResizeObserver`-triggered re-captures, in ms.
@@ -257,7 +696,12 @@ interface ShapeProbeOptions {
    * always immediate via `requestAnimationFrame`.
    */
   resizeDebounceMs?: number;
-  onCapture: (shape: CachedShape) => void;
+  /**
+   * Capture strategy. Default: `walkDom` (flat positioned-block model).
+   * Pass `walkStructural` for the tree-shaped Recipe 3 model.
+   */
+  capture?: CaptureStrategy<S>;
+  onCapture: (shape: S) => void;
 }
 /**
  * Observe `getTarget()` and capture its rendered shape whenever the element
@@ -269,10 +713,10 @@ interface ShapeProbeOptions {
  *     render queue.
  *   - Subsequent `ResizeObserver` callbacks are debounced (default 150 ms) so a
  *     drag-resize doesn't trigger a fresh DOM walk per frame.
- *   - `walkDom` itself enforces `maxNodes` so even a worst-case capture (10k
- *     descendants) returns in bounded time.
+ *   - The capture strategy itself enforces `maxNodes` so even a worst-case
+ *     capture (10k descendants) returns in bounded time.
  */
-declare function useShapeProbe(getTarget: () => HTMLElement | null, options: ShapeProbeOptions): void;
+declare function useShapeProbe<S extends ProbeShape = CachedShape>(getTarget: () => HTMLElement | null, options: ShapeProbeOptions<S>): void;
 //#endregion
 //#region src/composables/useSkeletonCache.d.ts
 /**
@@ -280,12 +724,29 @@ declare function useShapeProbe(getTarget: () => HTMLElement | null, options: Sha
  * `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.
  */
 declare function getCached(key: string, persist: boolean): CachedShape | undefined;
 /** Store a captured shape. `persist=true` mirrors to `localStorage`. */
 declare function setCached(key: string, value: CachedShape, persist: boolean): void;
-/** 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.
+ */
 declare function clearCached(key?: string): void;
+/**
+ * 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.
+ */
+declare function clearCachedStructural(key?: string): void;
+/**
+ * Lookup a structural shape by key. Reads in-memory first, then `localStorage`
+ * when `persist` is enabled. Stale schema versions get purged on read.
+ */
+declare function getCachedStructural(key: string, persist: boolean): StructuralShape | undefined;
+/** Store a structural shape. `persist=true` mirrors to `localStorage`. */
+declare function setCachedStructural(key: string, value: StructuralShape, persist: boolean): void;
 //#endregion
 //#region src/utils/walkDom.d.ts
 interface WalkOptions {
@@ -312,29 +773,59 @@ interface WalkOptions {
  */
 declare function walkDom(root: HTMLElement, options: WalkOptions): CachedShape;
 //#endregion
+//#region src/utils/walkStructural.d.ts
+interface WalkStructuralOptions {
+  /** Max recursion depth. Default 12. */
+  maxDepth?: number;
+  /** Hard cap on captured nodes. Default 500. */
+  maxNodes?: number;
+  /** Skip elements smaller than this many CSS pixels (either axis). Default 4. */
+  minSize?: number;
+}
+/**
+ * Walk `root`'s descendants and produce a frozen tree-shaped capture.
+ * Direct children of `root` become top-level `nodes`; recursive children
+ * live on their respective `ContainerNode`s.
+ */
+declare function walkStructural(root: HTMLElement, options?: WalkStructuralOptions): StructuralShape;
+//#endregion
 //#region src/utils/buildStructuralSkeleton.d.ts
 interface BuildOptions {
+  /** Animation class applied to every emitted shimmer surface. `null` disables animation. */
   animationClass: string | null;
-  /** Max recursion depth — guards runaway templates. Default 8. */
+  /** Max recursion depth — guards runaway templates. Default 16. */
   maxDepth?: number;
   /**
-   * Hard cap on emitted skeleton nodes. Default 300. A 200-row table doesn't
-   * need 200 distinct skeleton rows on first paint; cap and stop early.
+   * Hard cap on emitted skeleton nodes. Default 600. The walk stops emitting
+   * past this cap; the partial tree is still valid (it just won't include the
+   * leaves beyond the budget).
    */
   maxNodes?: number;
 }
 /**
- * Walk a slot's vnode tree and produce a skeleton that mirrors its rendered
- * structure: same wrapping tags, same `class` strings (so flex/grid/spacing/
- * sizing utilities still apply), but text/atomic leaves replaced with shimmer
- * blocks. The result renders correctly on the FIRST paint without any DOM
- * measurement, as long as the slot's template renders structure even when its
- * data is empty (use `v-if`/`v-else` to swap content, not to gate the wrapper).
+ * Walk a slot's vnode tree and produce a **DOM-mirror skeleton**: every element
+ * is preserved (same tag, same `class`, same inline `style`), and only the
+ * content is replaced. The output is structurally identical to what the real
+ * component would render — Tailwind utilities for layout, spacing, sizing,
+ * backgrounds and shadows all carry through. The CSS does the work of making
+ * it *look* like a skeleton.
  *
- * Performance: `maxNodes` caps the work. When the cap is hit we stop emitting
- * — the caller still gets a valid skeleton, just clipped at the budget. A 1000-
- * row list renders ~300 skeleton rows on first paint and then the measured cache
- * takes over for subsequent loads.
+ * Replacement rules:
+ * - **Raw text** (e.g. interpolations, static strings) is wrapped in
+ *   `<span class="a-skel-text-content">…the real text…</span>`. The text is
+ *   kept as the span's children so the inline layout reserves its real
+ *   rendered width — but the glyphs are painted transparent and a skeleton
+ *   gradient is painted in their place. Multi-line text wraps naturally,
+ *   producing one shimmer rect per visual line at the exact rendered position.
+ * - **Atomic / interactive tags** (`img`, `svg`, `button`, `input`, …) are
+ *   replaced by a `<div class="a-skel-block">` carrying the original element's
+ *   `class` and `style`, so dimensions and shapes (size, border-radius, etc.)
+ *   still drive the layout.
+ * - **Container elements** (`div`, `section`, `h1`, `p`, `a`, `span`, …) are
+ *   preserved as the same tag with the same `class` and `style`; we recurse
+ *   into their children.
+ * - **Component vnodes** can't be introspected at render time, so we emit a
+ *   single `<div class="a-skel-block">` carrying their outer `class` / `style`.
  */
 declare function buildStructuralSkeleton(vnodes: VNodeChild | VNodeArrayChildren | undefined | null, opts: BuildOptions): VNode[];
 //#endregion
@@ -347,5 +838,5 @@ declare function buildStructuralSkeleton(vnodes: VNodeChild | VNodeArrayChildren
  */
 declare function fingerprintSlot(vnodes: VNode[] | undefined): string;
 //#endregion
-export { _default as ASkeleton, _default$1 as ASkeletonBlock, type ASkeletonBlockProps, _default$2 as ASkeletonLayer, type ASkeletonLayerProps, type ASkeletonProps, type ASkeletonSlots, type BuildOptions, type CachedShape, type ShapeNode, type ShapeNodeType, type ShapeProbeOptions, type SkeletonAnimation, type SkeletonFallback, StructuralSkeleton, type UseSkeletonOptions, type UseSkeletonReturn, type WalkOptions, buildStructuralSkeleton, clearCached, fingerprintSlot, getCached, setCached, useShapeProbe, useSkeleton, walkDom };
+export { _default as ASkeleton, _default$1 as ASkeletonArticle, _default$2 as ASkeletonAvatar, _default$3 as ASkeletonBlock, type ASkeletonBlockProps, _default$4 as ASkeletonButton, _default$5 as ASkeletonCard, _default$6 as ASkeletonChart, _default$7 as ASkeletonChip, _default$8 as ASkeletonClone, _default$9 as ASkeletonDivider, _default$10 as ASkeletonForm, _default$11 as ASkeletonHeading, _default$12 as ASkeletonImage, _default$13 as ASkeletonInput, _default$14 as ASkeletonLayer, type ASkeletonLayerProps, _default$15 as ASkeletonListItem, type ASkeletonProps, type ASkeletonSlots, _default$16 as ASkeletonTable, _default$17 as ASkeletonText, _default$18 as ASkeletonVideo, type BuildOptions, type CachedShape, type CaptureOptions, type CaptureSnapshot, type CaptureStrategy, type CapturedNode, type ContainerNode, type LeafKind, type LeafNode, type ProbeShape, type ShapeNode, type ShapeNodeType, type ShapeProbeOptions, type SkeletonAnimation, type SkeletonFallback, type StructuralNode, type StructuralShape, StructuralSkeleton, type StructuralTextLineRect, type TextLineRect, type UseSkeletonOptions, type UseSkeletonReturn, type WalkOptions, type WalkStructuralOptions, buildStructuralSkeleton, captureSnapshot, clearCached, clearCachedStructural, fingerprintSlot, getCached, getCachedStructural, setCached, setCachedStructural, useShapeProbe, useSkeleton, walkDom, walkStructural };
 //# sourceMappingURL=index.d.cts.map