@babylonjs-toolkit/agent 1.1.0

package/skills/bt-design/templates/3d-hero-scroll/hero-scroll.css

@@ -0,0 +1,268 @@
+/* ═══════════════════════════════════════════════════════════════════
+   3D-HERO-SCROLL — structural + control styles
+   Brand-agnostic: every color/font flows through --hs-* tokens.
+   MAP THESE TO THE HOST SITE'S DESIGN SYSTEM — do not ship defaults
+   unless the host has no tokens of its own.
+   ═══════════════════════════════════════════════════════════════════ */
+
+:root {
+  --hs-bg: #060607;            /* page/veil background            */
+  --hs-ink: #e8ecee;           /* primary text                    */
+  --hs-dim: #878e93;           /* secondary text                  */
+  --hs-accent: #35e9ff;        /* the ONE accent — HUD / highlights */
+  --hs-accent-soft: rgba(53, 233, 255, 0.35);
+  --hs-accent-ghost: rgba(53, 233, 255, 0.08);
+  --hs-display: inherit;       /* host display font               */
+  --hs-mono: ui-monospace, "SFMono-Regular", Menlo, monospace;
+}
+
+/* ── loading gate: no scrolling until footage is ready ─────────── */
+
+body[data-hs-state="loading"] { overflow: hidden; }
+
+/* ── journey stage ──────────────────────────────────────────────── */
+
+#hs-journey { position: relative; /* height set inline or by host, e.g. 640vh */ }
+
+#hs-journey .hs-stage {
+  position: sticky; top: 0;
+  height: 100vh; width: 100%;
+  overflow: hidden;
+  background: var(--hs-bg);
+}
+
+#hs-video {
+  position: absolute; inset: 0;
+  width: 100%; height: 100%;
+  object-fit: cover;
+  will-change: filter;
+}
+
+body.hs-no-video #hs-video { display: none; }
+body.hs-no-video .hs-stage {
+  background: var(--hs-poster, var(--hs-bg)) center/cover no-repeat;
+}
+
+.hs-stage-shade {
+  position: absolute; inset: 0; pointer-events: none;
+  background: linear-gradient(180deg, rgba(0,0,0,0.35) 0%, transparent 30%,
+              transparent 62%, rgba(0,0,0,0.55) 100%);
+}
+
+/* ── overlays (choreographed by the engine) ─────────────────────── */
+
+.hs-ovl {
+  position: absolute; inset: 0;
+  display: flex; flex-direction: column; justify-content: center;
+  padding: 0 clamp(24px, 7vw, 120px);
+  opacity: 0; visibility: hidden;
+  pointer-events: none;
+  will-change: opacity, transform, filter;
+}
+
+/* directional scrim so copy survives bright footage behind it.
+   Add .hs-scrim to any overlay with left-anchored text. */
+.hs-ovl.hs-scrim::before {
+  content: "";
+  position: absolute; inset: 0; z-index: -1;
+  background: linear-gradient(100deg, rgba(0, 0, 0, 0.82) 0%,
+              rgba(0, 0, 0, 0.5) 38%, rgba(0, 0, 0, 0.08) 68%, transparent 82%);
+}
+
+/* ── rewind veil (injected by the engine) ───────────────────────── */
+
+#hs-veil {
+  position: fixed; inset: 0; z-index: 150;
+  background: var(--hs-bg);
+  opacity: 0;
+  pointer-events: none;
+  transition: opacity 0.45s ease;
+}
+
+#hs-veil.hs-on { opacity: 1; pointer-events: auto; }
+
+/* accent sweep while on black — the journey re-arming */
+#hs-veil::after {
+  content: "";
+  position: absolute; left: 22%; right: 22%; top: 50%; height: 1px;
+  background: var(--hs-accent);
+  box-shadow: 0 0 12px var(--hs-accent), 0 0 44px var(--hs-accent-soft);
+  transform: scaleX(0);
+  opacity: 0;
+  transition: transform 0.55s cubic-bezier(0.16, 1, 0.3, 1) 0.25s,
+              opacity 0.2s ease 0.25s;
+}
+
+#hs-veil.hs-on::after { transform: scaleX(1); opacity: 1; }
+
+/* ── loader (optional) ──────────────────────────────────────────── */
+
+#hs-loader {
+  position: fixed; inset: 0; z-index: 200;
+  background: var(--hs-bg);
+  display: flex; flex-direction: column; align-items: center;
+  justify-content: center; gap: 22px;
+  transition: opacity 0.9s ease 0.35s, visibility 0.9s ease 0.35s;
+}
+
+body[data-hs-state="ready"] #hs-loader { opacity: 0; visibility: hidden; }
+
+.hs-loader-bar {
+  width: min(420px, 70vw); height: 2px;
+  background: rgba(255, 255, 255, 0.08);
+  overflow: hidden;
+}
+
+#hs-loader-fill {
+  display: block; height: 100%; width: 0%;
+  background: var(--hs-accent);
+  box-shadow: 0 0 12px var(--hs-accent), 0 0 32px var(--hs-accent-soft);
+  transition: width 0.25s ease;
+}
+
+/* ── telemetry HUD (optional) ───────────────────────────────────── */
+
+#hs-hud {
+  position: fixed; right: clamp(18px, 3vw, 44px); bottom: clamp(18px, 3vw, 40px);
+  z-index: 100;
+  width: 200px;
+  padding: 14px 16px 12px;
+  background: rgba(0, 0, 0, 0.55);
+  border: 1px solid rgba(255, 255, 255, 0.07);
+  border-left: 2px solid var(--hs-accent);
+  backdrop-filter: blur(10px);
+  -webkit-backdrop-filter: blur(10px);
+  opacity: 0;
+  transform: translateY(12px);
+  transition: opacity 0.6s ease, transform 0.6s ease;
+}
+
+body[data-hs-state="ready"] #hs-hud { opacity: 1; transform: none; }
+body[data-hs-state="ready"] #hs-hud.hs-hud-off {
+  opacity: 0; transform: translateY(12px); pointer-events: none;
+}
+
+#hs-hud-value {
+  font: 700 52px/0.9 var(--hs-display);
+  color: var(--hs-ink);
+  font-variant-numeric: tabular-nums;
+}
+
+.hs-hud-unit { font: 600 11px var(--hs-mono); letter-spacing: 0.3em; color: var(--hs-accent); }
+
+.hs-hud-bar { margin: 12px 0 8px; height: 2px; background: rgba(255,255,255,0.1); overflow: hidden; }
+
+#hs-hud-progress {
+  display: block; height: 100%; width: 100%;
+  background: var(--hs-accent);
+  box-shadow: 0 0 10px var(--hs-accent-soft);
+  transform: scaleX(0); transform-origin: left center;
+}
+
+.hs-hud-meta {
+  display: flex; justify-content: space-between;
+  font: 400 9px var(--hs-mono); letter-spacing: 0.14em; color: var(--hs-dim);
+}
+
+/* ── play button (optional) ─────────────────────────────────────── */
+
+#hs-play {
+  position: fixed; top: clamp(18px, 3vh, 30px); left: 50%;
+  transform: translateX(-50%) translateY(-8px);
+  z-index: 110;
+  display: flex; align-items: center; gap: 12px;
+  padding: 13px 26px;
+  background: rgba(0, 0, 0, 0.55);
+  border: 1px solid var(--hs-accent-soft);
+  border-radius: 999px;
+  color: var(--hs-accent);
+  font: 600 10px var(--hs-mono);
+  letter-spacing: 0.32em;
+  cursor: pointer;
+  backdrop-filter: blur(10px);
+  -webkit-backdrop-filter: blur(10px);
+  opacity: 0;
+  pointer-events: none;
+  transition: opacity 0.6s ease, transform 0.6s ease, background 0.35s ease,
+              border-color 0.35s ease, box-shadow 0.35s ease, color 0.35s ease;
+  animation: hs-breathe 3.2s ease-in-out infinite;
+}
+
+body[data-hs-state="ready"] #hs-play {
+  opacity: 1; pointer-events: auto;
+  transform: translateX(-50%) translateY(0);
+}
+
+@keyframes hs-breathe {
+  0%, 100% { box-shadow: 0 0 0 rgba(0, 0, 0, 0); }
+  50% { box-shadow: 0 0 22px var(--hs-accent-soft), 0 0 60px var(--hs-accent-ghost); }
+}
+
+#hs-play:hover {
+  background: var(--hs-accent-ghost);
+  border-color: var(--hs-accent);
+  box-shadow: 0 0 26px var(--hs-accent-soft);
+}
+
+.hs-play-icon {
+  width: 0; height: 0;
+  border-left: 9px solid var(--hs-accent);
+  border-top: 6px solid transparent;
+  border-bottom: 6px solid transparent;
+}
+
+#hs-play.hs-playing {
+  animation: none;
+  border-color: rgba(255, 255, 255, 0.18);
+  color: var(--hs-dim);
+}
+
+#hs-play.hs-playing .hs-play-icon {
+  border: none;
+  width: 9px; height: 9px;
+  background: var(--hs-dim);
+}
+
+/* ── jump nav (optional) ────────────────────────────────────────── */
+
+#hs-jump-nav {
+  position: fixed; left: clamp(18px, 3vw, 44px); bottom: clamp(18px, 3vw, 40px);
+  z-index: 100;
+  display: flex; gap: 10px;
+  opacity: 0;
+  transform: translateY(12px);
+  transition: opacity 0.6s ease, transform 0.6s ease;
+}
+
+body[data-hs-state="ready"] #hs-jump-nav { opacity: 1; transform: none; }
+
+#hs-jump-nav button {
+  display: flex; align-items: center; gap: 9px;
+  padding: 11px 18px;
+  background: rgba(0, 0, 0, 0.55);
+  border: 1px solid rgba(255, 255, 255, 0.1);
+  color: var(--hs-dim);
+  font: 600 9px var(--hs-mono);
+  letter-spacing: 0.28em;
+  cursor: pointer;
+  backdrop-filter: blur(10px);
+  -webkit-backdrop-filter: blur(10px);
+  transition: border-color 0.3s ease, color 0.3s ease,
+              box-shadow 0.3s ease, opacity 0.3s ease;
+}
+
+#hs-jump-nav .hs-arrow { color: var(--hs-accent); font-size: 11px; }
+
+#hs-jump-nav button:hover {
+  border-color: var(--hs-accent);
+  color: var(--hs-ink);
+  box-shadow: 0 0 18px var(--hs-accent-ghost);
+}
+
+#hs-jump-nav button.hs-nav-dim { opacity: 0.3; pointer-events: none; }
+
+/* ── reduced motion ─────────────────────────────────────────────── */
+
+@media (prefers-reduced-motion: reduce) {
+  #hs-play { animation: none; }
+}

package/skills/bt-design/templates/3d-hero-scroll/hero-scroll.d.ts

@@ -0,0 +1,67 @@
+/* Type declarations for the framework-agnostic hero-scroll engine. */
+
+export interface HeroScrollTelemetry {
+  /** HUD value at endP. */
+  max: number;
+  /** Progress (0–1) where the value leaves 0 — CALIBRATE from footage frames. */
+  startP: number;
+  /** Progress where the value reaches max (default 0.95). */
+  endP?: number;
+  /** Curve exponent: <1 = violent launch, 1 = linear (default 0.45). */
+  exponent?: number;
+  /** [progressThreshold, label] pairs; the HUD shows the last one reached. */
+  segments?: Array<[number, string]>;
+}
+
+export interface HeroScrollConfig {
+  /** Path to the ALL-INTRA (`-g 1`) scrub-encoded mp4. */
+  video?: string;
+  /** Scrub low-pass factor, 1 = no smoothing (default 0.16). */
+  smoothing?: number;
+  /** Scroll-velocity motion blur on the footage (default true). */
+  motionBlur?: boolean;
+  /** Body class applied when the footage can't load (default "hs-no-video"). */
+  fallbackClass?: string;
+  /** Telemetry HUD curve; omit/null to disable HUD math. */
+  telemetry?: HeroScrollTelemetry | null;
+  /**
+   * Where PLAY/END consider "the end":
+   * - "page" (default): PLAY glides on to the document bottom, END jumps there.
+   * - "hero": PLAY/END stop at the journey's end (land on the next section).
+   * Named `sweep` (not `reach`) so it never collides with a spec/plan's
+   * route/DOM-scope terminology.
+   */
+  sweep?: "page" | "hero";
+  /** Autoplay tail speed after the journey, as a fraction of the viewport
+   *  (sweep: "page" only; default 0.5). */
+  tailRate?: number;
+  /** Veiled-cut fade duration in ms (default 480). */
+  veilFadeMs?: number;
+  /** Hold-on-black duration in ms while the sweep re-arms (default 450). */
+  veilHoldMs?: number;
+}
+
+export interface HeroScrollController {
+  /** Start film-speed autoplay. */
+  play(): void;
+  /** Stop autoplay / veil. */
+  stop(): void;
+  /** Fade to black, jump to `y`, re-sync, lift; optional continuation. */
+  veilTo(y: number, done?: (token: number) => void): void;
+  /** Current smoothed journey progress (0–1). */
+  progress(): number;
+  /** Tear everything down (listeners, rAF, injected veil, blob URL). */
+  destroy(): void;
+}
+
+/**
+ * Mount the hero-scroll engine against a root element (or `document`).
+ * The root must already contain the `#hs-journey` markup. Returns a
+ * controller — call `.destroy()` on unmount.
+ */
+export function initHeroScroll(
+  root?: ParentNode,
+  config?: HeroScrollConfig,
+): HeroScrollController;
+
+export default initHeroScroll;

package/skills/bt-design/templates/3d-hero-scroll/hero-scroll.html

@@ -0,0 +1,78 @@
+<!-- ═══════════════════════════════════════════════════════════════════
+  3D-HERO-SCROLL — markup skeleton
+  Replaces a placeholder 100vh hero. Every block marked OPTIONAL can be
+  deleted; the engine activates features by element presence only.
+  Set --hs-* tokens (hero-scroll.css) to the host brand before shipping.
+  ═══════════════════════════════════════════════════════════════════ -->
+
+<!-- OPTIONAL · preload gate (scroll is locked until footage is ready) -->
+<div id="hs-loader" role="status" aria-label="Loading">
+  <div class="hs-loader-mark"><!-- host wordmark/logo --></div>
+  <div class="hs-loader-bar"><span id="hs-loader-fill"></span></div>
+  <span id="hs-loader-pct">000</span>
+</div>
+
+<!-- OPTIONAL · film-speed autoplay. data-idle / data-busy set the labels -->
+<button id="hs-play" aria-pressed="false" title="Play — cinematic auto-scroll">
+  <span class="hs-play-icon" aria-hidden="true"></span>
+  <span class="hs-play-label" data-idle="PLAY THE RUN" data-busy="STOP">PLAY THE RUN</span>
+</button>
+
+<!-- OPTIONAL · veiled jump nav -->
+<nav id="hs-jump-nav" aria-label="Quick navigation">
+  <button id="hs-top" title="Go to top"><span class="hs-arrow" aria-hidden="true">↑</span><span>TOP</span></button>
+  <button id="hs-end" title="Skip to the end"><span class="hs-arrow" aria-hidden="true">↓</span><span>END</span></button>
+</nav>
+
+<!-- OPTIONAL · telemetry HUD (value curve configured in HS_CONFIG) -->
+<aside id="hs-hud" aria-label="Telemetry">
+  <div><span id="hs-hud-value">0</span> <span class="hs-hud-unit">UNIT</span></div>
+  <div class="hs-hud-bar"><span id="hs-hud-progress"></span></div>
+  <div class="hs-hud-meta"><span id="hs-hud-seg"></span><span id="hs-hud-pct">000%</span></div>
+</aside>
+
+<!-- REQUIRED · the journey. height = scroll length: ~15–20vh per second
+     of footage (e.g. 32s film → 560–640vh). Poster = FIRST frame of the
+     scrub file, not a glamour still, or the load-in will jump-cut. -->
+<div id="hs-journey" style="height: 640vh">
+  <div class="hs-stage">
+    <video id="hs-video" muted playsinline preload="none" poster="media/poster.jpg"></video>
+    <div class="hs-stage-shade" aria-hidden="true"></div>
+
+    <!-- OPTIONAL · choreographed overlays. data-from/data-to are journey
+         progress (0–1). Add .hs-scrim for left-anchored copy over bright
+         footage. [data-hs-depth] children parallax; [data-hs-count]
+         numbers count up when the overlay activates. -->
+    <section class="hs-ovl" data-from="0" data-to="0.115">
+      <!-- hero wordmark / tagline / scroll cue -->
+    </section>
+
+    <section class="hs-ovl hs-scrim" data-from="0.26" data-to="0.46">
+      <!-- e.g. stats: <span data-hs-count data-target="1200" data-group="1">0</span> -->
+    </section>
+  </div>
+</div>
+
+<!-- The rest of the host page (below) becomes the autoplay "tail". -->
+
+<script>
+  window.HS_CONFIG = {
+    video: "media/journey-scrub.mp4", // ALL-INTRA (-g 1) scrub encode
+    sweep: "page",   // "page" (default): PLAY/END traverse the whole landing
+                     // page; "hero": PLAY/END stop at the journey's end — you
+                     // land on the next regular HTML section, same as a
+                     // normal scroll (opt in explicitly). Named `sweep`, not
+                     // `reach`, to avoid colliding with route/DOM-scope terms.
+    telemetry: {
+      max: 250,        // HUD value at endP
+      startP: 0.286,   // CALIBRATE: first frame of real subject motion
+      endP: 0.95,
+      exponent: 0.45,  // <1 = hard launch
+      segments: [[0, "SEG 01"], [0.25, "SEG 02"], [0.5, "SEG 03"], [0.75, "SEG 04"]],
+    },
+  };
+</script>
+<!-- ESM module: auto-boots against the document because HS_CONFIG is set above.
+     (React/bundler hosts import initHeroScroll from hero-scroll.js instead —
+     see HeroScroll.tsx — and never set window.HS_CONFIG.) -->
+<script type="module" src="hero-scroll.js"></script>