Skip to content

Production-ready animations, transitions, backgrounds, and scenes for Remotion

feat: added skeleton, shimmer block

dev_wandry19b3e4f8a00e
diff --git a/components/docs/examples/index.tsx b/components/docs/examples/index.tsx
index 1319213c..87deb089 100644
--- a/components/docs/examples/index.tsx
+++ b/components/docs/examples/index.tsx
@@ -36,6 +36,10 @@ import {
ProgressExampleScene,
progressExampleCode,
} from "./progress-example";
+import {
+ SkeletonExampleScene,
+ skeletonExampleCode,
+} from "./skeleton-example";
export interface ExampleEntry {
Component: ComponentType;
@@ -204,4 +208,14 @@ export const examples: Record<string, ExampleEntry> = {
width: W,
height: H,
},
+ "skeleton-example": {
+ Component: SkeletonExampleScene,
+ code: skeletonExampleCode,
+ // ~3 shimmer cycles (180), crossfade completes at 180 + 16 = 196; a short
+ // settle on the revealed content then loop.
+ durationInFrames: 220,
+ fps: FPS,
+ width: W,
+ height: H,
+ },
};
diff --git a/components/docs/examples/skeleton-example.tsx b/components/docs/examples/skeleton-example.tsx
new file mode 100644
index 00000000..3fdfe89f
--- /dev/null
+++ b/components/docs/examples/skeleton-example.tsx
@@ -0,0 +1,113 @@
+"use client";
+
+import { Skeleton } from "@/registry/remocn-ui/skeleton";
+import { useSkeletonTransition } from "@/registry/remocn-ui/skeleton/use-skeleton-transition";
+
+export const SkeletonExampleScene = () => {
+ // Shimmer for ~3 full sweep cycles (180 frames) as if waiting on data, then
+ // crossfade to real content.
+ const skeletonStyle = useSkeletonTransition([
+ { at: 180, state: "loaded", duration: 16 },
+ ]);
+
+ return (
+ <div
+ style={{
+ position: "absolute",
+ inset: 0,
+ display: "flex",
+ alignItems: "center",
+ justifyContent: "center",
+ }}
+ >
+ <Skeleton style={skeletonStyle} layout="card">
+ {/* Real content — defines the box size; revealed on crossfade. */}
+ <div style={{ display: "flex", gap: 14, alignItems: "center" }}>
+ <div
+ style={{
+ width: 48,
+ height: 48,
+ borderRadius: 24,
+ background: "oklch(0.92 0 0)",
+ flexShrink: 0,
+ }}
+ />
+ <div style={{ display: "flex", flexDirection: "column", gap: 6 }}>
+ <div
+ style={{
+ width: 180,
+ height: 14,
+ borderRadius: 6,
+ background: "oklch(0.85 0 0)",
+ }}
+ />
+ <div
+ style={{
+ width: 120,
+ height: 14,
+ borderRadius: 6,
+ background: "oklch(0.9 0 0)",
+ }}
+ />
+ </div>
+ </div>
+ </Skeleton>
+ </div>
+ );
+};
+
+export const skeletonExampleCode = `import { Skeleton } from "@/components/remocn/skeleton";
+import { useSkeletonTransition } from "@/components/remocn/use-skeleton-transition";
+
+export const Scene = () => {
+ // Shimmer for ~3 full sweep cycles (180 frames) as if waiting on data, then
+ // crossfade to real content.
+ const skeletonStyle = useSkeletonTransition([
+ { at: 180, state: "loaded", duration: 16 },
+ ]);
+
+ return (
+ <div
+ style={{
+ position: "absolute",
+ inset: 0,
+ display: "flex",
+ alignItems: "center",
+ justifyContent: "center",
+ }}
+ >
+ <Skeleton style={skeletonStyle} layout="card">
+ {/* Real content — defines the box size; revealed on crossfade. */}
+ <div style={{ display: "flex", gap: 14, alignItems: "center" }}>
+ <div
+ style={{
+ width: 48,
+ height: 48,
+ borderRadius: 24,
+ background: "oklch(0.92 0 0)",
+ flexShrink: 0,
+ }}
+ />
+ <div style={{ display: "flex", flexDirection: "column", gap: 6 }}>
+ <div
+ style={{
+ width: 180,
+ height: 14,
+ borderRadius: 6,
+ background: "oklch(0.85 0 0)",
+ }}
+ />
+ <div
+ style={{
+ width: 120,
+ height: 14,
+ borderRadius: 6,
+ background: "oklch(0.9 0 0)",
+ }}
+ />
+ </div>
+ </div>
+ </Skeleton>
+ </div>
+ );
+};`;
diff --git a/content/docs/ui/components/meta.json b/content/docs/ui/components/meta.json
index db11275b..6b22f420 100644
--- a/content/docs/ui/components/meta.json
+++ b/content/docs/ui/components/meta.json
@@ -1,5 +1,5 @@
{
"title": "Components",
"collapsible": false,
- "pages": ["accordion", "alert-dialog", "button", "checkbox", "command-menu", "cursor", "dialog", "drawer", "sheet", "dropdown-menu", "input", "progress", "radio", "select", "spinner", "switch", "tabs", "toast", "tooltip"]
+ "pages": ["accordion", "alert-dialog", "button", "checkbox", "command-menu", "cursor", "dialog", "drawer", "sheet", "dropdown-menu", "input", "progress", "radio", "select", "skeleton", "spinner", "switch", "tabs", "toast", "tooltip"]
}
diff --git a/content/docs/ui/components/skeleton.mdx b/content/docs/ui/components/skeleton.mdx
new file mode 100644
index 00000000..7613852b
--- /dev/null
+++ b/content/docs/ui/components/skeleton.mdx
@@ -0,0 +1,217 @@
+---
+title: Skeleton
+description: A shimmer placeholder that crossfades to real content when loaded
+---
+
+<ComponentPreview name="skeleton" />
+
+A state atom that crossfades between a shimmer placeholder and real content. Its appearance (`loading`, `loaded`) is a pure function of the `state` prop. Pass a state directly or drive it from the Remotion timeline via `useCurrentState`. The component reads no frame — only the animated `SkeletonBlock` motion atom inside the placeholder does. The two opacity layers always sum to 1 so the crossfade never dims the bounding box.
+
+## Installation
+
+<InstallBlock name="skeleton" />
+
+<Note>
+Installing `skeleton` automatically installs the shared `remocn-ui` core (`lib/remocn-ui/`) and the `skeleton-block` motion atom via `registryDependencies` (`["remocn-ui", "skeleton-block"]`). You do not need to install them separately. `skeleton` (the state atom), `use-skeleton-transition` (the hook), and `skeleton-block` (the shimmer renderer) are all copied into your project.
+</Note>
+
+## Example
+
+<LiveExample name="skeleton-example" />
+
+## States
+
+`SkeletonState` is:
+
+```ts
+type SkeletonState =
+ | "loading" // skeletonOpacity 1, contentOpacity 0 — placeholder visible, content hidden
+ | "loaded" // skeletonOpacity 0, contentOpacity 1 — placeholder hidden, content visible
+```
+
+`loading` is the default. The two opacities always sum to 1: the crossfade is a complementary pair so the box never dims mid-transition. The placeholder is an absolute overlay positioned over the real content — the box dimensions are set by the children, not the placeholder, so no layout jump occurs on crossfade.
+
+## Snap usage
+
+Pass `state` directly — the component snaps instantly to that visual. Useful for static previews or when you drive state from your own logic:
+
+```tsx
+import { Skeleton } from "@/components/remocn/skeleton";
+
+export const Scene = () => (
+ <div style={{ position: "absolute", inset: 0, display: "flex", alignItems: "center", justifyContent: "center" }}>
+ <Skeleton state="loading" layout="card" />
+ </div>
+);
+```
+
+To drive state from the timeline, use `useCurrentState`:
+
+```tsx
+import { useCurrentState } from "@/lib/remocn-ui";
+import { Skeleton } from "@/components/remocn/skeleton";
+
+export const Scene = () => {
+ const state = useCurrentState(
+ [
+ { at: 45, state: "loaded" },
+ ],
+ "loading",
+ );
+
+ return (
+ <div style={{ position: "absolute", inset: 0, display: "flex", alignItems: "center", justifyContent: "center" }}>
+ <Skeleton state={state} layout="card">
+ <div>Real content here</div>
+ </Skeleton>
+ </div>
+ );
+};
+```
+
+Each `at` is a **Sequence-local authored frame**. State persists between steps: `loaded` at frame 45 keeps the content visible for the rest of the composition. See [Concepts](/docs/ui/concepts) for the full `useCurrentState` API.
+
+## Smooth transitions
+
+State changes via `state` snap with no cross-fade. For an animated shimmer-to-content reveal, use `useSkeletonTransition` from the copied `use-skeleton-transition.ts` file. It reads the frame, interpolates between state presets, and returns a resolved `SkeletonStyle` — pass it to the `style` prop:
+
+```tsx
+import { Skeleton } from "@/components/remocn/skeleton";
+import { useSkeletonTransition } from "@/components/remocn/use-skeleton-transition";
+
+export const Scene = () => {
+ const style = useSkeletonTransition([
+ { at: 45, state: "loaded", duration: 16 },
+ ]);
+
+ return (
+ <div style={{ position: "absolute", inset: 0, display: "flex", alignItems: "center", justifyContent: "center" }}>
+ <Skeleton style={style} layout="card">
+ <div>Real content here</div>
+ </Skeleton>
+ </div>
+ );
+};
+```
+
+The `duration` field on each step overrides the file's `DEFAULT_DURATION` (= `12`) for that specific transition. To globally tune timing and easing, edit `use-skeleton-transition.ts` directly in your project — that file is yours (shadcn "own your code" philosophy).
+
+`style` takes precedence over `state` when both are provided.
+
+## Layout presets
+
+When no `placeholder` prop is given, `Skeleton` renders a built-in placeholder assembled from `SkeletonBlock` atoms. The `layout` prop selects the preset:
+
+```ts
+type SkeletonLayout =
+ | "lines" // three stacked rows: 260px, 240px, 160px wide — generic text block
+ | "card" // 48×48 circle avatar + two lines (180px, 120px) — profile or list item
+```
+
+```tsx
+<Skeleton state="loading" layout="lines" />
+<Skeleton state="loading" layout="card" />
+```
+
+For a custom placeholder, pass a `placeholder` prop — any `ReactNode` of `SkeletonBlock` atoms arranged however you like. The `placeholder` prop overrides `layout` when present:
+
+```tsx
+import { SkeletonBlock } from "@/components/remocn/skeleton-block";
+
+<Skeleton style={skeletonStyle} placeholder={
+ <div style={{ display: "flex", flexDirection: "column", gap: 8 }}>
+ <SkeletonBlock width={300} height={20} />
+ <SkeletonBlock width={200} height={14} />
+ </div>
+}>
+ <div>Real content</div>
+</Skeleton>
+```
+
+## Shimmer block
+
+The `SkeletonBlock` motion atom is the building block behind every shimmer effect. It reads `useCurrentFrame()` directly — it is the only file in this component allowed to do so — and drives a diagonal highlight gradient sweep that loops seamlessly every 60 frames at `speed = 1`.
+
+<ComponentPreview name="skeleton-block" />
+
+```tsx
+import { SkeletonBlock } from "@/components/remocn/skeleton-block";
+
+// A pill-shaped shimmer rectangle
+<SkeletonBlock width={240} height={16} radius={8} />
+
+// A circular avatar placeholder
+<SkeletonBlock width={48} height={48} radius={24} />
+
+// Double speed sweep
+<SkeletonBlock width={180} height={14} speed={2} />
+```
+
+`SkeletonBlock` props:
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `width` | `number \| string` | `120` | Block width in px (or any CSS length string). |
+| `height` | `number` | `16` | Block height in px. |
+| `radius` | `number` | `6` | Corner radius in px. |
+| `speed` | `number` | `1` | Playhead scale — a full sweep takes `60 / speed` frames. |
+| `baseColor` | `string` | `theme.muted` | Resting block color. |
+| `highlightColor` | `string` | `theme.accent` | Moving highlight band color. |
+| `className` | `string` | — | Optional className applied to the div. |
+
+When you install `skeleton`, `skeleton-block` is automatically pulled in via `registryDependencies` — no separate install needed.
+
+## Props
+
+<PropsTable
+ rows={[
+ {
+ name: "state",
+ type: "\"loading\" | \"loaded\"",
+ default: "\"loading\"",
+ description: "Current visual state (snap path). State changes snap — no automatic cross-fade.",
+ },
+ {
+ name: "style",
+ type: "SkeletonStyle",
+ description: "Resolved animated visual (smooth path). Pass an interpolated SkeletonStyle from useSkeletonTransition. Takes precedence over state when provided.",
+ },
+ {
+ name: "children",
+ type: "ReactNode",
+ description: "The real content. Sits in normal flow and defines the box size. Revealed when contentOpacity reaches 1.",
+ },
+ {
+ name: "placeholder",
+ type: "ReactNode",
+ description: "Custom placeholder layer (arbitrary SkeletonBlock arrangement). Overrides layout when present.",
+ },
+ {
+ name: "layout",
+ type: "\"lines\" | \"card\"",
+ default: "\"lines\"",
+ description: "Built-in placeholder preset when no placeholder prop is given. lines renders three stacked rows; card renders a circle avatar with two lines.",
+ },
+ {
+ name: "speed",
+ type: "number",
+ description: "Playhead scale forwarded to the built-in placeholder SkeletonBlocks. Higher values make the shimmer sweep faster.",
+ },
+ {
+ name: "theme",
+ type: "Partial<RemocnTheme>",
+ description: "Per-component theme override. Merges with the active RemocnUIProvider theme and the mode defaults. Must be concrete oklch/hex/rgb values — not CSS custom properties.",
+ },
+ {
+ name: "mode",
+ type: "\"light\" | \"dark\"",
+ default: "\"light\"",
+ description: "Sets the base palette. Overrides the mode on RemocnUIProvider when both are present.",
+ },
+ {
+ name: "className",
+ type: "string",
+ description: "Optional className applied to the outer wrapper element.",
+ },
+ ]}
+/>
diff --git a/registry/__index__.tsx b/registry/__index__.tsx
index f729e29c..e3c1f1ce 100644
--- a/registry/__index__.tsx
+++ b/registry/__index__.tsx
@@ -149,6 +149,10 @@ import { TooltipPreview } from "@/registry/remocn-ui/tooltip/preview";
import { tooltipConfig } from "@/registry/remocn-ui/tooltip/config";
import { ProgressPreview } from "@/registry/remocn-ui/progress/preview";
import { progressConfig } from "@/registry/remocn-ui/progress/config";
+import { SkeletonBlockPreview } from "@/registry/remocn-ui/skeleton-block/preview";
+import { skeletonBlockConfig } from "@/registry/remocn-ui/skeleton-block/config";
+import { SkeletonPreview } from "@/registry/remocn-ui/skeleton/preview";
+import { skeletonConfig } from "@/registry/remocn-ui/skeleton/config";
import { ZoomThroughTransition } from "@/registry/remocn/zoom-through-transition";
import { zoomThroughTransitionConfig } from "@/registry/remocn/zoom-through-transition/config";
@@ -360,6 +364,14 @@ const registry: Record<string, RegistryEntry> = {
// progress's customizer Component is the preview-only ProgressPreview wrapper:
// a bare inline bar would sit top-left, so the wrapper centers it on a stage.
"progress": { Component: ProgressPreview, config: progressConfig },
+ // skeleton-block is the shimmer motion atom; its preview centers the bare block
+ // on a stage. skeleton is the state atom whose preview supplies demo content +
+ // placeholder for the loading↔loaded crossfade.
+ "skeleton-block": {
+ Component: SkeletonBlockPreview,
+ config: skeletonBlockConfig,
+ },
+ "skeleton": { Component: SkeletonPreview, config: skeletonConfig },
"spinner": { Component: Spinner, config: spinnerConfig },
};
diff --git a/registry/remocn-ui/registry.json b/registry/remocn-ui/registry.json
index e5effa1e..356db77e 100644
--- a/registry/remocn-ui/registry.json
+++ b/registry/remocn-ui/registry.json
@@ -476,6 +476,41 @@
"target": "components/remocn/use-progress-transition.ts"
}
]
+ },
+ {
+ "name": "skeleton-block",
+ "type": "registry:component",
+ "title": "UI Skeleton Block",
+ "description": "A shimmer placeholder block — a motion atom (spinner pattern). A directional highlight gradient sweeps across deterministically from useCurrentFrame() and loops seamlessly. Configurable width/height/radius/speed and base/highlight colors.",
+ "dependencies": ["remotion"],
+ "registryDependencies": [],
+ "files": [
+ {
+ "path": "skeleton-block/index.tsx",
+ "type": "registry:component",
+ "target": "components/remocn/skeleton-block.tsx"
+ }
+ ]
+ },
+ {
+ "name": "skeleton",
+ "type": "registry:component",
+ "title": "UI Skeleton",
+ "description": "A skeleton→content crossfade whose loading/loaded state is a pure function of the timeline. The Skeleton renderer is pure (reads no frame); only the composed SkeletonBlock shimmer reads it. SkeletonStyle opacities sum to 1 so the box never dims; real children sit in normal flow and the placeholder (a lines/card layout or a custom node) is an absolute overlay.",
+ "dependencies": ["remotion"],
+ "registryDependencies": ["remocn-ui", "skeleton-block"],
+ "files": [
+ {
+ "path": "skeleton/index.tsx",
+ "type": "registry:component",
+ "target": "components/remocn/skeleton.tsx"
+ },
+ {
+ "path": "skeleton/use-skeleton-transition.ts",
+ "type": "registry:component",
+ "target": "components/remocn/use-skeleton-transition.ts"
+ }
+ ]
}
]
}
diff --git a/registry/remocn-ui/skeleton-block/__tests__/README.md b/registry/remocn-ui/skeleton-block/__tests__/README.md
new file mode 100644
index 00000000..9e87c2db
--- /dev/null
+++ b/registry/remocn-ui/skeleton-block/__tests__/README.md
@@ -0,0 +1,108 @@
+# `skeleton-block` — verification tests
+
+Pure / deterministic verification for the `skeleton-block` component
+(`registry/remocn-ui/skeleton-block/`).
+
+## Why render is NOT unit-tested
+
+`SkeletonBlock` is a **motion atom** — it is the only file in the skeleton
+primitive family explicitly allowed to read the frame. It calls
+`useCurrentFrame()` directly (index.tsx line 52) and also calls
+`useRemocnTheme()`. Neither can be invoked outside a Remotion render context,
+so the render path is excluded from unit tests (STYLE-GUIDE §10).
+
+The shimmer offset computation is module-private:
+
+```ts
+// index.tsx lines 52-54
+const frame = useCurrentFrame() * speed;
+const progress = (frame % SWEEP_FRAMES) / SWEEP_FRAMES;
+const positionX = 100 - progress * 200;
+```
+
+`SWEEP_FRAMES` (60) and `positionX` are not exported. The seamless-loop
+property and monotonicity within a cycle are documented below for manual
+verification; they cannot be exercised by a unit test without a render
+context.
+
+## Shimmer math — documented for manual verification
+
+| Property | Value / Formula |
+|----------|-----------------|
+| `SWEEP_FRAMES` | 60 (one full sweep at speed=1) |
+| `progress` | `(frame * speed % 60) / 60` — wraps every 60 effective frames |
+| `positionX` | `100 - progress * 200` — travels from 100% to −100% across one period |
+| Frame 0 | `positionX = 100%` |
+| Frame 30 (mid) | `positionX = 0%` |
+| Frame 60 (loop end) | `positionX = 100%` (60 % 60 = 0 → same as frame 0) |
+
+**Seamless-loop invariant:** `positionX(frame=0) === positionX(frame=60)`.
+Because the gradient is 200% wide and tiles, position 100% and −100% are
+visually identical — the loop wraps without a jump.
+
+**Monotonic within a cycle:** `positionX` decreases strictly from 100% to
+(approaching) −100% as `frame` goes from 0 to 59. The highlight band sweeps
+left→right on screen.
+
+**Speed contract:** `speed > 1` compresses the cycle: at `speed=2`, one full
+sweep takes 30 raw frames (`effective = raw * speed`).
+
+These properties are verified by reading the source and the numeric table
+above. To confirm in a real render, set up a Remotion composition with
+`<SkeletonBlock />` and scrub from frame 0 to frame 60.
+
+## Pure surface that IS tested
+
+Only `skeletonBlockConfig` (from `config.ts`) is a pure value and is
+unit-tested. `config.ts` imports no React hooks and has no side effects.
+
+## How to run
+
+```bash
+bun install
+bun test registry/remocn-ui/skeleton-block/__tests__
+```
+
+## What is covered
+
+- **`skeletonBlockConfig.controls`** — control wiring: `width` is a `number`
+ control with default=240, min=40, max=600; `height` is a `number` control
+ with default=20, min=8, max=120; `radius` is a `number` control with
+ default=6, min=0, max=60.
+
+- **`skeletonBlockConfig.snippet`** — pure JSX string builder. Asserts:
+ `import { SkeletonBlock }` from the correct path; `<SkeletonBlock` element
+ ending with `/>` (self-closing); default `width=240`, `height=20`, and
+ `radius=6` are omitted; when all props are default the element is the
+ compact form `<SkeletonBlock/>`; non-default width/height/radius are emitted
+ with the correct values; only changed props are emitted when some are
+ default; numeric round-trips for width.
+
+## Import strategy
+
+`skeleton-block.test.ts` imports only:
+
+- `../config` — relative, for `skeletonBlockConfig`
+
+`SkeletonBlock` itself is NOT imported — it calls `useCurrentFrame()` and
+`useRemocnTheme()` which require a Remotion render context.
+
+## Determinism note
+
+`skeleton-block/index.tsx` legitimately reads `useCurrentFrame()` — it is the
+motion atom for the skeleton primitive. This is by design, not a violation.
+The determinism grep target for this primitive is `skeleton/index.tsx` (the
+state atom parent), NOT `skeleton-block/index.tsx`.
+
+For completeness, `skeleton-block/index.tsx` must NOT contain any of:
+`useState`, `useEffect`, `onClick`, `onChange`, `addEventListener`,
+`Date.now`, `Math.random`, `requestAnimationFrame` (non-deterministic
+patterns). `useCurrentFrame()` is the single frame-reading call and is
+expected. Run:
+
+```bash
+grep -nE "useState|useEffect|onClick|onChange|addEventListener|Date\.now|Math\.random|requestAnimationFrame" \
+ registry/remocn-ui/skeleton-block/index.tsx
+```
+
+Expected: **no output** (only `useCurrentFrame` is present, which is correct).
diff --git a/registry/remocn-ui/skeleton-block/__tests__/skeleton-block.test.ts b/registry/remocn-ui/skeleton-block/__tests__/skeleton-block.test.ts
new file mode 100644
index 00000000..068dce6b
--- /dev/null
+++ b/registry/remocn-ui/skeleton-block/__tests__/skeleton-block.test.ts
@@ -0,0 +1,201 @@
+/**
+ * Verification tests for the PURE / DETERMINISTIC parts of `skeleton-block`.
+ *
+ * Scope:
+ * - registry/remocn-ui/skeleton-block/config.ts
+ * skeletonBlockConfig.controls wiring + skeletonBlockConfig.snippet codegen
+ *
+ * WHY RENDER IS NOT UNIT-TESTED:
+ * `SkeletonBlock` is a MOTION ATOM — it is the only file in the skeleton
+ * primitive family explicitly allowed to read the frame. It calls
+ * `useCurrentFrame()` directly (line 52 of index.tsx) and also calls
+ * `useRemocnTheme()`. Neither can be called outside a Remotion render context.
+ * The shimmer offset computation (`positionX = 100 - progress * 200`, where
+ * `progress = (frame * speed % SWEEP_FRAMES) / SWEEP_FRAMES`) is module-private
+ * and not exported. Per STYLE-GUIDE §10, frame-reading hooks are excluded from
+ * unit tests; only the pure surface is in scope here.
+ *
+ * The shimmer seamless-loop property (frame 0 and frame SWEEP_FRAMES render
+ * identically, positionX is monotonically decreasing within a cycle) is
+ * documented in README.md and verified by reading the source; it cannot be
+ * tested without a Remotion render context.
+ *
+ * Runner: Bun's built-in test runner (TypeScript-native, no framework dep).
+ * bun test registry/remocn-ui/skeleton-block/__tests__
+ *
+ * --------------------------------------------------------------------------
+ * IMPORT STRATEGY
+ * --------------------------------------------------------------------------
+ * Relative import for config only. SkeletonBlock itself is NOT imported here.
+ * --------------------------------------------------------------------------
+ */
+
+import { describe, expect, it } from "bun:test";
+import { skeletonBlockConfig } from "../config";
+
+// ===========================================================================
+// Shared fixtures
+// ===========================================================================
+
+/** Convenience wrapper for snippet(). */
+type SnippetValues = {
+ width?: number;
+ height?: number;
+ radius?: number;
+};
+const snippet = (values: SnippetValues): string =>
+ skeletonBlockConfig.snippet(values as Record<string, unknown>);
+
+// ===========================================================================
+// 1. skeletonBlockConfig.controls — customizer control wiring
+// ===========================================================================
+
+describe("skeletonBlockConfig.controls: width", () => {
+ it("width is a number control", () => {
+ expect(skeletonBlockConfig.controls.width.type).toBe("number");
+ });
+
+ it("width default is 240", () => {
+ expect(skeletonBlockConfig.controls.width.default).toBe(240);
+ });
+
+ it("width min is 40, max is 600", () => {
+ const ctrl = skeletonBlockConfig.controls.width;
+ if (ctrl.type !== "number") throw new Error("expected number");
+ expect(ctrl.min).toBe(40);
+ expect(ctrl.max).toBe(600);
+ });
+});
+
+describe("skeletonBlockConfig.controls: height", () => {
+ it("height is a number control", () => {
+ expect(skeletonBlockConfig.controls.height.type).toBe("number");
+ });
+
+ it("height default is 20", () => {
+ expect(skeletonBlockConfig.controls.height.default).toBe(20);
+ });
+
+ it("height min is 8, max is 120", () => {
+ const ctrl = skeletonBlockConfig.controls.height;
+ if (ctrl.type !== "number") throw new Error("expected number");
+ expect(ctrl.min).toBe(8);
+ expect(ctrl.max).toBe(120);
+ });
+});
+
+describe("skeletonBlockConfig.controls: radius", () => {
+ it("radius is a number control", () => {
+ expect(skeletonBlockConfig.controls.radius.type).toBe("number");
+ });
+
+ it("radius default is 6", () => {
+ expect(skeletonBlockConfig.controls.radius.default).toBe(6);
+ });
+
+ it("radius min is 0, max is 60", () => {
+ const ctrl = skeletonBlockConfig.controls.radius;
+ if (ctrl.type !== "number") throw new Error("expected number");
+ expect(ctrl.min).toBe(0);
+ expect(ctrl.max).toBe(60);
+ });
+});
+
+// ===========================================================================
+// 2. skeletonBlockConfig.snippet — pure JSX string builder
+// ===========================================================================
+
+describe("skeletonBlockConfig.snippet: import line", () => {
+ it("includes 'import { SkeletonBlock }' from the correct path", () => {
+ const out = snippet({});
+ expect(out).toContain("import { SkeletonBlock }");
+ expect(out).toContain('from "@/components/remocn/skeleton-block"');
+ });
+});
+
+describe("skeletonBlockConfig.snippet: structural invariants", () => {
+ it("contains a <SkeletonBlock element", () => {
+ expect(snippet({})).toContain("<SkeletonBlock");
+ });
+
+ it("ends with a self-closing />", () => {
+ expect(snippet({}).trimEnd().endsWith("/>")).toBe(true);
+ });
+});
+
+describe("skeletonBlockConfig.snippet: default props are omitted", () => {
+ // Defaults: width=240, height=20, radius=6
+
+ it("omits width when it equals the default 240", () => {
+ const out = snippet({ width: 240 });
+ expect(out).not.toContain("width=");
+ });
+
+ it("omits height when it equals the default 20", () => {
+ const out = snippet({ height: 20 });
+ expect(out).not.toContain("height=");
+ });
+
+ it("omits radius when it equals the default 6", () => {
+ const out = snippet({ radius: 6 });
+ expect(out).not.toContain("radius=");
+ });
+
+ it("all defaults omitted → compact self-closing element on one line", () => {
+ // When all props are default, propsBlock is "" and the element is compact
+ const out = snippet({ width: 240, height: 20, radius: 6 });
+ expect(out).toContain("<SkeletonBlock/>");
+ });
+});
+
+describe("skeletonBlockConfig.snippet: non-default props are emitted", () => {
+ it("emits width={120} when non-default", () => {
+ expect(snippet({ width: 120 })).toContain("width={120}");
+ });
+
+ it("emits width={400} when non-default", () => {
+ expect(snippet({ width: 400 })).toContain("width={400}");
+ });
+
+ it("emits height={14} when non-default", () => {
+ expect(snippet({ height: 14 })).toContain("height={14}");
+ });
+
+ it("emits height={48} when non-default (circle use case)", () => {
+ expect(snippet({ height: 48 })).toContain("height={48}");
+ });
+
+ it("emits radius={0} when non-default (sharp corners)", () => {
+ expect(snippet({ radius: 0 })).toContain("radius={0}");
+ });
+
+ it("emits radius={24} when non-default (circle use case)", () => {
+ expect(snippet({ radius: 24 })).toContain("radius={24}");
+ });
+});
+
+describe("skeletonBlockConfig.snippet: multiple non-default props", () => {
+ it("emits all three props when all are non-default", () => {
+ const out = snippet({ width: 180, height: 48, radius: 24 });
+ expect(out).toContain("width={180}");
+ expect(out).toContain("height={48}");
+ expect(out).toContain("radius={24}");
+ });
+
+ it("emits only changed props when some are default", () => {
+ const out = snippet({ width: 180, height: 20, radius: 6 });
+ expect(out).toContain("width={180}");
+ expect(out).not.toContain("height=");
+ expect(out).not.toContain("radius=");
+ });
+});
+
+describe("skeletonBlockConfig.snippet: numeric round-trips", () => {
+ it("emits correct width for various non-default values", () => {
+ for (const w of [40, 120, 320, 600]) {
+ if (w !== 240) {
+ expect(snippet({ width: w })).toContain(`width={${w}}`);
+ }
+ }
+ });
+});
diff --git a/registry/remocn-ui/skeleton-block/config.ts b/registry/remocn-ui/skeleton-block/config.ts
new file mode 100644
index 00000000..381bab36
--- /dev/null
+++ b/registry/remocn-ui/skeleton-block/config.ts
@@ -0,0 +1,30 @@
+import { type ComponentConfig, FPS, H, W } from "@/lib/customizer-config";
+
+export const skeletonBlockConfig: ComponentConfig = {
+ componentName: "SkeletonBlock",
+ importPath: "@/components/remocn/skeleton-block",
+ controls: {
+ width: { type: "number", default: 240, min: 40, max: 600, step: 10, label: "Width" },
+ height: { type: "number", default: 20, min: 8, max: 120, step: 2, label: "Height" },
+ radius: { type: "number", default: 6, min: 0, max: 60, step: 1, label: "Radius" },
+ },
+ durationInFrames: 120,
+ fps: FPS,
+ compositionWidth: W,
+ compositionHeight: H,
+ snippet: (values) => {
+ const width = values.width as number | undefined;
+ const height = values.height as number | undefined;
+ const radius = values.radius as number | undefined;
+
+ const props: string[] = [];
+ if (width !== undefined && width !== 240) props.push(` width={${width}}`);
+ if (height !== undefined && height !== 20) props.push(` height={${height}}`);
+ if (radius !== undefined && radius !== 6) props.push(` radius={${radius}}`);
+
+ const propsBlock = props.length ? `\n${props.join("\n")}\n` : "";
+ return `import { SkeletonBlock } from "@/components/remocn/skeleton-block";
+
+<SkeletonBlock${propsBlock}/>`;
+ },
+};
diff --git a/registry/remocn-ui/skeleton-block/index.tsx b/registry/remocn-ui/skeleton-block/index.tsx
new file mode 100644
index 00000000..6e8db6b0
--- /dev/null
+++ b/registry/remocn-ui/skeleton-block/index.tsx
@@ -0,0 +1,80 @@
+"use client";
+
+import { useCurrentFrame } from "remotion";
+import { mixOklch, useRemocnTheme } from "@/lib/remocn-ui";
+
+export interface SkeletonBlockProps {
+ /** Block width in px (or any CSS length via string). */
+ width?: number | string;
+ /** Block height in px. */
+ height?: number;
+ /** Corner radius in px. */
+ radius?: number;
+ /** Playhead scale: a full shimmer sweep takes (SWEEP_FRAMES / speed) frames. */
+ speed?: number;
+ /** Base (resting) color of the block. Defaults to the theme muted token. */
+ baseColor?: string;
+ /** Moving highlight color of the sweep. Defaults to a lighter wash. */
+ highlightColor?: string;
+ /** CSS `flex-shrink`. Set 0 to stop a fixed-size block (e.g. an avatar) from
+ * collapsing when it sits in a flex row narrower than its blocks. */
+ flexShrink?: number;
+ className?: string;
+}
+
+/** Frames for one full shimmer sweep at speed 1. The loop is seamless. */
+const SWEEP_FRAMES = 60;
+
+/**
+ * A deterministic shimmer block — the motion atom behind `Skeleton`'s
+ * placeholder. A diagonal highlight gradient sweeps left→right and wraps
+ * seamlessly: background-position cycles over exactly one period of the
+ * 200%-wide gradient, so frame 0 and frame SWEEP_FRAMES render identically.
+ *
+ * Pure function of `useCurrentFrame()` — it uses no wall-clock, no randomness,
+ * and no animation-frame callbacks — so it renders frame-perfectly on the
+ * Remotion timeline. This is a MOTION atom: the only file here allowed to read
+ * the frame.
+ */
+export function SkeletonBlock({
+ width = 120,
+ height = 16,
+ radius = 6,
+ speed = 1,
+ baseColor,
+ highlightColor,
+ flexShrink,
+ className,
+}: SkeletonBlockProps) {
+ const theme = useRemocnTheme();
+ const base = baseColor ?? theme.muted;
+ // Derive the moving highlight from the base toward the high-contrast
+ // `foreground` token (dark in light theme, light in dark theme), so the sweep
+ // band is visibly different from the base in BOTH themes. We deliberately do
+ // NOT use the muted/accent tokens for the highlight — in the default theme
+ // those equal the base, giving a zero-contrast (invisible) shimmer. 0.13 is
+ // subtle but clearly visible.
+ const highlight = highlightColor ?? mixOklch(base, theme.foreground, 0.13);
+
+ // progress 0→1 over one sweep, then wraps. The gradient is 200% wide and we
+ // pan background-position from 100% → -100% across the period; because the
+ // gradient tiles, position 100% and -100% are visually identical → seamless.
+ const frame = useCurrentFrame() * speed;
+ const progress = (frame % SWEEP_FRAMES) / SWEEP_FRAMES;
+ const positionX = 100 - progress * 200;
+
+ return (
+ <div
+ className={className}
+ style={{
+ width,
+ height,
+ flexShrink,
+ borderRadius: radius,
+ background: `linear-gradient(90deg, ${base} 20%, ${highlight} 50%, ${base} 80%)`,
+ backgroundSize: "200% 100%",
+ backgroundPosition: `${positionX}% 0`,
+ }}
+ />
+ );
+}
diff --git a/registry/remocn-ui/skeleton-block/preview.tsx b/registry/remocn-ui/skeleton-block/preview.tsx
new file mode 100644
index 00000000..461f043b
--- /dev/null
+++ b/registry/remocn-ui/skeleton-block/preview.tsx
@@ -0,0 +1,41 @@
+"use client";
+
+import { useRemocnTheme } from "@/lib/remocn-ui";
+import { SkeletonBlock } from "@/registry/remocn-ui/skeleton-block";
+
+export interface SkeletonBlockPreviewProps {
+ width?: number;
+ height?: number;
+ radius?: number;
+ speed?: number;
+}
+
+/**
+ * Preview-only wrapper for the customizer. The shipped `SkeletonBlock` is a bare
+ * inline block; the customizer Player renders its `component` as the composition
+ * root, so this thin wrapper centers it on a theme-background stage just for the
+ * preview. NOT shipped: not listed in registry.json files.
+ */
+export function SkeletonBlockPreview({
+ width = 240,
+ height = 20,
+ radius = 6,
+ speed,
+}: SkeletonBlockPreviewProps) {
+ const theme = useRemocnTheme();
+
+ return (
+ <div
+ style={{
+ position: "absolute",
+ inset: 0,
+ display: "flex",
+ alignItems: "center",
+ justifyContent: "center",
+ background: theme.background,
+ }}
+ >
+ <SkeletonBlock width={width} height={height} radius={radius} speed={speed} />
+ </div>
+ );
+}
diff --git a/registry/remocn-ui/skeleton/__tests__/README.md b/registry/remocn-ui/skeleton/__tests__/README.md
new file mode 100644
index 00000000..a8872574
--- /dev/null
+++ b/registry/remocn-ui/skeleton/__tests__/README.md
@@ -0,0 +1,142 @@
+# `skeleton` — verification tests
+
+Pure / deterministic verification for the `skeleton` component
+(`registry/remocn-ui/skeleton/`). The render path (`index.tsx`) imports
+`useRemocnTheme` and composes `SkeletonBlock` motion atoms — these require
+React context and cannot run headlessly, so they are NOT exercised here. This
+suite covers everything that IS pure: `skeletonStyle` presets + the crossfade
+invariant, `tweenSkeletonStyle` interpolation, the `useSkeletonTransition`
+pure resolver mirror, and `skeletonConfig` controls wiring + snippet codegen.
+
+## Animation model — crossfade state atom
+
+Skeleton follows the standard state-atom pattern (see STYLE-GUIDE §1) with a
+two-field crossfade visual:
+
+**Snap path** (`state?: SkeletonState` prop):
+`<Skeleton>` is a frame-free pure renderer. The `state` prop drives all
+visuals. Each state maps to a complete resting keyframe via the exported pure
+function `skeletonStyle(state) => SkeletonStyle`. State changes snap — no
+tweening inside the component.
+
+**Smooth path** (`style?: SkeletonStyle` prop):
+Callers opt in to smooth loading→loaded crossfades by passing a
+pre-interpolated `SkeletonStyle` to the `style` prop. The caller — typically
+`useSkeletonTransition` — reads `useCurrentFrame()` via `useStateTransition`,
+applies `easings.out` to the raw linear progress, and blends the two state
+presets via `tweenSkeletonStyle(from, to, t)`. The `<Skeleton>` component
+remains frame-free; it renders whatever `SkeletonStyle` it receives.
+
+**Crossfade invariant (§3):** every `SkeletonStyle` must satisfy
+`skeletonOpacity + contentOpacity === 1`. This is true for both presets and
+is preserved through `tweenSkeletonStyle` because a lerp of two complementary
+pairs (`(1,0)` and `(0,1)`) always yields a complementary pair — the box
+never dims during the transition.
+
+**No color tween:** `SkeletonStyle` carries only `skeletonOpacity` and
+`contentOpacity` — both numeric. There are no animated color channels, so
+`tweenSkeletonStyle` is a simple two-field lerp with no `mixOklch` call.
+
+**Motion atom boundary:** `<Skeleton>` itself reads no frame. Only the
+composed `SkeletonBlock` motion atoms (the shimmer blocks inside the
+placeholder layer) read `useCurrentFrame()`. This keeps `<Skeleton>` testable
+as a pure renderer.
+
+## How to run
+
+The repo uses **Bun**, which has a built-in test runner — runs TypeScript
+natively, no test-framework dep.
+
+```bash
+bun install
+bun test registry/remocn-ui/skeleton/__tests__
+```
+
+`skeleton.test.ts` imports `bun:test` (not `vitest`/`jest`), so no test
+script or framework dep is added to `package.json`.
+
+## What is covered
+
+- **`DEFAULT_DURATION`** — asserts the constant is 12 frames.
+
+- **`skeletonStyle` presets** — exported pure `(state) => SkeletonStyle`.
+ Asserts every field for every state: `loading` gives
+ `{skeletonOpacity:1, contentOpacity:0}`; `loaded` gives
+ `{skeletonOpacity:0, contentOpacity:1}`. Also asserts all fields are
+ numeric for every state, that the two states have distinct values on every
+ field, and crucially that **both presets satisfy the crossfade invariant**
+ (`skeletonOpacity + contentOpacity === 1`).
+
+- **`tweenSkeletonStyle`** — exported pure `(a, b, t) => SkeletonStyle`.
+ Asserts: at t=0 both fields equal `a`; at t=1 both equal `b`; at t=0.5
+ each field is the midpoint (`skeletonOpacity` 1→0 gives 0.5,
+ `contentOpacity` 0→1 gives 0.5); at t=0.25 gives 0.75/0.25; identity case
+ (a===b preserves values); reverse direction (loaded→loading). The
+ **crossfade invariant is asserted at every t** (t=0, 0.1, 0.25, 0.333,
+ 0.5, 0.9, 1) — the sum always equals 1.
+
+- **`useSkeletonTransition` resolver replica** — `resolveSkeletonTransition`
+ mirrors `use-skeleton-transition.ts` lines 47-60 with `raw` injected in
+ place of `useCurrentFrame()`. Asserts: before any step → loading style with
+ both endpoints `loading`; exactly at a step boundary → progress=0 →
+ t=out(0)=0 → style equals `loading` keyframe; mid-window at raw=6/dur=12
+ (linear progress=0.5) → t=out(0.5)=0.875 → skeletonOpacity=0.125,
+ contentOpacity=0.875 (not linear 0.5); crossfade invariant holds
+ mid-window; past the window → fully loaded style; speed contract (speed=2
+ halves the raw frame to reach a step).
+
+- **`skeletonConfig.controls`** — control wiring assertions: `state` is a
+ `select` with options `["loading","loaded"]` and default `"loading"`; `layout`
+ is a `select` with options `["lines","card"]` and default `"card"`; `mode` is
+ a `select` with options `["light","dark"]` and default `"light"`.
+
+- **`skeletonConfig.snippet`** — pure JSX string builder. Asserts: `import {
+ Skeleton }` from the correct path; `<Skeleton` element with a closing
+ `</Skeleton>` tag (not self-closing — it wraps children); real-content
+ placeholder comment; `state` is always emitted; default `layout="lines"` and
+ `mode="light"` are omitted; `layout="card"` and `mode="dark"` are emitted;
+ all state options round-trip; all non-default layout options round-trip.
+
+**Skeleton render** is a pure `(style | state, layout) => visual` wrapping
+`SkeletonBlock` motion atoms; it is not unit-tested here.
+
+## Import strategy
+
+`skeleton.test.ts` imports via **relative paths** and the `@/lib/remocn-ui`
+alias:
+
+- `../index` — relative, for `skeletonStyle`, `SkeletonState`, `SkeletonLayout`
+- `../use-skeleton-transition` — relative, for `tweenSkeletonStyle`,
+ `DEFAULT_DURATION`
+- `../config` — relative, for `skeletonConfig`
+- `@/lib/remocn-ui` — alias, for `defaultLightTheme`, `defaultDarkTheme`,
+ `easings`, and `Step` type
+
+`useSkeletonTransition` is NOT imported — it calls `useStateTransition` which
+reads `useCurrentFrame()`. Its pure logic is mirrored as
+`resolveSkeletonTransition` with the frame injected as `raw`. `bun test`
+resolves tsconfig `paths`, so the alias works without additional config.
+
+## Determinism grep checklist (run manually; must print NOTHING)
+
+`skeleton/index.tsx` is a pure renderer — the component must contain **none**
+of the following:
+
+```bash
+grep -nE "useState|useEffect|useCurrentFrame|onClick|onChange|addEventListener|Date\.now|Math\.random|requestAnimationFrame" \
+ registry/remocn-ui/skeleton/index.tsx
+```
+
+Expected: **no output**. Any match is a determinism violation.
+
+`use-skeleton-transition.ts` is the caller hook that intentionally reads
+`useCurrentFrame()` (via `useStateTransition`). That is correct and expected;
+the smooth-path design isolates all frame-reading to the hook and to the
+`SkeletonBlock` motion atoms, keeping `<Skeleton>` pure.
+
+Tier-wide sweep for `index.tsx`:
+
+```bash
+grep -nE "useState|useEffect|onClick|onChange|addEventListener|Date\.now|Math\.random" \
+ registry/remocn-ui/skeleton/index.tsx registry/remocn-ui/core/*.ts
+```
diff --git a/registry/remocn-ui/skeleton/__tests__/skeleton.test.ts b/registry/remocn-ui/skeleton/__tests__/skeleton.test.ts
new file mode 100644
index 00000000..b04d060f
--- /dev/null
+++ b/registry/remocn-ui/skeleton/__tests__/skeleton.test.ts
@@ -0,0 +1,622 @@
+/**
+ * Verification tests for the PURE / DETERMINISTIC parts of `skeleton`.
+ *
+ * Scope:
+ * - registry/remocn-ui/skeleton/index.tsx
+ * skeletonStyle(state) — complete state→visual preset map
+ * (crossfade invariant: opacities sum to 1)
+ * - registry/remocn-ui/skeleton/use-skeleton-transition.ts
+ * tweenSkeletonStyle(a, b, t) — pure lerp across both fields
+ * DEFAULT_DURATION constant
+ * useSkeletonTransition resolver — mirrored as resolveSkeletonTransition
+ * with frame injected as `raw` (annotated source lines)
+ * - registry/remocn-ui/skeleton/config.ts
+ * skeletonConfig.controls wiring + skeletonConfig.snippet codegen
+ *
+ * The render path (index.tsx) imports `useRemocnTheme` which requires React
+ * context — it is NOT exercised here. The pure-testable surface is everything
+ * above.
+ *
+ * Runner: Bun's built-in test runner (TypeScript-native, no framework dep).
+ * bun test registry/remocn-ui/skeleton/__tests__
+ *
+ * --------------------------------------------------------------------------
+ * IMPORT STRATEGY
+ * --------------------------------------------------------------------------
+ * Relative imports from component source; `@/lib/remocn-ui` alias for core.
+ * `skeletonStyle` and `tweenSkeletonStyle` are pure value functions — they call
+ * neither `useCurrentFrame()` nor `useRemocnTheme` at import or call time.
+ * `useSkeletonTransition` IS a hook (calls `useStateTransition` → `useCurrentFrame`)
+ * and is NOT imported; we mirror its pure resolver body below.
+ * --------------------------------------------------------------------------
+ */
+
+import { describe, expect, it } from "bun:test";
+import {
+ skeletonStyle,
+ type SkeletonState,
+ type SkeletonLayout,
+} from "../index";
+import {
+ tweenSkeletonStyle,
+ DEFAULT_DURATION,
+} from "../use-skeleton-transition";
+import { skeletonConfig } from "../config";
+import { defaultLightTheme, defaultDarkTheme, easings } from "@/lib/remocn-ui";
+import type { Step } from "@/lib/remocn-ui";
+
+// ===========================================================================
+// Shared fixtures
+// ===========================================================================
+
+const VALID_STATES: readonly SkeletonState[] = ["loading", "loaded"];
+const VALID_LAYOUTS: readonly SkeletonLayout[] = ["lines", "card"];
+
+/** Convenience wrapper for snippet(). */
+type SnippetValues = {
+ state?: string;
+ layout?: string;
+ mode?: string;
+};
+const snippet = (values: SnippetValues): string =>
+ skeletonConfig.snippet(values as Record<string, unknown>);
+
+// ===========================================================================
+// 1. DEFAULT_DURATION constant
+// ===========================================================================
+
+describe("DEFAULT_DURATION", () => {
+ it("is 12 frames", () => {
+ expect(DEFAULT_DURATION).toBe(12);
+ });
+});
+
+// ===========================================================================
+// 2. skeletonStyle — pure (state) => SkeletonStyle map
+// MIRROR of index.tsx lines 56-63
+// KEY INVARIANT: skeletonOpacity + contentOpacity === 1 in every preset.
+// ===========================================================================
+
+describe("skeletonStyle: loading state — placeholder visible", () => {
+ const s = skeletonStyle("loading");
+
+ it("skeletonOpacity is 1 (placeholder fully visible)", () => {
+ expect(s.skeletonOpacity).toBe(1);
+ });
+
+ it("contentOpacity is 0 (content hidden)", () => {
+ expect(s.contentOpacity).toBe(0);
+ });
+
+ it("crossfade invariant: skeletonOpacity + contentOpacity === 1", () => {
+ expect(s.skeletonOpacity + s.contentOpacity).toBeCloseTo(1, 10);
+ });
+});
+
+describe("skeletonStyle: loaded state — content visible", () => {
+ const s = skeletonStyle("loaded");
+
+ it("skeletonOpacity is 0 (placeholder hidden)", () => {
+ expect(s.skeletonOpacity).toBe(0);
+ });
+
+ it("contentOpacity is 1 (content fully visible)", () => {
+ expect(s.contentOpacity).toBe(1);
+ });
+
+ it("crossfade invariant: skeletonOpacity + contentOpacity === 1", () => {
+ expect(s.skeletonOpacity + s.contentOpacity).toBeCloseTo(1, 10);
+ });
+});
+
+describe("skeletonStyle: both states satisfy the crossfade invariant", () => {
+ it("every state preset has opacities summing to 1", () => {
+ for (const state of VALID_STATES) {
+ const s = skeletonStyle(state);
+ expect(s.skeletonOpacity + s.contentOpacity).toBeCloseTo(1, 10);
+ }
+ });
+
+ it("every SkeletonStyle field is defined and numeric for every state", () => {
+ for (const state of VALID_STATES) {
+ const s = skeletonStyle(state);
+ expect(typeof s.skeletonOpacity).toBe("number");
+ expect(typeof s.contentOpacity).toBe("number");
+ }
+ });
+
+ it("loading and loaded have distinct skeletonOpacity (1 vs 0)", () => {
+ expect(skeletonStyle("loading").skeletonOpacity).toBe(1);
+ expect(skeletonStyle("loaded").skeletonOpacity).toBe(0);
+ });
+
+ it("loading and loaded have distinct contentOpacity (0 vs 1)", () => {
+ expect(skeletonStyle("loading").contentOpacity).toBe(0);
+ expect(skeletonStyle("loaded").contentOpacity).toBe(1);
+ });
+
+ it("unknown state falls through to loading preset (skeletonOpacity=1)", () => {
+ // switch default arm → loading preset
+ expect(skeletonStyle("loading").skeletonOpacity).toBe(1);
+ });
+});
+
+// ===========================================================================
+// 3. tweenSkeletonStyle — pure lerp across both fields
+// MIRROR of use-skeleton-transition.ts lines 23-34
+// KEY INVARIANT: the tween of two complementary pairs is complementary —
+// the crossfade invariant is preserved at every t.
+// ===========================================================================
+
+describe("tweenSkeletonStyle: t=0 returns values equal to `a`", () => {
+ const a = skeletonStyle("loading");
+ const b = skeletonStyle("loaded");
+ const r = tweenSkeletonStyle(a, b, 0);
+
+ it("skeletonOpacity equals a.skeletonOpacity at t=0", () => {
+ expect(r.skeletonOpacity).toBeCloseTo(a.skeletonOpacity, 10);
+ });
+
+ it("contentOpacity equals a.contentOpacity at t=0", () => {
+ expect(r.contentOpacity).toBeCloseTo(a.contentOpacity, 10);
+ });
+
+ it("crossfade invariant preserved at t=0", () => {
+ expect(r.skeletonOpacity + r.contentOpacity).toBeCloseTo(1, 10);
+ });
+});
+
+describe("tweenSkeletonStyle: t=1 returns values equal to `b`", () => {
+ const a = skeletonStyle("loading");
+ const b = skeletonStyle("loaded");
+ const r = tweenSkeletonStyle(a, b, 1);
+
+ it("skeletonOpacity equals b.skeletonOpacity at t=1", () => {
+ expect(r.skeletonOpacity).toBeCloseTo(b.skeletonOpacity, 10);
+ });
+
+ it("contentOpacity equals b.contentOpacity at t=1", () => {
+ expect(r.contentOpacity).toBeCloseTo(b.contentOpacity, 10);
+ });
+
+ it("crossfade invariant preserved at t=1", () => {
+ expect(r.skeletonOpacity + r.contentOpacity).toBeCloseTo(1, 10);
+ });
+});
+
+describe("tweenSkeletonStyle: t=0.5 midpoint (loading → loaded)", () => {
+ // loading: skeletonOpacity=1, contentOpacity=0
+ // loaded: skeletonOpacity=0, contentOpacity=1
+ // midpoint: skeletonOpacity=0.5, contentOpacity=0.5
+ const a = skeletonStyle("loading");
+ const b = skeletonStyle("loaded");
+ const r = tweenSkeletonStyle(a, b, 0.5);
+
+ it("skeletonOpacity midpoint: 1 → 0 gives 0.5", () => {
+ expect(r.skeletonOpacity).toBeCloseTo(0.5, 10);
+ });
+
+ it("contentOpacity midpoint: 0 → 1 gives 0.5", () => {
+ expect(r.contentOpacity).toBeCloseTo(0.5, 10);
+ });
+
+ it("crossfade invariant preserved at t=0.5 (sum === 1)", () => {
+ expect(r.skeletonOpacity + r.contentOpacity).toBeCloseTo(1, 10);
+ });
+});
+
+describe("tweenSkeletonStyle: t=0.5 midpoint (loaded → loading, reverse direction)", () => {
+ const a = skeletonStyle("loaded");
+ const b = skeletonStyle("loading");
+ const r = tweenSkeletonStyle(a, b, 0.5);
+
+ it("skeletonOpacity midpoint: 0 → 1 gives 0.5", () => {
+ expect(r.skeletonOpacity).toBeCloseTo(0.5, 10);
+ });
+
+ it("contentOpacity midpoint: 1 → 0 gives 0.5", () => {
+ expect(r.contentOpacity).toBeCloseTo(0.5, 10);
+ });
+
+ it("crossfade invariant preserved at t=0.5 reverse direction", () => {
+ expect(r.skeletonOpacity + r.contentOpacity).toBeCloseTo(1, 10);
+ });
+});
+
+describe("tweenSkeletonStyle: identity (a === b, any t)", () => {
+ const s = skeletonStyle("loading");
+
+ it("skeletonOpacity is unchanged when both endpoints are the same", () => {
+ expect(tweenSkeletonStyle(s, s, 0.5).skeletonOpacity).toBeCloseTo(s.skeletonOpacity, 10);
+ });
+
+ it("contentOpacity is unchanged when both endpoints are the same", () => {
+ expect(tweenSkeletonStyle(s, s, 0.5).contentOpacity).toBeCloseTo(s.contentOpacity, 10);
+ });
+
+ it("crossfade invariant preserved for identity tween", () => {
+ const r = tweenSkeletonStyle(s, s, 0.5);
+ expect(r.skeletonOpacity + r.contentOpacity).toBeCloseTo(1, 10);
+ });
+});
+
+describe("tweenSkeletonStyle: t=0.25 quarter-point (loading → loaded)", () => {
+ // skeletonOpacity: 1 + 0.25*(0-1) = 0.75
+ // contentOpacity: 0 + 0.25*(1-0) = 0.25
+ const a = skeletonStyle("loading");
+ const b = skeletonStyle("loaded");
+ const r = tweenSkeletonStyle(a, b, 0.25);
+
+ it("skeletonOpacity at t=0.25 is 0.75", () => {
+ expect(r.skeletonOpacity).toBeCloseTo(0.75, 10);
+ });
+
+ it("contentOpacity at t=0.25 is 0.25", () => {
+ expect(r.contentOpacity).toBeCloseTo(0.25, 10);
+ });
+
+ it("crossfade invariant preserved at t=0.25", () => {
+ expect(r.skeletonOpacity + r.contentOpacity).toBeCloseTo(1, 10);
+ });
+});
+
+describe("tweenSkeletonStyle: crossfade invariant holds at any arbitrary t", () => {
+ const a = skeletonStyle("loading");
+ const b = skeletonStyle("loaded");
+
+ it("sum === 1 at t=0.1", () => {
+ const r = tweenSkeletonStyle(a, b, 0.1);
+ expect(r.skeletonOpacity + r.contentOpacity).toBeCloseTo(1, 10);
+ });
+
+ it("sum === 1 at t=0.333", () => {
+ const r = tweenSkeletonStyle(a, b, 1/3);
+ expect(r.skeletonOpacity + r.contentOpacity).toBeCloseTo(1, 10);
+ });
+
+ it("sum === 1 at t=0.9", () => {
+ const r = tweenSkeletonStyle(a, b, 0.9);
+ expect(r.skeletonOpacity + r.contentOpacity).toBeCloseTo(1, 10);
+ });
+});
+
+// ===========================================================================
+// 4. useSkeletonTransition resolver replica
+// MIRRORS use-skeleton-transition.ts lines 47-60.
+// `useSkeletonTransition` calls `useStateTransition` (which reads
+// `useCurrentFrame()`) then applies `easings.out(progress)` and
+// `tweenSkeletonStyle`. We inject `raw` in place of `useCurrentFrame()`.
+//
+// Key additional contract: progress is eased with `easings.out` before the
+// tween. The crossfade invariant must hold on the eased result too.
+//
+// MAINTENANCE CONTRACT: if use-skeleton-transition.ts lines 47-60 change,
+// update this replica in lockstep. Annotated source lines below.
+// ===========================================================================
+
+/** MIRROR of core/timeline.ts:clamp01. */
+function clamp01Mirror(t: number): number {
+ return Math.max(0, Math.min(1, t));
+}
+
+/** MIRROR of core/motion.ts:easings.out (cubic ease-out). */
+function easingOut(t: number): number {
+ return 1 - (1 - t) ** 3;
+}
+
+/**
+ * MIRROR of timeline.ts:useStateTransition pure resolver body,
+ * with `raw` injected.
+ */
+function resolveStateTransition<S extends string>(
+ raw: number,
+ steps: Step<S>[],
+ defaultState: S,
+ speed = 1,
+ defaultDuration = 8,
+): { from: S; to: S; progress: number } {
+ const effectiveFrame = raw * speed;
+ const started = steps
+ .map((step, index) => ({ step, index }))
+ .sort((a, b) => a.step.at - b.step.at || a.index - b.index)
+ .filter((e) => e.step.at <= effectiveFrame);
+ if (started.length === 0)
+ return { from: defaultState, to: defaultState, progress: 1 };
+ const to = started[started.length - 1].step;
+ const from = started.length >= 2 ? started[started.length - 2].step : null;
+ const dur = to.duration ?? defaultDuration;
+ const progress = dur > 0 ? clamp01Mirror((effectiveFrame - to.at) / dur) : 1;
+ return { from: from ? from.state : defaultState, to: to.state, progress };
+}
+
+/**
+ * MIRROR of use-skeleton-transition.ts:useSkeletonTransition (lines 47-60).
+ * `raw` is injected in place of useCurrentFrame().
+ * Annotated source lines:
+ * line 51: destructure speed + defaultDuration from opts
+ * line 52-57: call useStateTransition (mirrored as resolveStateTransition)
+ * line 58: t = easings.out(progress) ← MIRROR line 58
+ * line 59: tweenSkeletonStyle(from, to, t) ← MIRROR line 59
+ */
+function resolveSkeletonTransition(
+ raw: number, // injected useCurrentFrame() — MIRROR line 52
+ steps: Step<SkeletonState>[],
+ speed = 1,
+ defaultDuration = DEFAULT_DURATION,
+): { style: ReturnType<typeof tweenSkeletonStyle>; progress: number; from: SkeletonState; to: SkeletonState } {
+ const { from, to, progress } = resolveStateTransition( // MIRROR lines 52-57
+ raw,
+ steps,
+ "loading",
+ speed,
+ defaultDuration,
+ );
+ const t = easingOut(progress); // MIRROR line 58
+ const style = tweenSkeletonStyle(
+ skeletonStyle(from as SkeletonState),
+ skeletonStyle(to as SkeletonState),
+ t,
+ ); // MIRROR line 59
+ return { style, progress, from: from as SkeletonState, to: to as SkeletonState };
+}
+
+// ---------------------------------------------------------------------------
+// Before any step: holds at loading
+// ---------------------------------------------------------------------------
+
+describe("resolveSkeletonTransition: before any step — holds at loading", () => {
+ it("returns the loading style when no steps have started", () => {
+ const { style } = resolveSkeletonTransition(0, []);
+ const loading = skeletonStyle("loading");
+ expect(style.skeletonOpacity).toBeCloseTo(loading.skeletonOpacity, 10);
+ expect(style.contentOpacity).toBeCloseTo(loading.contentOpacity, 10);
+ });
+
+ it("from and to are both 'loading' before any step", () => {
+ const { from, to } = resolveSkeletonTransition(0, []);
+ expect(from).toBe("loading");
+ expect(to).toBe("loading");
+ });
+
+ it("crossfade invariant holds before any step", () => {
+ const { style } = resolveSkeletonTransition(0, []);
+ expect(style.skeletonOpacity + style.contentOpacity).toBeCloseTo(1, 10);
+ });
+});
+
+// ---------------------------------------------------------------------------
+// Exactly at a step boundary: progress=0, t=out(0)=0
+// ---------------------------------------------------------------------------
+
+describe("resolveSkeletonTransition: exactly at loading→loaded step boundary", () => {
+ const steps: Step<SkeletonState>[] = [{ at: 10, state: "loaded" }];
+
+ it("at raw=10 exactly, progress=0, t=out(0)=0 → style equals loading (from)", () => {
+ const { style, progress } = resolveSkeletonTransition(10, steps);
+ expect(progress).toBe(0);
+ const loading = skeletonStyle("loading");
+ expect(style.skeletonOpacity).toBeCloseTo(loading.skeletonOpacity, 10);
+ expect(style.contentOpacity).toBeCloseTo(loading.contentOpacity, 10);
+ });
+
+ it("from='loading', to='loaded' at the step boundary", () => {
+ const { from, to } = resolveSkeletonTransition(10, steps);
+ expect(from).toBe("loading");
+ expect(to).toBe("loaded");
+ });
+});
+
+// ---------------------------------------------------------------------------
+// Mid-window: easings.out applied — non-linear + crossfade invariant
+// ---------------------------------------------------------------------------
+
+describe("resolveSkeletonTransition: mid-window uses easings.out (not linear)", () => {
+ // step at=0, dur=12. At raw=6: progress=0.5, t=out(0.5)=0.875
+ // skeletonOpacity: tween(1, 0, 0.875) = 1 - 0.875 = 0.125
+ // contentOpacity: tween(0, 1, 0.875) = 0.875
+ const steps: Step<SkeletonState>[] = [{ at: 0, state: "loaded" }];
+
+ it("skeletonOpacity at raw=6 is tween(1,0,out(0.5))=0.125 (not linear 0.5)", () => {
+ const { style } = resolveSkeletonTransition(6, steps, 1, 12);
+ expect(style.skeletonOpacity).toBeCloseTo(0.125, 8);
+ });
+
+ it("contentOpacity at raw=6 is tween(0,1,out(0.5))=0.875", () => {
+ const { style } = resolveSkeletonTransition(6, steps, 1, 12);
+ expect(style.contentOpacity).toBeCloseTo(0.875, 8);
+ });
+
+ it("crossfade invariant holds mid-window (sum === 1)", () => {
+ const { style } = resolveSkeletonTransition(6, steps, 1, 12);
+ expect(style.skeletonOpacity + style.contentOpacity).toBeCloseTo(1, 8);
+ });
+});
+
+// ---------------------------------------------------------------------------
+// Past the window: fully loaded
+// ---------------------------------------------------------------------------
+
+describe("resolveSkeletonTransition: past the transition window → fully loaded", () => {
+ const steps: Step<SkeletonState>[] = [{ at: 0, state: "loaded" }];
+
+ it("skeletonOpacity is 0 after DEFAULT_DURATION frames", () => {
+ const { style } = resolveSkeletonTransition(DEFAULT_DURATION, steps);
+ expect(style.skeletonOpacity).toBeCloseTo(0, 10);
+ });
+
+ it("contentOpacity is 1 after DEFAULT_DURATION frames", () => {
+ const { style } = resolveSkeletonTransition(DEFAULT_DURATION, steps);
+ expect(style.contentOpacity).toBeCloseTo(1, 10);
+ });
+
+ it("crossfade invariant holds past the window", () => {
+ const { style } = resolveSkeletonTransition(DEFAULT_DURATION, steps);
+ expect(style.skeletonOpacity + style.contentOpacity).toBeCloseTo(1, 10);
+ });
+});
+
+// ---------------------------------------------------------------------------
+// Speed contract
+// ---------------------------------------------------------------------------
+
+describe("resolveSkeletonTransition: speed contract", () => {
+ // step at=12. speed=2: effectiveFrame = raw*2 → fires at raw=6.
+ const steps: Step<SkeletonState>[] = [{ at: 12, state: "loaded" }];
+
+ it("speed=2: step at=12 fires at raw=6 (eff=12)", () => {
+ const { to } = resolveSkeletonTransition(6, steps, 2);
+ expect(to).toBe("loaded");
+ });
+
+ it("speed=2: step at=12 has NOT fired at raw=5 (eff=10 < 12)", () => {
+ const { to } = resolveSkeletonTransition(5, steps, 2);
+ expect(to).toBe("loading");
+ });
+});
+
+// ===========================================================================
+// 5. skeletonConfig.controls — customizer control wiring
+// ===========================================================================
+
+describe("skeletonConfig.controls: state", () => {
+ it("state is a select control", () => {
+ expect(skeletonConfig.controls.state.type).toBe("select");
+ });
+
+ it("state options are ['loading', 'loaded']", () => {
+ const ctrl = skeletonConfig.controls.state;
+ if (ctrl.type !== "select") throw new Error("expected select");
+ expect(ctrl.options).toEqual(["loading", "loaded"]);
+ });
+
+ it("state default is 'loading' (shows live shimmer in preview)", () => {
+ expect(skeletonConfig.controls.state.default).toBe("loading");
+ });
+
+ it("every state option is a valid SkeletonState", () => {
+ const ctrl = skeletonConfig.controls.state;
+ if (ctrl.type !== "select") throw new Error("expected select");
+ for (const opt of ctrl.options) {
+ expect(VALID_STATES).toContain(opt as SkeletonState);
+ }
+ });
+});
+
+describe("skeletonConfig.controls: layout", () => {
+ it("layout is a select control", () => {
+ expect(skeletonConfig.controls.layout.type).toBe("select");
+ });
+
+ it("layout options are ['lines', 'card']", () => {
+ const ctrl = skeletonConfig.controls.layout;
+ if (ctrl.type !== "select") throw new Error("expected select");
+ expect(ctrl.options).toEqual(["lines", "card"]);
+ });
+
+ it("layout default is 'card'", () => {
+ expect(skeletonConfig.controls.layout.default).toBe("card");
+ });
+
+ it("every layout option is a valid SkeletonLayout", () => {
+ const ctrl = skeletonConfig.controls.layout;
+ if (ctrl.type !== "select") throw new Error("expected select");
+ for (const opt of ctrl.options) {
+ expect(VALID_LAYOUTS).toContain(opt as SkeletonLayout);
+ }
+ });
+});
+
+describe("skeletonConfig.controls: mode", () => {
+ it("mode is a select control", () => {
+ expect(skeletonConfig.controls.mode.type).toBe("select");
+ });
+
+ it("mode options are ['light', 'dark']", () => {
+ const ctrl = skeletonConfig.controls.mode;
+ if (ctrl.type !== "select") throw new Error("expected select");
+ expect(ctrl.options).toEqual(["light", "dark"]);
+ });
+
+ it("mode default is 'light'", () => {
+ expect(skeletonConfig.controls.mode.default).toBe("light");
+ });
+});
+
+// ===========================================================================
+// 6. skeletonConfig.snippet — pure JSX string builder
+// ===========================================================================
+
+describe("skeletonConfig.snippet: import line", () => {
+ it("includes 'import { Skeleton }' from the correct path", () => {
+ const out = snippet({ state: "loading" });
+ expect(out).toContain("import { Skeleton }");
+ expect(out).toContain('from "@/components/remocn/skeleton"');
+ });
+});
+
+describe("skeletonConfig.snippet: structural invariants", () => {
+ it("contains a <Skeleton JSX element", () => {
+ expect(snippet({ state: "loading" })).toContain("<Skeleton");
+ });
+
+ it("has a closing </Skeleton> tag (not self-closing — it wraps children)", () => {
+ expect(snippet({ state: "loading" })).toContain("</Skeleton>");
+ });
+
+ it("includes a placeholder comment for real content", () => {
+ expect(snippet({ state: "loading" })).toContain("{/* your real content */}");
+ });
+
+ it("state prop is always emitted", () => {
+ expect(snippet({ state: "loading" })).toContain('state="loading"');
+ expect(snippet({ state: "loaded" })).toContain('state="loaded"');
+ });
+});
+
+describe("skeletonConfig.snippet: default props are omitted", () => {
+ // Defaults: layout='lines' (snippet omits when 'lines'), mode='light'
+ it("omits layout when it equals the default 'lines'", () => {
+ const out = snippet({ state: "loading", layout: "lines" });
+ expect(out).not.toContain("layout=");
+ });
+
+ it("omits mode when it equals the default 'light'", () => {
+ const out = snippet({ state: "loading", mode: "light" });
+ expect(out).not.toContain("mode=");
+ });
+});
+
+describe("skeletonConfig.snippet: non-default props are emitted", () => {
+ it("emits layout='card' when non-default", () => {
+ expect(snippet({ state: "loading", layout: "card" })).toContain(
+ 'layout="card"',
+ );
+ });
+
+ it("emits mode='dark' when non-default", () => {
+ expect(snippet({ state: "loading", mode: "dark" })).toContain(
+ 'mode="dark"',
+ );
+ });
+});
+
+describe("skeletonConfig.snippet: state options round-trip", () => {
+ it("emits the correct state for every control option", () => {
+ const ctrl = skeletonConfig.controls.state;
+ if (ctrl.type !== "select") throw new Error("expected select");
+ for (const state of ctrl.options) {
+ expect(snippet({ state })).toContain(`state="${state}"`);
+ }
+ });
+});
+
+describe("skeletonConfig.snippet: layout options round-trip", () => {
+ it("emits the correct layout for every non-default layout option", () => {
+ const ctrl = skeletonConfig.controls.layout;
+ if (ctrl.type !== "select") throw new Error("expected select");
+ const nonDefault = ctrl.options.filter((o) => o !== "lines");
+ for (const layout of nonDefault) {
+ expect(snippet({ state: "loading", layout })).toContain(`layout="${layout}"`);
+ }
+ });
+});
diff --git a/registry/remocn-ui/skeleton/config.ts b/registry/remocn-ui/skeleton/config.ts
new file mode 100644
index 00000000..ccb2838b
--- /dev/null
+++ b/registry/remocn-ui/skeleton/config.ts
@@ -0,0 +1,51 @@
+import { type ComponentConfig, FPS, H, W } from "@/lib/customizer-config";
+import type { SkeletonState } from "@/registry/remocn-ui/skeleton";
+
+export const skeletonConfig: ComponentConfig = {
+ componentName: "Skeleton",
+ importPath: "@/components/remocn/skeleton",
+ controls: {
+ layout: {
+ type: "select",
+ default: "card",
+ options: ["lines", "card"],
+ label: "Layout",
+ },
+ state: {
+ type: "select",
+ // Default to `loading` so the preview showcases the live shimmer.
+ default: "loading",
+ options: ["loading", "loaded"],
+ label: "State",
+ },
+ mode: {
+ type: "select",
+ default: "light",
+ options: ["light", "dark"],
+ label: "Mode",
+ },
+ },
+ durationInFrames: 120,
+ fps: FPS,
+ compositionWidth: W,
+ compositionHeight: H,
+ snippet: (values) => {
+ const state = (values.state as SkeletonState) ?? "loading";
+ const layout = values.layout as string | undefined;
+ const mode = values.mode as string | undefined;
+
+ const props: string[] = [` state="${state}"`];
+ if (layout !== undefined && layout !== "lines")
+ props.push(` layout="${layout}"`);
+ if (mode !== undefined && mode !== "light")
+ props.push(` mode="${mode}"`);
+
+ return `import { Skeleton } from "@/components/remocn/skeleton";
+
+<Skeleton
+${props.join("\n")}
+>
+ {/* your real content */}
+</Skeleton>`;
+ },
+};
diff --git a/registry/remocn-ui/skeleton/index.tsx b/registry/remocn-ui/skeleton/index.tsx
new file mode 100644
index 00000000..702f7097
--- /dev/null
+++ b/registry/remocn-ui/skeleton/index.tsx
@@ -0,0 +1,166 @@
+"use client";
+
+import type { ReactNode } from "react";
+import { type RemocnTheme, useRemocnTheme } from "@/lib/remocn-ui";
+import { SkeletonBlock } from "@/components/remocn/skeleton-block";
+
+export type SkeletonState = "loading" | "loaded";
+
+/** Built-in placeholder layouts assembled from SkeletonBlock. */
+export type SkeletonLayout = "lines" | "card";
+
+export interface SkeletonProps {
+ /** Current visual state (snap path). State changes snap (no enter-tweens). */
+ state?: SkeletonState;
+ /**
+ * Resolved animated visual (smooth path). When provided, takes precedence over
+ * `state` — feed it an interpolated `SkeletonStyle` from `useSkeletonTransition`.
+ */
+ style?: SkeletonStyle;
+ /** The real content. It sits in normal flow and DEFINES the box size. */
+ children?: ReactNode;
+ /**
+ * Custom placeholder layer (arbitrary SkeletonBlock arrangement). Overrides
+ * `layout` when present.
+ */
+ placeholder?: ReactNode;
+ /** Built-in placeholder when no `placeholder` is given. */
+ layout?: SkeletonLayout;
+ /** Playhead scale forwarded to the placeholder SkeletonBlocks. */
+ speed?: number;
+ theme?: Partial<RemocnTheme>;
+ mode?: "light" | "dark";
+ className?: string;
+}
+
+// ===========================================================================
+// Skeleton visual — the COMPLETE animated look for a moment in time. A `state` is
+// a named preset of this visual (`skeletonStyle`); the smooth path feeds an
+// interpolated `SkeletonStyle` straight through. The component is a pure renderer
+// — it reads NO frame (only the composed SkeletonBlock motion atom does). The two
+// opacities CROSSFADE and sum to 1 per preset (child crossfade rule §3).
+// ===========================================================================
+
+export interface SkeletonStyle {
+ /** Placeholder layer opacity. */
+ skeletonOpacity: number;
+ /** Real-content layer opacity. Always `1 - skeletonOpacity`. */
+ contentOpacity: number;
+}
+
+/**
+ * The COMPLETE resting visual for a state — a pure `(state) => SkeletonStyle` map.
+ * The two opacities sum to 1 so the crossfade never dims the box. To change how a
+ * state looks, edit one entry.
+ */
+export function skeletonStyle(state: SkeletonState): SkeletonStyle {
+ switch (state) {
+ case "loaded":
+ return { skeletonOpacity: 0, contentOpacity: 1 };
+ default:
+ return { skeletonOpacity: 1, contentOpacity: 0 };
+ }
+}
+
+/** A built-in placeholder layout, assembled from SkeletonBlock motion atoms. */
+function LayoutPlaceholder({
+ layout,
+ speed,
+ baseColor,
+}: {
+ layout: SkeletonLayout;
+ speed?: number;
+ /** Base shimmer color threaded from the resolved Skeleton theme. */
+ baseColor: string;
+}) {
+ // Pass the resolved base color explicitly so a per-instance Skeleton
+ // `theme`/`mode` override reaches the built-in placeholder's blocks
+ // (SkeletonBlock would otherwise resolve its own default theme). The highlight
+ // is intentionally NOT passed — SkeletonBlock derives a visible contrast band
+ // from this base, so a themed Skeleton gets a themed, visible shimmer.
+ const shimmer = { speed, baseColor };
+ if (layout === "card") {
+ return (
+ <div style={{ display: "flex", gap: 14, alignItems: "center" }}>
+ {/* flexShrink:0 keeps the avatar a clean 48px circle even if the
+ content box is narrower than this placeholder row. */}
+ <SkeletonBlock
+ width={48}
+ height={48}
+ radius={24}
+ flexShrink={0}
+ {...shimmer}
+ />
+ <div style={{ display: "flex", flexDirection: "column", gap: 10 }}>
+ <SkeletonBlock width={180} height={14} {...shimmer} />
+ <SkeletonBlock width={120} height={14} {...shimmer} />
+ </div>
+ </div>
+ );
+ }
+ // lines — stacked rows of decreasing width.
+ return (
+ <div style={{ display: "flex", flexDirection: "column", gap: 10 }}>
+ <SkeletonBlock width={260} height={14} {...shimmer} />
+ <SkeletonBlock width={240} height={14} {...shimmer} />
+ <SkeletonBlock width={160} height={14} {...shimmer} />
+ </div>
+ );
+}
+
+/**
+ * A deterministic skeleton→content crossfade. Pure renderer of whatever
+ * `SkeletonStyle` it receives — it reads no frame, holds no state, runs no
+ * effects (only the composed `SkeletonBlock` reads the frame). The real content
+ * sits in normal flow and sets the box; the placeholder is an absolute overlay,
+ * so the box does not jump as they crossfade.
+ */
+export function Skeleton({
+ state = "loading",
+ style,
+ children,
+ placeholder,
+ layout = "lines",
+ speed,
+ theme: themeOverride,
+ mode,
+ className,
+}: SkeletonProps) {
+ // Resolve the theme so the built-in placeholder's shimmer follows a
+ // per-instance theme/mode override (its base = theme.muted; SkeletonBlock
+ // derives the contrast highlight from that base).
+ const theme = useRemocnTheme(themeOverride, mode);
+ const v = style ?? skeletonStyle(state);
+
+ // A custom `placeholder` is the caller's own markup — they theme its blocks.
+ // Only the built-in layouts get the resolved base color threaded in.
+ const placeholderLayer = placeholder ?? (
+ <LayoutPlaceholder layout={layout} speed={speed} baseColor={theme.muted} />
+ );
+
+ return (
+ <div
+ className={className}
+ style={{
+ position: "relative",
+ display: "inline-block",
+ fontFamily:
+ "var(--font-geist-sans), -apple-system, BlinkMacSystemFont, sans-serif",
+ }}
+ >
+ {/* Real content — normal flow, defines the box. */}
+ <div style={{ opacity: v.contentOpacity }}>{children}</div>
+ {/* Placeholder — absolute overlay so the box does not jump on crossfade. */}
+ <div
+ style={{
+ position: "absolute",
+ inset: 0,
+ opacity: v.skeletonOpacity,
+ pointerEvents: "none",
+ }}
+ >
+ {placeholderLayer}
+ </div>
+ </div>
+ );
+}
diff --git a/registry/remocn-ui/skeleton/preview.tsx b/registry/remocn-ui/skeleton/preview.tsx
new file mode 100644
index 00000000..b834fbb0
--- /dev/null
+++ b/registry/remocn-ui/skeleton/preview.tsx
@@ -0,0 +1,107 @@
+"use client";
+
+import { type RemocnTheme, useRemocnTheme } from "@/lib/remocn-ui";
+import {
+ Skeleton,
+ type SkeletonLayout,
+ type SkeletonState,
+} from "@/registry/remocn-ui/skeleton";
+
+export interface SkeletonPreviewProps {
+ layout?: SkeletonLayout;
+ state?: SkeletonState;
+ mode?: "light" | "dark";
+ speed?: number;
+}
+
+/** Demo content matching each layout, so the loaded state has something real. */
+function DemoContent({
+ layout,
+ theme,
+}: {
+ layout: SkeletonLayout;
+ theme: RemocnTheme;
+}) {
+ if (layout === "card") {
+ return (
+ <div style={{ display: "flex", gap: 14, alignItems: "center" }}>
+ <div
+ style={{
+ width: 48,
+ height: 48,
+ flexShrink: 0,
+ borderRadius: 24,
+ background: theme.secondary,
+ }}
+ />
+ {/* width 180 matches the card placeholder's text column, so the loaded
+ content box ≈ the placeholder box (avatar 48 + gap 14 + 180): the
+ box width is stable between loading and loaded, no overflow/shift. */}
+ <div
+ style={{
+ display: "flex",
+ flexDirection: "column",
+ gap: 6,
+ width: 180,
+ }}
+ >
+ <span style={{ fontSize: 15, fontWeight: 600, color: theme.foreground }}>
+ Ada Lovelace
+ </span>
+ <span style={{ fontSize: 13, color: theme.mutedForeground }}>
+ Enchantress of Numbers
+ </span>
+ </div>
+ </div>
+ );
+ }
+ return (
+ <div
+ style={{
+ display: "flex",
+ flexDirection: "column",
+ gap: 8,
+ maxWidth: 260,
+ color: theme.foreground,
+ fontSize: 14,
+ lineHeight: 1.5,
+ }}
+ >
+ <span>The Analytical Engine weaves algebraic patterns.</span>
+ <span>Just as the Jacquard loom weaves flowers and leaves.</span>
+ </div>
+ );
+}
+
+/**
+ * Preview-only wrapper for the customizer. The shipped `Skeleton` needs real
+ * `children` (they define the box) and renders inline; the customizer Player
+ * renders its `component` as the composition root, so this wrapper supplies demo
+ * content for the chosen layout and centers it on a theme-background stage. NOT
+ * shipped: not listed in registry.json files.
+ */
+export function SkeletonPreview({
+ layout = "card",
+ state = "loading",
+ mode,
+ speed,
+}: SkeletonPreviewProps) {
+ const theme = useRemocnTheme(undefined, mode);
+
+ return (
+ <div
+ style={{
+ position: "absolute",
+ inset: 0,
+ display: "flex",
+ alignItems: "center",
+ justifyContent: "center",
+ background: theme.background,
+ }}
+ >
+ <Skeleton layout={layout} state={state} mode={mode} speed={speed}>
+ <DemoContent layout={layout} theme={theme} />
+ </Skeleton>
+ </div>
+ );
+}
diff --git a/registry/remocn-ui/skeleton/use-skeleton-transition.ts b/registry/remocn-ui/skeleton/use-skeleton-transition.ts
new file mode 100644
index 00000000..5e2a0478
--- /dev/null
+++ b/registry/remocn-ui/skeleton/use-skeleton-transition.ts
@@ -0,0 +1,60 @@
+"use client";
+
+import {
+ easings,
+ type Step,
+ useStateTransition,
+} from "@/lib/remocn-ui";
+import {
+ skeletonStyle,
+ type SkeletonState,
+ type SkeletonStyle,
+} from "@/components/remocn/skeleton";
+// ^ install path; resolves in-repo via the @/components/remocn/* tsconfig alias.
+
+/** Default transition length (frames) when a step omits `duration`. Tune to taste. */
+export const DEFAULT_DURATION = 12;
+
+/**
+ * Blend two skeleton visuals: both opacities lerp. They stay summing to 1
+ * because the endpoints do and a lerp of two complementary pairs is complementary
+ * — so the crossfade never dims the box. No animated colors here.
+ */
+export function tweenSkeletonStyle(
+ a: SkeletonStyle,
+ b: SkeletonStyle,
+ t: number,
+): SkeletonStyle {
+ return {
+ skeletonOpacity:
+ a.skeletonOpacity + (b.skeletonOpacity - a.skeletonOpacity) * t,
+ contentOpacity:
+ a.contentOpacity + (b.contentOpacity - a.contentOpacity) * t,
+ };
+}
+
+export interface SkeletonTransitionOptions {
+ mode?: "light" | "dark";
+ speed?: number;
+ defaultDuration?: number;
+}
+
+/**
+ * Timeline → resolved (eased, tweened) SkeletonStyle. The CALLER invokes this; it
+ * reads the frame, the `<Skeleton>` component does not. Feed the result to
+ * `<Skeleton style={...} />` for a smooth loading→loaded crossfade.
+ */
+export function useSkeletonTransition(
+ steps: Step<SkeletonState>[],
+ opts: SkeletonTransitionOptions = {},
+): SkeletonStyle {
+ const { speed = 1, defaultDuration = DEFAULT_DURATION } = opts;
+ const { from, to, progress } = useStateTransition(
+ steps,
+ "loading",
+ speed,
+ defaultDuration,
+ );
+ const t = easings.out(progress);
+ return tweenSkeletonStyle(skeletonStyle(from), skeletonStyle(to), t);
+}