feat(motion): Conditional Motion Engine (vl-motion) with CSS if() progressive enhancement

.cursor/hooks/state/continual-learning-index.json

@@ -0,0 +1,93 @@
+{
+  "version": 1,
+  "transcripts": {
+    "/Users/erikassiscardoso/.cursor/projects/Users-erikassiscardoso-Local-Sites-velora/agent-transcripts/18618295-bdf2-46e6-b561-c3a2775071d4/18618295-bdf2-46e6-b561-c3a2775071d4.jsonl": {
+      "mtimeMs": 1778184725699,
+      "mtimeSec": 1778184725
+    },
+    "/Users/erikassiscardoso/.cursor/projects/Users-erikassiscardoso-Local-Sites-velora/agent-transcripts/18618295-bdf2-46e6-b561-c3a2775071d4/subagents/0f44cf87-7461-4845-9f03-338f5dc902fa.jsonl": {
+      "mtimeMs": 1778184539161,
+      "mtimeSec": 1778184539
+    },
+    "/Users/erikassiscardoso/.cursor/projects/Users-erikassiscardoso-Local-Sites-velora/agent-transcripts/18618295-bdf2-46e6-b561-c3a2775071d4/subagents/3a538d77-2c55-4b14-9d9e-7cc1bc4a3e78.jsonl": {
+      "mtimeMs": 1778184550203,
+      "mtimeSec": 1778184550
+    },
+    "/Users/erikassiscardoso/.cursor/projects/Users-erikassiscardoso-Local-Sites-velora/agent-transcripts/18618295-bdf2-46e6-b561-c3a2775071d4/subagents/e7c111ca-606d-4a7c-b6ed-6f15fd594ad7.jsonl": {
+      "mtimeMs": 1778184530873,
+      "mtimeSec": 1778184530
+    },
+    "/Users/erikassiscardoso/.cursor/projects/Users-erikassiscardoso-Local-Sites-velora/agent-transcripts/1a0acb75-2678-41d9-a434-61d34aa5db6e/1a0acb75-2678-41d9-a434-61d34aa5db6e.jsonl": {
+      "mtimeMs": 1777455389418,
+      "mtimeSec": 1777455389
+    },
+    "/Users/erikassiscardoso/.cursor/projects/Users-erikassiscardoso-Local-Sites-velora/agent-transcripts/4784ec19-7f3e-4ce7-84bb-485c708340f8/4784ec19-7f3e-4ce7-84bb-485c708340f8.jsonl": {
+      "mtimeMs": 1778189613797,
+      "mtimeSec": 1778189613
+    },
+    "/Users/erikassiscardoso/.cursor/projects/Users-erikassiscardoso-Local-Sites-velora/agent-transcripts/558abbbe-b072-48ec-82e2-2b80941fbe18/558abbbe-b072-48ec-82e2-2b80941fbe18.jsonl": {
+      "mtimeMs": 1777456066747,
+      "mtimeSec": 1777456066
+    },
+    "/Users/erikassiscardoso/.cursor/projects/Users-erikassiscardoso-Local-Sites-velora/agent-transcripts/6607f714-8ca0-4f9c-8438-37e472087f00/6607f714-8ca0-4f9c-8438-37e472087f00.jsonl": {
+      "mtimeMs": 1778186899932,
+      "mtimeSec": 1778186899
+    },
+    "/Users/erikassiscardoso/.cursor/projects/Users-erikassiscardoso-Local-Sites-velora/agent-transcripts/6607f714-8ca0-4f9c-8438-37e472087f00/subagents/3421c42d-30dc-4c0a-8862-3e7bef09293c.jsonl": {
+      "mtimeMs": 1778185139365,
+      "mtimeSec": 1778185139
+    },
+    "/Users/erikassiscardoso/.cursor/projects/Users-erikassiscardoso-Local-Sites-velora/agent-transcripts/6607f714-8ca0-4f9c-8438-37e472087f00/subagents/5257044c-1ee3-4a8a-8bcc-e832c1098b75.jsonl": {
+      "mtimeMs": 1778186072210,
+      "mtimeSec": 1778186072
+    },
+    "/Users/erikassiscardoso/.cursor/projects/Users-erikassiscardoso-Local-Sites-velora/agent-transcripts/6607f714-8ca0-4f9c-8438-37e472087f00/subagents/5f1fbb68-c2a6-4653-bc18-39fd65714456.jsonl": {
+      "mtimeMs": 1778185807372,
+      "mtimeSec": 1778185807
+    },
+    "/Users/erikassiscardoso/.cursor/projects/Users-erikassiscardoso-Local-Sites-velora/agent-transcripts/6607f714-8ca0-4f9c-8438-37e472087f00/subagents/71601be8-1824-4ff6-bff6-10979b3b9d1c.jsonl": {
+      "mtimeMs": 1778185707953,
+      "mtimeSec": 1778185707
+    },
+    "/Users/erikassiscardoso/.cursor/projects/Users-erikassiscardoso-Local-Sites-velora/agent-transcripts/6607f714-8ca0-4f9c-8438-37e472087f00/subagents/8cdb1bbe-17af-4e99-99d4-753cd306a954.jsonl": {
+      "mtimeMs": 1778185806433,
+      "mtimeSec": 1778185806
+    },
+    "/Users/erikassiscardoso/.cursor/projects/Users-erikassiscardoso-Local-Sites-velora/agent-transcripts/6a780cd3-579a-44fb-8723-104e3be1c936/6a780cd3-579a-44fb-8723-104e3be1c936.jsonl": {
+      "mtimeMs": 1777826388114,
+      "mtimeSec": 1777826388
+    },
+    "/Users/erikassiscardoso/.cursor/projects/Users-erikassiscardoso-Local-Sites-velora/agent-transcripts/70831a21-356c-4321-aab2-c64a327f61b0/70831a21-356c-4321-aab2-c64a327f61b0.jsonl": {
+      "mtimeMs": 1787600611440,
+      "mtimeSec": 1787600611
+    },
+    "/Users/erikassiscardoso/.cursor/projects/Users-erikassiscardoso-Local-Sites-velora/agent-transcripts/70831a21-356c-4321-aab2-c64a327f61b0/subagents/4392098b-6f8c-46d5-8890-ba2c6014af90.jsonl": {
+      "mtimeMs": 1787600620087,
+      "mtimeSec": 1787600620
+    },
+    "/Users/erikassiscardoso/.cursor/projects/Users-erikassiscardoso-Local-Sites-velora/agent-transcripts/70831a21-356c-4321-aab2-c64a327f61b0/subagents/43e4de2c-1f21-4226-92bf-d7a8a53125ed.jsonl": {
+      "mtimeMs": 1787582184721,
+      "mtimeSec": 1787582184
+    },
+    "/Users/erikassiscardoso/.cursor/projects/Users-erikassiscardoso-Local-Sites-velora/agent-transcripts/70831a21-356c-4321-aab2-c64a327f61b0/subagents/cd35309d-843b-4b29-b69d-cd2ac29eee1e.jsonl": {
+      "mtimeMs": 1787572666994,
+      "mtimeSec": 1787572666
+    },
+    "/Users/erikassiscardoso/.cursor/projects/Users-erikassiscardoso-Local-Sites-velora/agent-transcripts/9dbf47df-d1ff-4804-94ec-bcd6cc7a408f/9dbf47df-d1ff-4804-94ec-bcd6cc7a408f.jsonl": {
+      "mtimeMs": 1778167194799,
+      "mtimeSec": 1778167194
+    },
+    "/Users/erikassiscardoso/.cursor/projects/Users-erikassiscardoso-Local-Sites-velora/agent-transcripts/e4897ba2-a6c9-4962-a6eb-182c160d18da/e4897ba2-a6c9-4962-a6eb-182c160d18da.jsonl": {
+      "mtimeMs": 1787316784737,
+      "mtimeSec": 1787316784
+    },
+    "/Users/erikassiscardoso/.cursor/projects/Users-erikassiscardoso-Local-Sites-velora/agent-transcripts/ed1cd72f-1fd4-49a1-92ef-18325437cf3e/ed1cd72f-1fd4-49a1-92ef-18325437cf3e.jsonl": {
+      "mtimeMs": 1777753610368,
+      "mtimeSec": 1777753610
+    },
+    "/Users/erikassiscardoso/.cursor/projects/Users-erikassiscardoso-Local-Sites-velora/agent-transcripts/f903c4dc-dba1-4bb0-bbc0-2916acc9cfb3/f903c4dc-dba1-4bb0-bbc0-2916acc9cfb3.jsonl": {
+      "mtimeMs": 1777633041954,
+      "mtimeSec": 1777633041
+    }
+  }
+}

.cursor/hooks/state/continual-learning.json

@@ -0,0 +1,8 @@
+{
+  "version": 1,
+  "lastRunAtMs": 1787600605625,
+  "turnsSinceLastRun": 1,
+  "lastTranscriptMtimeMs": 1787600605478.6738,
+  "lastProcessedGenerationId": "0851e63a-0490-413f-8bf7-d36a295dfdfc",
+  "trialStartedAtMs": null
+}

AGENTS.md

@@ -0,0 +1,25 @@
+## Learned User Preferences
+
+- Prefer communication in Portuguese.
+- Zero-JS motion is non-negotiable: never introduce JS animation runtimes; keep the CSS-only / HTML+CSS path.
+- Treat Velora as a declarative CSS motion runtime and modern reference—not a utility framework; prioritize positioning, consistency, technical demos, and perceived value over feature volume.
+- Prefer evaluate-then-plan against the execution roadmap before large changes; often wants page-by-page reformulation using Velora CSS and the Showcase template.
+- Showcase pages should feel cinematic and exercise the design system plus motion catalog resources, not generic or simplistic layouts.
+- Prefer complex, coordinated scenes (3D stages, large type, enter/exit choreography, horizontal/stacked sections) over sparse section layouts.
+- Keep showcase UI patterns consistent across pages; avoid exaggerated glow and one-off chrome that breaks the shared look.
+- Stage 3D should be a reusable CSS-only stage contract (perspective/preserve-3d on the container; positional transforms via CSS vars on items; motion on inner content), not cube-triad-specific demos; preserve text-ring-orbit and circle-text-scroll.
+- Aim for GSAP-like scene authorship in HTML/CSS (shared scene clock, relative timing, pin+scrub)—preferred product direction for the scene engine.
+- Core motion must stay host-agnostic and work with any UI (Tailwind and others); **Skins** is the product name for the Velora design-system layer (named themes via `data-editorial-theme`); Showcase is the cinematic reference UI, not the motion contract.
+- Prefer modern CSS capabilities (e.g. `if()`, typed `attr()`, `sibling-index()`) as progressive enhancement for scene choreography.
+- Prefer fixing contract/consistency before expanding demos; prefer a lean public Showcase that archives surplus pages in-repo rather than deleting Skins/DS work; reuse existing motion examples rather than inventing parallel systems.
+
+## Learned Workspace Facts
+
+- Monorepo layout: canonical CSS in `packages/css/src/`; Vite playground in `apps/showcase/`; Astro docs app in `apps/docs/`; markdown source of truth in repo-root `docs/`; plus `design-system/`, `examples/`, `experiments/`, and `starters/html-css-minimal/`.
+- Always edit CSS in `packages/css/src/` and sync to showcase (`pnpm sync:showcase-css`); `apps/showcase/public/css/` is derived and must not be edited as source.
+- Motion is attribute-driven (`vl-effect`, `vl-timeline`, `vl-range`, `vl-scene`, related `vl-*`); rules live in ordered `@layer velora.*` (reset → tokens → layout → motion → components → transitions → utilities → overrides).
+- Product surfaces split: Velora core = scene/motion engine; Showcase = cinematic reference UI/DS; docs site documents the framework once the API is stable.
+- `@velora/css` ships separable entrypoints: `motion-core` (host-agnostic engine) vs `theme` / full bundle (visual Skins); editorial skins use `html[data-editorial-theme]` (e.g. noir, earth, aethel, meridian).
+- Lean Showcase restarts should snapshot retired pages under a dated in-repo `archive/` (outside live Vite registry and contract checks), not delete recoverable DS/skin work.
+- Workspace tooling is pnpm + Turborepo; common checks include `pnpm verify:contract` and showcase CSS drift checks.
+- Root `AGENTS.md` holds learned memory only; agent operating instructions live under `docs/agents/AGENTS.md` and must not be mixed into the learned-memory file.

CHANGELOG.md

@@ -9,6 +9,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Changed
+- Public Showcase reduced to six routes (Home, Timeline, Skins, Catalog, Hosts, Archive). Pre-lean pages snapshotted in `archive/showcase-2026-08/` (not Vite/CI).
+- **Skins** is the product name for named editorial models (`data-editorial-theme`). Home is didactic: engine vs Skins.
+- Motion Catalog: `#pin` teaching replaced by `#scene-engine` (numeric pin + stage/acts live demo); Engine vs Skins lanes; DX toolbar framed as optional CSS-only helper.
+- Catalog Phase C (P1): channel-first cards for CONTRACT `vl-enter` / `vl-scroll` / `vl-hover` extensions; scene-engine overlap + auto-clock demos.
+- Catalog DX runtime: toolbar covers full CONTRACT attr set, scene-engine targets, CSS var duration/speed, stagger-aware replay.
+
 ---
 
 ## [1.0.0] — 2025-01-01

README.md

@@ -4,9 +4,9 @@
 
 ![License: ISC](https://img.shields.io/badge/license-ISC-blue.svg)
 
-Velora is a CSS-first design system for building premium, cinematic web interfaces using nothing but modern browser APIs. No JavaScript frameworks. No runtime animation libraries. Just HTML and CSS that move.
+Velora is a **declarative CSS motion engine**. HTML attributes describe intent; the browser executes it. No JavaScript animation runtime. Works with Tailwind, Relume, or any UI.
 
-Built for developers and agencies who want production-ready motion without the weight.
+The cinematic **Showcase** is the optional Velora design-system skin — not a requirement to turn motion on.
 
 ## Features
 
@@ -32,26 +32,28 @@ pnpm add @velora/css
 
 ### 2. Import
 
+Host-agnostic (any UI — Tailwind, etc.):
+
 ```css
-@import "@velora/css";
+@import "@velora/css/motion-core";
+@import "@velora/css/transitions"; /* optional */
 ```
 
-Or consume only the bundles you need:
+Full Velora look (theme + components + motion):
 
 ```css
-@import "@velora/css/base";
-@import "@velora/css/motion-core";
-@import "@velora/css/components-core";
-@import "@velora/css/transitions";
+@import "@velora/css";
 ```
 
 ### 3. Use
 
 ```html
-<div vl-effect="fade-up" vl-timeline="view">
-  <h2>Zero-JS motion</h2>
-  <p>Pure CSS. Pure performance.</p>
-</div>
+<section vl-scene vl-timeline="view" vl-pin="3" vl-scrub>
+  <div vl-stage>
+    <h1 vl-enter="clip-rise" vl-act="1">Zero-JS motion</h1>
+    <p vl-enter="fade-up" vl-act="1">Same attributes on Tailwind or Velora UI.</p>
+  </div>
+</section>
 ```
 
 That's it. No build config. No framework bindings. Works with any stack.
@@ -71,18 +73,19 @@ It includes:
 
 ## Modular Entry Points
 
-Velora now ships stable modular entry points in addition to the full bundle:
-
-- `@velora/css` or `@velora/css/full` — full framework bundle (default)
-- `@velora/css/base` — reset, tokens, layout, utilities
-- `@velora/css/motion-core` — core declarative motion grammar
-- `@velora/css/motion-extended` — extended motion effects
-- `@velora/css/components-core` — components, forms, dialogs, structures
+- `@velora/css` or `@velora/css/full` — convenience bundle (theme + components + motion)
+- `@velora/css/motion-core` — host-agnostic motion grammar + scene engine
+- `@velora/css/motion-extended` — extra effect presets
+- `@velora/css/theme` — visual tokens + editorial + scene look recipes
+- `@velora/css/base` — reset, motion tokens, structural layout, utilities
+- `@velora/css/components-core` — optional UI primitives
 - `@velora/css/transitions` — view transition presets
 - `@velora/css/premium` — premium components
 - `@velora/css/overrides` — last-mile override layer
 
-All bundles keep the same `@layer` contract to avoid cascade drift between pages.
+Proofs: `examples/tailwind-host/` (motion-core + Tailwind) · `apps/showcase` (six-page reference UI: Home, Timeline, Skins, Catalog, Hosts, Archive). Older Showcase pages: `archive/showcase-2026-08/`.
+
+**Skins** are named design-system models (`html[data-editorial-theme]`). They are optional; motion works without them.
 
 ## Motion Channels (v2)
 

apps/docs/src/layouts/Base.astro

@@ -417,24 +417,17 @@ function isActive(href: string): boolean {
         <nav aria-label="Documentation navigation">
           <p class="docs-nav-section">Core</p>
           <a href="/" aria-current={isActive("/") ? "page" : undefined}>Getting Started</a>
-          <a href="/tokens/" aria-current={isActive("/tokens") ? "page" : undefined}
-            >Design Tokens</a
-          >
-          <a href="/effects/" aria-current={isActive("/effects") ? "page" : undefined}
-            >Motion Effects</a
-          >
+          <a href="/attributes/" aria-current={isActive("/attributes") ? "page" : undefined}>Attributes</a>
+          <a href="/effects/" aria-current={isActive("/effects") ? "page" : undefined}>Effects</a>
+          <a href="/timelines/" aria-current={isActive("/timelines") ? "page" : undefined}>Timelines</a>
           <a href="/scenes/" aria-current={isActive("/scenes") ? "page" : undefined}>Scenes</a>
-          <a href="/transitions/" aria-current={isActive("/transitions") ? "page" : undefined}
-            >Page Transitions</a
-          >
-          <a href="/attributes/" aria-current={isActive("/attributes") ? "page" : undefined}
-            >Attribute Reference</a
-          >
+          <a href="/hosts/" aria-current={isActive("/hosts") ? "page" : undefined}>Hosts</a>
+          <a href="/motion-conditions/" aria-current={isActive("/motion-conditions") ? "page" : undefined}>Conditional Motion</a>
+          <a href="/transitions/" aria-current={isActive("/transitions") ? "page" : undefined}>Transitions</a>
+          <a href="/tokens/" aria-current={isActive("/tokens") ? "page" : undefined}>Tokens</a>
           <p class="docs-nav-section">For Agents</p>
           <a href="/skills/" aria-current={isActive("/skills") ? "page" : undefined}>Skill Sets</a>
-          <a href="/agents/" aria-current={isActive("/agents") ? "page" : undefined}
-            >Agent Handbook</a
-          >
+          <a href="/agents/" aria-current={isActive("/agents") ? "page" : undefined}>Agent Handbook</a>
         </nav>
       </aside>
       <main class="docs-main">

apps/docs/src/pages/hosts.astro

@@ -0,0 +1,43 @@
+---
+import Base from "../layouts/Base.astro";
+---
+
+<Base title="Hosts" description="Use Velora motion-core with Tailwind or any UI — no Velora skin required.">
+  <span class="vl-kicker">Interoperability</span>
+
+  <h1 class="docs-page-title">Hosts (Tailwind &amp; others)</h1>
+  <p class="docs-page-lead">
+    Velora is a motion engine. Your host owns layout and visual styling.
+  </p>
+
+  <h2>Minimal import</h2>
+  <pre><code>@import "@velora/css/motion-core";
+/* optional page transitions */
+@import "@velora/css/transitions";</code></pre>
+
+  <p>Do <strong>not</strong> require <code>@velora/css/theme</code> or component classes for scenes to work.</p>
+
+  <h2>Tailwind example</h2>
+  <pre><code>&lt;section vl-scene vl-timeline="view" vl-pin="3" vl-scrub&gt;
+  &lt;div vl-stage class="min-h-svh grid place-items-center gap-6 px-6"&gt;
+    &lt;p class="text-sm uppercase tracking-widest" vl-enter="fade-up" vl-act="1"&gt;Kicker&lt;/p&gt;
+    &lt;h1 class="text-5xl font-semibold" vl-enter="clip-rise" vl-act="1"&gt;Title&lt;/h1&gt;
+    &lt;img class="w-full max-w-3xl rounded-2xl" vl-scroll="media-zoom" vl-act="2" vl-span="2" alt="" /&gt;
+  &lt;/div&gt;
+&lt;/section&gt;</code></pre>
+
+  <p>
+    Repo proof: <code>examples/tailwind-host/</code>. Showcase proves the Velora cinematic UI;
+    examples prove the host-agnostic path.
+  </p>
+
+  <h2>Layers</h2>
+  <p>
+    Velora uses <code>@layer velora.*</code>. Keep host utilities outside or after those layers so
+    Tailwind wins on appearance while <code>vl-*</code> attributes still drive animation.
+  </p>
+
+  <h2>Optional skin</h2>
+  <pre><code>@import "@velora/css/motion-core";
+@import "@velora/css/theme"; /* brand tokens + scene recipes */</code></pre>
+</Base>