ab-nextjs-components 0.1.8 → 0.1.9

package/CHANGELOG.md

@@ -1,3 +1,16 @@
+## 0.1.9 — 2026-10-14
+
+- **AbLogo:** `wordmark` prop (`true` → "Elements", or any string) renders a mark + Quicksand Bold lockup (`font-quicksand-bold` from ab-nextjs-fonts); `color` prop (`--ab-logo-color`); light / dark (`html.dark`)
+- **AbLogo fix:** `naked` with no `src` now masks with the shipped Ab mark (via `--app-logo-url` fallback) instead of a bronze square when the chrome CSS isn't loaded
+- **AbSplash (new, `ab-nextjs-components/ab-splash`):** brand overlay + `abSplashGateScript` / `buildAbSplashGateScript({ locales, defaultLocale })`; root-path RegExp built from locales minus the default and JSON-injected; skips `navigator.webdriver` / bot UAs; standalone via `matchMedia` OR `navigator.standalone`; each storage get/set in its own try (failed get = seen); `data-ab-splash` set last; page behind is `inert` while shown; track `min(18rem, 28vw)`
+- **CSP:** `ab-nextjs-components/ab-splash/csp` → `getAbSplashGateSha256(script)`, `buildAbSplashGate(options)`, `AB_SPLASH_GATE_SHA256`
+- **AbLinearProgress (new here, `ab-nextjs-components/ab-linear-progress`):** ported from the reviewed core work — determinate / indeterminate, `color`, reduced motion, dark, RTL sweep, empty `aria-label` dropped; shipped CSS module. AbSplash uses it, so **no `ab-nextjs-core` peer is needed**
+- **CSP (P1):** `ab-nextjs-components/ab-splash/csp` now ships compiled `csp.mjs` + `csp.d.ts` (Node-loadable from `next.config.*`); `build:csp` script, `check:publish` / `prepublishOnly` fail when it's stale
+- **AbSplash:** unmount removes `data-ab-splash` + `inert`; scroll lock gets the same 1.2 s CSS failsafe; surfaces `#FFF8F3` / `#1A1310` (mocks)
+- **Tooling:** `esbuild ^0.28.2` is now an explicit devDependency (direct in `pnpm-lock.yaml`; frozen install verified)
+- **AbSplash:** StrictMode-safe teardown (`scheduleAbSplashFinish` / `cancelAbSplashFinish`); overflow failsafe verified in Chromium + WebKit
+- **Tooling:** `typecheck` script, `types/css.d.ts`, vitest automatic JSX, `scripts/build-demo.mjs`
+
 ## 0.1.8 — 2026-10-05
 
 - **Chrome styles:** dialog, toast, logo (`span.app-logo`), spinner, and empty-state doodle CSS + SVG assets now ship here via `@import "ab-nextjs-components/styles.css"` (import after `ab-nextjs-theme/styles.css`)

package/ab-linear-progress/index.tsx

@@ -0,0 +1,125 @@
+/* 
+* @license MIT
+* ~~~~~~~~~~~~
+* ab-nextjs-components
+* ~~~~~~~~~~~~ 
+* Copyright (c) 2026 Abraham Ukachi. The abElements Project.
+*
+* Permission is hereby granted, free of charge, to any person obtaining a copy
+* of this software and associated documentation files (the 'Software'), to deal
+* in the Software without restriction, including without limitation the rights
+* to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+* copies of the Software, and to permit persons to whom the Software is
+* furnished to do so, subject to the following conditions: 
+*  
+* The above copyright notice and this permission notice shall be included in all 
+* copies or substantial portions of the Software. 
+*
+* THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 
+* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 
+* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+* SOFTWARE.
+*
+* @project: ab-nextjs-components
+* @name: AB Linear Progress
+* @file: ab-linear-progress/index.tsx
+* @type: Component (server-safe, no hooks) — ported from the reviewed ab-nextjs-core version
+* @authors: Abraham Ukachi <abrahamukachi@gmail.com>
+*/
+
+/*
+* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+* MOTTO: We'll always do more 😜!!!
+* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+*/
+
+// 🧩 React types only (no runtime hooks → works in server components too)
+import type { CSSProperties, ReactElement } from 'react';
+// 🧵 tiny class-name joiner
+import clsx from 'clsx';
+// 🎨 package-shipped CSS module (no Tailwind scanning of node_modules needed)
+import styles from './styles.module.css';
+
+// 📐 public props of <AbLinearProgress />
+export interface AbLinearProgressProps {
+  // 🏷️ extra class names from the consumer
+  className?: string;
+  // 🎨 bar color (any CSS color); defaults to the bronze brand color
+  color?: string;
+  // 🙈 hide the whole bar (kept for API parity with LYD chrome)
+  hidden?: boolean;
+  // 🔁 indeterminate mode: no known value, bar sweeps back and forth
+  isIndeterminate?: boolean;
+  // 📊 determinate value from 0 to 100
+  progress?: number;
+  // 🗣️ accessible name for screen readers
+  label?: string;
+}
+
+// 🔒 clamp any number into the 0..100 range (NaN → 0)
+export const clampAbProgress = (value: number): number => {
+  // 🚫 non-finite values become 0
+  if (!Number.isFinite(value)) return 0;
+  // ✂️ clamp and return
+  return Math.min(100, Math.max(0, value));
+};
+
+/**
+ * 📊 AbLinearProgress — determinate (`progress`) or indeterminate (`isIndeterminate`)
+ * linear progress bar. Respects prefers-reduced-motion and html.dark.
+ */
+const AbLinearProgress = ({
+  className, // 🏷️ consumer classes
+  color, // 🎨 optional custom color
+  hidden = false, // 👀 visible by default
+  isIndeterminate = false, // 🔁 determinate by default
+  progress = 0, // 📊 start empty
+  label = 'Loading', // 🗣️ default accessible name
+}: AbLinearProgressProps): ReactElement => {
+  // ✂️ safe 0..100 value
+  const value = clampAbProgress(progress);
+  // 🎨 expose the color as a CSS custom property (only when provided)
+  const rootStyle = (color ? { '--ab-linear-progress-color': color } : undefined) as CSSProperties | undefined;
+
+  // 🧱 render the track + bar
+  return (
+    <div
+      // 🏷️ stable public class + module class + consumer class
+      className={clsx('AbLinearProgress', styles.abLinearProgress, className)}
+      // 🎨 custom color, if any
+      style={rootStyle}
+      // 🙈 native hidden attribute
+      hidden={hidden}
+      // ♿ ARIA progressbar role
+      role="progressbar"
+      // 🗣️ accessible name (dropped when empty, e.g. inside an aria-hidden overlay)
+      aria-label={label ? label : undefined}
+      // 📏 range lower bound
+      aria-valuemin={0}
+      // 📏 range upper bound
+      aria-valuemax={100}
+      // 📊 current value only in determinate mode (omitted = indeterminate per ARIA)
+      aria-valuenow={isIndeterminate ? undefined : value}
+      // ⏳ tell AT we're busy while indeterminate
+      aria-busy={isIndeterminate ? true : undefined}
+      // 🙈 hide from AT when hidden
+      aria-hidden={hidden ? true : undefined}
+      // 🔖 mode hook for styling/tests
+      data-ab-mode={isIndeterminate ? 'indeterminate' : 'determinate'}
+    >
+      {/* 🟫 the moving / filling bar */}
+      <div
+        // 🏷️ bar class (indeterminate gets the sweep class)
+        className={clsx(styles.abLinearProgress__bar, isIndeterminate && styles.abLinearProgress__bar_indeterminate)}
+        // 📐 determinate width via transform (GPU friendly) — none in indeterminate
+        style={isIndeterminate ? undefined : { transform: `scaleX(${value / 100})` }}
+      />
+    </div>
+  );
+};
+
+// 📦 default export
+export default AbLinearProgress;

package/ab-linear-progress/styles.module.css

@@ -0,0 +1,121 @@
+/* 
+* @license MIT
+* ~~~~~~~~~~~~
+* ab-nextjs-components
+* ~~~~~~~~~~~~ 
+* Copyright (c) 2026 Abraham Ukachi. The abElements Project.
+*
+* Permission is hereby granted, free of charge, to any person obtaining a copy
+* of this software and associated documentation files (the 'Software'), to deal
+* in the Software without restriction, including without limitation the rights
+* to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+* copies of the Software, and to permit persons to whom the Software is
+* furnished to do so, subject to the following conditions: 
+*  
+* The above copyright notice and this permission notice shall be included in all 
+* copies or substantial portions of the Software. 
+*
+* THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 
+* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 
+* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+* SOFTWARE.
+*
+* @project: ab-nextjs-components
+* @name: AB Linear Progress - Component Stylesheet (plain CSS, Tailwind-independent)
+* @file: ab-linear-progress/styles.module.css
+* @type: CSS Module
+* @authors: Abraham Ukachi <abrahamukachi@gmail.com>
+*/
+
+/*
+* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+* MOTTO: We'll always do more 😜!!!
+* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+*/
+
+/* ===== 📊 AB LINEAR PROGRESS ===== */
+
+/* 🧱 track */
+.abLinearProgress {
+  /* 🎨 default bronze color (light) */
+  --_ab-lp-color: var(--ab-linear-progress-color, #A67C52);
+  /* 📏 default height, overridable */
+  --_ab-lp-height: var(--ab-linear-progress-height, 4px);
+  position: relative; /* 📌 anchor for the bar */
+  display: block; /* 🧱 full-width block */
+  width: 100%; /* ↔️ fill the parent */
+  height: var(--_ab-lp-height); /* ↕️ thin bar */
+  overflow: hidden; /* ✂️ clip the sweeping bar */
+  border-radius: 9999px; /* 💊 pill */
+  /* 🌫️ faint track tinted by the bar color */
+  background-color: color-mix(in srgb, var(--_ab-lp-color) 18%, transparent);
+}
+
+/* 🙈 honor the hidden attribute even if display is set */
+.abLinearProgress[hidden] {
+  display: none;
+}
+
+/* 🌙 dark mode: lighter bronze on dark surfaces */
+:global(html.dark) .abLinearProgress {
+  --_ab-lp-color: var(--ab-linear-progress-color, #C9A27A);
+  background-color: color-mix(in srgb, var(--_ab-lp-color) 22%, transparent);
+}
+
+/* 🟫 bar */
+.abLinearProgress__bar {
+  position: absolute; /* 📌 sits on the track */
+  inset: 0; /* 📐 full size, scaled via transform */
+  border-radius: inherit; /* 💊 same pill */
+  background-color: var(--_ab-lp-color); /* 🎨 bar color */
+  transform-origin: left center; /* ⬅️ grow from the start */
+  transition: transform 240ms ease-out; /* 🎞️ smooth value changes */
+}
+
+/* ↔️ RTL: grow from the right */
+:global([dir='rtl']) .abLinearProgress__bar {
+  transform-origin: right center;
+}
+
+/* 🔁 indeterminate: a 40% segment sweeping across */
+.abLinearProgress__bar_indeterminate {
+  right: auto; /* 🔓 free the right edge */
+  width: 40%; /* 📏 segment width */
+  animation: abLinearProgressSweep 1.4s ease-in-out infinite; /* 🔁 loop */
+}
+
+/* 🎞️ sweep keyframes */
+@keyframes abLinearProgressSweep {
+  0% { transform: translateX(-100%); } /* ⬅️ off-screen left */
+  100% { transform: translateX(250%); } /* ➡️ off-screen right */
+}
+
+/* ↔️ RTL indeterminate: anchor on the right and sweep right → left (mirrored keyframes) */
+:global([dir='rtl']) .abLinearProgress__bar_indeterminate {
+  left: auto; /* 🔓 free the left edge */
+  right: 0; /* 📌 start on the right */
+  animation-name: abLinearProgressSweepRtl; /* ⬅️ mirrored sweep */
+}
+
+/* 🎞️ mirrored sweep keyframes (RTL) */
+@keyframes abLinearProgressSweepRtl {
+  0% { transform: translateX(100%); } /* ➡️ off-screen right */
+  100% { transform: translateX(-250%); } /* ⬅️ off-screen left */
+}
+
+/* ♿ reduced motion: no animation, static bar */
+@media (prefers-reduced-motion: reduce) {
+  .abLinearProgress__bar {
+    transition: none; /* 🚫 no value tween */
+  }
+  .abLinearProgress__bar_indeterminate,
+  :global([dir='rtl']) .abLinearProgress__bar_indeterminate {
+    animation: none; /* 🚫 no sweep (LTR + RTL) */
+    width: 100%; /* 🟫 full static bar */
+    opacity: 0.55; /* 🌫️ softened so it reads as "busy", not "done" */
+    transform: none; /* 📐 in place */
+  }
+}

package/ab-logo/index.tsx

@@ -27,70 +27,128 @@
 * @project: ab-nextjs-components
 * @name: AbLogo - Client
 * @file: ab-logo/index.tsx
+* @authors: Abraham Ukachi <abrahamukachi@gmail.com>
 */
 
-'use client';
+/*
+* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+* MOTTO: We'll always do more 😜!!!
+* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+*/
+
+'use client'; // 💧 client build (the server twin lives in `server/ab-logo`)
 
-import type { ReactElement } from 'react';
+// 🧩 React types only
+import type { CSSProperties, ReactElement } from 'react';
+// 🧵 class-name joiner
 import clsx from 'clsx';
+// 🎨 package-shipped CSS module (Tailwind-independent)
 import styles from './styles.module.css';
 
+// 🅰️ the four logo looks
 export type AbLogoType = 'contained' | 'outlined' | 'hollow' | 'naked';
 
+// 📐 public props
 export interface AbLogoProps {
+  // 🅰️ look of the mark (default: naked)
   type?: AbLogoType;
+  // 🏷️ consumer classes
   className?: string;
-  /** Optional image src (contained). Defaults to the Ab logo shipped in this package (data URI). */
+  /** 🖼️ Optional image src. Defaults to the Ab mark shipped in this package (data URI). */
   src?: string;
-  /** Optional CSS mask value for outlined/hollow/naked. */
+  /** 🎭 Optional CSS mask value for outlined/hollow/naked. */
   mask?: string;
+  // 🗣️ accessible name of the mark
   alt?: string;
+  // 📏 mark size (or wordmark font-size when `wordmark` is on)
   size?: number | string;
+  /** 🔤 Show the wordmark next to the mark: `true` → "Elements", or any string. */
+  wordmark?: boolean | string;
+  /** 🎨 Mark + wordmark color (CSS color). Defaults to bronze (light) / #FFF8F5 (dark). */
+  color?: string;
 }
 
-/** Inlined Ab logo shipped with this package (also at `ab-logo/ab-logo.svg`). */
-const DEFAULT_SRC = 'data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A//www.w3.org/2000/svg%22%20xml%3Aspace%3D%22preserve%22%20viewBox%3D%220%200%2024%2024%22%3E%3Cpath%20fill%3D%22%23A67C52%22%20d%3D%22m1.8%2020.5%209.3-17v17zM22.2%207.7l-9.3-4.2v17l9.3-4.2-4.7-4.3z%22/%3E%3Cpath%20d%3D%22m12.9%2020.5%209.3-4.2-9.3-8.6z%22%20opacity%3D%22.1%22/%3E%3C/svg%3E';
+/** 🅰️ Inlined Ab logo shipped with this package (also at `ab-logo/ab-logo.svg`). */
+export const AB_LOGO_DEFAULT_SRC = 'data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A//www.w3.org/2000/svg%22%20xml%3Aspace%3D%22preserve%22%20viewBox%3D%220%200%2024%2024%22%3E%3Cpath%20fill%3D%22%23A67C52%22%20d%3D%22m1.8%2020.5%209.3-17v17zM22.2%207.7l-9.3-4.2v17l9.3-4.2-4.7-4.3z%22/%3E%3Cpath%20d%3D%22m12.9%2020.5%209.3-4.2-9.3-8.6z%22%20opacity%3D%22.1%22/%3E%3C/svg%3E';
+
+// 🔤 the default wordmark text (a brand name, never translated)
+export const AB_LOGO_DEFAULT_WORDMARK = 'Elements';
+
+// 📏 number → px, string → as is
+const toCssSize = (size?: number | string): string | undefined =>
+  size != null ? (typeof size === 'number' ? `${size}px` : size) : undefined;
 
 const AbLogo = ({
-  type = 'naked',
-  className,
-  src,
-  mask,
-  alt = 'Ab',
-  size,
+  type = 'naked', // 🅰️ naked by default
+  className, // 🏷️ consumer classes
+  src, // 🖼️ optional image
+  mask, // 🎭 optional mask
+  alt = 'Ab', // 🗣️ default name
+  size, // 📏 optional size
+  wordmark, // 🔤 optional wordmark
+  color, // 🎨 optional color
 }: AbLogoProps): ReactElement => {
-  const dim = size != null ? (typeof size === 'number' ? `${size}px` : size) : undefined;
+  // 📏 normalized size
+  const dim = toCssSize(size);
+  // 🔤 wordmark text (null = no wordmark)
+  const text = wordmark === true ? AB_LOGO_DEFAULT_WORDMARK : typeof wordmark === 'string' && wordmark ? wordmark : null;
+  // 🎨 color as a custom property consumed by the CSS module
+  const colorVar = (color ? { '--ab-logo-color': color } : {}) as CSSProperties;
 
+  // 🖼️ build the mark
+  let mark: ReactElement;
   if (type === 'contained') {
-    return (
+    // 🖼️ contained = a real <img>
+    mark = (
+      // eslint-disable-next-line @next/next/no-img-element -- 🖼️ the default src is an inline data-URI SVG (nothing for next/image to optimize), and this package must not require next/image's loader config in consumer apps
       <img
-        className={clsx('AbLogo', 'app-logo', styles.abLogoContained, className)}
-        src={src ?? DEFAULT_SRC}
-        alt={alt}
+        className={clsx(!text && ['AbLogo', 'app-logo', className], styles.abLogoContained, text && styles.abLogo__mark)}
+        src={src ?? AB_LOGO_DEFAULT_SRC}
+        alt={text ? '' : alt}
+        aria-hidden={text ? true : undefined}
         data-type="contained"
-        style={dim ? { width: dim, height: dim } : undefined}
+        style={!text && dim ? { width: dim, height: dim } : undefined}
+      />
+    );
+  } else {
+    // 🎭 explicit mask/src wins; otherwise the CSS module masks with `--app-logo-url` or the shipped mark (no brown square ✅)
+    const maskValue = mask ?? (src ? `url('${src}') no-repeat 50% 50%` : undefined);
+    mark = (
+      <span
+        className={clsx(!text && ['AbLogo', 'app-logo', className], styles.abLogo, text && styles.abLogo__mark)}
+        data-type={type}
+        role={text ? undefined : 'img'}
+        aria-label={text ? undefined : alt}
+        aria-hidden={text ? true : undefined}
+        style={{
+          ...(!text ? colorVar : {}), // 🎨 color (standalone mark only; lockup sets it on the wrapper)
+          ...(!text && dim ? { width: dim, height: dim } : {}), // 📏 size
+          ...(maskValue ? { WebkitMask: maskValue, mask: maskValue, WebkitMaskSize: 'cover', maskSize: 'cover' } : {}), // 🎭 custom mask
+        }}
       />
     );
   }
 
-  // With no `mask`/`src`, leave the mask to `ab-nextjs-components` chrome (`--app-logo-url` / `.app-logo`).
-  // When `mask` or `src` is set, apply it inline (src becomes a CSS mask url).
-  const maskValue = mask ?? (src ? `url('${src}') no-repeat 50% 50%` : undefined);
+  // 🅰️ no wordmark → just the mark (unchanged API)
+  if (!text) return mark;
+
+  // 🔤 lockup: mark + wordmark, one accessible image
   return (
     <span
-      className={clsx('AbLogo', 'app-logo', styles.abLogo, className)}
+      className={clsx('AbLogo', 'AbLogo--wordmark', styles.abLogo__lockup, className)}
       data-type={type}
       role="img"
-      aria-label={alt}
-      style={{
-        ...(dim ? { width: dim, height: dim } : {}),
-        ...(maskValue
-          ? { WebkitMask: maskValue, mask: maskValue, WebkitMaskSize: 'cover', maskSize: 'cover' }
-          : {}),
-      }}
-    />
+      aria-label={`${alt} ${text}`.trim()}
+      style={{ ...colorVar, ...(dim ? { fontSize: dim } : {}) }}
+    >
+      {/* 🅰️ the mark */}
+      {mark}
+      {/* 🔤 the wordmark — Quicksand Bold from ab-nextjs-fonts */}
+      <span className={clsx('font-quicksand-bold', styles.abLogo__wordmark)} aria-hidden="true">{text}</span>
+    </span>
   );
 };
 
+// 📦 exports
 export default AbLogo;
 export { AbLogo };

package/ab-logo/styles.module.css

@@ -4,7 +4,31 @@
 * ab-nextjs-components
 * ~~~~~~~~~~~~ 
 * Copyright (c) 2026 Abraham Ukachi. The abElements Project.
-* Plain CSS modules — no Tailwind Tailwind apply (Turbopack-safe).
+*
+* Permission is hereby granted, free of charge, to any person obtaining a copy
+* of this software and associated documentation files (the 'Software'), to deal
+* in the Software without restriction, including without limitation the rights
+* to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+* copies of the Software, and to permit persons to whom the Software is
+* furnished to do so, subject to the following conditions: 
+*  
+* The above copyright notice and this permission notice shall be included in all 
+* copies or substantial portions of the Software. 
+*
+* THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 
+* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 
+* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+* SOFTWARE.
+
+*
+* @project: ab-nextjs-components
+* @name: AbLogo - Component Stylesheet (plain CSS, Tailwind-independent)
+* @file: ab-logo/styles.module.css
+* @type: CSS Module
+* @authors: Abraham Ukachi <abrahamukachi@gmail.com>
 */
 
 /*
@@ -13,18 +37,62 @@
 * !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
 */
 
+/* 🅰️ masked mark (naked / outlined / hollow) */
 .abLogo {
-  display: block;
-  position: relative;
-  width: 1.5rem;
-  height: 1.5rem;
-  background-color: var(--app-logo-color, #a67c52);
+  display: block; /* 🧱 block box */
+  position: relative; /* 📌 positioning context */
+  width: 1.5rem; /* ↔️ default size */
+  height: 1.5rem; /* ↕️ default size */
+  /* 🎨 bronze by default; `--app-logo-color` (chrome) or `--ab-logo-color` (prop) override */
+  background-color: var(--app-logo-color, var(--ab-logo-color, #A67C52));
+  /* 🎭 the shipped Ab mark as mask → no brown square without chrome CSS ✅ */
+  -webkit-mask: var(--app-logo-url, url("data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A//www.w3.org/2000/svg%22%20xml%3Aspace%3D%22preserve%22%20viewBox%3D%220%200%2024%2024%22%3E%3Cpath%20fill%3D%22%23A67C52%22%20d%3D%22m1.8%2020.5%209.3-17v17zM22.2%207.7l-9.3-4.2v17l9.3-4.2-4.7-4.3z%22/%3E%3Cpath%20d%3D%22m12.9%2020.5%209.3-4.2-9.3-8.6z%22%20opacity%3D%22.1%22/%3E%3C/svg%3E")) no-repeat 50% 50%;
+  mask: var(--app-logo-url, url("data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A//www.w3.org/2000/svg%22%20xml%3Aspace%3D%22preserve%22%20viewBox%3D%220%200%2024%2024%22%3E%3Cpath%20fill%3D%22%23A67C52%22%20d%3D%22m1.8%2020.5%209.3-17v17zM22.2%207.7l-9.3-4.2v17l9.3-4.2-4.7-4.3z%22/%3E%3Cpath%20d%3D%22m12.9%2020.5%209.3-4.2-9.3-8.6z%22%20opacity%3D%22.1%22/%3E%3C/svg%3E")) no-repeat 50% 50%;
+  -webkit-mask-size: contain; /* 📐 keep proportions */
+  mask-size: contain; /* 📐 keep proportions */
+}
+
+/* 🌙 dark: light mark on dark surfaces */
+:global(html.dark) .abLogo:not(.abLogo__mark) {
+  background-color: var(--app-logo-color, var(--ab-logo-color, #FFF8F5));
 }
 
+/* 🖼️ contained mark (a real <img>) */
 .abLogoContained {
-  display: block;
-  position: relative;
-  width: 1.5rem;
-  height: 1.5rem;
-  object-fit: contain;
+  display: block; /* 🧱 block box */
+  position: relative; /* 📌 positioning context */
+  width: 1.5rem; /* ↔️ default size */
+  height: 1.5rem; /* ↕️ default size */
+  object-fit: contain; /* 📐 keep proportions */
+}
+
+/* 🔤 lockup = mark + wordmark */
+.abLogo__lockup {
+  display: inline-flex; /* ➡️ one row */
+  align-items: center; /* ↕️ centered */
+  gap: 0.28em; /* ↔️ gap scales with the text */
+  font-size: 2rem; /* 📏 default lockup size (override with `size`) */
+  line-height: 1; /* 📐 tight */
+  color: var(--ab-logo-color, #A67C52); /* 🎨 bronze */
+}
+
+/* 🌙 dark lockup */
+:global(html.dark) .abLogo__lockup {
+  color: var(--ab-logo-color, #FFF8F5);
+}
+
+/* 🅰️ the mark inside a lockup follows the text size & color */
+.abLogo__mark {
+  width: 1.15em; /* ↔️ ≈ cap height + descender, as in the splash mock */
+  height: 1.15em; /* ↕️ square */
+  flex: none; /* 🚫 never shrink */
+  background-color: currentColor; /* 🎨 same as the wordmark */
+}
+
+/* 🔤 the wordmark — Quicksand Bold (font files ship with ab-nextjs-fonts/quicksand/styles.css) */
+.abLogo__wordmark {
+  font-family: 'Quicksand-Bold', 'Quicksand', ui-rounded, system-ui, sans-serif; /* 🔤 */
+  font-weight: 700; /* 💪 bold */
+  letter-spacing: 0.01em; /* ↔️ as in the mock */
+  white-space: nowrap; /* 🚫 no wrap */
 }

package/ab-splash/csp.d.ts

@@ -0,0 +1,54 @@
+/* 
+* @license MIT
+* ~~~~~~~~~~~~
+* ab-nextjs-components
+* ~~~~~~~~~~~~ 
+* Copyright (c) 2026 Abraham Ukachi. The abElements Project.
+*
+* Permission is hereby granted, free of charge, to any person obtaining a copy
+* of this software and associated documentation files (the 'Software'), to deal
+* in the Software without restriction, including without limitation the rights
+* to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+* copies of the Software, and to permit persons to whom the Software is
+* furnished to do so, subject to the following conditions: 
+*  
+* The above copyright notice and this permission notice shall be included in all 
+* copies or substantial portions of the Software. 
+*
+* THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 
+* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 
+* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+* SOFTWARE.
+
+*
+* @project: ab-nextjs-components
+* @name: AbSplash - CSP hash helpers (types for csp.mjs)
+* @file: ab-splash/csp.d.ts
+* @authors: Abraham Ukachi <abrahamukachi@gmail.com>
+*/
+
+/*
+* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+* MOTTO: We'll always do more 😜!!!
+* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+*/
+
+// ⚙️ gate options (mirror of `AbSplashGateOptions` in ./gate.ts)
+export interface AbSplashGateOptions {
+  // 🌍 every configured locale
+  locales?: readonly string[]
+  // 🏠 the default (unprefixed) locale
+  defaultLocale?: string
+  // 🚪 extra root sub-paths (default ['welcome'])
+  rootSubPaths?: readonly string[]
+}
+
+// 🔐 `'sha256-<base64>'` CSP source for an inline script
+export declare function getAbSplashGateSha256(script: string): string
+// 🔐 the gate script + its hash, from the same options
+export declare function buildAbSplashGate(options?: AbSplashGateOptions): { script: string; sha256: string }
+// 🔐 hash of the default `abSplashGateScript`
+export declare const AB_SPLASH_GATE_SHA256: string

package/ab-splash/csp.mjs

@@ -0,0 +1,82 @@
+/*
+* @license MIT
+* ~~~~~~~~~~~~
+* ab-nextjs-components
+* ~~~~~~~~~~~~
+* Copyright (c) 2026 Abraham Ukachi. The abElements Project.
+* (MIT license text: see LICENSE)
+*
+* @project: ab-nextjs-components
+* @name: AbSplash - CSP hash helpers (COMPILED, do not edit — run `node scripts/build-csp.mjs`)
+* @file: ab-splash/csp.mjs
+* @authors: Abraham Ukachi <abrahamukachi@gmail.com>
+*/
+// 🤖 generated from ab-splash/csp.ts + ab-splash/gate.ts (bundled, ESM, Node)
+
+// ab-splash/csp.ts
+import { createHash } from "node:crypto";
+
+// ab-splash/gate.ts
+var AB_SPLASH_ATTRIBUTE = "data-ab-splash";
+var AB_SPLASH_VISITED_KEY = "ab-splash-visited";
+var AB_SPLASH_SESSION_KEY = "ab-splash-session";
+var AB_SPLASH_BOT_PATTERN = "bot|crawl|spider|slurp|bingpreview|facebookexternalhit|embedly|quora link preview|whatsapp|telegrambot|discordbot|headlesschrome|lighthouse|pagespeed|prerender";
+var escapeRe = (value) => value.replace(/[.*+?^${}()|[\]\\/-]/g, "\\$&");
+function buildAbSplashRootPathPattern(options = {}) {
+  const prefixed = (options.locales ?? []).filter((locale) => locale && locale !== options.defaultLocale).map(escapeRe);
+  const subPaths = (options.rootSubPaths ?? ["welcome"]).filter(Boolean).map(escapeRe);
+  const localePart = prefixed.length ? `(?:\\/(?:${prefixed.join("|")}))?` : "";
+  const subPart = subPaths.length ? `(?:\\/(?:${subPaths.join("|")}))?` : "";
+  return `^${localePart}${subPart}\\/?$`;
+}
+function buildAbSplashGateScript(options = {}) {
+  const pattern = JSON.stringify(buildAbSplashRootPathPattern(options));
+  const bots = JSON.stringify(AB_SPLASH_BOT_PATTERN);
+  return `(function () {
+  // \u{1F9ED} shortcuts
+  var w = window, d = document, nav = w.navigator || {};
+  // \u{1F916} skip automation and bots (no Splash for crawlers, previews or headless tests)
+  if (nav.webdriver || new RegExp(${bots}, 'i').test(nav.userAgent || '')) return;
+  // \u{1F4D6} safe storage read: a failing get counts as "already seen" ('1')
+  function get(store, key) { try { return w[store].getItem(key); } catch (e) { return '1'; } }
+  // \u270D\uFE0F safe storage write: a failing set is ignored
+  function set(store, key) { try { w[store].setItem(key, '1'); } catch (e) {} }
+  // \u{1F4F1} installed PWA? (matchMedia OR iOS navigator.standalone)
+  var mm = false;
+  try { mm = !!(w.matchMedia && w.matchMedia('(display-mode: standalone)').matches); } catch (e) {}
+  var isStandalone = mm || nav.standalone === true;
+  // \u{1F3E0} a root page? (/, /<locale>, /welcome, /<locale>/welcome \u2014 never the default locale prefix)
+  var isRootPage = false;
+  try { isRootPage = new RegExp(${pattern}).test(w.location.pathname); } catch (e) {}
+  // \u{1F6A6} decision
+  var show = false;
+  // \u{1F4F1} standalone: once per session
+  if (isStandalone) {
+    if (!get('sessionStorage', ${JSON.stringify(AB_SPLASH_SESSION_KEY)})) show = true;
+    set('sessionStorage', ${JSON.stringify(AB_SPLASH_SESSION_KEY)});
+  }
+  // \u{1F463} first ever visit, on a root page only
+  if (!get('localStorage', ${JSON.stringify(AB_SPLASH_VISITED_KEY)})) {
+    if (isRootPage) show = true;
+    set('localStorage', ${JSON.stringify(AB_SPLASH_VISITED_KEY)});
+  }
+  // \u{1F6A9} last step: turn the Splash on
+  if (show) { try { d.documentElement.setAttribute(${JSON.stringify(AB_SPLASH_ATTRIBUTE)}, 'on'); } catch (e) {} }
+})();`;
+}
+var abSplashGateScript = buildAbSplashGateScript();
+
+// ab-splash/csp.ts
+function getAbSplashGateSha256(script) {
+  return `'sha256-${createHash("sha256").update(script, "utf8").digest("base64")}'`;
+}
+function buildAbSplashGate(options = {}) {
+  const script = buildAbSplashGateScript(options);
+  return { script, sha256: getAbSplashGateSha256(script) };
+}
+var AB_SPLASH_GATE_SHA256 = getAbSplashGateSha256(abSplashGateScript);
+export {
+  AB_SPLASH_GATE_SHA256,
+  buildAbSplashGate,
+  getAbSplashGateSha256
+};