@meetreeve/ui 0.5.0 → 0.6.1

package/dist/index.d.mts

@@ -49,6 +49,61 @@ interface BrandGlyphProps {
 }
 declare function BrandGlyph({ brand, size, subtle, className }: BrandGlyphProps): react.JSX.Element;
 
+/**
+ * Brand lockup metric rules (DEV-5139) — the single source of truth for how a
+ * lettermark relates to its wordmark. Grounded in standard identity-system
+ * practice: the measurement unit for a lockup is the WORDMARK'S CAP HEIGHT,
+ * proportions are locked as ratios, and the pieces share one baseline.
+ *
+ * Rules v1:
+ *  1. Baseline lock — mark, accent dot, and wordmark sit on ONE shared
+ *     baseline. Flex `items-baseline` in the lockup; never `items-center`
+ *     for text marks (center-aligning boxes ≠ aligning baselines — measured
+ *     3px baseline float on cadasense, DEV-5139).
+ *  2. Cap-height parity + optical overshoot — the mark's cap height is
+ *     MARK_CAP_RATIO × the wordmark's cap height. A lone round glyph
+ *     (C/G/O/Q/S) optically undershoots flat caps, so exact parity reads
+ *     small; 1.08 restores perceived equality (measured 0.93 before).
+ *  3. Lockup gap — mark→wordmark gap is 0.5–0.8× the wordmark cap height.
+ *  4. Clearspace — ≥1 cap height of empty space around the whole lockup
+ *     (the header's own padding satisfies this; consumers embedding the
+ *     lockup elsewhere own the rule).
+ *  5. Standalone glyph fill — on a square canvas (favicon, avatar), the
+ *     letter's cap height is ~60–70% of the canvas edge; ghost-tile below
+ *     20px (DEV-4539).
+ *  6. Ratios are locked — scale the lockup uniformly; never resize one
+ *     element of it. These constants are that lock.
+ *
+ * The generated-asset pipeline (reeve-services brand_identity
+ * svg_templates) mirrors these values — see DEV-5140. Change them together.
+ */
+/** Rule 2 — mark cap height ÷ wordmark cap height. */
+declare const MARK_CAP_RATIO = 1.08;
+/**
+ * Rule 7 (DEV-5340) — family construction weights, pixel-matched to the
+ * asset family (reeve-mark.svg, MindFortress "M." v2, reeve-services
+ * svg_templates): the mark is Black (900), the wordmark ExtraBold (800).
+ * The live-DOM lockup previously ran both at semibold (600) — Matt's
+ * measured "too thin" on cadasense. Numeric constants are the spec; the
+ * *_CLASS twins are the Tailwind application. The generated-asset pipeline
+ * mirrors the numeric values — see DEV-5140. Change them together.
+ */
+declare const MARK_WEIGHT = 900;
+declare const WORDMARK_WEIGHT = 800;
+/**
+ * Rule 3, applied: 8px gap ≈ 0.70× the wordmark's ~11.5px cap height (at
+ * text-base) — inside the 0.5–0.8 band. Named so nobody "fixes" it
+ * per-surface.
+ */
+declare const LOCKUP_GAP = "gap-2";
+/**
+ * Rule 1, applied: the lockup is one locked unit — baseline-aligned inside,
+ * centered as a whole by whatever wraps it (e.g. a touch target).
+ */
+declare const LOCKUP_ROW = "flex items-baseline";
+/** Rule 5 — standalone glyph cap height as a fraction of the canvas edge. */
+declare const GLYPH_CANVAS_FILL = 0.65;
+
 interface HeaderNavItem {
     label: string;
     href?: string;
@@ -268,6 +323,22 @@ interface AppSidebarProps {
     /** Accessible label for the mobile hamburger button. */
     menuLabel?: string;
     ladderOptions?: UseLadderRungOptions;
+    /**
+     * Link renderer for every nav row (desktop + mobile drawer NavLink rows,
+     * and Flyout's folded-group child rows). Defaults to a bare `"a"` so the
+     * package stays framework-agnostic; consumers pass their router's link
+     * (e.g. `next/link`) for client-side navigation. Mirrors ResponsiveHeader's
+     * `linkComponent` prop (DEV-4429) exactly.
+     */
+    linkComponent?: ElementType;
+    /**
+     * Active-route predicate driving row highlighting + `aria-current`
+     * everywhere the package would otherwise use its own naive prefix match
+     * (`activePath === href || activePath.startsWith(href + "/")`). Defaults
+     * to that same behavior — override to add exclusion semantics (e.g.
+     * `/studio` should NOT light up on `/studio/photo`).
+     */
+    isActive?: (href: string, activePath: string) => boolean;
     /** Merged onto the desktop `<aside>` itself — there is no extra wrapping
      *  element (see the render note below on why that matters for height). */
     className?: string;
@@ -282,7 +353,7 @@ interface AppSidebarProps {
  * dependency, matching ResponsiveHeader's existing disclosure pattern in
  * this same package.
  */
-declare function AppSidebar({ ladder, modules, groupOrder, activePath, brand, topItem, menuLabel, ladderOptions, className, }: AppSidebarProps): react.JSX.Element;
+declare function AppSidebar({ ladder, modules, groupOrder, activePath, brand, topItem, menuLabel, ladderOptions, linkComponent, isActive, className, }: AppSidebarProps): react.JSX.Element;
 
 /**
  * Minimal shape AppSidebar's fallback derivation needs from a module registry
@@ -354,6 +425,15 @@ interface FlyoutProps {
      *  its own `active` flag. */
     active: boolean;
     children: FlyoutChild[];
+    /**
+     * Link renderer for the panel's child rows. Defaults to a bare `"a"` so
+     * the package stays framework-agnostic; consumers pass their router's
+     * link (e.g. `next/link`) for client-side navigation. Flyout is
+     * independently exported (see src/index.ts), so it carries its own copy
+     * of this prop rather than requiring AppSidebar as an intermediary —
+     * mirrors ResponsiveHeader's `linkComponent` prop (DEV-4429) exactly.
+     */
+    linkComponent?: ElementType;
     className?: string;
 }
 /**
@@ -391,7 +471,7 @@ interface FlyoutProps {
  * than working around it. jsdom never computes real scrollable-overflow
  * geometry, so no unit test caught this — only an actual browser render did.
  */
-declare function Flyout({ label, icon, active, children, className }: FlyoutProps): react.JSX.Element;
+declare function Flyout({ label, icon, active, children, linkComponent, className }: FlyoutProps): react.JSX.Element;
 
 /**
  * ContextSwitcher (DEV-4408) — promoted out of reeve-frontend's
@@ -458,4 +538,4 @@ interface ContextSwitcherProps {
 }
 declare function ContextSwitcher({ items, activeRefId, onSelect, footer, placeholder, collapsed, side, align, contentClassName, }: ContextSwitcherProps): react.JSX.Element;
 
-export { type AppRungItem, AppSidebar, type AppSidebarBrand, type AppSidebarModuleDef, type AppSidebarProps, type AppSidebarTopItem, type Brand, BrandGlyph, type BrandGlyphProps, type ContextOrgGroup, ContextSwitcher, type ContextSwitcherItem, type ContextSwitcherProps, type FallbackModuleDef, Flyout, type FlyoutChild, type FlyoutProps, type GroupRungItem, type HeaderNavItem, REEVE_ACCENT, ResponsiveHeader, type ResponsiveHeaderProps, type RungItem, type SidebarLadder, type SidebarLadderParsed, type SidebarRung, type UseLadderRungOptions, deriveFallbackLadder, faviconUrl, groupByOrg, reconcileLadder, resolveLadder, useLadderRung, useResponsivePlaceholder, zSidebarLadder };
+export { type AppRungItem, AppSidebar, type AppSidebarBrand, type AppSidebarModuleDef, type AppSidebarProps, type AppSidebarTopItem, type Brand, BrandGlyph, type BrandGlyphProps, type ContextOrgGroup, ContextSwitcher, type ContextSwitcherItem, type ContextSwitcherProps, type FallbackModuleDef, Flyout, type FlyoutChild, type FlyoutProps, GLYPH_CANVAS_FILL, type GroupRungItem, type HeaderNavItem, LOCKUP_GAP, LOCKUP_ROW, MARK_CAP_RATIO, MARK_WEIGHT, REEVE_ACCENT, ResponsiveHeader, type ResponsiveHeaderProps, type RungItem, type SidebarLadder, type SidebarLadderParsed, type SidebarRung, type UseLadderRungOptions, WORDMARK_WEIGHT, deriveFallbackLadder, faviconUrl, groupByOrg, reconcileLadder, resolveLadder, useLadderRung, useResponsivePlaceholder, zSidebarLadder };

package/dist/index.d.ts

@@ -49,6 +49,61 @@ interface BrandGlyphProps {
 }
 declare function BrandGlyph({ brand, size, subtle, className }: BrandGlyphProps): react.JSX.Element;
 
+/**
+ * Brand lockup metric rules (DEV-5139) — the single source of truth for how a
+ * lettermark relates to its wordmark. Grounded in standard identity-system
+ * practice: the measurement unit for a lockup is the WORDMARK'S CAP HEIGHT,
+ * proportions are locked as ratios, and the pieces share one baseline.
+ *
+ * Rules v1:
+ *  1. Baseline lock — mark, accent dot, and wordmark sit on ONE shared
+ *     baseline. Flex `items-baseline` in the lockup; never `items-center`
+ *     for text marks (center-aligning boxes ≠ aligning baselines — measured
+ *     3px baseline float on cadasense, DEV-5139).
+ *  2. Cap-height parity + optical overshoot — the mark's cap height is
+ *     MARK_CAP_RATIO × the wordmark's cap height. A lone round glyph
+ *     (C/G/O/Q/S) optically undershoots flat caps, so exact parity reads
+ *     small; 1.08 restores perceived equality (measured 0.93 before).
+ *  3. Lockup gap — mark→wordmark gap is 0.5–0.8× the wordmark cap height.
+ *  4. Clearspace — ≥1 cap height of empty space around the whole lockup
+ *     (the header's own padding satisfies this; consumers embedding the
+ *     lockup elsewhere own the rule).
+ *  5. Standalone glyph fill — on a square canvas (favicon, avatar), the
+ *     letter's cap height is ~60–70% of the canvas edge; ghost-tile below
+ *     20px (DEV-4539).
+ *  6. Ratios are locked — scale the lockup uniformly; never resize one
+ *     element of it. These constants are that lock.
+ *
+ * The generated-asset pipeline (reeve-services brand_identity
+ * svg_templates) mirrors these values — see DEV-5140. Change them together.
+ */
+/** Rule 2 — mark cap height ÷ wordmark cap height. */
+declare const MARK_CAP_RATIO = 1.08;
+/**
+ * Rule 7 (DEV-5340) — family construction weights, pixel-matched to the
+ * asset family (reeve-mark.svg, MindFortress "M." v2, reeve-services
+ * svg_templates): the mark is Black (900), the wordmark ExtraBold (800).
+ * The live-DOM lockup previously ran both at semibold (600) — Matt's
+ * measured "too thin" on cadasense. Numeric constants are the spec; the
+ * *_CLASS twins are the Tailwind application. The generated-asset pipeline
+ * mirrors the numeric values — see DEV-5140. Change them together.
+ */
+declare const MARK_WEIGHT = 900;
+declare const WORDMARK_WEIGHT = 800;
+/**
+ * Rule 3, applied: 8px gap ≈ 0.70× the wordmark's ~11.5px cap height (at
+ * text-base) — inside the 0.5–0.8 band. Named so nobody "fixes" it
+ * per-surface.
+ */
+declare const LOCKUP_GAP = "gap-2";
+/**
+ * Rule 1, applied: the lockup is one locked unit — baseline-aligned inside,
+ * centered as a whole by whatever wraps it (e.g. a touch target).
+ */
+declare const LOCKUP_ROW = "flex items-baseline";
+/** Rule 5 — standalone glyph cap height as a fraction of the canvas edge. */
+declare const GLYPH_CANVAS_FILL = 0.65;
+
 interface HeaderNavItem {
     label: string;
     href?: string;
@@ -268,6 +323,22 @@ interface AppSidebarProps {
     /** Accessible label for the mobile hamburger button. */
     menuLabel?: string;
     ladderOptions?: UseLadderRungOptions;
+    /**
+     * Link renderer for every nav row (desktop + mobile drawer NavLink rows,
+     * and Flyout's folded-group child rows). Defaults to a bare `"a"` so the
+     * package stays framework-agnostic; consumers pass their router's link
+     * (e.g. `next/link`) for client-side navigation. Mirrors ResponsiveHeader's
+     * `linkComponent` prop (DEV-4429) exactly.
+     */
+    linkComponent?: ElementType;
+    /**
+     * Active-route predicate driving row highlighting + `aria-current`
+     * everywhere the package would otherwise use its own naive prefix match
+     * (`activePath === href || activePath.startsWith(href + "/")`). Defaults
+     * to that same behavior — override to add exclusion semantics (e.g.
+     * `/studio` should NOT light up on `/studio/photo`).
+     */
+    isActive?: (href: string, activePath: string) => boolean;
     /** Merged onto the desktop `<aside>` itself — there is no extra wrapping
      *  element (see the render note below on why that matters for height). */
     className?: string;
@@ -282,7 +353,7 @@ interface AppSidebarProps {
  * dependency, matching ResponsiveHeader's existing disclosure pattern in
  * this same package.
  */
-declare function AppSidebar({ ladder, modules, groupOrder, activePath, brand, topItem, menuLabel, ladderOptions, className, }: AppSidebarProps): react.JSX.Element;
+declare function AppSidebar({ ladder, modules, groupOrder, activePath, brand, topItem, menuLabel, ladderOptions, linkComponent, isActive, className, }: AppSidebarProps): react.JSX.Element;
 
 /**
  * Minimal shape AppSidebar's fallback derivation needs from a module registry
@@ -354,6 +425,15 @@ interface FlyoutProps {
      *  its own `active` flag. */
     active: boolean;
     children: FlyoutChild[];
+    /**
+     * Link renderer for the panel's child rows. Defaults to a bare `"a"` so
+     * the package stays framework-agnostic; consumers pass their router's
+     * link (e.g. `next/link`) for client-side navigation. Flyout is
+     * independently exported (see src/index.ts), so it carries its own copy
+     * of this prop rather than requiring AppSidebar as an intermediary —
+     * mirrors ResponsiveHeader's `linkComponent` prop (DEV-4429) exactly.
+     */
+    linkComponent?: ElementType;
     className?: string;
 }
 /**
@@ -391,7 +471,7 @@ interface FlyoutProps {
  * than working around it. jsdom never computes real scrollable-overflow
  * geometry, so no unit test caught this — only an actual browser render did.
  */
-declare function Flyout({ label, icon, active, children, className }: FlyoutProps): react.JSX.Element;
+declare function Flyout({ label, icon, active, children, linkComponent, className }: FlyoutProps): react.JSX.Element;
 
 /**
  * ContextSwitcher (DEV-4408) — promoted out of reeve-frontend's
@@ -458,4 +538,4 @@ interface ContextSwitcherProps {
 }
 declare function ContextSwitcher({ items, activeRefId, onSelect, footer, placeholder, collapsed, side, align, contentClassName, }: ContextSwitcherProps): react.JSX.Element;
 
-export { type AppRungItem, AppSidebar, type AppSidebarBrand, type AppSidebarModuleDef, type AppSidebarProps, type AppSidebarTopItem, type Brand, BrandGlyph, type BrandGlyphProps, type ContextOrgGroup, ContextSwitcher, type ContextSwitcherItem, type ContextSwitcherProps, type FallbackModuleDef, Flyout, type FlyoutChild, type FlyoutProps, type GroupRungItem, type HeaderNavItem, REEVE_ACCENT, ResponsiveHeader, type ResponsiveHeaderProps, type RungItem, type SidebarLadder, type SidebarLadderParsed, type SidebarRung, type UseLadderRungOptions, deriveFallbackLadder, faviconUrl, groupByOrg, reconcileLadder, resolveLadder, useLadderRung, useResponsivePlaceholder, zSidebarLadder };
+export { type AppRungItem, AppSidebar, type AppSidebarBrand, type AppSidebarModuleDef, type AppSidebarProps, type AppSidebarTopItem, type Brand, BrandGlyph, type BrandGlyphProps, type ContextOrgGroup, ContextSwitcher, type ContextSwitcherItem, type ContextSwitcherProps, type FallbackModuleDef, Flyout, type FlyoutChild, type FlyoutProps, GLYPH_CANVAS_FILL, type GroupRungItem, type HeaderNavItem, LOCKUP_GAP, LOCKUP_ROW, MARK_CAP_RATIO, MARK_WEIGHT, REEVE_ACCENT, ResponsiveHeader, type ResponsiveHeaderProps, type RungItem, type SidebarLadder, type SidebarLadderParsed, type SidebarRung, type UseLadderRungOptions, WORDMARK_WEIGHT, deriveFallbackLadder, faviconUrl, groupByOrg, reconcileLadder, resolveLadder, useLadderRung, useResponsivePlaceholder, zSidebarLadder };

package/dist/index.js

@@ -35,8 +35,14 @@ __export(src_exports, {
   BrandGlyph: () => BrandGlyph,
   ContextSwitcher: () => ContextSwitcher,
   Flyout: () => Flyout,
+  GLYPH_CANVAS_FILL: () => GLYPH_CANVAS_FILL,
+  LOCKUP_GAP: () => LOCKUP_GAP,
+  LOCKUP_ROW: () => LOCKUP_ROW,
+  MARK_CAP_RATIO: () => MARK_CAP_RATIO,
+  MARK_WEIGHT: () => MARK_WEIGHT,
   REEVE_ACCENT: () => REEVE_ACCENT,
   ResponsiveHeader: () => ResponsiveHeader,
+  WORDMARK_WEIGHT: () => WORDMARK_WEIGHT,
   deriveFallbackLadder: () => deriveFallbackLadder,
   faviconUrl: () => faviconUrl,
   groupByOrg: () => groupByOrg,
@@ -49,7 +55,6 @@ __export(src_exports, {
 module.exports = __toCommonJS(src_exports);
 
 // src/brand-glyph.tsx
-var import_image = __toESM(require("next/image"));
 var import_react = require("react");
 
 // src/lib/cn.ts
@@ -77,6 +82,18 @@ function firstInitial(name) {
   return trimmed ? trimmed[0].toUpperCase() : "?";
 }
 
+// src/lib/lockup.ts
+var MARK_CAP_RATIO = 1.08;
+var MARK_WEIGHT = 900;
+var MARK_WEIGHT_CLASS = "font-black";
+var WORDMARK_WEIGHT = 800;
+var WORDMARK_WEIGHT_CLASS = "font-extrabold";
+var WORDMARK_TEXT_LG = "text-base";
+var MONOGRAM_TEXT_LG = "text-[17px]";
+var LOCKUP_GAP = "gap-2";
+var LOCKUP_ROW = "flex items-baseline";
+var GLYPH_CANVAS_FILL = 0.65;
+
 // src/lib/monogram.ts
 var MONOGRAM_COLORS = [
   "#7c3aed",
@@ -125,21 +142,26 @@ function BrandGlyph({ brand, size = "sm", subtle = false, className }) {
       "span",
       {
         className: cn(
-          "flex shrink-0 items-center justify-center overflow-hidden rounded",
+          // `self-center` opts image glyphs out of the lockup's baseline
+          // alignment (DEV-5139): an image box has no text baseline, so
+          // flexbox would seat its BOTTOM edge on the wordmark baseline and
+          // shove the icon upward. Centering preserves the pre-DEV-5139 look.
+          "flex shrink-0 items-center justify-center self-center overflow-hidden rounded",
           // Tint needs a dark-mode counterpart or it vanishes on dark backgrounds.
           subtle ? "bg-black/5 dark:bg-white/10" : "bg-black/10 dark:bg-white/15",
           box,
           className
         ),
         children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
-          import_image.default,
+          "img",
           {
             src,
             alt: "",
             width: dim,
             height: dim,
+            loading: "lazy",
+            decoding: "async",
             "data-testid": "brand-image",
-            unoptimized: true,
             onError: () => setFailed((prev) => new Set(prev).add(src)),
             className: cn(img, "rounded-sm object-contain")
           }
@@ -155,8 +177,15 @@ function BrandGlyph({ brand, size = "sm", subtle = false, className }) {
       "aria-hidden": true,
       "data-testid": "brand-monogram",
       className: cn(
-        "flex shrink-0 select-none items-baseline justify-center font-semibold uppercase",
-        size === "lg" ? "text-[13px]" : "text-[11px]",
+        // DEV-5340 rule 7: the mark carries the family weight (Black 900)
+        // at every size — weight is family-wide, unlike the size audit.
+        "flex shrink-0 select-none items-baseline justify-center uppercase",
+        MARK_WEIGHT_CLASS,
+        // DEV-5139 rule 2: at "lg" the letter runs 17px = the text-base
+        // wordmark (16px) × MARK_CAP_RATIO (1.08) — a lone round glyph at
+        // exact parity optically reads small. "sm" has no wordmark partner
+        // in its surfaces; SIZE unchanged pending a lockup audit there.
+        size === "lg" ? MONOGRAM_TEXT_LG : "text-[11px]",
         box,
         className
       ),
@@ -199,7 +228,9 @@ var MIN_SIZES = {
   /** Generic minimum width/height for a secondary control (button, select), px. */
   control: 44,
   /** Max width of the brand wordmark before it truncates, px. */
-  wordmarkMaxWidth: 180
+  // DEV-5340: scaled with the wordmark's text-sm→text-base bump (180 × 16/14
+  // ≈ 206) so the truncation point keeps the same character budget.
+  wordmarkMaxWidth: 205
 };
 var BREAKPOINTS = {
   /** Tailwind `sm`. */
@@ -304,13 +335,19 @@ function ResponsiveHeader({
     };
   }, [open]);
   const hasSecondary = Boolean(nav && nav.length > 0 || auth || themeToggle);
-  const brandLockup = /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)(import_jsx_runtime2.Fragment, { children: [
+  const brandLockup = /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)("span", { "data-testid": "header-lockup", className: cn(LOCKUP_ROW, LOCKUP_GAP), children: [
     /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(BrandGlyph, { brand, size: "lg" }),
     /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(
       "span",
       {
         "data-testid": "header-wordmark",
-        className: "hidden truncate text-sm font-semibold text-foreground @min-[768px]:block",
+        className: cn(
+          // DEV-5340: family scale + weight — text-base / ExtraBold (800),
+          // via the named lockup constants (never per-surface literals).
+          "hidden truncate text-foreground @min-[768px]:block",
+          WORDMARK_TEXT_LG,
+          WORDMARK_WEIGHT_CLASS
+        ),
         style: { maxWidth: MIN_SIZES.wordmarkMaxWidth },
         children: brand.name
       }
@@ -335,10 +372,10 @@ function ResponsiveHeader({
             "aria-label": brand.name || "Home",
             "data-testid": "header-brand",
             style: TOUCH_TARGET_STYLE,
-            className: "flex shrink-0 items-center gap-2",
+            className: "flex shrink-0 items-center",
             children: brandLockup
           }
-        ) : /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("div", { "data-testid": "header-brand", className: "flex shrink-0 items-center gap-2", children: brandLockup }),
+        ) : /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("div", { "data-testid": "header-brand", className: "flex shrink-0 items-center", children: brandLockup }),
         /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(
           "div",
           {
@@ -715,7 +752,7 @@ function useLadderRung(ladder, containerRef, options = {}) {
 var import_react7 = require("react");
 var import_jsx_runtime3 = require("react/jsx-runtime");
 var PANEL_GAP = 4;
-function Flyout({ label, icon, active, children, className }) {
+function Flyout({ label, icon, active, children, linkComponent, className }) {
   const [hoverOpen, setHoverOpen] = (0, import_react7.useState)(false);
   const [clickOpen, setClickOpen] = (0, import_react7.useState)(false);
   const [panelPosition, setPanelPosition] = (0, import_react7.useState)(null);
@@ -726,6 +763,7 @@ function Flyout({ label, icon, active, children, className }) {
   const firstItemRef = (0, import_react7.useRef)(null);
   const prefersReducedMotion = useMediaQuery("(prefers-reduced-motion: reduce)");
   const Icon = resolveIcon(icon);
+  const LinkEl = linkComponent ?? "a";
   const reposition = (0, import_react7.useCallback)(() => {
     const rect = triggerRef.current?.getBoundingClientRect();
     if (rect) setPanelPosition({ top: rect.top, left: rect.right + PANEL_GAP });
@@ -799,20 +837,32 @@ function Flyout({ label, icon, active, children, className }) {
               "z-50 flex min-w-[12rem] flex-col gap-0.5 rounded-md border border-border bg-background p-2 shadow-lg",
               !prefersReducedMotion && "transition-all duration-150 ease-out"
             ),
-            children: children.map((child, i) => /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(
-              "a",
-              {
-                ref: i === 0 ? firstItemRef : void 0,
-                href: child.href,
-                "aria-current": child.active ? "page" : void 0,
-                style: TOUCH_TARGET_STYLE,
-                className: cn(
-                  "flex items-center truncate rounded-md px-3 py-1.5 text-sm transition-colors",
-                  child.active ? "bg-primary/10 text-foreground" : "text-muted-foreground hover:bg-foreground/5 hover:text-foreground"
-                ),
-                children: child.label
-              },
-              child.moduleId
+            children: children.map((child, i) => (
+              // `ref` on the first row (DEV-4391): the "focus moves into the
+              // panel on click open" behavior above needs a real
+              // HTMLAnchorElement here. A custom `linkComponent` must forward
+              // its ref to the underlying <a> for that to keep working —
+              // true for `next/link` (the intended consumer here) and for any
+              // React 19 function component (ref-as-prop, no forwardRef
+              // needed). A non-forwarding custom component on React <19 just
+              // silently loses the focus-on-open behavior (a console ref
+              // warning, not a crash) — same tradeoff any Link-injection
+              // pattern accepts; not a regression from today's plain `<a>`.
+              /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(
+                LinkEl,
+                {
+                  ref: i === 0 ? firstItemRef : void 0,
+                  href: child.href,
+                  "aria-current": child.active ? "page" : void 0,
+                  style: TOUCH_TARGET_STYLE,
+                  className: cn(
+                    "flex items-center truncate rounded-md px-3 py-1.5 text-sm transition-colors",
+                    child.active ? "bg-primary/10 text-foreground" : "text-muted-foreground hover:bg-foreground/5 hover:text-foreground"
+                  ),
+                  children: child.label
+                },
+                child.moduleId
+              )
             ))
           }
         )
@@ -823,7 +873,7 @@ function Flyout({ label, icon, active, children, className }) {
 
 // src/app-sidebar.tsx
 var import_jsx_runtime4 = require("react/jsx-runtime");
-function isHrefActive(activePath, href) {
+function isHrefActive(href, activePath) {
   return activePath === href || activePath.startsWith(`${href}/`);
 }
 function NavLink({
@@ -831,11 +881,13 @@ function NavLink({
   active,
   icon,
   label,
-  testId
+  testId,
+  linkComponent
 }) {
   const Icon = resolveIcon(icon);
+  const LinkEl = linkComponent ?? "a";
   return /* @__PURE__ */ (0, import_jsx_runtime4.jsxs)(
-    "a",
+    LinkEl,
     {
       href,
       "data-testid": testId,
@@ -867,8 +919,11 @@ function AppSidebar({
   topItem,
   menuLabel = "Menu",
   ladderOptions,
+  linkComponent,
+  isActive,
   className
 }) {
+  const isActiveFn = isActive ?? isHrefActive;
   const isDesktop = useMediaQuery(`(min-width: ${BREAKPOINTS.md}px)`);
   const [mobileOpen, setMobileOpen] = (0, import_react8.useState)(false);
   const containerRef = (0, import_react8.useRef)(null);
@@ -904,10 +959,11 @@ function AppSidebar({
       NavLink,
       {
         href: def.href,
-        active: isHrefActive(activePath, def.href),
+        active: isActiveFn(def.href, activePath),
         icon: def.icon,
         label: def.label,
-        testId: `${testIdPrefix}-${item.moduleId}`
+        testId: `${testIdPrefix}-${item.moduleId}`,
+        linkComponent
       },
       item.moduleId
     );
@@ -920,11 +976,21 @@ function AppSidebar({
         moduleId,
         label: def?.label ?? moduleId,
         href,
-        active: isHrefActive(activePath, href)
+        active: isActiveFn(href, activePath)
       };
     });
     const active = children.some((c) => c.active);
-    return /* @__PURE__ */ (0, import_jsx_runtime4.jsx)(Flyout, { label: item.label, icon: item.icon, active, children }, item.id);
+    return /* @__PURE__ */ (0, import_jsx_runtime4.jsx)(
+      Flyout,
+      {
+        label: item.label,
+        icon: item.icon,
+        active,
+        children,
+        linkComponent
+      },
+      item.id
+    );
   }
   const brandBlock = brand && /* @__PURE__ */ (0, import_jsx_runtime4.jsxs)(
     "a",
@@ -944,10 +1010,11 @@ function AppSidebar({
       NavLink,
       {
         href: topItem.href,
-        active: isHrefActive(activePath, topItem.href),
+        active: isActiveFn(topItem.href, activePath),
         icon: topItem.icon,
         label: topItem.label,
-        testId
+        testId,
+        linkComponent
       }
     ) });
   }
@@ -1212,8 +1279,14 @@ function ContextSwitcher({
   BrandGlyph,
   ContextSwitcher,
   Flyout,
+  GLYPH_CANVAS_FILL,
+  LOCKUP_GAP,
+  LOCKUP_ROW,
+  MARK_CAP_RATIO,
+  MARK_WEIGHT,
   REEVE_ACCENT,
   ResponsiveHeader,
+  WORDMARK_WEIGHT,
   deriveFallbackLadder,
   faviconUrl,
   groupByOrg,

package/dist/index.mjs

@@ -1,7 +1,6 @@
 "use client";
 
 // src/brand-glyph.tsx
-import Image from "next/image";
 import { useState } from "react";
 
 // src/lib/cn.ts
@@ -29,6 +28,18 @@ function firstInitial(name) {
   return trimmed ? trimmed[0].toUpperCase() : "?";
 }
 
+// src/lib/lockup.ts
+var MARK_CAP_RATIO = 1.08;
+var MARK_WEIGHT = 900;
+var MARK_WEIGHT_CLASS = "font-black";
+var WORDMARK_WEIGHT = 800;
+var WORDMARK_WEIGHT_CLASS = "font-extrabold";
+var WORDMARK_TEXT_LG = "text-base";
+var MONOGRAM_TEXT_LG = "text-[17px]";
+var LOCKUP_GAP = "gap-2";
+var LOCKUP_ROW = "flex items-baseline";
+var GLYPH_CANVAS_FILL = 0.65;
+
 // src/lib/monogram.ts
 var MONOGRAM_COLORS = [
   "#7c3aed",
@@ -77,21 +88,26 @@ function BrandGlyph({ brand, size = "sm", subtle = false, className }) {
       "span",
       {
         className: cn(
-          "flex shrink-0 items-center justify-center overflow-hidden rounded",
+          // `self-center` opts image glyphs out of the lockup's baseline
+          // alignment (DEV-5139): an image box has no text baseline, so
+          // flexbox would seat its BOTTOM edge on the wordmark baseline and
+          // shove the icon upward. Centering preserves the pre-DEV-5139 look.
+          "flex shrink-0 items-center justify-center self-center overflow-hidden rounded",
           // Tint needs a dark-mode counterpart or it vanishes on dark backgrounds.
           subtle ? "bg-black/5 dark:bg-white/10" : "bg-black/10 dark:bg-white/15",
           box,
           className
         ),
         children: /* @__PURE__ */ jsx(
-          Image,
+          "img",
           {
             src,
             alt: "",
             width: dim,
             height: dim,
+            loading: "lazy",
+            decoding: "async",
             "data-testid": "brand-image",
-            unoptimized: true,
             onError: () => setFailed((prev) => new Set(prev).add(src)),
             className: cn(img, "rounded-sm object-contain")
           }
@@ -107,8 +123,15 @@ function BrandGlyph({ brand, size = "sm", subtle = false, className }) {
       "aria-hidden": true,
       "data-testid": "brand-monogram",
       className: cn(
-        "flex shrink-0 select-none items-baseline justify-center font-semibold uppercase",
-        size === "lg" ? "text-[13px]" : "text-[11px]",
+        // DEV-5340 rule 7: the mark carries the family weight (Black 900)
+        // at every size — weight is family-wide, unlike the size audit.
+        "flex shrink-0 select-none items-baseline justify-center uppercase",
+        MARK_WEIGHT_CLASS,
+        // DEV-5139 rule 2: at "lg" the letter runs 17px = the text-base
+        // wordmark (16px) × MARK_CAP_RATIO (1.08) — a lone round glyph at
+        // exact parity optically reads small. "sm" has no wordmark partner
+        // in its surfaces; SIZE unchanged pending a lockup audit there.
+        size === "lg" ? MONOGRAM_TEXT_LG : "text-[11px]",
         box,
         className
       ),
@@ -151,7 +174,9 @@ var MIN_SIZES = {
   /** Generic minimum width/height for a secondary control (button, select), px. */
   control: 44,
   /** Max width of the brand wordmark before it truncates, px. */
-  wordmarkMaxWidth: 180
+  // DEV-5340: scaled with the wordmark's text-sm→text-base bump (180 × 16/14
+  // ≈ 206) so the truncation point keeps the same character budget.
+  wordmarkMaxWidth: 205
 };
 var BREAKPOINTS = {
   /** Tailwind `sm`. */
@@ -256,13 +281,19 @@ function ResponsiveHeader({
     };
   }, [open]);
   const hasSecondary = Boolean(nav && nav.length > 0 || auth || themeToggle);
-  const brandLockup = /* @__PURE__ */ jsxs2(Fragment, { children: [
+  const brandLockup = /* @__PURE__ */ jsxs2("span", { "data-testid": "header-lockup", className: cn(LOCKUP_ROW, LOCKUP_GAP), children: [
     /* @__PURE__ */ jsx2(BrandGlyph, { brand, size: "lg" }),
     /* @__PURE__ */ jsx2(
       "span",
       {
         "data-testid": "header-wordmark",
-        className: "hidden truncate text-sm font-semibold text-foreground @min-[768px]:block",
+        className: cn(
+          // DEV-5340: family scale + weight — text-base / ExtraBold (800),
+          // via the named lockup constants (never per-surface literals).
+          "hidden truncate text-foreground @min-[768px]:block",
+          WORDMARK_TEXT_LG,
+          WORDMARK_WEIGHT_CLASS
+        ),
         style: { maxWidth: MIN_SIZES.wordmarkMaxWidth },
         children: brand.name
       }
@@ -287,10 +318,10 @@ function ResponsiveHeader({
             "aria-label": brand.name || "Home",
             "data-testid": "header-brand",
             style: TOUCH_TARGET_STYLE,
-            className: "flex shrink-0 items-center gap-2",
+            className: "flex shrink-0 items-center",
             children: brandLockup
           }
-        ) : /* @__PURE__ */ jsx2("div", { "data-testid": "header-brand", className: "flex shrink-0 items-center gap-2", children: brandLockup }),
+        ) : /* @__PURE__ */ jsx2("div", { "data-testid": "header-brand", className: "flex shrink-0 items-center", children: brandLockup }),
         /* @__PURE__ */ jsx2(
           "div",
           {
@@ -667,7 +698,7 @@ function useLadderRung(ladder, containerRef, options = {}) {
 import { useCallback as useCallback2, useEffect as useEffect4, useId as useId2, useLayoutEffect as useLayoutEffect2, useRef as useRef3, useState as useState5 } from "react";
 import { jsx as jsx3, jsxs as jsxs3 } from "react/jsx-runtime";
 var PANEL_GAP = 4;
-function Flyout({ label, icon, active, children, className }) {
+function Flyout({ label, icon, active, children, linkComponent, className }) {
   const [hoverOpen, setHoverOpen] = useState5(false);
   const [clickOpen, setClickOpen] = useState5(false);
   const [panelPosition, setPanelPosition] = useState5(null);
@@ -678,6 +709,7 @@ function Flyout({ label, icon, active, children, className }) {
   const firstItemRef = useRef3(null);
   const prefersReducedMotion = useMediaQuery("(prefers-reduced-motion: reduce)");
   const Icon = resolveIcon(icon);
+  const LinkEl = linkComponent ?? "a";
   const reposition = useCallback2(() => {
     const rect = triggerRef.current?.getBoundingClientRect();
     if (rect) setPanelPosition({ top: rect.top, left: rect.right + PANEL_GAP });
@@ -751,20 +783,32 @@ function Flyout({ label, icon, active, children, className }) {
               "z-50 flex min-w-[12rem] flex-col gap-0.5 rounded-md border border-border bg-background p-2 shadow-lg",
               !prefersReducedMotion && "transition-all duration-150 ease-out"
             ),
-            children: children.map((child, i) => /* @__PURE__ */ jsx3(
-              "a",
-              {
-                ref: i === 0 ? firstItemRef : void 0,
-                href: child.href,
-                "aria-current": child.active ? "page" : void 0,
-                style: TOUCH_TARGET_STYLE,
-                className: cn(
-                  "flex items-center truncate rounded-md px-3 py-1.5 text-sm transition-colors",
-                  child.active ? "bg-primary/10 text-foreground" : "text-muted-foreground hover:bg-foreground/5 hover:text-foreground"
-                ),
-                children: child.label
-              },
-              child.moduleId
+            children: children.map((child, i) => (
+              // `ref` on the first row (DEV-4391): the "focus moves into the
+              // panel on click open" behavior above needs a real
+              // HTMLAnchorElement here. A custom `linkComponent` must forward
+              // its ref to the underlying <a> for that to keep working —
+              // true for `next/link` (the intended consumer here) and for any
+              // React 19 function component (ref-as-prop, no forwardRef
+              // needed). A non-forwarding custom component on React <19 just
+              // silently loses the focus-on-open behavior (a console ref
+              // warning, not a crash) — same tradeoff any Link-injection
+              // pattern accepts; not a regression from today's plain `<a>`.
+              /* @__PURE__ */ jsx3(
+                LinkEl,
+                {
+                  ref: i === 0 ? firstItemRef : void 0,
+                  href: child.href,
+                  "aria-current": child.active ? "page" : void 0,
+                  style: TOUCH_TARGET_STYLE,
+                  className: cn(
+                    "flex items-center truncate rounded-md px-3 py-1.5 text-sm transition-colors",
+                    child.active ? "bg-primary/10 text-foreground" : "text-muted-foreground hover:bg-foreground/5 hover:text-foreground"
+                  ),
+                  children: child.label
+                },
+                child.moduleId
+              )
             ))
           }
         )
@@ -775,7 +819,7 @@ function Flyout({ label, icon, active, children, className }) {
 
 // src/app-sidebar.tsx
 import { Fragment as Fragment2, jsx as jsx4, jsxs as jsxs4 } from "react/jsx-runtime";
-function isHrefActive(activePath, href) {
+function isHrefActive(href, activePath) {
   return activePath === href || activePath.startsWith(`${href}/`);
 }
 function NavLink({
@@ -783,11 +827,13 @@ function NavLink({
   active,
   icon,
   label,
-  testId
+  testId,
+  linkComponent
 }) {
   const Icon = resolveIcon(icon);
+  const LinkEl = linkComponent ?? "a";
   return /* @__PURE__ */ jsxs4(
-    "a",
+    LinkEl,
     {
       href,
       "data-testid": testId,
@@ -819,8 +865,11 @@ function AppSidebar({
   topItem,
   menuLabel = "Menu",
   ladderOptions,
+  linkComponent,
+  isActive,
   className
 }) {
+  const isActiveFn = isActive ?? isHrefActive;
   const isDesktop = useMediaQuery(`(min-width: ${BREAKPOINTS.md}px)`);
   const [mobileOpen, setMobileOpen] = useState6(false);
   const containerRef = useRef4(null);
@@ -856,10 +905,11 @@ function AppSidebar({
       NavLink,
       {
         href: def.href,
-        active: isHrefActive(activePath, def.href),
+        active: isActiveFn(def.href, activePath),
         icon: def.icon,
         label: def.label,
-        testId: `${testIdPrefix}-${item.moduleId}`
+        testId: `${testIdPrefix}-${item.moduleId}`,
+        linkComponent
       },
       item.moduleId
     );
@@ -872,11 +922,21 @@ function AppSidebar({
         moduleId,
         label: def?.label ?? moduleId,
         href,
-        active: isHrefActive(activePath, href)
+        active: isActiveFn(href, activePath)
       };
     });
     const active = children.some((c) => c.active);
-    return /* @__PURE__ */ jsx4(Flyout, { label: item.label, icon: item.icon, active, children }, item.id);
+    return /* @__PURE__ */ jsx4(
+      Flyout,
+      {
+        label: item.label,
+        icon: item.icon,
+        active,
+        children,
+        linkComponent
+      },
+      item.id
+    );
   }
   const brandBlock = brand && /* @__PURE__ */ jsxs4(
     "a",
@@ -896,10 +956,11 @@ function AppSidebar({
       NavLink,
       {
         href: topItem.href,
-        active: isHrefActive(activePath, topItem.href),
+        active: isActiveFn(topItem.href, activePath),
         icon: topItem.icon,
         label: topItem.label,
-        testId
+        testId,
+        linkComponent
       }
     ) });
   }
@@ -1163,8 +1224,14 @@ export {
   BrandGlyph,
   ContextSwitcher,
   Flyout,
+  GLYPH_CANVAS_FILL,
+  LOCKUP_GAP,
+  LOCKUP_ROW,
+  MARK_CAP_RATIO,
+  MARK_WEIGHT,
   REEVE_ACCENT,
   ResponsiveHeader,
+  WORDMARK_WEIGHT,
   deriveFallbackLadder,
   faviconUrl,
   groupByOrg,

package/dist/tokens/index.d.mts

@@ -17,7 +17,7 @@ declare const MIN_SIZES: {
     /** Generic minimum width/height for a secondary control (button, select), px. */
     readonly control: 44;
     /** Max width of the brand wordmark before it truncates, px. */
-    readonly wordmarkMaxWidth: 180;
+    readonly wordmarkMaxWidth: 205;
 };
 declare const BREAKPOINTS: {
     /** Tailwind `sm`. */

package/dist/tokens/index.d.ts

@@ -17,7 +17,7 @@ declare const MIN_SIZES: {
     /** Generic minimum width/height for a secondary control (button, select), px. */
     readonly control: 44;
     /** Max width of the brand wordmark before it truncates, px. */
-    readonly wordmarkMaxWidth: 180;
+    readonly wordmarkMaxWidth: 205;
 };
 declare const BREAKPOINTS: {
     /** Tailwind `sm`. */

package/dist/tokens/index.js

@@ -33,7 +33,9 @@ var MIN_SIZES = {
   /** Generic minimum width/height for a secondary control (button, select), px. */
   control: 44,
   /** Max width of the brand wordmark before it truncates, px. */
-  wordmarkMaxWidth: 180
+  // DEV-5340: scaled with the wordmark's text-sm→text-base bump (180 × 16/14
+  // ≈ 206) so the truncation point keeps the same character budget.
+  wordmarkMaxWidth: 205
 };
 var BREAKPOINTS = {
   /** Tailwind `sm`. */

package/dist/tokens/index.mjs

@@ -7,7 +7,9 @@ var MIN_SIZES = {
   /** Generic minimum width/height for a secondary control (button, select), px. */
   control: 44,
   /** Max width of the brand wordmark before it truncates, px. */
-  wordmarkMaxWidth: 180
+  // DEV-5340: scaled with the wordmark's text-sm→text-base bump (180 × 16/14
+  // ≈ 206) so the truncation point keeps the same character budget.
+  wordmarkMaxWidth: 205
 };
 var BREAKPOINTS = {
   /** Tailwind `sm`. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meetreeve/ui",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "description": "Shared brand-adaptive UI primitives for MindFortress frontends — min-size tokens, a favicon→logo→monogram BrandGlyph, a responsive header that keeps the search bar usable on mobile, and AppSidebar's viewport-driven auto-collapse ladder.",
   "license": "UNLICENSED",
   "main": "./dist/index.js",
@@ -30,6 +30,7 @@
     "dev": "tsup --watch",
     "test": "vitest run",
     "typecheck": "tsc --noEmit",
+    "check:esm": "node scripts/check-esm-import.mjs",
     "prepublishOnly": "npm run build"
   },
   "publishConfig": {