@plannotator/ui 0.22.0

package/components/SparklesIcon.tsx

@@ -0,0 +1,45 @@
+import React from 'react';
+
+interface SparklesIconProps {
+  className?: string;
+  animated?: boolean;
+}
+
+/**
+ * Three-star sparkle icon used for Ask AI entry points.
+ * Uses currentColor for fill so it inherits from parent text color.
+ */
+export const SparklesIcon: React.FC<SparklesIconProps> = ({ className = 'w-3 h-3', animated = false }) => (
+  <svg className={`${className} flex-shrink-0`} viewBox="0 0 128 128" fill="none">
+    {animated && (
+      <style>{`
+        @keyframes sparkle-idle {
+          0%, 100% { opacity: 0.5; }
+          50% { opacity: 1; }
+        }
+      `}</style>
+    )}
+    <g style={animated ? { animation: 'sparkle-idle 2s infinite ease-in-out', animationDelay: '0.35s' } : undefined}>
+      <path
+        d="M121.59 60.83l-13.93-4.49c-8.91-2.94-14.13-10.15-16.58-19.21L84.95 7.27c-.16-.59-.55-1.38-1.75-1.38c-1.01 0-1.59.79-1.75 1.38l-6.13 29.87c-2.46 9.06-7.67 16.27-16.58 19.21l-13.93 4.49c-1.97.64-2 3.42-.04 4.09l14.03 4.83c8.88 2.95 14.06 10.15 16.52 19.17l6.14 29.53c.16.59.49 1.65 1.75 1.65c1.33 0 1.59-1.06 1.75-1.65l6.14-29.53c2.46-9.03 7.64-16.23 16.52-19.17l14.03-4.83c1.94-.68 1.91-3.46-.06-4.1z"
+        fill="currentColor"
+      />
+      <path
+        d="M122.91 62.08c-.22-.55-.65-1.03-1.32-1.25l-13.93-4.49c-8.91-2.94-14.13-10.15-16.58-19.21L84.95 7.27c-.09-.34-.41-.96-.78-1.14l1.98 29.97c1.47 13.68 2.73 20.12 13.65 22c9.38 1.62 20.23 3.48 23.11 3.98z"
+        fill="currentColor" opacity={0.7}
+      />
+    </g>
+    <g style={animated ? { animation: 'sparkle-idle 2s infinite ease-in-out', animationDelay: '0.15s' } : undefined}>
+      <path
+        d="M41.81 86.81c-8.33-2.75-9.09-5.85-10.49-11.08l-3.49-12.24c-.21-.79-2.27-.79-2.49 0L22.97 74.8c-1.41 5.21-4.41 9.35-9.53 11.04l-8.16 3.54c-1.13.37-1.15 1.97-.02 2.35l8.22 2.91c5.1 1.69 8.08 5.83 9.5 11.02l2.37 10.82c.22.79 2.27.79 2.48 0l2.78-10.77c1.41-5.22 3.57-9.37 10.5-11.07l7.72-2.91c1.13-.39 1.12-1.99-.02-2.36l-7-2.56z"
+        fill="currentColor"
+      />
+    </g>
+    <g style={animated ? { animation: 'sparkle-idle 2s infinite ease-in-out', animationDelay: '0.5s' } : undefined}>
+      <path
+        d="M59.74 28.14c.56-.19.54-.99-.03-1.15l-7.72-2.08a4.77 4.77 0 0 1-3.34-3.3L45.61 9.06c-.15-.61-1.02-.61-1.17.01l-2.86 12.5a4.734 4.734 0 0 1-3.4 3.37l-7.67 1.99c-.57.15-.61.95-.05 1.15l8.09 2.8c1.45.5 2.57 1.68 3.01 3.15l2.89 11.59c.15.6 1.01.61 1.16 0l2.99-11.63a4.773 4.773 0 0 1 3.04-3.13l8.1-2.72z"
+        fill="currentColor" opacity={0.5}
+      />
+    </g>
+  </svg>
+);

package/components/StickyHeaderLane.tsx

@@ -0,0 +1,260 @@
+/**
+ * StickyHeaderLane — compact "ghost" header that pins as the user scrolls
+ * past the AnnotationToolstrip.
+ *
+ * At rest (top of doc): invisible, non-interactive. The original toolstrip
+ * and badge cluster on the card remain the visible source of truth.
+ *
+ * Layout is driven by two ResizeObserver measurements — the sticky
+ * wrapper's actual width AND the Viewer action button cluster's actual
+ * width — so the bar fits exactly into the space between its left edge
+ * and the buttons, with no fixed pixel reserves.
+ *
+ *   availableForBar = wrapperWidth - LEFT_OFFSET - actionsWidth - GAP
+ *
+ * Three states based on availableForBar:
+ *   wide  (>= WIDE_BAR_WIDTH): shared lane, toolstrip with active labels.
+ *   tight (>= MIN_BAR_WIDTH):  shared lane, toolstrip icon-only — gives
+ *                              the bar another ~160px of room before
+ *                              forcing a layout change.
+ *   narrow (< MIN_BAR_WIDTH):  stacked below the action buttons on its
+ *                              own full-width row, icon-only toolstrip.
+ *
+ * Composes <AnnotationToolstrip compact /> + <DocBadges layout="row" />.
+ * No state is duplicated — all props are passed through from App.tsx.
+ */
+
+import React, { useEffect, useRef, useState } from 'react';
+import { AnnotationToolstrip } from './AnnotationToolstrip';
+import { DocBadges } from './DocBadges';
+import { useScrollViewport } from '../hooks/useScrollViewport';
+import type { EditorMode, InputMethod } from '../types';
+import type { PlanDiffStats } from '../utils/planDiffEngine';
+
+// Snap a measured pixel width to a 16px grid. ResizeObserver fires every
+// frame during a drag; without quantization the sticky bar would
+// re-render on every pixel. Hoisted to module scope so the effects
+// (which use [] deps) can't accidentally close over a stale instance.
+// Floor (not round) so wrapper undershoots and actions overshoots — both
+// errors push toward a more cautious layout, avoiding a one-bucket overlap
+// flash right at the 300/460 thresholds during a slow drag.
+const snap = (n: number) => Math.floor(n / 16) * 16;
+
+// Layout geometry — static tuning constants, hoisted alongside `snap`.
+// LEFT_OFFSET: matches the bar's `md:left-5` (20px).
+// GAP: minimum breathing room between the bar's right edge and the
+//      action button cluster's left edge when they share a lane.
+// Two-stage shared-lane shrinkage, mirroring the right side:
+//   WIDE_BAR_WIDTH: full toolstrip (active labels Pinpoint/Markup ~300px)
+//                   + badges (~140px) on a single line.
+//   MIN_BAR_WIDTH:  icon-only toolstrip (~140px) + badges (~140px).
+// Below MIN, even the icon-only bar can't fit beside the (likely also
+// icon-only) action cluster — stack as the final fallback.
+const LEFT_OFFSET = 20;
+const GAP = 16;
+const WIDE_BAR_WIDTH = 460;
+const MIN_BAR_WIDTH = 300;
+
+interface StickyHeaderLaneProps {
+  // Toolstrip state
+  inputMethod: InputMethod;
+  onInputMethodChange: (method: InputMethod) => void;
+  mode: EditorMode;
+  onModeChange: (mode: EditorMode) => void;
+  taterMode?: boolean;
+
+  // Badge state
+  repoInfo?: { display: string; branch?: string } | null;
+  planDiffStats?: PlanDiffStats | null;
+  isPlanDiffActive?: boolean;
+  hasPreviousVersion?: boolean;
+  onPlanDiffToggle?: () => void;
+  archiveInfo?: { status: 'approved' | 'denied' | 'unknown'; timestamp: string; title: string } | null;
+
+  // Layout
+  maxWidth?: number | null;
+
+  // Re-query token for the [data-sticky-actions] ResizeObserver. When the
+  // Viewer remounts (e.g., toggling a linked doc), its `data-sticky-actions`
+  // node is replaced — but StickyHeaderLane itself does NOT remount, so
+  // its observer would otherwise stay attached to the now-detached old
+  // node and freeze `actionsWidth`. Pass a string that changes whenever
+  // Viewer remounts and the effect re-runs against the fresh DOM.
+  remountToken?: string;
+}
+
+export const StickyHeaderLane: React.FC<StickyHeaderLaneProps> = ({
+  inputMethod,
+  onInputMethodChange,
+  mode,
+  onModeChange,
+  taterMode,
+  repoInfo,
+  planDiffStats,
+  isPlanDiffActive,
+  hasPreviousVersion,
+  onPlanDiffToggle,
+  archiveInfo,
+  maxWidth,
+  remountToken,
+}) => {
+  const sentinelRef = useRef<HTMLDivElement>(null);
+  const wrapperRef = useRef<HTMLDivElement>(null);
+  const [isStuck, setIsStuck] = useState(false);
+  const [wrapperWidth, setWrapperWidth] = useState(0);
+  const [actionsWidth, setActionsWidth] = useState(0);
+  const scrollViewport = useScrollViewport();
+
+  // Space available for the bar in the shared lane = wrapper width, minus
+  // the bar's left offset, minus the action buttons' measured width, minus
+  // the breathing gap.
+  const availableForBar = wrapperWidth - LEFT_OFFSET - actionsWidth - GAP;
+
+  // Narrow = not enough room in the shared lane for even the icon-only
+  // bar. Falls back to a stacked row below the action buttons.
+  // actionsWidth=0 before measurement is treated as "don't know yet"
+  // (not narrow), so we don't flash the wrong layout on first paint.
+  const measured = wrapperWidth > 0 && actionsWidth > 0;
+  const isNarrow = measured && availableForBar < MIN_BAR_WIDTH;
+  // Tight = shared lane still fits, but only if the toolstrip drops its
+  // active labels and goes icon-only. Lets us stay horizontally aligned
+  // for an extra ~160px of width before stacking.
+  const isToolstripIconOnly =
+    measured && !isNarrow && availableForBar < WIDE_BAR_WIDTH;
+
+  useEffect(() => {
+    if (!wrapperRef.current) return;
+    const ro = new ResizeObserver(([entry]) => {
+      const next = snap(entry.contentRect.width);
+      setWrapperWidth((prev) => (prev === next ? prev : next));
+    });
+    ro.observe(wrapperRef.current);
+    return () => ro.disconnect();
+  }, []);
+
+  // Measure the Viewer's action button cluster so the right reserve
+  // reflects its REAL width (which varies with viewport — short vs full
+  // labels — and with button count). No more guessing at ~310/360/400px.
+  // The action button div is tagged with `data-sticky-actions` in
+  // Viewer.tsx. It's a sibling in the DOM by the time effects fire.
+  // Re-runs when `remountToken` changes so we re-query after Viewer
+  // unmounts/remounts (e.g., linked-doc toggle) instead of leaving the
+  // observer attached to a detached node.
+  useEffect(() => {
+    // Reset to the unmeasured state so the bar falls back to the safe
+    // "no maxWidth cap" path for the one frame between Viewer remounting
+    // and the new observer firing its first callback.
+    setActionsWidth(0);
+    const el = document.querySelector<HTMLElement>('[data-sticky-actions]');
+    if (!el) return;
+    const ro = new ResizeObserver(([entry]) => {
+      const next = snap(entry.contentRect.width);
+      setActionsWidth((prev) => (prev === next ? prev : next));
+    });
+    ro.observe(el);
+    return () => ro.disconnect();
+  }, [remountToken]);
+
+  // IntersectionObserver-on-sentinel pattern (mirrors Viewer.tsx:257-267).
+  // Sentinel sits inline at the top of the column. The 80px positive top
+  // rootMargin grows the effective viewport upward so the sentinel is
+  // considered "visible" for an extra ~80px of scroll — delaying the bar's
+  // appearance until the real toolstrip has actually scrolled past. Without
+  // this, the sentinel fires the moment scrolling begins and the ghost bar
+  // doubles up with the still-visible toolstrip. Root is the OverlayScrollArea
+  // viewport from context, NOT <main> (which doesn't actually scroll).
+  useEffect(() => {
+    if (!sentinelRef.current || !scrollViewport) return;
+    const observer = new IntersectionObserver(
+      ([entry]) => setIsStuck(!entry.isIntersecting),
+      { root: scrollViewport, rootMargin: '80px 0px 0px 0px', threshold: 0 }
+    );
+    observer.observe(sentinelRef.current);
+    return () => observer.disconnect();
+  }, [scrollViewport]);
+
+  return (
+    <>
+      {/* Sentinel — zero-size, rendered in normal flow at the top of the
+          column. When it scrolls out of the OverlayScrollArea viewport,
+          the sticky bar fades in. */}
+      <div ref={sentinelRef} aria-hidden="true" className="h-0 w-0" />
+
+      {/* Sticky wrapper — zero-height so it never pushes content down. The
+          visible bar is positioned absolutely relative to this wrapper.
+          The Viewer's outer wrapper uses z-50, so the sticky lane must
+          sit above that to paint over the card.
+
+          Narrow: the bar pins at top-[52px] / md:top-[60px] on its OWN
+          full-width row BELOW the card's sticky action buttons. Stacked
+          horizontal lanes, no horizontal collision possible.
+
+          Wide / tight: the bar shares the top-3 lane with the action
+          buttons (single horizontal header). */}
+      <div
+        ref={wrapperRef}
+        data-sticky-header-lane="true"
+        className={`sticky z-[60] w-full self-center pointer-events-none ${
+          isNarrow ? 'top-[52px] md:top-[60px]' : 'top-3'
+        }`}
+        style={maxWidth == null ? { height: 0 } : { maxWidth, height: 0 }}
+      >
+        {/* Responsive bar.
+
+            `inline-flex flex-wrap` + a measured `max-width` cap (set inline
+            below) lets the bar wrap badges to a second row if the toolstrip
+            + badges can't fit on one line. The max-width is computed from
+            the real measured action button width — no fixed reserves.
+
+            `flex-shrink-0` on the toolstrip wrapper is a defensive measure:
+            if a long branch name pushes the badges, this stops the toolstrip
+            from being squeezed below its natural width. `overflow-hidden`
+            is the final safety net so any overflow clips inside the chrome
+            rather than leaking out.
+
+            `inert` removes the bar from the tab order when not stuck. */}
+        <div
+          inert={!isStuck || undefined}
+          className={`absolute left-3 md:left-5 top-0 inline-flex flex-wrap items-center gap-x-3 gap-y-1 min-w-0 overflow-hidden rounded-lg py-1 md:py-1.5 bg-card/95 backdrop-blur-sm shadow-sm border border-border/30 motion-reduce:transform-none ${
+            isStuck
+              ? 'opacity-100 translate-y-0 pointer-events-auto'
+              : 'opacity-0 -translate-y-1 pointer-events-none'
+          }`}
+          style={{
+            paddingLeft: 12,
+            paddingRight: 12,
+            maxWidth: isNarrow
+              ? 'calc(100% - 24px)'
+              : availableForBar > 0
+                ? availableForBar
+                : undefined,
+            transition:
+              'opacity 180ms cubic-bezier(0.2, 0, 0, 1), transform 180ms cubic-bezier(0.2, 0, 0, 1)',
+            willChange: 'opacity, transform',
+          }}
+        >
+          <div className="flex-shrink-0">
+            <AnnotationToolstrip
+              inputMethod={inputMethod}
+              onInputMethodChange={onInputMethodChange}
+              mode={mode}
+              onModeChange={onModeChange}
+              taterMode={taterMode}
+              compact
+              iconOnly={isNarrow || isToolstripIconOnly}
+            />
+          </div>
+          <DocBadges
+            layout="row"
+            repoInfo={repoInfo}
+            planDiffStats={planDiffStats}
+            isPlanDiffActive={isPlanDiffActive}
+            hasPreviousVersion={hasPreviousVersion}
+            onPlanDiffToggle={onPlanDiffToggle}
+            archiveInfo={archiveInfo}
+          />
+        </div>
+      </div>
+    </>
+  );
+};

package/components/TableOfContents.tsx

@@ -0,0 +1,157 @@
+import React, { useMemo, useCallback } from 'react';
+import type { Block, Annotation } from '../types';
+import {
+  buildTocHierarchy,
+  getAnnotationCountBySection,
+  type TocItem,
+} from '../utils/annotationHelpers';
+import { useScrollViewport } from '../hooks/useScrollViewport';
+
+interface TableOfContentsProps {
+  blocks: Block[];
+  annotations: Annotation[];
+  activeId: string | null;
+  onNavigate: (blockId: string) => void;
+  className?: string;
+  style?: React.CSSProperties;
+  linkedDocFilepath?: string | null;
+  onLinkedDocBack?: () => void;
+  backLabel?: string;
+}
+
+// The prototype's TOC is a FLAT list — heading depth is conveyed by indentation
+// + tonal de-emphasis, not an expand/collapse chevron tree. Flatten the built
+// hierarchy (depth-first = document order) into a single ordered list.
+function flattenToc(items: TocItem[]): TocItem[] {
+  const out: TocItem[] = [];
+  const walk = (list: TocItem[]) => {
+    for (const it of list) {
+      out.push(it);
+      if (it.children.length) walk(it.children);
+    }
+  };
+  walk(items);
+  return out;
+}
+
+// Indentation + tonal de-emphasis by heading level (prototype style):
+// H1 flush + near-full strength, H2/H3 indented and dimmed to muted. Active row
+// is a soft neutral surface tint (not a loud primary fill).
+function itemClasses(level: number, isActive: boolean): string {
+  const indent = level <= 1 ? '' : level === 2 ? 'ml-3' : 'ml-6';
+  const tone = isActive
+    ? 'bg-surface-1 text-foreground'
+    : level <= 1
+      ? 'text-foreground/80 hover:bg-surface-1/70'
+      : 'text-muted-foreground hover:bg-surface-1/70';
+  return `${indent} ${tone}`;
+}
+
+export function TableOfContents({
+  blocks,
+  annotations,
+  activeId,
+  onNavigate,
+  className = '',
+  style,
+  linkedDocFilepath,
+  onLinkedDocBack,
+  backLabel,
+}: TableOfContentsProps) {
+  // Annotation count per section (kept — production feature).
+  const annotationCounts = useMemo(
+    () => getAnnotationCountBySection(blocks, annotations),
+    [blocks, annotations]
+  );
+
+  // Build the hierarchy (filters to heading levels ≤ 3 and attaches counts),
+  // then flatten to a plain list.
+  const tocItems = useMemo(
+    () => flattenToc(buildTocHierarchy(blocks, annotationCounts)),
+    [blocks, annotationCounts]
+  );
+
+  // The real scroll element is the OverlayScrollArea viewport, not <main>.
+  const scrollViewport = useScrollViewport();
+
+  // Smooth scroll-to-heading, accounting for the sticky header.
+  const handleNavigate = useCallback(
+    (blockId: string) => {
+      onNavigate(blockId);
+      const target = (scrollViewport ?? document).querySelector(`[data-block-id="${blockId}"]`);
+      if (target && scrollViewport) {
+        const scrollContainer = scrollViewport;
+        const headerOffset = 80; // sticky header (h-12) + breathing room
+        const containerRect = scrollContainer.getBoundingClientRect();
+        const targetRect = target.getBoundingClientRect();
+        const offsetPosition =
+          scrollContainer.scrollTop + (targetRect.top - containerRect.top) - headerOffset;
+        scrollContainer.scrollTo({ top: offsetPosition, behavior: 'smooth' });
+      }
+    },
+    [onNavigate, scrollViewport]
+  );
+
+  if (tocItems.length === 0) {
+    return null;
+  }
+
+  return (
+    <nav
+      // Use ?? not || — an explicit empty string from a caller means "I'm
+      // managing my own container styling" (e.g. SidebarContainer wrapping
+      // us in an OverlayScrollArea), which should NOT trigger the default.
+      className={className ?? 'bg-card/50 backdrop-blur-sm border-r border-border overflow-y-auto'}
+      aria-label="Table of contents"
+      style={style}
+    >
+      <div className="p-1.5">
+        {linkedDocFilepath && (
+          <div className="mb-2 px-0.5 pb-1.5 border-b border-border/50">
+            <div className="flex items-center justify-between">
+              <span className="text-[10px] font-medium text-primary/80">Viewing</span>
+              {onLinkedDocBack && (
+                <button
+                  onClick={onLinkedDocBack}
+                  className="flex items-center gap-0.5 text-[10px] font-medium text-primary hover:text-primary/80 transition-colors"
+                >
+                  <svg className="w-2.5 h-2.5" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={2.5}>
+                    <path strokeLinecap="round" strokeLinejoin="round" d="M10.5 19.5L3 12m0 0l7.5-7.5M3 12h18" />
+                  </svg>
+                  Back to {backLabel || 'plan'}
+                </button>
+              )}
+            </div>
+            <p className="text-[11px] text-foreground/70 truncate mt-0.5" title={linkedDocFilepath}>
+              {linkedDocFilepath.split('/').pop()}
+            </p>
+          </div>
+        )}
+        <div className="flex flex-col gap-0.5">
+          {tocItems.map((item) => {
+            const isActive = item.id === activeId;
+            return (
+              <button
+                key={item.id}
+                type="button"
+                onClick={() => handleNavigate(item.id)}
+                aria-current={isActive ? 'location' : undefined}
+                className={`flex items-center justify-between gap-2 rounded-lg px-2 py-1.5 text-left text-[11px] font-medium leading-snug transition-colors ${itemClasses(
+                  item.level,
+                  isActive
+                )}`}
+              >
+                <span className="line-clamp-2">{item.content}</span>
+                {item.annotationCount > 0 && (
+                  <span className="ml-1 flex h-4 min-w-4 shrink-0 items-center justify-center rounded-full bg-primary/10 px-1 font-mono text-[9px] text-primary">
+                    {item.annotationCount}
+                  </span>
+                )}
+              </button>
+            );
+          })}
+        </div>
+      </div>
+    </nav>
+  );
+}

package/components/TaterSpritePullup.tsx

@@ -0,0 +1,34 @@
+/// <reference path="../globals.d.ts" />
+import React from 'react';
+import spriteSheet from '../sprite_package_pulluphang/sprite.png';
+
+// Sprite specs: 96x96 native, 24 frames, 3 seconds
+const NATIVE_SIZE = 96;
+const DISPLAY_SIZE = 56;
+const FRAMES = 24;
+const SCALE = DISPLAY_SIZE / NATIVE_SIZE;
+const TOTAL_WIDTH = NATIVE_SIZE * FRAMES * SCALE;
+
+export const TaterSpritePullup: React.FC = () => {
+  return (
+    <div
+      className="absolute pointer-events-none hidden md:block -z-10"
+      style={{
+        bottom: -49, // Hangs off bottom of dialog
+        left: 12,
+        width: DISPLAY_SIZE,
+        height: DISPLAY_SIZE,
+        backgroundImage: `url(${spriteSheet})`,
+        backgroundSize: `${TOTAL_WIDTH}px ${DISPLAY_SIZE}px`,
+        animation: 'tater-pullup 3.5s steps(24) infinite',
+        imageRendering: 'pixelated',
+      }}
+    >
+      <style>{`
+        @keyframes tater-pullup {
+          to { background-position: -${TOTAL_WIDTH}px 0; }
+        }
+      `}</style>
+    </div>
+  );
+};

package/components/TaterSpriteRunning.tsx

@@ -0,0 +1,54 @@
+/// <reference path="../globals.d.ts" />
+import React from 'react';
+import spriteSheet from '../sprite_package_additional/sprite.png';
+
+// Sprite: 176x96 native, 24 frames, 5 second animation cycle
+// Running across screen should sync with animation speed
+const NATIVE_WIDTH = 176;
+const NATIVE_HEIGHT = 96;
+const DISPLAY_HEIGHT = 64;
+const SCALE = DISPLAY_HEIGHT / NATIVE_HEIGHT;
+const DISPLAY_WIDTH = NATIVE_WIDTH * SCALE; // ~117px
+const FRAMES = 24;
+const FRAME_DURATION = 5; // seconds for full run cycle
+const TOTAL_SPRITE_WIDTH = NATIVE_WIDTH * FRAMES * SCALE;
+
+// Screen traverse: character runs across in ~12 seconds
+// This gives ~2.4 run cycles per screen width, feels natural
+const SCREEN_TRAVERSE_TIME = 18;
+
+export const TaterSpriteRunning: React.FC = () => {
+  return (
+    <div
+      className="fixed pointer-events-none hidden md:block"
+      style={{
+        bottom: 0,
+        right: -DISPLAY_WIDTH, // Start off-screen right
+        width: DISPLAY_WIDTH,
+        height: DISPLAY_HEIGHT,
+        zIndex: 5, // Above sidebars (z-auto) but below plan document (z-10)
+        backgroundImage: `url(${spriteSheet})`,
+        backgroundSize: `${TOTAL_SPRITE_WIDTH}px ${DISPLAY_HEIGHT}px`,
+        backgroundPosition: 'left center',
+        imageRendering: 'pixelated',
+        animation: `tater-run-sprite ${FRAME_DURATION}s steps(${FRAMES}) infinite, tater-run-across ${SCREEN_TRAVERSE_TIME}s linear infinite`,
+      }}
+    >
+      <style>{`
+        @keyframes tater-run-sprite {
+          to {
+            background-position: -${TOTAL_SPRITE_WIDTH}px 0;
+          }
+        }
+        @keyframes tater-run-across {
+          from {
+            right: -${DISPLAY_WIDTH}px;
+          }
+          to {
+            right: 100vw;
+          }
+        }
+      `}</style>
+    </div>
+  );
+};

package/components/TaterSpriteSitting.tsx

@@ -0,0 +1,37 @@
+/// <reference path="../globals.d.ts" />
+import React from 'react';
+import spriteSheet from '../sprite_package_new/sprite.png';
+
+// Sprite: 96x96 native, 12 frames, scaled to 64x64 for display
+const NATIVE_SIZE = 96;
+const DISPLAY_SIZE = 64;
+const FRAMES = 12;
+const SCALE = DISPLAY_SIZE / NATIVE_SIZE;
+const TOTAL_WIDTH = NATIVE_SIZE * FRAMES * SCALE; // 768px at 64px scale
+
+export const TaterSpriteSitting: React.FC = () => {
+  return (
+    <div
+      className="hidden md:block absolute pointer-events-none z-10"
+      style={{
+        top: -40,
+        right: -4,
+        width: DISPLAY_SIZE,
+        height: DISPLAY_SIZE,
+        backgroundImage: `url(${spriteSheet})`,
+        backgroundSize: `${TOTAL_WIDTH}px ${DISPLAY_SIZE}px`,
+        backgroundPosition: 'left center',
+        animation: 'tater-sit 3s steps(12) infinite',
+        imageRendering: 'pixelated',
+      }}
+    >
+      <style>{`
+        @keyframes tater-sit {
+          to {
+            background-position: -${TOTAL_WIDTH}px 0;
+          }
+        }
+      `}</style>
+    </div>
+  );
+};

package/components/TextShimmer.tsx

@@ -0,0 +1,57 @@
+import React, { useMemo, type JSX } from 'react';
+import { motion } from 'motion/react';
+
+export interface TextShimmerProps {
+  children: string;
+  as?: React.ElementType;
+  className?: string;
+  duration?: number;
+  spread?: number;
+}
+
+function TextShimmerComponent({
+  children,
+  as: Component = 'span',
+  className,
+  duration = 2,
+  spread = 2,
+}: TextShimmerProps) {
+  const MotionComponent = motion.create(
+    Component as keyof JSX.IntrinsicElements
+  );
+
+  const dynamicSpread = useMemo(() => {
+    return children.length * spread;
+  }, [children, spread]);
+
+  return (
+    <MotionComponent
+      className={[
+        'relative inline-block bg-[length:250%_100%,auto] bg-clip-text',
+        'text-transparent [--base-color:#a1a1aa] [--base-gradient-color:#000]',
+        '[background-repeat:no-repeat,padding-box] [--bg:linear-gradient(90deg,#0000_calc(50%-var(--spread)),var(--base-gradient-color),#0000_calc(50%+var(--spread)))]',
+        'dark:[--base-color:#71717a] dark:[--base-gradient-color:#ffffff] dark:[--bg:linear-gradient(90deg,#0000_calc(50%-var(--spread)),var(--base-gradient-color),#0000_calc(50%+var(--spread)))]',
+        className,
+      ]
+        .filter(Boolean)
+        .join(' ')}
+      initial={{ backgroundPosition: '100% center' }}
+      animate={{ backgroundPosition: '0% center' }}
+      transition={{
+        repeat: Infinity,
+        duration,
+        ease: 'linear',
+      }}
+      style={
+        {
+          '--spread': `${dynamicSpread}px`,
+          backgroundImage: `var(--bg), linear-gradient(var(--base-color), var(--base-color))`,
+        } as React.CSSProperties
+      }
+    >
+      {children}
+    </MotionComponent>
+  );
+}
+
+export const TextShimmer = React.memo(TextShimmerComponent);