@alikhalilll/a-skeleton 1.0.0 → 1.2.0

package/src/utils/walkDom.ts

@@ -1,5 +1,5 @@
 import type { CSSProperties } from 'vue';
-import type { CachedShape, ShapeNode, ShapeNodeType } from '../types';
+import type { CachedShape, ShapeNode, ShapeNodeType, TextLineRect } from '../types';
 
 export interface WalkOptions {
   maxDepth: number;
@@ -78,11 +78,19 @@ export function walkDom(root: HTMLElement, options: WalkOptions): CachedShape {
     const isLeaf = isLeafTag || hasStop || reachedDepth || childElements.length === 0;
 
     if (isLeaf) {
-      const node = elementToShape(tag, cs, rect, rootRect, hasOwnText);
+      const node = elementToShape(el, tag, cs, rect, rootRect, hasOwnText);
       if (node) nodes.push(node);
       return;
     }
 
+    /* Container with a visible surface (background / border / shadow / opacity)
+     * — emit a backing block at the container's exact rect BEFORE recursing, so
+     * children render on top of a card that keeps its identity. Without this,
+     * a `<div class="bg-white shadow-lg rounded-2xl">` wrapping content would
+     * vanish from the replay because the walker only ever recurses into it. */
+    const containerNode = containerSurfaceToShape(cs, rect, rootRect);
+    if (containerNode) nodes.push(containerNode);
+
     for (let i = 0; i < childElements.length; i++) {
       if (nodes.length >= maxNodes) {
         truncated = true;
@@ -118,7 +126,40 @@ function hasDirectTextContent(el: Element): boolean {
   return false;
 }
 
+/**
+ * Emit a backing block for a container with its own visible surface — real
+ * background, border, box-shadow, or non-full opacity. Geometry is the
+ * container's exact bounding rect so the width / height / radius match the
+ * real DOM 1:1. Returns `null` when the container has no visible surface
+ * (a plain unstyled `<div>` is layout-only and shouldn't add a block).
+ */
+function containerSurfaceToShape(
+  cs: CSSStyleDeclaration,
+  rect: DOMRect,
+  origin: DOMRect
+): ShapeNode | null {
+  const bg = readBackgroundColor(cs);
+  const border = readBorder(cs);
+  const boxShadow = readBoxShadow(cs);
+  const opacity = readOpacity(cs);
+  if (!bg && !border && !boxShadow && opacity === undefined) return null;
+
+  return freezeShape({
+    type: 'block',
+    x: Math.round(rect.left - origin.left),
+    y: Math.round(rect.top - origin.top),
+    w: Math.round(rect.width),
+    h: Math.round(rect.height),
+    radius: parseFloat(cs.borderRadius) || 0,
+    bg,
+    border,
+    boxShadow,
+    opacity,
+  });
+}
+
 function elementToShape(
+  el: Element,
   tag: string,
   cs: CSSStyleDeclaration,
   rect: DOMRect,
@@ -138,6 +179,8 @@ function elementToShape(
   let resolvedRadius = radius;
   let lines: number | undefined;
   let lineHeight: number | undefined;
+  let textRects: TextLineRect[] | undefined;
+  let textAlign: ShapeNode['textAlign'];
 
   if (tag === 'IMG' || tag === 'SVG' || tag === 'VIDEO' || tag === 'CANVAS') {
     type = 'image';
@@ -149,10 +192,21 @@ function elementToShape(
     lineHeight = Math.round(parseFloat(cs.lineHeight) || parseFloat(cs.fontSize) * 1.4 || 16);
     lines = Math.max(1, Math.round(h / lineHeight));
     resolvedRadius = Math.min(radius, 4);
+    textAlign = readTextAlign(cs);
+    textRects = measureTextRects(el, origin);
   } else {
     type = 'block';
   }
 
+  /* Style detectors — captured for every leaf so the replay carries the actual
+   * fill / border / shadow / opacity from the real DOM. Each captured value is
+   * "non-default": skip transparent backgrounds, zero-width borders, "none"
+   * shadows, opacity≥1 — so the persisted payload stays small. */
+  const bg = readBackgroundColor(cs);
+  const border = readBorder(cs);
+  const boxShadow = readBoxShadow(cs);
+  const opacity = readOpacity(cs);
+
   return freezeShape({
     type,
     x,
@@ -162,12 +216,129 @@ function elementToShape(
     radius: resolvedRadius,
     lines,
     lineHeight,
+    textRects,
+    bg,
+    border,
+    boxShadow,
+    opacity,
+    textAlign,
   });
 }
 
+/**
+ * Per-line text rects via `Range.getClientRects()`. Returns one rect per visual
+ * line of rendered text — exact left/width for each line so wrapped paragraphs,
+ * RTL last-line position, centered headings all replay 1:1 without heuristics.
+ * Returns `undefined` if the element has no direct text content or the Range
+ * API isn't usable in this environment.
+ */
+function measureTextRects(el: Element, origin: DOMRect): TextLineRect[] | undefined {
+  if (typeof document === 'undefined' || typeof document.createRange !== 'function')
+    return undefined;
+  let range: Range;
+  try {
+    range = document.createRange();
+    range.selectNodeContents(el);
+  } catch {
+    return undefined;
+  }
+  const rects = range.getClientRects();
+  if (!rects || rects.length === 0) return undefined;
+  /* De-duplicate rects that share the same baseline AND actually touch
+   * horizontally. Two inline spans on the same line emit two rects with
+   * identical y/h whose x ranges abut; merging them gives one bar that
+   * spans the whole rendered line. Two rects with the same y/h on
+   * different visual lines (rare, but possible with float-into-paragraph
+   * layouts) won't touch horizontally, so they stay separate.
+   *
+   * We keep zero-width rects out (they're real but invisible — collapsed
+   * whitespace at line breaks), but we don't filter sub-pixel `width`/
+   * `height` — those are legitimate (1-glyph symbol, etc). */
+  const merged: TextLineRect[] = [];
+  for (let i = 0; i < rects.length; i++) {
+    const r = rects[i];
+    if (r.width <= 0 || r.height <= 0) continue;
+    const lr: TextLineRect = {
+      x: Math.round(r.left - origin.left),
+      y: Math.round(r.top - origin.top),
+      w: Math.round(r.width),
+      h: Math.round(r.height),
+    };
+    const last = merged[merged.length - 1];
+    const sameLine = last && Math.abs(last.y - lr.y) <= 1 && Math.abs(last.h - lr.h) <= 1;
+    /* Touching = `gap` between the trailing edge of `last` and the leading
+     * edge of `lr` is at most 2 px (one rounding slack on each end). */
+    const touching =
+      sameLine && Math.max(last!.x, lr.x) - Math.min(last!.x + last!.w, lr.x + lr.w) <= 2;
+    if (touching) {
+      const leftEdge = Math.min(last!.x, lr.x);
+      const rightEdge = Math.max(last!.x + last!.w, lr.x + lr.w);
+      last!.x = leftEdge;
+      last!.w = rightEdge - leftEdge;
+    } else {
+      merged.push(lr);
+    }
+  }
+  return merged.length > 0 ? merged : undefined;
+}
+
+const TRANSPARENT_RE = /^(transparent|rgba?\([^)]*,\s*0(\.0+)?\s*\)|hsla?\([^)]*,\s*0%?\s*\))$/i;
+
+function readBackgroundColor(cs: CSSStyleDeclaration): string | undefined {
+  const bg = cs.backgroundColor;
+  if (!bg || TRANSPARENT_RE.test(bg)) return undefined;
+  return bg;
+}
+
+function readBorder(cs: CSSStyleDeclaration): string | undefined {
+  /* Treat the top border as representative — uniform borders are the common case.
+   * Skip 0-width and `none` style. */
+  const width = parseFloat(cs.borderTopWidth) || 0;
+  if (width < 0.5) return undefined;
+  const style = cs.borderTopStyle;
+  if (!style || style === 'none' || style === 'hidden') return undefined;
+  const color = cs.borderTopColor;
+  if (!color || TRANSPARENT_RE.test(color)) return undefined;
+  return `${Math.round(width)}px ${style} ${color}`;
+}
+
+function readBoxShadow(cs: CSSStyleDeclaration): string | undefined {
+  const sh = cs.boxShadow;
+  if (!sh || sh === 'none') return undefined;
+  return sh;
+}
+
+function readOpacity(cs: CSSStyleDeclaration): number | undefined {
+  const o = parseFloat(cs.opacity);
+  if (!Number.isFinite(o) || o >= 1) return undefined;
+  if (o <= 0) return undefined; /* fully transparent — caller already skipped these */
+  return Math.round(o * 100) / 100;
+}
+
+function readTextAlign(cs: CSSStyleDeclaration): ShapeNode['textAlign'] {
+  const ta = cs.textAlign as ShapeNode['textAlign'] | undefined;
+  if (!ta) return undefined;
+  if (
+    ta === 'left' ||
+    ta === 'right' ||
+    ta === 'center' ||
+    ta === 'justify' ||
+    ta === 'start' ||
+    ta === 'end'
+  ) {
+    return ta;
+  }
+  return undefined;
+}
+
 /**
  * Pre-compute (and freeze) the inline styles used at render time. Doing it once
  * here means rendering 500 blocks doesn't allocate 500 style objects per frame.
+ *
+ * Captured visual signals (bg, border, shadow, opacity) are merged into the
+ * frozen style so the replay carries the real DOM's surface — a white button
+ * stays white, a ring-bordered button keeps its ring, a shadowed card keeps
+ * its elevation.
  */
 function freezeShape(node: {
   type: ShapeNodeType;
@@ -178,35 +349,73 @@ function freezeShape(node: {
   radius: number;
   lines?: number;
   lineHeight?: number;
+  textRects?: TextLineRect[];
+  bg?: string;
+  border?: string;
+  boxShadow?: string;
+  opacity?: number;
+  textAlign?: ShapeNode['textAlign'];
 }): 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) {
+
+  /* Range-based per-line capture — exact rendered geometry, no heuristics.
+   * Bars sit at the exact captured rect; no shrink/centre math, so dense
+   * paragraphs don't accumulate baseline drift. */
+  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) {
+    /* Fallback path (kept for shapes rehydrated from pre-2 captures): synthesize
+     * lines from `lines` + `lineHeight`. */
     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;
+      /* Honour captured text-align so the short last line lands where the eye
+       * expects: right for RTL, centered for centered headings. */
+      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);
   }
@@ -220,7 +429,43 @@ function freezeShape(node: {
     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,
   });
 }
+
+/**
+ * Merge captured surface signals into a style object in place. Each signal is
+ * additive; `bg` uses `background` shorthand so it wipes the default linear
+ * gradient on `.a-skel-block` cleanly.
+ */
+function applyVisualSignals(
+  out: CSSProperties,
+  node: {
+    bg?: string;
+    border?: string;
+    boxShadow?: string;
+    opacity?: number;
+  }
+): void {
+  if (node.bg) {
+    /* Use `background` (shorthand) so the default `background-image` gradient
+     * from `.a-skel-block` is overridden, not stacked. */
+    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;
+  }
+}