@alikhalilll/a-skeleton 1.0.0 → 1.1.0

package/README.md

@@ -216,17 +216,17 @@ useShapeProbe(() => containerRef.value, {
 
 ## `<ASkeleton>` props
 
-| Prop          | Type                             | Default     | Description                                                                                          |
-| ------------- | -------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------- |
-| `loading`     | `boolean`                        | —           | When `true`, show the skeleton.                                                                      |
-| `cacheKey`    | `string`                         | slot's name | Identifier for the shape cache. Pass explicitly when one component renders different shapes by prop. |
-| `maxDepth`    | `number`                         | `6`         | Max recursion depth when capturing shape.                                                            |
-| `maxNodes`    | `number`                         | `500`       | Hard cap on captured / structural nodes. Walk bails out beyond this with `truncated: true`.          |
-| `minNodeSize` | `number`                         | `4`         | Skip elements smaller than this many CSS pixels (either axis) during capture.                        |
-| `persist`     | `boolean`                        | `false`     | Mirror captured shape to `localStorage` so first-visit-after-reload skips the cold-start fallback.   |
-| `animation`   | `'shimmer' \| 'pulse' \| 'none'` | `'shimmer'` | Animation variant. `prefers-reduced-motion` disables animation automatically.                        |
-| `fallback`    | `'shimmer' \| 'block'`           | `'shimmer'` | Default cache-miss UI when no `#fallback` slot is provided.                                          |
-| `class`       | `HTMLAttributes['class']`        | —           | Class on the outer wrapper.                                                                          |
+| Prop          | Type                             | Default            | Description                                                                                                                                                                                                               |
+| ------------- | -------------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `loading`     | `boolean`                        | —                  | When `true`, show the skeleton.                                                                                                                                                                                           |
+| `cacheKey`    | `string`                         | auto, per-instance | Identifier for the shape cache. Auto-generated as `"<slot-name>:<useId()>"` so each instance has its own slot. Pass explicitly to share a shape across instances, or when one instance renders different shapes per prop. |
+| `maxDepth`    | `number`                         | `6`                | Max recursion depth when capturing shape.                                                                                                                                                                                 |
+| `maxNodes`    | `number`                         | `500`              | Hard cap on captured / structural nodes. Walk bails out beyond this with `truncated: true`.                                                                                                                               |
+| `minNodeSize` | `number`                         | `4`                | Skip elements smaller than this many CSS pixels (either axis) during capture.                                                                                                                                             |
+| `persist`     | `boolean`                        | `false`            | Mirror captured shape to `localStorage` so first-visit-after-reload skips the cold-start fallback.                                                                                                                        |
+| `animation`   | `'shimmer' \| 'pulse' \| 'none'` | `'shimmer'`        | Animation variant. `prefers-reduced-motion` disables animation automatically.                                                                                                                                             |
+| `fallback`    | `'shimmer' \| 'block'`           | `'shimmer'`        | Default cache-miss UI when no `#fallback` slot is provided.                                                                                                                                                               |
+| `class`       | `HTMLAttributes['class']`        | —                  | Class on the outer wrapper.                                                                                                                                                                                               |
 
 ### Slots
 
@@ -255,6 +255,8 @@ setCached('user-card', shape, true); // write + persist
 const shape = getCached('user-card', true);
 ```
 
+Persisted entries carry a schema version. Whenever the `ShapeNode` / `CachedShape` shape changes between releases the version is bumped, and `getCached` purges stale payloads on read — so an upgrade can't replay wrong geometry from a previous version's cache.
+
 ---
 
 ## Theming
@@ -305,7 +307,7 @@ The `.light` scope overrides `--ak-skeleton-shimmer` to a brighter value so pola
 
 Designed for components with hundreds of leaf elements (busy dashboards, long lists, dense forms). Cost is bounded at every layer:
 
-- **Walk budget** — `walkDom` stops emitting after `maxNodes` (default 500) and returns `CachedShape.truncated: true`. A 5000-row table will not lock up the main thread. The structural pass enforces a separate cap (default 300).
+- **Walk budget** — `walkDom` stops emitting after `maxNodes` (default 500) and returns `CachedShape.truncated: true`. A 5000-row table will not lock up the main thread. The structural pass enforces a separate cap (default 300). `<ASkeleton>` logs a one-time `console.warn` per `cacheKey` whenever a capture truncates, so missing nodes surface during development instead of silently replaying a clipped shape.
 - **Min-size filter** — `minNodeSize` (default 4 px) drops hairlines / spacer dots.
 - **Allocation-free render** — captured `ShapeNode`s carry frozen, pre-computed `style` and `lineStyles` objects. Per-type block class strings are pre-joined once per animation value. The cache-hit render loop reads them directly with no per-node function calls.
 - **Batched DOM reads** — `getBoundingClientRect` + `getComputedStyle` happen in one top-down pass with no intervening writes. One layout up front instead of one per element.
@@ -318,6 +320,7 @@ Designed for components with hundreds of leaf elements (busy dashboards, long li
 - The structural pass mirrors what the slot's template actually renders during loading. Gate everything on `v-if="data"` and the walker sees only a comment — fall back to the generic shimmer.
 - Captured shapes are snapshots. `ResizeObserver` re-measures when the wrapper resizes (debounced 150 ms). If you resize _during_ a skeleton render, the cached shape replays unchanged.
 - SSR: the structural skeleton works during SSR (no `window` access needed). Pixel-aligned positioned blocks require a captured shape, which only happens client-side after mount.
+- Two `<ASkeleton>` instances rendering the same component get separate caches by default — the auto-generated key includes `useId()`, so the slot is per-instance. Pass an explicit `cacheKey` to share one captured shape across, e.g., a list of identical cards.
 
 ## License
 

package/dist/index.cjs

@@ -3653,19 +3653,32 @@ function useShapeProbe(getTarget, options) {
 const memory = /* @__PURE__ */ new Map();
 const STORAGE_PREFIX = "a-skeleton:";
 /**
+* Schema version for persisted 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.
+*/
+const SCHEMA_VERSION = 1;
+/**
 * 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.
 */
 function getCached(key, persist) {
 	const hit = memory.get(key);
 	if (hit) return hit;
 	if (!persist || typeof window === "undefined") return void 0;
 	try {
-		const raw = window.localStorage.getItem(STORAGE_PREFIX + key);
+		const storageKey = STORAGE_PREFIX + key;
+		const raw = window.localStorage.getItem(storageKey);
 		if (!raw) return void 0;
-		const rehydrated = rehydrateShape(JSON.parse(raw));
+		const parsed = JSON.parse(raw);
+		if (parsed.v !== SCHEMA_VERSION) {
+			window.localStorage.removeItem(storageKey);
+			return;
+		}
+		const rehydrated = rehydrateShape(parsed);
 		memory.set(key, rehydrated);
 		return rehydrated;
 	} catch {
@@ -3678,9 +3691,11 @@ function setCached(key, value, persist) {
 	if (!persist || typeof window === "undefined") return;
 	try {
 		const lean = {
+			v: SCHEMA_VERSION,
 			width: value.width,
 			height: value.height,
-			nodes: leanNodes(value.nodes)
+			nodes: leanNodes(value.nodes),
+			truncated: value.truncated
 		};
 		window.localStorage.setItem(STORAGE_PREFIX + key, JSON.stringify(lean));
 	} catch {}
@@ -3707,7 +3722,7 @@ function clearCached(key) {
 * path stays allocation-free.
 */
 function rehydrateShape(shape) {
-	const nodes = shape.nodes.map((n) => n.style ? n : freezeNodeStyles(n));
+	const nodes = shape.nodes.map((n) => freezeNodeStyles(n));
 	return Object.freeze({
 		nodes: Object.freeze(nodes),
 		width: shape.width,
@@ -4132,7 +4147,9 @@ const _sfc_main$2 = /* @__PURE__ */ (0, vue.defineComponent)({
 		__expose();
 		const props = __props;
 		const slots = (0, vue.useSlots)();
-		const resolvedKey = (0, vue.computed)(() => props.cacheKey ?? fingerprintSlot(slots.default?.()));
+		const instanceId = (0, vue.useId)();
+		const resolvedKey = (0, vue.computed)(() => props.cacheKey ?? `${fingerprintSlot(slots.default?.())}:${instanceId}`);
+		const warnedKeys = /* @__PURE__ */ new Set();
 		const cached = (0, vue.shallowRef)(getCached(resolvedKey.value, props.persist));
 		(0, vue.watch)(resolvedKey, (key) => {
 			cached.value = getCached(key, props.persist);
@@ -4145,6 +4162,10 @@ const _sfc_main$2 = /* @__PURE__ */ (0, vue.defineComponent)({
 			onCapture: (shape) => {
 				setCached(resolvedKey.value, shape, props.persist);
 				cached.value = shape;
+				if (shape.truncated && !warnedKeys.has(resolvedKey.value)) {
+					warnedKeys.add(resolvedKey.value);
+					console.warn(`[ASkeleton] Capture truncated at maxNodes=${props.maxNodes} for cacheKey="${resolvedKey.value}". The replayed skeleton will be missing nodes. Raise \`max-nodes\` or mark dense subtrees with \`data-skeleton-stop\` to collapse them into a single block.`);
+				}
 			}
 		});
 		const animationClass = (0, vue.computed)(() => props.animation === "none" ? null : `a-skel-block--anim-${props.animation}`);
@@ -4166,7 +4187,9 @@ const _sfc_main$2 = /* @__PURE__ */ (0, vue.defineComponent)({
 		const __returned__ = {
 			props,
 			slots,
+			instanceId,
 			resolvedKey,
+			warnedKeys,
 			cached,
 			wrapperRef,
 			animationClass,