@substrate-platform/site 0.1.1-canary.0

package/dist/animations.d.ts

@@ -0,0 +1,37 @@
+import Lenis from 'lenis';
+/**
+ * Initialize Lenis smooth scrolling.
+ * Call once in a client component's useEffect.
+ */
+export declare function initSmoothScroll(options?: {
+    duration?: number;
+    easing?: (t: number) => number;
+}): () => void;
+/** Get the current Lenis instance (if initialized). */
+export declare function getLenis(): Lenis | null;
+/** Scroll to a target element or position smoothly. */
+export declare function scrollTo(target: string | number | HTMLElement, options?: {
+    offset?: number;
+    duration?: number;
+}): void;
+/**
+ * Fade-in-up animation for page sections.
+ */
+export declare function fadeInUp(target: HTMLElement | string, delay?: number): gsap.core.Tween;
+/**
+ * Stagger reveal for grid items.
+ */
+export declare function staggerReveal(target: HTMLElement | string, stagger?: number): gsap.core.Tween;
+/**
+ * Scale + rotate entrance for hero / canvas elements.
+ */
+export declare function scaleEntrance(target: HTMLElement | string): gsap.core.Tween;
+/**
+ * 3D Y-axis rotation card flip.
+ */
+export declare function cardFlip(target: HTMLElement | string): gsap.core.Tween;
+/**
+ * Magnetic hover effect — element follows cursor slightly.
+ */
+export declare function magneticHover(target: HTMLElement, strength?: number): () => void;
+//# sourceMappingURL=animations.d.ts.map

package/dist/animations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"animations.d.ts","sourceRoot":"","sources":["../src/animations.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,MAAM,OAAO,CAAC;AAS1B;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,CAAC,EAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,CAAA;CAAE,cAwB/F;AAED,uDAAuD;AACvD,wBAAgB,QAAQ,iBAEvB;AAED,uDAAuD;AACvD,wBAAgB,QAAQ,CACtB,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,WAAW,EACrC,OAAO,CAAC,EAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,QAMjD;AAID;;GAEG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,EAAE,KAAK,SAAI,mBAY/D;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,EAAE,OAAO,SAAM,mBAaxE;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,mBAYzD;AAED;;GAEG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,mBAapD;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,WAAW,EAAE,QAAQ,SAAM,cA6BhE"}

package/dist/animations.js

@@ -0,0 +1,139 @@
+/**
+ * GSAP + Lenis — smooth scroll and animation utilities.
+ *
+ * Lenis provides buttery smooth scrolling (replaces native scroll with
+ * a rAF-driven interpolated scroll). GSAP's ScrollTrigger integrates
+ * with Lenis for scroll-driven animations.
+ *
+ * All factories are generic — no application-specific names or semantics.
+ */
+'use client';
+import { gsap } from 'gsap';
+import { ScrollTrigger } from 'gsap/ScrollTrigger';
+import Lenis from 'lenis';
+// Register GSAP plugin (client-side only).
+gsap.registerPlugin(ScrollTrigger);
+// ── Lenis smooth scroll ─────────────────────────────────────────────
+let lenisInstance = null;
+/**
+ * Initialize Lenis smooth scrolling.
+ * Call once in a client component's useEffect.
+ */
+export function initSmoothScroll(options) {
+    if (typeof window === 'undefined')
+        return () => { };
+    const lenis = new Lenis({
+        duration: options?.duration ?? 1.2,
+        easing: options?.easing ?? ((t) => Math.min(1, 1.001 - 2 ** (-10 * t))),
+        smoothWheel: true,
+    });
+    lenisInstance = lenis;
+    // Sync Lenis with GSAP ScrollTrigger.
+    lenis.on('scroll', ScrollTrigger.update);
+    // Drive Lenis via GSAP's ticker for unified rAF loop.
+    gsap.ticker.add((time) => {
+        lenis.raf(time * 1000);
+    });
+    gsap.ticker.lagSmoothing(0);
+    return () => {
+        lenis.destroy();
+        lenisInstance = null;
+    };
+}
+/** Get the current Lenis instance (if initialized). */
+export function getLenis() {
+    return lenisInstance;
+}
+/** Scroll to a target element or position smoothly. */
+export function scrollTo(target, options) {
+    lenisInstance?.scrollTo(target, {
+        offset: options?.offset ?? 0,
+        duration: options?.duration ?? 1.2,
+    });
+}
+// ── GSAP animation factories ────────────────────────────────────────
+/**
+ * Fade-in-up animation for page sections.
+ */
+export function fadeInUp(target, delay = 0) {
+    const vars = {
+        opacity: 1,
+        y: 0,
+        duration: 0.8,
+        delay,
+        ease: 'power3.out',
+    };
+    if (typeof target === 'string') {
+        vars.scrollTrigger = target;
+    }
+    return gsap.fromTo(target, { opacity: 0, y: 40 }, vars);
+}
+/**
+ * Stagger reveal for grid items.
+ */
+export function staggerReveal(target, stagger = 0.1) {
+    return gsap.fromTo(target, { opacity: 0, y: 30, scale: 0.95 }, {
+        opacity: 1,
+        y: 0,
+        scale: 1,
+        duration: 0.6,
+        stagger,
+        ease: 'power2.out',
+    });
+}
+/**
+ * Scale + rotate entrance for hero / canvas elements.
+ */
+export function scaleEntrance(target) {
+    return gsap.fromTo(target, { opacity: 0, scale: 0.8, rotation: -5 }, {
+        opacity: 1,
+        scale: 1,
+        rotation: 0,
+        duration: 1.2,
+        ease: 'power4.out',
+    });
+}
+/**
+ * 3D Y-axis rotation card flip.
+ */
+export function cardFlip(target) {
+    return gsap.fromTo(target, { rotationY: 90, opacity: 0 }, {
+        rotationY: 0,
+        opacity: 1,
+        duration: 0.6,
+        ease: 'back.out(1.7)',
+        transformPerspective: 800,
+        transformOrigin: 'center center',
+    });
+}
+/**
+ * Magnetic hover effect — element follows cursor slightly.
+ */
+export function magneticHover(target, strength = 0.3) {
+    const onMove = (e) => {
+        const rect = target.getBoundingClientRect();
+        const x = e.clientX - rect.left - rect.width / 2;
+        const y = e.clientY - rect.top - rect.height / 2;
+        gsap.to(target, {
+            x: x * strength,
+            y: y * strength,
+            duration: 0.4,
+            ease: 'power2.out',
+        });
+    };
+    const onLeave = () => {
+        gsap.to(target, {
+            x: 0,
+            y: 0,
+            duration: 0.6,
+            ease: 'elastic.out(1, 0.3)',
+        });
+    };
+    target.addEventListener('mousemove', onMove);
+    target.addEventListener('mouseleave', onLeave);
+    return () => {
+        target.removeEventListener('mousemove', onMove);
+        target.removeEventListener('mouseleave', onLeave);
+    };
+}
+//# sourceMappingURL=animations.js.map

package/dist/animations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"animations.js","sourceRoot":"","sources":["../src/animations.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,YAAY,CAAC;AAEb,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAC5B,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,KAAK,MAAM,OAAO,CAAC;AAE1B,2CAA2C;AAC3C,IAAI,CAAC,cAAc,CAAC,aAAa,CAAC,CAAC;AAEnC,uEAAuE;AAEvE,IAAI,aAAa,GAAiB,IAAI,CAAC;AAEvC;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAA+D;IAC9F,IAAI,OAAO,MAAM,KAAK,WAAW;QAAE,OAAO,GAAG,EAAE,GAAE,CAAC,CAAC;IAEnD,MAAM,KAAK,GAAG,IAAI,KAAK,CAAC;QACtB,QAAQ,EAAE,OAAO,EAAE,QAAQ,IAAI,GAAG;QAClC,MAAM,EAAE,OAAO,EAAE,MAAM,IAAI,CAAC,CAAC,CAAS,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,GAAG,CAAC,IAAI,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC;QAC/E,WAAW,EAAE,IAAI;KAClB,CAAC,CAAC;IAEH,aAAa,GAAG,KAAK,CAAC;IAEtB,sCAAsC;IACtC,KAAK,CAAC,EAAE,CAAC,QAAQ,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAEzC,sDAAsD;IACtD,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE;QACvB,KAAK,CAAC,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC,CAAC;IACzB,CAAC,CAAC,CAAC;IACH,IAAI,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;IAE5B,OAAO,GAAG,EAAE;QACV,KAAK,CAAC,OAAO,EAAE,CAAC;QAChB,aAAa,GAAG,IAAI,CAAC;IACvB,CAAC,CAAC;AACJ,CAAC;AAED,uDAAuD;AACvD,MAAM,UAAU,QAAQ;IACtB,OAAO,aAAa,CAAC;AACvB,CAAC;AAED,uDAAuD;AACvD,MAAM,UAAU,QAAQ,CACtB,MAAqC,EACrC,OAAgD;IAEhD,aAAa,EAAE,QAAQ,CAAC,MAAM,EAAE;QAC9B,MAAM,EAAE,OAAO,EAAE,MAAM,IAAI,CAAC;QAC5B,QAAQ,EAAE,OAAO,EAAE,QAAQ,IAAI,GAAG;KACnC,CAAC,CAAC;AACL,CAAC;AAED,uEAAuE;AAEvE;;GAEG;AACH,MAAM,UAAU,QAAQ,CAAC,MAA4B,EAAE,KAAK,GAAG,CAAC;IAC9D,MAAM,IAAI,GAAmB;QAC3B,OAAO,EAAE,CAAC;QACV,CAAC,EAAE,CAAC;QACJ,QAAQ,EAAE,GAAG;QACb,KAAK;QACL,IAAI,EAAE,YAAY;KACnB,CAAC;IACF,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;QAC/B,IAAI,CAAC,aAAa,GAAG,MAAM,CAAC;IAC9B,CAAC;IACD,OAAO,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,EAAE,OAAO,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,IAAI,CAAC,CAAC;AAC1D,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,aAAa,CAAC,MAA4B,EAAE,OAAO,GAAG,GAAG;IACvE,OAAO,IAAI,CAAC,MAAM,CAChB,MAAM,EACN,EAAE,OAAO,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,EAClC;QACE,OAAO,EAAE,CAAC;QACV,CAAC,EAAE,CAAC;QACJ,KAAK,EAAE,CAAC;QACR,QAAQ,EAAE,GAAG;QACb,OAAO;QACP,IAAI,EAAE,YAAY;KACnB,CACF,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,aAAa,CAAC,MAA4B;IACxD,OAAO,IAAI,CAAC,MAAM,CAChB,MAAM,EACN,EAAE,OAAO,EAAE,CAAC,EAAE,KAAK,EAAE,GAAG,EAAE,QAAQ,EAAE,CAAC,CAAC,EAAE,EACxC;QACE,OAAO,EAAE,CAAC;QACV,KAAK,EAAE,CAAC;QACR,QAAQ,EAAE,CAAC;QACX,QAAQ,EAAE,GAAG;QACb,IAAI,EAAE,YAAY;KACnB,CACF,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,QAAQ,CAAC,MAA4B;IACnD,OAAO,IAAI,CAAC,MAAM,CAChB,MAAM,EACN,EAAE,SAAS,EAAE,EAAE,EAAE,OAAO,EAAE,CAAC,EAAE,EAC7B;QACE,SAAS,EAAE,CAAC;QACZ,OAAO,EAAE,CAAC;QACV,QAAQ,EAAE,GAAG;QACb,IAAI,EAAE,eAAe;QACrB,oBAAoB,EAAE,GAAG;QACzB,eAAe,EAAE,eAAe;KACjC,CACF,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,aAAa,CAAC,MAAmB,EAAE,QAAQ,GAAG,GAAG;IAC/D,MAAM,MAAM,GAAG,CAAC,CAAa,EAAE,EAAE;QAC/B,MAAM,IAAI,GAAG,MAAM,CAAC,qBAAqB,EAAE,CAAC;QAC5C,MAAM,CAAC,GAAG,CAAC,CAAC,OAAO,GAAG,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,KAAK,GAAG,CAAC,CAAC;QACjD,MAAM,CAAC,GAAG,CAAC,CAAC,OAAO,GAAG,IAAI,CAAC,GAAG,GAAG,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC;QACjD,IAAI,CAAC,EAAE,CAAC,MAAM,EAAE;YACd,CAAC,EAAE,CAAC,GAAG,QAAQ;YACf,CAAC,EAAE,CAAC,GAAG,QAAQ;YACf,QAAQ,EAAE,GAAG;YACb,IAAI,EAAE,YAAY;SACnB,CAAC,CAAC;IACL,CAAC,CAAC;IAEF,MAAM,OAAO,GAAG,GAAG,EAAE;QACnB,IAAI,CAAC,EAAE,CAAC,MAAM,EAAE;YACd,CAAC,EAAE,CAAC;YACJ,CAAC,EAAE,CAAC;YACJ,QAAQ,EAAE,GAAG;YACb,IAAI,EAAE,qBAAqB;SAC5B,CAAC,CAAC;IACL,CAAC,CAAC;IAEF,MAAM,CAAC,gBAAgB,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC;IAC7C,MAAM,CAAC,gBAAgB,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC;IAE/C,OAAO,GAAG,EAAE;QACV,MAAM,CAAC,mBAAmB,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC;QAChD,MAAM,CAAC,mBAAmB,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC;IACpD,CAAC,CAAC;AACJ,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,41 @@
+/**
+ * @substrate-platform/site — site shell primitives for Substrate-based Next.js sites.
+ *
+ * This package provides the minimal set of components, hooks, and
+ * utilities that every Substrate site needs. It does NOT include
+ * any application-specific features (newsletter, search, auth, etc.).
+ *
+ * ## Usage
+ *
+ * ```tsx
+ * // app/layout.tsx
+ * import {
+ *   SubstrateLayout,
+ *   SubstrateProviders,
+ *   SubstrateFooter,
+ *   createMetadata,
+ *   ThemeScript,
+ *   SmoothScroll,
+ *   PaintRegistrar,
+ * } from '@substrate-platform/site';
+ * import '@substrate-platform/site/globals.css';
+ * ```
+ *
+ * ## Dependency invariant
+ *
+ * `@substrate-platform/site` only depends on platform packages:
+ *   @substrate-platform/ui, @substrate-platform/contracts, @substrate-platform/config, @substrate-platform/observability
+ *
+ * It MUST NOT depend on any application package. Applications depend
+ * on `@substrate-platform/site`, never the reverse.
+ */
+export { cardFlip, fadeInUp, getLenis, initSmoothScroll, magneticHover, scaleEntrance, scrollTo, staggerReveal, } from './animations';
+export { type InstrumentationConfig, registerInstrumentation } from './instrumentation';
+export { type PoweredByConfig, SubstrateFooter, SubstrateLayout, type SubstrateLayoutProps, } from './layout';
+export { createMetadata } from './metadata';
+export { PaintRegistrar } from './paint-registrar';
+export { SubstrateProviders, type SubstrateProvidersProps } from './providers';
+export { type ErrorShellProps, SubstrateError, SubstrateGlobalError, SubstrateLoading, SubstrateNotFound, } from './shells';
+export { SmoothScroll } from './smooth-scroll';
+export { ThemeScript } from './theme-script';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAGH,OAAO,EACL,QAAQ,EACR,QAAQ,EACR,QAAQ,EACR,gBAAgB,EAChB,aAAa,EACb,aAAa,EACb,QAAQ,EACR,aAAa,GACd,MAAM,cAAc,CAAC;AAEtB,OAAO,EAAE,KAAK,qBAAqB,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAC;AAExF,OAAO,EACL,KAAK,eAAe,EACpB,eAAe,EACf,eAAe,EACf,KAAK,oBAAoB,GAC1B,MAAM,UAAU,CAAC;AAElB,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAEnD,OAAO,EAAE,kBAAkB,EAAE,KAAK,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAE/E,OAAO,EACL,KAAK,eAAe,EACpB,cAAc,EACd,oBAAoB,EACpB,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,UAAU,CAAC;AAElB,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAE/C,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/index.js

@@ -0,0 +1,49 @@
+/**
+ * @substrate-platform/site — site shell primitives for Substrate-based Next.js sites.
+ *
+ * This package provides the minimal set of components, hooks, and
+ * utilities that every Substrate site needs. It does NOT include
+ * any application-specific features (newsletter, search, auth, etc.).
+ *
+ * ## Usage
+ *
+ * ```tsx
+ * // app/layout.tsx
+ * import {
+ *   SubstrateLayout,
+ *   SubstrateProviders,
+ *   SubstrateFooter,
+ *   createMetadata,
+ *   ThemeScript,
+ *   SmoothScroll,
+ *   PaintRegistrar,
+ * } from '@substrate-platform/site';
+ * import '@substrate-platform/site/globals.css';
+ * ```
+ *
+ * ## Dependency invariant
+ *
+ * `@substrate-platform/site` only depends on platform packages:
+ *   @substrate-platform/ui, @substrate-platform/contracts, @substrate-platform/config, @substrate-platform/observability
+ *
+ * It MUST NOT depend on any application package. Applications depend
+ * on `@substrate-platform/site`, never the reverse.
+ */
+// ── Animation utilities ────────────────────────────────────────────
+export { cardFlip, fadeInUp, getLenis, initSmoothScroll, magneticHover, scaleEntrance, scrollTo, staggerReveal, } from './animations.js';
+// ── Instrumentation ────────────────────────────────────────────────
+export { registerInstrumentation } from './instrumentation.js';
+// ── Layout primitives ──────────────────────────────────────────────
+export { SubstrateFooter, SubstrateLayout, } from './layout.js';
+// ── Metadata helpers ───────────────────────────────────────────────
+export { createMetadata } from './metadata.js';
+export { PaintRegistrar } from './paint-registrar.js';
+// ── Providers ──────────────────────────────────────────────────────
+export { SubstrateProviders } from './providers.js';
+// ── Error / Loading / Not-Found shells ─────────────────────────────
+export { SubstrateError, SubstrateGlobalError, SubstrateLoading, SubstrateNotFound, } from './shells.js';
+// ── Side-effect components ─────────────────────────────────────────
+export { SmoothScroll } from './smooth-scroll.js';
+// ── Theme ──────────────────────────────────────────────────────────
+export { ThemeScript } from './theme-script.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,sEAAsE;AACtE,OAAO,EACL,QAAQ,EACR,QAAQ,EACR,QAAQ,EACR,gBAAgB,EAChB,aAAa,EACb,aAAa,EACb,QAAQ,EACR,aAAa,GACd,MAAM,cAAc,CAAC;AACtB,sEAAsE;AACtE,OAAO,EAA8B,uBAAuB,EAAE,MAAM,mBAAmB,CAAC;AACxF,sEAAsE;AACtE,OAAO,EAEL,eAAe,EACf,eAAe,GAEhB,MAAM,UAAU,CAAC;AAClB,sEAAsE;AACtE,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACnD,sEAAsE;AACtE,OAAO,EAAE,kBAAkB,EAAgC,MAAM,aAAa,CAAC;AAC/E,sEAAsE;AACtE,OAAO,EAEL,cAAc,EACd,oBAAoB,EACpB,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,UAAU,CAAC;AAClB,sEAAsE;AACtE,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC/C,sEAAsE;AACtE,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/instrumentation.d.ts

@@ -0,0 +1,46 @@
+/**
+ * registerInstrumentation — Next.js instrumentation hook factory.
+ *
+ * The application calls this from its `instrumentation.ts`:
+ *
+ * ```ts
+ * // instrumentation.ts
+ * import { registerInstrumentation } from '@substrate-platform/site/instrumentation';
+ *
+ * export const register = registerInstrumentation({
+ *   featurePreset: 'reference',
+ *   serviceName: 'my-site',
+ * });
+ * ```
+ *
+ * The factory handles:
+ *   1. Feature manifest initialization from a preset name.
+ *   2. OpenTelemetry SDK startup (if endpoint is configured).
+ *   3. Env validation warnings for enabled features.
+ *
+ * The platform does NOT hardcode any application name, service name,
+ * or feature preset.
+ */
+import type { FeatureManifest } from '@substrate-platform/config/features';
+export type InstrumentationConfig = {
+    /**
+     * Feature preset name. Maps to presets in @substrate-platform/config.
+     * If omitted, defaults to 'minimal' in production, 'full' otherwise.
+     */
+    featurePreset?: 'minimal' | 'graphics' | 'ai-archive' | 'realtime' | 'reference';
+    /**
+     * OTEL service name. Defaults to 'substrate'.
+     * Applications should override with their own name.
+     */
+    serviceName?: string;
+    /**
+     * OTEL trace sample rate. Defaults to 0.1.
+     */
+    traceSampleRate?: number;
+    /**
+     * Custom feature manifest. If provided, overrides `featurePreset`.
+     */
+    featureManifest?: FeatureManifest;
+};
+export declare function registerInstrumentation(config?: InstrumentationConfig): () => Promise<void>;
+//# sourceMappingURL=instrumentation.d.ts.map

package/dist/instrumentation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"instrumentation.d.ts","sourceRoot":"","sources":["../src/instrumentation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qCAAqC,CAAC;AAE3E,MAAM,MAAM,qBAAqB,GAAG;IAClC;;;OAGG;IACH,aAAa,CAAC,EAAE,SAAS,GAAG,UAAU,GAAG,YAAY,GAAG,UAAU,GAAG,WAAW,CAAC;IACjF;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;OAEG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;OAEG;IACH,eAAe,CAAC,EAAE,eAAe,CAAC;CACnC,CAAC;AAEF,wBAAgB,uBAAuB,CAAC,MAAM,CAAC,EAAE,qBAAqB,SAClC,OAAO,CAAC,IAAI,CAAC,CA6DhD"}

package/dist/instrumentation.js

@@ -0,0 +1,48 @@
+export function registerInstrumentation(config) {
+    return async function register() {
+        const { initFeatures, minimalSiteFeatures, graphicsLabFeatures, aiArchiveFeatures, realtimeRoomFeatures, referenceFeatures, validateEnv, } = await import('@substrate-platform/config/features');
+        // Determine the feature manifest.
+        const isProduction = process.env.NODE_ENV === 'production';
+        const profile = config?.featurePreset ?? (isProduction ? 'minimal' : 'reference');
+        const presets = {
+            minimal: minimalSiteFeatures,
+            graphics: graphicsLabFeatures,
+            'ai-archive': aiArchiveFeatures,
+            realtime: realtimeRoomFeatures,
+            reference: referenceFeatures,
+        };
+        const manifest = config?.featureManifest ?? presets[profile] ?? minimalSiteFeatures;
+        initFeatures(manifest);
+        // Warn about missing env vars for enabled features.
+        const missing = validateEnv(manifest);
+        if (missing.length > 0) {
+            console.warn(`[features] Missing env vars: ${missing.join(', ')}`);
+        }
+        // Start OpenTelemetry if on Node.js runtime and endpoint is configured.
+        if (process.env.NEXT_RUNTIME === 'nodejs') {
+            const endpoint = process.env.OTEL_EXPORTER_OTLP_ENDPOINT;
+            if (!endpoint) {
+                console.warn('[OTel] OTEL_EXPORTER_OTLP_ENDPOINT not set — skipping SDK init');
+                return;
+            }
+            const { startOTEL } = await import('@substrate-platform/observability');
+            // Parse headers from "key1=val1,key2=val2" format.
+            const headers = {};
+            const rawHeaders = process.env.OTEL_EXPORTER_OTLP_HEADERS;
+            if (rawHeaders) {
+                for (const pair of rawHeaders.split(',')) {
+                    const [k, v] = pair.split('=').map((s) => s.trim());
+                    if (k && v)
+                        headers[k] = v;
+                }
+            }
+            await startOTEL({
+                endpoint,
+                headers,
+                serviceName: config?.serviceName ?? process.env.OTEL_SERVICE_NAME ?? 'substrate',
+                traceSampleRate: config?.traceSampleRate ?? Number(process.env.OTEL_TRACES_SAMPLE_RATE ?? 0.1),
+            });
+        }
+    };
+}
+//# sourceMappingURL=instrumentation.js.map

package/dist/instrumentation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"instrumentation.js","sourceRoot":"","sources":["../src/instrumentation.ts"],"names":[],"mappings":"AA8CA,MAAM,UAAU,uBAAuB,CAAC,MAA8B;IACpE,OAAO,KAAK,UAAU,QAAQ;QAC5B,MAAM,EACJ,YAAY,EACZ,mBAAmB,EACnB,mBAAmB,EACnB,iBAAiB,EACjB,oBAAoB,EACpB,iBAAiB,EACjB,WAAW,GACZ,GAAG,MAAM,MAAM,CAAC,qCAAqC,CAAC,CAAC;QAExD,kCAAkC;QAClC,MAAM,YAAY,GAAG,OAAO,CAAC,GAAG,CAAC,QAAQ,KAAK,YAAY,CAAC;QAC3D,MAAM,OAAO,GAAG,MAAM,EAAE,aAAa,IAAI,CAAC,YAAY,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC;QAElF,MAAM,OAAO,GAAG;YACd,OAAO,EAAE,mBAAmB;YAC5B,QAAQ,EAAE,mBAAmB;YAC7B,YAAY,EAAE,iBAAiB;YAC/B,QAAQ,EAAE,oBAAoB;YAC9B,SAAS,EAAE,iBAAiB;SAC7B,CAAC;QAEF,MAAM,QAAQ,GAAG,MAAM,EAAE,eAAe,IAAI,OAAO,CAAC,OAAO,CAAC,IAAI,mBAAmB,CAAC;QACpF,YAAY,CAAC,QAAQ,CAAC,CAAC;QAEvB,oDAAoD;QACpD,MAAM,OAAO,GAAG,WAAW,CAAC,QAAQ,CAAC,CAAC;QACtC,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACvB,OAAO,CAAC,IAAI,CAAC,gCAAgC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACrE,CAAC;QAED,wEAAwE;QACxE,IAAI,OAAO,CAAC,GAAG,CAAC,YAAY,KAAK,QAAQ,EAAE,CAAC;YAC1C,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,2BAA2B,CAAC;YACzD,IAAI,CAAC,QAAQ,EAAE,CAAC;gBACd,OAAO,CAAC,IAAI,CAAC,gEAAgE,CAAC,CAAC;gBAC/E,OAAO;YACT,CAAC;YAED,MAAM,EAAE,SAAS,EAAE,GAAG,MAAM,MAAM,CAAC,mCAAmC,CAAC,CAAC;YAExE,mDAAmD;YACnD,MAAM,OAAO,GAA2B,EAAE,CAAC;YAC3C,MAAM,UAAU,GAAG,OAAO,CAAC,GAAG,CAAC,0BAA0B,CAAC;YAC1D,IAAI,UAAU,EAAE,CAAC;gBACf,KAAK,MAAM,IAAI,IAAI,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;oBACzC,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;oBACpD,IAAI,CAAC,IAAI,CAAC;wBAAE,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;gBAC7B,CAAC;YACH,CAAC;YAED,MAAM,SAAS,CAAC;gBACd,QAAQ;gBACR,OAAO;gBACP,WAAW,EAAE,MAAM,EAAE,WAAW,IAAI,OAAO,CAAC,GAAG,CAAC,iBAAiB,IAAI,WAAW;gBAChF,eAAe,EACb,MAAM,EAAE,eAAe,IAAI,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,uBAAuB,IAAI,GAAG,CAAC;aAChF,CAAC,CAAC;QACL,CAAC;IACH,CAAC,CAAC;AACJ,CAAC"}

package/dist/layout.d.ts

@@ -0,0 +1,75 @@
+/**
+ * SubstrateLayout — minimal root layout shell for a Next.js site.
+ *
+ * Wraps children in the standard HTML structure with font variables,
+ * dark theme default, and an optional "Powered by Substrate" footer.
+ *
+ * The attribution is **on by default** and can be disabled via
+ * `poweredBy: { enabled: false }`. The label and link are **not
+ * configurable** — when shown, the attribution always reads
+ * "Powered by Substrate" and always links to the official repository.
+ *
+ * ```tsx
+ * // Default — shows "Powered by Substrate" → official GitHub.
+ * <SubstrateLayout fontClass={fontVar}>{children}</SubstrateLayout>
+ *
+ * // Disable.
+ * <SubstrateLayout poweredBy={{ enabled: false }}>
+ * ```
+ *
+ * The footer is a platform brand default, not a licence requirement.
+ * Consumers are free to disable it under Apache-2.0.
+ */
+import type { ReactNode } from 'react';
+/**
+ * Configuration for the "Powered by Substrate" attribution.
+ *
+ * `enabled` is the **only** option. The label and link URL are
+ * platform constants — they cannot be overridden by consumers.
+ * This ensures the attribution always serves its purpose as an
+ * ecosystem entry point to the official Substrate project.
+ */
+export type PoweredByConfig = {
+    /** Show the attribution? Defaults to `true`. */
+    enabled?: boolean;
+};
+export type SubstrateLayoutProps = {
+    children: ReactNode;
+    /** CSS class containing font CSS variables (e.g. GeistSans.variable). */
+    fontClass?: string;
+    /** Language attribute. Defaults to 'en'. */
+    lang?: string;
+    /** Additional className for <html>. Defaults to 'dark'. */
+    htmlClassName?: string;
+    /**
+     * Render the SubstrateFooter? Defaults to `true`.
+     *
+     * Legacy shorthand for `poweredBy: { enabled: true }`.
+     */
+    footer?: boolean;
+    /** Configure the "Powered by Substrate" attribution. */
+    poweredBy?: PoweredByConfig;
+};
+export declare function SubstrateLayout({ children, fontClass, lang, htmlClassName, footer, poweredBy, }: SubstrateLayoutProps): import("react").JSX.Element;
+/**
+ * SubstrateFooter — renders the "Powered by Substrate" attribution.
+ *
+ * **On by default.** This is a platform brand default, not a licence
+ * requirement. Under Apache-2.0, consumers are free to disable it:
+ *
+ * ```tsx
+ * // Disable
+ * <SubstrateFooter enabled={false} />
+ *
+ * // Or via layout
+ * <SubstrateLayout poweredBy={{ enabled: false }}>
+ * ```
+ *
+ * The label is always "Powered by Substrate" and the link always
+ * points to the official Substrate repository. Neither is
+ * configurable — see `PoweredByConfig`.
+ */
+export declare function SubstrateFooter({ enabled }?: {
+    enabled?: boolean;
+}): import("react").JSX.Element | null;
+//# sourceMappingURL=layout.d.ts.map

package/dist/layout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"layout.d.ts","sourceRoot":"","sources":["../src/layout.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAIvC;;;;;;;GAOG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,gDAAgD;IAChD,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,QAAQ,EAAE,SAAS,CAAC;IACpB,yEAAyE;IACzE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,4CAA4C;IAC5C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,2DAA2D;IAC3D,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,wDAAwD;IACxD,SAAS,CAAC,EAAE,eAAe,CAAC;CAC7B,CAAC;AAeF,wBAAgB,eAAe,CAAC,EAC9B,QAAQ,EACR,SAAc,EACd,IAAW,EACX,aAAsB,EACtB,MAAa,EACb,SAAS,GACV,EAAE,oBAAoB,+BAYtB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,eAAe,CAAC,EAAE,OAAc,EAAE,GAAE;IAAE,OAAO,CAAC,EAAE,OAAO,CAAA;CAAO,sCAqB7E"}

package/dist/layout.js

@@ -0,0 +1,40 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// ── Constants ───────────────────────────────────────────────────────
+/**
+ * The official Substrate repository URL.
+ *
+ * This is a platform constant. It is not exported and cannot be
+ * overridden by consumers. When the "Powered by Substrate"
+ * attribution is shown, it always links here.
+ */
+const SUBSTRATE_REPOSITORY = 'https://github.com/Juwan-Hwang/substrate';
+// ── Components ──────────────────────────────────────────────────────
+export function SubstrateLayout({ children, fontClass = '', lang = 'en', htmlClassName = 'dark', footer = true, poweredBy, }) {
+    // `poweredBy` takes precedence over legacy `footer` prop.
+    const enabled = poweredBy?.enabled ?? footer;
+    return (_jsx("html", { lang: lang, className: `${htmlClassName} ${fontClass}`.trim(), suppressHydrationWarning: true, children: _jsxs("body", { children: [children, _jsx(SubstrateFooter, { enabled: enabled })] }) }));
+}
+/**
+ * SubstrateFooter — renders the "Powered by Substrate" attribution.
+ *
+ * **On by default.** This is a platform brand default, not a licence
+ * requirement. Under Apache-2.0, consumers are free to disable it:
+ *
+ * ```tsx
+ * // Disable
+ * <SubstrateFooter enabled={false} />
+ *
+ * // Or via layout
+ * <SubstrateLayout poweredBy={{ enabled: false }}>
+ * ```
+ *
+ * The label is always "Powered by Substrate" and the link always
+ * points to the official Substrate repository. Neither is
+ * configurable — see `PoweredByConfig`.
+ */
+export function SubstrateFooter({ enabled = true } = {}) {
+    if (!enabled)
+        return null;
+    return (_jsx("footer", { className: "mx-auto max-w-5xl px-6 pb-4 pt-4 text-center", children: _jsxs("p", { className: "text-[0.6875rem]", style: { color: 'var(--substrate-text-tertiary)', opacity: 0.35 }, children: ["Powered by", ' ', _jsx("a", { href: SUBSTRATE_REPOSITORY, target: "_blank", rel: "noopener noreferrer", className: "underline transition-opacity hover:opacity-80", children: "Substrate" })] }) }));
+}
+//# sourceMappingURL=layout.js.map

package/dist/layout.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"layout.js","sourceRoot":"","sources":["../src/layout.tsx"],"names":[],"mappings":";AAyDA,uEAAuE;AAEvE;;;;;;GAMG;AACH,MAAM,oBAAoB,GAAG,0CAA0C,CAAC;AAExE,uEAAuE;AAEvE,MAAM,UAAU,eAAe,CAAC,EAC9B,QAAQ,EACR,SAAS,GAAG,EAAE,EACd,IAAI,GAAG,IAAI,EACX,aAAa,GAAG,MAAM,EACtB,MAAM,GAAG,IAAI,EACb,SAAS,GACY;IACrB,0DAA0D;IAC1D,MAAM,OAAO,GAAG,SAAS,EAAE,OAAO,IAAI,MAAM,CAAC;IAE7C,OAAO,CACL,eAAM,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,GAAG,aAAa,IAAI,SAAS,EAAE,CAAC,IAAI,EAAE,EAAE,wBAAwB,kBAC3F,2BACG,QAAQ,EACT,KAAC,eAAe,IAAC,OAAO,EAAE,OAAO,GAAI,IAChC,GACF,CACR,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,eAAe,CAAC,EAAE,OAAO,GAAG,IAAI,EAAE,GAA0B,EAAE;IAC5E,IAAI,CAAC,OAAO;QAAE,OAAO,IAAI,CAAC;IAE1B,OAAO,CACL,iBAAQ,SAAS,EAAC,8CAA8C,YAC9D,aACE,SAAS,EAAC,kBAAkB,EAC5B,KAAK,EAAE,EAAE,KAAK,EAAE,gCAAgC,EAAE,OAAO,EAAE,IAAI,EAAE,2BAEtD,GAAG,EACd,YACE,IAAI,EAAE,oBAAoB,EAC1B,MAAM,EAAC,QAAQ,EACf,GAAG,EAAC,qBAAqB,EACzB,SAAS,EAAC,+CAA+C,0BAGvD,IACF,GACG,CACV,CAAC;AACJ,CAAC"}

package/dist/metadata.d.ts

@@ -0,0 +1,21 @@
+/**
+ * createMetadata — generates Next.js Metadata from a SiteIdentity.
+ *
+ * The application calls this with its own identity:
+ *
+ * ```ts
+ * import { createMetadata } from '@substrate-platform/site/metadata';
+ *
+ * export const metadata = createMetadata({
+ *   name: 'My Site',
+ *   url: 'https://example.com',
+ * });
+ * ```
+ *
+ * The returned Metadata uses the site name as the default title and
+ * creates a `%s — Site Name` template for per-page titles.
+ */
+import type { SiteIdentity } from '@substrate-platform/contracts';
+import type { Metadata } from 'next';
+export declare function createMetadata(identity: SiteIdentity): Metadata;
+//# sourceMappingURL=metadata.d.ts.map

package/dist/metadata.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metadata.d.ts","sourceRoot":"","sources":["../src/metadata.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAClE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,MAAM,CAAC;AAErC,wBAAgB,cAAc,CAAC,QAAQ,EAAE,YAAY,GAAG,QAAQ,CAY/D"}

package/dist/metadata.js

@@ -0,0 +1,31 @@
+/**
+ * createMetadata — generates Next.js Metadata from a SiteIdentity.
+ *
+ * The application calls this with its own identity:
+ *
+ * ```ts
+ * import { createMetadata } from '@substrate-platform/site/metadata';
+ *
+ * export const metadata = createMetadata({
+ *   name: 'My Site',
+ *   url: 'https://example.com',
+ * });
+ * ```
+ *
+ * The returned Metadata uses the site name as the default title and
+ * creates a `%s — Site Name` template for per-page titles.
+ */
+export function createMetadata(identity) {
+    return {
+        title: {
+            default: identity.name,
+            template: `%s — ${identity.name}`,
+        },
+        metadataBase: new URL(identity.url),
+        openGraph: {
+            title: identity.name,
+            type: 'website',
+        },
+    };
+}
+//# sourceMappingURL=metadata.js.map

package/dist/metadata.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metadata.js","sourceRoot":"","sources":["../src/metadata.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAKH,MAAM,UAAU,cAAc,CAAC,QAAsB;IACnD,OAAO;QACL,KAAK,EAAE;YACL,OAAO,EAAE,QAAQ,CAAC,IAAI;YACtB,QAAQ,EAAE,QAAQ,QAAQ,CAAC,IAAI,EAAE;SAClC;QACD,YAAY,EAAE,IAAI,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC;QACnC,SAAS,EAAE;YACT,KAAK,EAAE,QAAQ,CAAC,IAAI;YACpB,IAAI,EAAE,SAAS;SAChB;KACF,CAAC;AACJ,CAAC"}

package/dist/paint-registrar.d.ts

@@ -0,0 +1,2 @@
+export declare function PaintRegistrar(): null;
+//# sourceMappingURL=paint-registrar.d.ts.map

package/dist/paint-registrar.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paint-registrar.d.ts","sourceRoot":"","sources":["../src/paint-registrar.tsx"],"names":[],"mappings":"AASA,wBAAgB,cAAc,SAM7B"}

package/dist/paint-registrar.js

@@ -0,0 +1,14 @@
+/**
+ * Registers Houdini Paint Worklets on mount.
+ * Renders nothing — it's a side-effect-only component.
+ */
+'use client';
+import { registerPaintWorklets } from '@substrate-platform/ui';
+import { useEffect } from 'react';
+export function PaintRegistrar() {
+    useEffect(() => {
+        registerPaintWorklets();
+    }, []);
+    return null;
+}
+//# sourceMappingURL=paint-registrar.js.map

package/dist/paint-registrar.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paint-registrar.js","sourceRoot":"","sources":["../src/paint-registrar.tsx"],"names":[],"mappings":"AAAA;;;GAGG;AACH,YAAY,CAAC;AAEb,OAAO,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAC/D,OAAO,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAElC,MAAM,UAAU,cAAc;IAC5B,SAAS,CAAC,GAAG,EAAE;QACb,qBAAqB,EAAE,CAAC;IAC1B,CAAC,EAAE,EAAE,CAAC,CAAC;IAEP,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/providers.d.ts

@@ -0,0 +1,18 @@
+import { type QueryClient } from '@tanstack/react-query';
+import type { ComponentType, ReactNode } from 'react';
+export type SubstrateProvidersProps = {
+    children: ReactNode;
+    queryClient: QueryClient;
+    /**
+     * Optional outer provider component (e.g. `trpc.Provider`).
+     * Receives `outerProps` plus `children`.
+     * Omit for static sites that only need React Query.
+     */
+    outerProvider?: ComponentType<Record<string, unknown> & {
+        children: ReactNode;
+    }>;
+    /** Props to pass to `outerProvider` (excluding children). */
+    outerProps?: Record<string, unknown>;
+};
+export declare function SubstrateProviders({ children, queryClient, outerProvider, outerProps, }: SubstrateProvidersProps): import("react").JSX.Element;
+//# sourceMappingURL=providers.d.ts.map

package/dist/providers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"providers.d.ts","sourceRoot":"","sources":["../src/providers.tsx"],"names":[],"mappings":"AAgCA,OAAO,EAAE,KAAK,WAAW,EAAuB,MAAM,uBAAuB,CAAC;AAC9E,OAAO,KAAK,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAEtD,MAAM,MAAM,uBAAuB,GAAG;IACpC,QAAQ,EAAE,SAAS,CAAC;IACpB,WAAW,EAAE,WAAW,CAAC;IACzB;;;;OAIG;IACH,aAAa,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG;QAAE,QAAQ,EAAE,SAAS,CAAA;KAAE,CAAC,CAAC;IACjF,6DAA6D;IAC7D,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACtC,CAAC;AAEF,wBAAgB,kBAAkB,CAAC,EACjC,QAAQ,EACR,WAAW,EACX,aAAa,EACb,UAAU,GACX,EAAE,uBAAuB,+BASzB"}

package/dist/providers.js

@@ -0,0 +1,42 @@
+/**
+ * SubstrateProviders — React Query provider wrapper with optional outer provider.
+ *
+ * The platform provides the shell; the application provides the
+ * configured providers. This keeps the platform free of any knowledge
+ * about API endpoints, auth, or transport.
+ *
+ * ## With tRPC
+ *
+ * ```tsx
+ * import { SubstrateProviders } from '@substrate-platform/site/providers';
+ * import { trpc, getTrpcLink, createQueryClient } from './lib/trpc.js';
+ *
+ * <SubstrateProviders
+ *   queryClient={queryClient}
+ *   outerProvider={trpc.Provider}
+ *   outerProps={{ client: trpcClient }}
+ * >
+ *   {children}
+ * </SubstrateProviders>
+ * ```
+ *
+ * ## Without tRPC (static site)
+ *
+ * ```tsx
+ * <SubstrateProviders queryClient={queryClient}>
+ *   {children}
+ * </SubstrateProviders>
+ * ```
+ */
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+import { QueryClientProvider } from '@tanstack/react-query';
+export function SubstrateProviders({ children, queryClient, outerProvider, outerProps, }) {
+    const inner = _jsx(QueryClientProvider, { client: queryClient, children: children });
+    if (outerProvider) {
+        const Outer = outerProvider;
+        return _jsx(Outer, { ...(outerProps ?? {}), children: inner });
+    }
+    return inner;
+}
+//# sourceMappingURL=providers.js.map

package/dist/providers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"providers.js","sourceRoot":"","sources":["../src/providers.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,YAAY,CAAC;;AAEb,OAAO,EAAoB,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAgB9E,MAAM,UAAU,kBAAkB,CAAC,EACjC,QAAQ,EACR,WAAW,EACX,aAAa,EACb,UAAU,GACc;IACxB,MAAM,KAAK,GAAG,KAAC,mBAAmB,IAAC,MAAM,EAAE,WAAW,YAAG,QAAQ,GAAuB,CAAC;IAEzF,IAAI,aAAa,EAAE,CAAC;QAClB,MAAM,KAAK,GAAG,aAAa,CAAC;QAC5B,OAAO,KAAC,KAAK,OAAK,CAAC,UAAU,IAAI,EAAE,CAAC,YAAG,KAAK,GAAS,CAAC;IACxD,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/shells.d.ts

@@ -0,0 +1,12 @@
+import { type ReactElement } from 'react';
+export type ErrorShellProps = {
+    error: Error & {
+        digest?: string;
+    };
+    reset: () => void;
+};
+export declare function SubstrateError({ error, reset }: ErrorShellProps): ReactElement;
+export declare function SubstrateGlobalError({ error, reset }: ErrorShellProps): ReactElement;
+export declare function SubstrateLoading(): ReactElement;
+export declare function SubstrateNotFound(): ReactElement;
+//# sourceMappingURL=shells.d.ts.map

package/dist/shells.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shells.d.ts","sourceRoot":"","sources":["../src/shells.tsx"],"names":[],"mappings":"AAcA,OAAO,EAAE,KAAK,YAAY,EAAa,MAAM,OAAO,CAAC;AAIrD,MAAM,MAAM,eAAe,GAAG;IAC5B,KAAK,EAAE,KAAK,GAAG;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACnC,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB,CAAC;AAIF,wBAAgB,cAAc,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,eAAe,GAAG,YAAY,CAqB9E;AAID,wBAAgB,oBAAoB,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,eAAe,GAAG,YAAY,CAyBpF;AAID,wBAAgB,gBAAgB,IAAI,YAAY,CAmB/C;AAID,wBAAgB,iBAAiB,IAAI,YAAY,CAehD"}

package/dist/shells.js

@@ -0,0 +1,38 @@
+/**
+ * Error / Loading / Not-Found shells — generic, application-agnostic
+ * UI for Next.js convention files.
+ *
+ * Applications re-export these from their `app/error.tsx`,
+ * `app/global-error.tsx`, `app/loading.tsx`, and `app/not-found.tsx`.
+ *
+ * ```tsx
+ * // app/error.tsx
+ * export { SubstrateError as default } from '@substrate-platform/site/shells';
+ * ```
+ */
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect } from 'react';
+// ── Error boundary ──────────────────────────────────────────────────
+export function SubstrateError({ error, reset }) {
+    useEffect(() => {
+        console.error('[Route Error]', error);
+    }, [error]);
+    return (_jsx("div", { className: "mx-auto flex min-h-screen max-w-2xl flex-col items-center justify-center px-6", children: _jsxs("div", { className: "substrate-glass-card p-8 text-center", children: [_jsx("h2", { className: "text-2xl font-semibold text-text-primary", children: "Something went wrong" }), _jsx("p", { className: "mt-3 text-sm text-text-secondary", children: error.message || 'An unexpected error occurred while rendering this page.' }), error.digest && (_jsxs("p", { className: "mt-2 font-mono text-xs text-text-tertiary", children: ["Error ID: ", error.digest] })), _jsx("button", { type: "button", className: "btn btn-accent mt-6", onClick: reset, children: "Try again" })] }) }));
+}
+// ── Global error boundary ───────────────────────────────────────────
+export function SubstrateGlobalError({ error, reset }) {
+    useEffect(() => {
+        console.error('[Global Error]', error);
+    }, [error]);
+    return (_jsx("html", { lang: "en", children: _jsx("body", { children: _jsx("div", { className: "mx-auto flex min-h-screen max-w-2xl flex-col items-center justify-center px-6", children: _jsxs("div", { className: "substrate-glass-card p-8 text-center", children: [_jsx("h2", { className: "text-2xl font-semibold text-text-primary", children: "Application error" }), _jsx("p", { className: "mt-3 text-sm text-text-secondary", children: error.message || 'A critical error occurred while rendering this page.' }), error.digest && (_jsxs("p", { className: "mt-2 font-mono text-xs text-text-tertiary", children: ["Error ID: ", error.digest] })), _jsx("button", { type: "button", className: "btn btn-accent mt-6", onClick: reset, children: "Try again" })] }) }) }) }));
+}
+// ── Loading shell ───────────────────────────────────────────────────
+export function SubstrateLoading() {
+    return (_jsx("div", { className: "mx-auto min-h-screen max-w-5xl px-6 py-24", "aria-busy": "true", children: _jsxs("div", { className: "animate-pulse", children: [_jsxs("div", { className: "mb-20", children: [_jsx("div", { className: "h-12 w-32 rounded-lg bg-text-primary/10" }), _jsx("div", { className: "mt-4 h-6 w-80 rounded-lg bg-text-primary/5" })] }), _jsx("div", { className: "grid gap-6 sm:grid-cols-3", children: [0, 1, 2].map((i) => (_jsxs("div", { className: "substrate-glass-card h-32 p-6", children: [_jsx("div", { className: "h-5 w-24 rounded bg-text-primary/10" }), _jsx("div", { className: "mt-3 h-4 w-40 rounded bg-text-primary/5" })] }, i))) })] }) }));
+}
+// ── Not-found shell ─────────────────────────────────────────────────
+export function SubstrateNotFound() {
+    return (_jsx("main", { className: "mx-auto flex min-h-screen max-w-2xl flex-col items-center justify-center px-6", children: _jsxs("div", { className: "substrate-glass-card p-8 text-center", children: [_jsx("p", { className: "font-mono text-sm text-text-tertiary", children: "404" }), _jsx("h1", { className: "mt-2 text-3xl font-semibold text-text-primary", children: "Page not found" }), _jsx("p", { className: "mt-3 text-sm text-text-secondary", children: "The page you're looking for doesn't exist or has been moved." }), _jsx("a", { href: "/", className: "btn btn-accent mt-6 inline-block", children: "Back to home" })] }) }));
+}
+//# sourceMappingURL=shells.js.map

package/dist/shells.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shells.js","sourceRoot":"","sources":["../src/shells.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,YAAY,CAAC;;AAEb,OAAO,EAAqB,SAAS,EAAE,MAAM,OAAO,CAAC;AASrD,uEAAuE;AAEvE,MAAM,UAAU,cAAc,CAAC,EAAE,KAAK,EAAE,KAAK,EAAmB;IAC9D,SAAS,CAAC,GAAG,EAAE;QACb,OAAO,CAAC,KAAK,CAAC,eAAe,EAAE,KAAK,CAAC,CAAC;IACxC,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC;IAEZ,OAAO,CACL,cAAK,SAAS,EAAC,+EAA+E,YAC5F,eAAK,SAAS,EAAC,sCAAsC,aACnD,aAAI,SAAS,EAAC,0CAA0C,qCAA0B,EAClF,YAAG,SAAS,EAAC,kCAAkC,YAC5C,KAAK,CAAC,OAAO,IAAI,yDAAyD,GACzE,EACH,KAAK,CAAC,MAAM,IAAI,CACf,aAAG,SAAS,EAAC,2CAA2C,2BAAY,KAAK,CAAC,MAAM,IAAK,CACtF,EACD,iBAAQ,IAAI,EAAC,QAAQ,EAAC,SAAS,EAAC,qBAAqB,EAAC,OAAO,EAAE,KAAK,0BAE3D,IACL,GACF,CACP,CAAC;AACJ,CAAC;AAED,uEAAuE;AAEvE,MAAM,UAAU,oBAAoB,CAAC,EAAE,KAAK,EAAE,KAAK,EAAmB;IACpE,SAAS,CAAC,GAAG,EAAE;QACb,OAAO,CAAC,KAAK,CAAC,gBAAgB,EAAE,KAAK,CAAC,CAAC;IACzC,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC;IAEZ,OAAO,CACL,eAAM,IAAI,EAAC,IAAI,YACb,yBACE,cAAK,SAAS,EAAC,+EAA+E,YAC5F,eAAK,SAAS,EAAC,sCAAsC,aACnD,aAAI,SAAS,EAAC,0CAA0C,kCAAuB,EAC/E,YAAG,SAAS,EAAC,kCAAkC,YAC5C,KAAK,CAAC,OAAO,IAAI,sDAAsD,GACtE,EACH,KAAK,CAAC,MAAM,IAAI,CACf,aAAG,SAAS,EAAC,2CAA2C,2BAAY,KAAK,CAAC,MAAM,IAAK,CACtF,EACD,iBAAQ,IAAI,EAAC,QAAQ,EAAC,SAAS,EAAC,qBAAqB,EAAC,OAAO,EAAE,KAAK,0BAE3D,IACL,GACF,GACD,GACF,CACR,CAAC;AACJ,CAAC;AAED,uEAAuE;AAEvE,MAAM,UAAU,gBAAgB;IAC9B,OAAO,CACL,cAAK,SAAS,EAAC,2CAA2C,eAAW,MAAM,YACzE,eAAK,SAAS,EAAC,eAAe,aAC5B,eAAK,SAAS,EAAC,OAAO,aACpB,cAAK,SAAS,EAAC,yCAAyC,GAAG,EAC3D,cAAK,SAAS,EAAC,4CAA4C,GAAG,IAC1D,EACN,cAAK,SAAS,EAAC,2BAA2B,YACvC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CACpB,eAAa,SAAS,EAAC,+BAA+B,aACpD,cAAK,SAAS,EAAC,qCAAqC,GAAG,EACvD,cAAK,SAAS,EAAC,yCAAyC,GAAG,KAFnD,CAAC,CAGL,CACP,CAAC,GACE,IACF,GACF,CACP,CAAC;AACJ,CAAC;AAED,uEAAuE;AAEvE,MAAM,UAAU,iBAAiB;IAC/B,OAAO,CACL,eAAM,SAAS,EAAC,+EAA+E,YAC7F,eAAK,SAAS,EAAC,sCAAsC,aACnD,YAAG,SAAS,EAAC,sCAAsC,oBAAQ,EAC3D,aAAI,SAAS,EAAC,+CAA+C,+BAAoB,EACjF,YAAG,SAAS,EAAC,kCAAkC,6EAE3C,EACJ,YAAG,IAAI,EAAC,GAAG,EAAC,SAAS,EAAC,kCAAkC,6BAEpD,IACA,GACD,CACR,CAAC;AACJ,CAAC"}

package/dist/smooth-scroll.d.ts

@@ -0,0 +1,2 @@
+export declare function SmoothScroll(): null;
+//# sourceMappingURL=smooth-scroll.d.ts.map

package/dist/smooth-scroll.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"smooth-scroll.d.ts","sourceRoot":"","sources":["../src/smooth-scroll.tsx"],"names":[],"mappings":"AASA,wBAAgB,YAAY,SAO3B"}

package/dist/smooth-scroll.js

@@ -0,0 +1,15 @@
+/**
+ * SmoothScroll — initializes Lenis smooth scrolling on mount.
+ * Renders nothing — it's a side-effect-only component.
+ */
+'use client';
+import { useEffect } from 'react';
+import { initSmoothScroll } from './animations.js';
+export function SmoothScroll() {
+    useEffect(() => {
+        const cleanup = initSmoothScroll();
+        return cleanup;
+    }, []);
+    return null;
+}
+//# sourceMappingURL=smooth-scroll.js.map

package/dist/smooth-scroll.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"smooth-scroll.js","sourceRoot":"","sources":["../src/smooth-scroll.tsx"],"names":[],"mappings":"AAAA;;;GAGG;AACH,YAAY,CAAC;AAEb,OAAO,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAClC,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAEhD,MAAM,UAAU,YAAY;IAC1B,SAAS,CAAC,GAAG,EAAE;QACb,MAAM,OAAO,GAAG,gBAAgB,EAAE,CAAC;QACnC,OAAO,OAAO,CAAC;IACjB,CAAC,EAAE,EAAE,CAAC,CAAC;IAEP,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/theme-script.d.ts

@@ -0,0 +1,26 @@
+/**
+ * ThemeScript — injects the theme class before hydration to prevent
+ * flash-of-incorrect-theme (FOIT).
+ *
+ * Place this inside <head> in your root layout:
+ *
+ * ```tsx
+ * <head>
+ *   <ThemeScript />
+ * </head>
+ * ```
+ *
+ * Reads the `theme` value from localStorage. Defaults to `dark` if
+ * no preference is stored. No application-specific logic — the theme
+ * token name and default are configurable via props.
+ */
+import type { ReactElement } from 'react';
+export declare function ThemeScript(options?: {
+    /** CSS custom property or class name prefix. */
+    attribute?: 'class' | 'data-theme';
+    /** Default theme when no localStorage entry exists. */
+    defaultTheme?: string;
+    /** localStorage key. */
+    storageKey?: string;
+}): ReactElement;
+//# sourceMappingURL=theme-script.d.ts.map

package/dist/theme-script.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"theme-script.d.ts","sourceRoot":"","sources":["../src/theme-script.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,OAAO,CAAC;AAE1C,wBAAgB,WAAW,CAAC,OAAO,CAAC,EAAE;IACpC,gDAAgD;IAChD,SAAS,CAAC,EAAE,OAAO,GAAG,YAAY,CAAC;IACnC,uDAAuD;IACvD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,wBAAwB;IACxB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,GAAG,YAAY,CAWf"}

package/dist/theme-script.js

@@ -0,0 +1,9 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+export function ThemeScript(options) {
+    const { attribute = 'class', defaultTheme = 'dark', storageKey = 'theme' } = options ?? {};
+    const script = `(function(){try{var t=localStorage.getItem('${storageKey}')||'${defaultTheme}';document.documentElement.setAttribute('${attribute}',t)}catch(e){document.documentElement.setAttribute('${attribute}','${defaultTheme}')}})()`;
+    return (_jsx("script", { 
+        // biome-ignore lint/security/noDangerouslySetInnerHtml: static string, no user input
+        dangerouslySetInnerHTML: { __html: script } }));
+}
+//# sourceMappingURL=theme-script.js.map

package/dist/theme-script.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"theme-script.js","sourceRoot":"","sources":["../src/theme-script.tsx"],"names":[],"mappings":";AAkBA,MAAM,UAAU,WAAW,CAAC,OAO3B;IACC,MAAM,EAAE,SAAS,GAAG,OAAO,EAAE,YAAY,GAAG,MAAM,EAAE,UAAU,GAAG,OAAO,EAAE,GAAG,OAAO,IAAI,EAAE,CAAC;IAE3F,MAAM,MAAM,GAAG,+CAA+C,UAAU,QAAQ,YAAY,4CAA4C,SAAS,wDAAwD,SAAS,MAAM,YAAY,SAAS,CAAC;IAE9O,OAAO,CACL;QACE,qFAAqF;QACrF,uBAAuB,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,GAC3C,CACH,CAAC;AACJ,CAAC"}

package/package.json

@@ -0,0 +1,82 @@
+{
+  "name": "@substrate-platform/site",
+  "version": "0.1.1-canary.0",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./providers": {
+      "import": "./dist/providers.js",
+      "types": "./dist/providers.d.ts"
+    },
+    "./layout": {
+      "import": "./dist/layout.js",
+      "types": "./dist/layout.d.ts"
+    },
+    "./shells": {
+      "import": "./dist/shells.js",
+      "types": "./dist/shells.d.ts"
+    },
+    "./metadata": {
+      "import": "./dist/metadata.js",
+      "types": "./dist/metadata.d.ts"
+    },
+    "./instrumentation": {
+      "import": "./dist/instrumentation.js",
+      "types": "./dist/instrumentation.d.ts"
+    },
+    "./animations": {
+      "import": "./dist/animations.js",
+      "types": "./dist/animations.d.ts"
+    },
+    "./smooth-scroll": {
+      "import": "./dist/smooth-scroll.js",
+      "types": "./dist/smooth-scroll.d.ts"
+    },
+    "./paint-registrar": {
+      "import": "./dist/paint-registrar.js",
+      "types": "./dist/paint-registrar.d.ts"
+    },
+    "./theme-script": {
+      "import": "./dist/theme-script.js",
+      "types": "./dist/theme-script.d.ts"
+    },
+    "./globals.css": "./src/globals.css"
+  },
+  "scripts": {
+    "build": "tsc --project tsconfig.build.json && bun run ../../scripts/fix-import-extensions.ts dist",
+    "lint": "biome check src",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests",
+    "clean": "rm -rf dist .turbo"
+  },
+  "dependencies": {
+    "@substrate-platform/ui": "workspace:*",
+    "@substrate-platform/contracts": "workspace:*",
+    "@substrate-platform/config": "workspace:*",
+    "@substrate-platform/observability": "workspace:*"
+  },
+  "peerDependencies": {
+    "next": "^16.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "gsap": "^3.13.0",
+    "lenis": "^1.1.18",
+    "@tanstack/react-query": "^5.65.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.2.17",
+    "@types/react-dom": "^19.2.3"
+  },
+  "files": [
+    "dist/**",
+    "README.md",
+    "LICENSE",
+    "src/**/*.css"
+  ]
+}

package/src/globals.css

@@ -0,0 +1,220 @@
+/**
+ * @substrate-platform/site — platform global styles.
+ *
+ * ## CSS Package Boundary Contract
+ *
+ * The CSS layering is explicitly defined as three tiers:
+ *
+ *   1. @substrate-platform/ui/styles.css
+ *      Design tokens (--substrate-*) and component styles (.substrate-*).
+ *      Uses relative @import only (./tokens.css, ./theme.css).
+ *      Zero external module dependencies.
+ *
+ *   2. @substrate-platform/site/globals.css  (THIS FILE)
+ *      Tailwind v4 @theme bridge: maps --substrate-* tokens into
+ *      Tailwind's --color-* / --font-* / --radius-* namespace.
+ *      Platform utility classes (.glass, .text-gradient, paint worklets).
+ *      Container queries and anchor positioning.
+ *      Does NOT @import "tailwindcss" — that is the consumer's responsibility.
+ *
+ *   3. Application globals.css
+ *      `@import "tailwindcss"` — the Tailwind v4 entry point.
+ *      Application-specific tokens (--accent-primary, --bg-primary, etc.).
+ *      Application-specific styles, layouts, and overrides.
+ *
+ * ## Consumer CSS Template
+ *
+ * A consumer's globals.css should look like:
+ *
+ *   @import "tailwindcss";
+ *   @import "@substrate-platform/ui/styles.css";
+ *   @import "@substrate-platform/site/globals.css";   // optional
+ *
+ *   :root {
+ *     --accent-primary: #your-brand-color;
+ *     --bg-primary: #your-bg;
+ *     ...
+ *   }
+ *
+ * Or, if the consumer does not need the Tailwind theme bridge:
+ *
+ *   @import "tailwindcss";
+ *   @import "@substrate-platform/ui/styles.css";
+ *
+ *   :root { ... }
+ *
+ * ## Why @substrate-platform/site/globals.css does NOT @import "tailwindcss"
+ *
+ * Tailwind v4's `@import "tailwindcss"` is processed by the
+ * @tailwindcss/postcss plugin, which runs in the consumer project's
+ * PostCSS environment. If a platform CSS file contains this directive,
+ * Turbopack's CSS module resolver attempts to resolve "tailwindcss" from
+ * the platform package's directory — but tailwindcss is installed in the
+ * consumer's node_modules, not the platform package's. This causes a
+ * "Can't resolve 'tailwindcss'" build error.
+ *
+ * The fix is architectural: the Tailwind entry directive belongs in the
+ * consumer's CSS, where the PostCSS environment can resolve it correctly.
+ */
+
+/* ── Tailwind v4 theme bridge ───────────────────────────────────────
+ *
+ * Maps the platform's --substrate-* design tokens into Tailwind v4's
+ * --color-* / --font-* / --radius-* namespace, so Tailwind utility
+ * classes (bg-bg-base, text-text-primary, etc.) work with the platform's
+ * design system.
+ *
+ * This block does not require @import "tailwindcss" — it only declares
+ * custom properties that Tailwind's @theme processor picks up if the
+ * consumer has imported Tailwind elsewhere in the CSS graph.
+ */
+@theme {
+  --font-sans: var(--font-sans);
+  --font-mono: var(--font-mono);
+
+  --color-accent: var(--color-accent);
+  --color-accent-glow: var(--color-accent-glow);
+
+  --color-bg-base: var(--substrate-bg-base);
+  --color-bg-secondary: var(--substrate-bg-secondary);
+  --color-bg-muted: var(--substrate-bg-muted);
+  --color-bg-elevated: var(--substrate-bg-elevated);
+
+  --color-text-primary: var(--substrate-text-primary);
+  --color-text-secondary: var(--substrate-text-secondary);
+  --color-text-tertiary: var(--substrate-text-tertiary);
+  --color-text-muted: var(--substrate-text-muted);
+
+  --color-border-default: var(--substrate-border-default);
+  --color-border-subtle: var(--substrate-border-subtle);
+  --color-border-strong: var(--substrate-border-strong);
+
+  --color-danger: var(--substrate-color-danger);
+  --color-warning: var(--substrate-color-warning);
+  --color-success: var(--substrate-color-success);
+  --color-info: var(--substrate-color-info);
+
+  --radius-card: var(--substrate-card-radius);
+  --radius-button: var(--substrate-button-radius);
+}
+
+/* ── Platform base styles ─────────────────────────────────────────── */
+
+@layer base {
+  body {
+    background: var(--substrate-bg-base);
+    color: var(--substrate-text-primary);
+    font-family: var(--font-sans);
+    -webkit-font-smoothing: antialiased;
+    text-rendering: optimizeLegibility;
+  }
+
+  /* View Transitions API */
+  ::view-transition-old(root),
+  ::view-transition-new(root) {
+    animation-duration: 0.3s;
+    animation-timing-function: var(--substrate-easing-spring);
+  }
+}
+
+@layer utilities {
+  .glass {
+    backdrop-filter: var(--substrate-glass-blur);
+    -webkit-backdrop-filter: var(--substrate-glass-blur);
+  }
+  .text-gradient {
+    background: linear-gradient(135deg, var(--color-accent), var(--substrate-color-info));
+    -webkit-background-clip: text;
+    background-clip: text;
+    -webkit-text-fill-color: transparent;
+  }
+
+  /* ── Houdini Paint Worklet ── */
+  .paint-noise {
+    background-image: paint(substrate-noise);
+    background-color: var(--substrate-bg-elevated);
+  }
+  .paint-mesh {
+    background-image: paint(substrate-mesh);
+    background-color: var(--substrate-bg-base);
+  }
+}
+
+/* ═══════════════════════════════════════════════════════════════
+   CSS Container Queries
+   ═══════════════════════════════════════════════════════════════ */
+
+.card-container {
+  container-type: inline-size;
+  container-name: card;
+}
+
+.sidebar-layout {
+  container-type: inline-size;
+  container-name: sidebar;
+}
+
+@container card (min-width: 400px) {
+  .card-grid {
+    grid-template-columns: 1fr 1fr;
+  }
+}
+
+@container card (min-width: 640px) {
+  .card-grid {
+    grid-template-columns: 1fr 1fr 1fr;
+  }
+}
+
+@container sidebar (max-width: 768px) {
+  .sidebar-nav {
+    display: none;
+  }
+  .sidebar-toggle {
+    display: block;
+  }
+}
+
+@container sidebar (min-width: 769px) {
+  .sidebar-toggle {
+    display: none;
+  }
+}
+
+/* ═══════════════════════════════════════════════════════════════
+   CSS Anchor Positioning
+   ═══════════════════════════════════════════════════════════════ */
+
+.anchor-tooltip {
+  anchor-name: --tooltip-anchor;
+  position: fixed;
+  position-anchor: --tooltip-anchor;
+  position-area: top span-left;
+  margin-bottom: 8px;
+}
+
+.anchor-popover {
+  anchor-name: --popover-anchor;
+  position: fixed;
+  position-anchor: --popover-anchor;
+  position-area: bottom span-right;
+  margin-top: 8px;
+}
+
+.anchor-dropdown {
+  anchor-name: --dropdown-anchor;
+  position: fixed;
+  position-anchor: --dropdown-anchor;
+  position-area: bottom span-left;
+  margin-top: 4px;
+}
+
+@supports not (anchor-name: --test) {
+  .anchor-tooltip,
+  .anchor-popover,
+  .anchor-dropdown {
+    position: absolute;
+    top: 100%;
+    left: 0;
+  }
+}