@mohasinac/appkit 3.6.4 → 3.7.0

package/dist/ui/components/StickyToolbar.d.ts

@@ -1,15 +1,24 @@
-import type { ReactNode } from "react";
+import { type ReactNode } from "react";
 /**
  * StickyToolbar — primitive for the recurrent translucent sticky bar pattern
  * (`sticky top-[calc(var(--header-height,0px)+var(--appkit-navbar-height,2.5rem))]
  * z-10 ... backdrop-blur-sm border-b ...`) used by search-results pages,
- * leaderboards, etc.
+ * leaderboards, sticky pagination rows, etc.
  *
  * The header offset is sourced from `--header-height`, which the global
  * AppLayoutShell sets at runtime. Consumer code never authors the offset
  * manually — only `audit-sticky-offsets` allowlisted files may.
+ *
+ * Dismiss/hide: pass `dismissible` (with a stable `id`) to let the user
+ * collapse the bar to a thin re-expand strip for the rest of the browser
+ * session — a viewport-annoyance-avoidance toggle, not a durable
+ * preference, so it resets on reload rather than persisting forever. This
+ * is what closes the mobile-overlap complaint the sticky toolbar pattern
+ * caused across listing pages: at narrow widths, any sticky bar competing
+ * with page content for vertical space needs a way out that doesn't require
+ * scrolling past it.
  */
-export type StickyToolbarOffset = "header" | "header+nav" | number;
+export type StickyToolbarOffset = "header" | "header+nav" | "header+pagination" | "header+bulk-actions" | number;
 export type StickyToolbarTone = "default" | "muted" | "translucent" | "inverse";
 export type StickyToolbarPadding = "none" | "sm" | "md" | "lg" | "toolbar";
 export interface StickyToolbarProps {
@@ -20,11 +29,31 @@ export interface StickyToolbarProps {
     tone?: StickyToolbarTone;
     /** Show a bottom border. Default `true`. */
     border?: boolean;
-    /** Padding preset. Default `"toolbar"`. */
+    /** Padding preset. Default `"toolbar"`. Use `"none"` + `className` for a responsive/custom padding a preset can't express. */
     padding?: StickyToolbarPadding;
-    /** Stacking layer. Default `"above-content"` (z-10). */
-    z?: "below-modal" | "above-content";
+    /**
+     * Stacking layer. Default `"above-content"` (z-10). Use `"above-toolbar"`
+     * (z-20) for a bar that must stack above another StickyToolbar beneath it
+     * — the common case being a bulk-action bar or primary filter toolbar
+     * sitting above a secondary sticky pagination row.
+     */
+    z?: "below-modal" | "above-content" | "above-toolbar";
     /** Accessible role override. */
     role?: string;
+    /** Extra classes appended after the primitive's own — the escape hatch for another primitive (e.g. ListingToolbar) built on top of this one. */
+    className?: string;
+    /** Forwarded to the root element — for `data-testid` and similar test/analytics hooks. */
+    dataTestId?: string;
+    /**
+     * When true, renders a collapse/expand control. Requires `id` — the
+     * collapsed state is stored in `sessionStorage` keyed by it, so distinct
+     * toolbars on the same page (or the same toolbar across route changes
+     * within a session) don't clobber each other.
+     */
+    dismissible?: boolean;
+    /** Required when `dismissible` is true — see above. */
+    id?: string;
+    /** Accessible label for the collapse/expand button. Default "Toolbar". */
+    label?: string;
 }
-export declare function StickyToolbar({ children, offset, tone, border, padding, z, role, }: StickyToolbarProps): import("react").JSX.Element;
+export declare function StickyToolbar({ children, offset, tone, border, padding, z, role, className, dataTestId, dismissible, id, label, }: StickyToolbarProps): import("react").JSX.Element;

package/dist/ui/components/StickyToolbar.js

@@ -1,4 +1,7 @@
-import { jsx as _jsx } from "react/jsx-runtime";
+"use client";
+import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
+import { useEffect, useState } from "react";
+import { normalizeError } from "../../errors/normalize";
 const TONE_CLS = {
     default: "bg-[var(--appkit-color-surface)]",
     muted: "bg-[var(--appkit-color-bg)]",
@@ -19,19 +22,74 @@ function resolveOffsetClass(offset) {
     if (offset === "header+nav") {
         return "top-[calc(var(--header-height,0px)+var(--appkit-navbar-height,2.5rem))]";
     }
+    if (offset === "header+pagination") {
+        // Matches the sticky pagination-row offset repeated verbatim across
+        // every DataListingView-style index listing (44px = the fixed toolbar
+        // row height above it) — consolidated here instead of copy-pasted.
+        return "top-[calc(var(--header-height,0px)+44px)]";
+    }
+    if (offset === "header+bulk-actions") {
+        // Matches the sticky bulk-action-bar offset that stacks below both the
+        // filter toolbar (44px) and the pagination row above it (88px total).
+        return "top-[calc(var(--header-height,0px)+88px)]";
+    }
     // Numeric offsets are applied via inline style instead (see below) —
     // Tailwind's static scanner can never see a dynamically-interpolated
     // `top-[${offset}px]` arbitrary value, so no CSS rule would ever be
     // generated for it in the compiled stylesheet.
     return "";
 }
-export function StickyToolbar({ children, offset = "header", tone = "translucent", border = true, padding = "toolbar", z = "above-content", role, }) {
+const STORAGE_PREFIX = "appkit:sticky-toolbar-collapsed:";
+function readCollapsed(id) {
+    if (typeof window === "undefined")
+        return false;
+    try {
+        return window.sessionStorage.getItem(STORAGE_PREFIX + id) === "1";
+    }
+    catch (_err) {
+        void normalizeError(_err);
+        return false;
+    }
+}
+function writeCollapsed(id, value) {
+    try {
+        if (value)
+            window.sessionStorage.setItem(STORAGE_PREFIX + id, "1");
+        else
+            window.sessionStorage.removeItem(STORAGE_PREFIX + id);
+    }
+    catch (_err) {
+        void normalizeError(_err);
+        // sessionStorage unavailable (private browsing, etc.) — collapse still
+        // works for the current render, just doesn't survive a re-mount.
+    }
+}
+export function StickyToolbar({ children, offset = "header", tone = "translucent", border = true, padding = "toolbar", z = "above-content", role, className, dataTestId, dismissible = false, id, label = "Toolbar", }) {
+    const [collapsed, setCollapsed] = useState(false);
+    useEffect(() => {
+        if (dismissible && id)
+            setCollapsed(readCollapsed(id));
+    }, [dismissible, id]);
     const offsetCls = resolveOffsetClass(offset);
     const offsetStyle = typeof offset === "number" ? { top: `${offset}px` } : undefined;
     const borderCls = border ? "border-b border-[var(--appkit-color-border)]" : "";
-    const zCls = z === "above-content" ? "z-10" : "z-[5]";
-    return (_jsx("div", { role: role, style: offsetStyle, 
+    const zCls = z === "above-toolbar" ? "z-20" : z === "above-content" ? "z-10" : "z-[5]";
+    const toggle = () => {
+        const next = !collapsed;
+        setCollapsed(next);
+        if (id)
+            writeCollapsed(id, next);
+    };
+    if (dismissible && id && collapsed) {
+        return (_jsx("div", { "data-testid": dataTestId, style: offsetStyle, className: `sticky ${offsetCls} ${zCls} ${TONE_CLS[tone]} ${borderCls} flex justify-center`, children: _jsxs("button", { type: "button", onClick: toggle, "aria-label": `Show ${label}`, "aria-expanded": false, className: "px-4 py-0.5 text-[length:var(--appkit-text-xs)] text-[var(--appkit-color-text-muted)] hover:text-[var(--appkit-color-text)]", children: ["\u2304 Show ", label] }) }));
+    }
+    return (_jsxs("div", { role: role, "data-testid": dataTestId, style: offsetStyle, 
         // for the translucent sticky-toolbar pattern. The header offset is
         // sourced from --header-height (set by AppLayoutShell at runtime).
-        className: `sticky ${offsetCls} ${zCls} ${TONE_CLS[tone]} ${borderCls} ${PADDING_CLS[padding]}`, children: children }));
+        // `relative` only when dismissible — the absolutely-positioned toggle
+        // button anchors to it without disturbing the existing internal
+        // layout of `children` (each of the 27+ migrated call sites has its
+        // own Row/Div structure; a flex wrapper here would double-nest and
+        // risk breaking their centering).
+        className: `sticky ${offsetCls} ${zCls} ${TONE_CLS[tone]} ${borderCls} ${PADDING_CLS[padding]} ${dismissible ? "relative pr-8" : ""} ${className ?? ""}`, children: [children, dismissible && id && (_jsx("button", { type: "button", onClick: toggle, "aria-label": `Hide ${label}`, "aria-expanded": true, className: "absolute right-1.5 top-1/2 -translate-y-1/2 px-1.5 py-1 text-[var(--appkit-color-text-muted)] hover:text-[var(--appkit-color-text)]", children: "\u2303" }))] }));
 }

package/dist/ui/components/Tabs.js

@@ -1,11 +1,17 @@
 "use client";
 import { jsx as _jsx } from "react/jsx-runtime";
-import { createContext, useContext, useMemo, useState } from "react";
+import React, { createContext, useContext, useMemo, useState } from "react";
+import { Select } from "./Select";
 const UI_TABS = {
     list: "appkit-tabs-list",
+    listDropdown: "appkit-tabs-list--dropdown",
     trigger: "appkit-tabs-trigger",
     content: "appkit-tabs-content",
 };
+/** Past this many items, TabsList renders a <Select> dropdown instead of a
+ * horizontal row — a scrollable row of 6+ tabs is unreadable/unreachable on
+ * mobile widths. */
+const TABS_DROPDOWN_THRESHOLD = 5;
 const TabsContext = createContext({
     active: "",
     setActive: () => { },
@@ -25,6 +31,16 @@ export function Tabs({ defaultValue = "", value, onChange, className = "", child
     return (_jsx(TabsContext.Provider, { value: contextValue, children: _jsx("div", { className: className, "data-section": "tabs-div-614", children: children }) }));
 }
 export function TabsList({ className = "", children }) {
+    const { active, setActive } = useContext(TabsContext);
+    const items = React.Children.toArray(children).filter((child) => React.isValidElement(child));
+    if (items.length > TABS_DROPDOWN_THRESHOLD) {
+        const options = items.map((item) => ({
+            value: item.props.value,
+            label: typeof item.props.children === "string" ? item.props.children : item.props.value,
+            disabled: item.props.disabled,
+        }));
+        return (_jsx(Select, { bare: true, "aria-label": "Tabs", role: "tablist", options: options, value: active, onValueChange: setActive, className: [UI_TABS.list, UI_TABS.listDropdown, className].filter(Boolean).join(" ") }));
+    }
     return (_jsx("div", { role: "tablist", className: [UI_TABS.list, className].filter(Boolean).join(" "), "data-section": "tabs-div-615", children: children }));
 }
 export function TabsTrigger({ value, disabled, className = "", children, }) {

package/dist/ui/components/Tabs.style.css

@@ -14,6 +14,16 @@
   scrollbar-width: thin;
 }
 
+/* Past TABS_DROPDOWN_THRESHOLD triggers, TabsList renders a <Select bare>
+   instead of the flex row above — override the row-specific layout rules
+   that don't apply to a native <select>. */
+.appkit-tabs-list--dropdown {
+  display: block;
+  overflow: visible;
+  border-bottom: none;
+  max-width: 20rem;
+}
+
 .appkit-tabs-trigger {
   margin-bottom: -1px;
   border-bottom: 2px solid transparent;

package/dist/ui/components/Typography.js

@@ -1,6 +1,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import React from "react";
 import { ROUNDED_MAP, PADDING_MAP, X_ONLY_MAP } from "./surface-tokens";
+import { getSurfaceTextClass } from "../../tokens/color-pairs";
 const TYPOGRAPHY = {
     headingLevel: {
         1: "appkit-heading--h1",
@@ -356,6 +357,11 @@ const SPAN_SHADOW_MAP = {
 };
 export const Span = React.forwardRef(function Span({ variant = "inherit", color, size, smSize, mdSize, lgSize, xlSize, weight, transform, truncate, numeric, italic, family, align, gradient, rounded, padding, surface, border, layout, gap, shadow, className = "", children, ...props }, ref) {
     const resolvedColor = color ?? variant;
+    // Colors as a function (appkit/src/tokens/color-pairs.ts): only fall back to
+    // the surface's paired default text color when the consumer hasn't already
+    // requested one explicitly (resolvedColor === "inherit", i.e. neither
+    // `color` nor `variant` was passed) — never fights an explicit choice.
+    const surfaceTextFallback = surface && resolvedColor === "inherit" ? getSurfaceTextClass(surface) : "";
     const classes = [
         "appkit-span",
         size ? TYPOGRAPHY.textSize[size] : "",
@@ -365,6 +371,7 @@ export const Span = React.forwardRef(function Span({ variant = "inherit", color,
         responsiveSizeClass("xl:", xlSize),
         weight ? TYPOGRAPHY.textWeight[weight] : "",
         TYPOGRAPHY.colorVariant[resolvedColor],
+        surfaceTextFallback,
         ...shapingClasses({ transform, truncate, numeric, italic, family, align, gradient }),
         rounded ? SPAN_ROUNDED_MAP[rounded] : "",
         padding ? SPAN_PADDING_MAP[padding] : "",

package/dist/ui/components/surface-tokens.d.ts

@@ -1,10 +1,3 @@
-/**
- * Surface & layout tokens — shared prop maps for all layout primitives.
- *
- * These maps power the Bootstrap/MUI-style props (`surface`, `padding`,
- * `rounded`, `border`, `shadow`) on Stack, Row, Grid, Container, Section,
- * Article, Main, Aside, Div, BlockHeader, and BlockFooter.
- */
 export declare const SURFACE_MAP: {
     readonly none: "";
     readonly default: "bg-[var(--appkit-color-surface)]";

package/dist/ui/components/surface-tokens.js

@@ -5,6 +5,7 @@
  * `rounded`, `border`, `shadow`) on Stack, Row, Grid, Container, Section,
  * Article, Main, Aside, Div, BlockHeader, and BlockFooter.
  */
+import { getSurfaceTextClass } from "../../tokens/color-pairs";
 export const SURFACE_MAP = {
     none: "",
     default: "bg-[var(--appkit-color-surface)]",
@@ -270,6 +271,12 @@ const OVERFLOW_MAP = {
 export function buildSurfaceClasses(props) {
     return [
         props.surface ? SURFACE_MAP[props.surface] : "",
+        // Colors as a function, not a convention (appkit/src/tokens/color-pairs.ts):
+        // every `surface` gets a readable default text color from here, resolved
+        // via getSurfaceTextClass — never picked independently. A child element's
+        // own explicit text color class still wins (normal CSS specificity), so
+        // this only fills in a floor, it never overrides an intentional choice.
+        props.surface ? getSurfaceTextClass(props.surface) : "",
         props.padding ? PADDING_MAP[props.padding] : "",
         props.paddingX ? X_ONLY_MAP[props.paddingX] : "",
         props.paddingY ? Y_ONLY_MAP[props.paddingY] : "",

package/dist/ui/index.d.ts

@@ -222,3 +222,9 @@ export { Scrim } from "./components/Scrim";
 export type { ScrimProps, ScrimDirection, ScrimIntensity } from "./components/Scrim";
 export { Kbd } from "./components/Kbd";
 export type { KbdProps, KbdSize, KbdTone } from "./components/Kbd";
+export { StickyToolbar } from "./components/StickyToolbar";
+export type { StickyToolbarProps, StickyToolbarOffset, StickyToolbarTone, StickyToolbarPadding, } from "./components/StickyToolbar";
+export { Show, Hide } from "./components/Responsive";
+export type { ShowProps, HideProps } from "./components/Responsive";
+export { CollapsibleSection } from "./components/CollapsibleSection";
+export type { CollapsibleSectionProps } from "./components/CollapsibleSection";

package/dist/ui/index.js

@@ -116,3 +116,6 @@ export { HorizontalRule } from "./components/HorizontalRule";
 export { Anchor } from "./components/Anchor";
 export { Scrim } from "./components/Scrim";
 export { Kbd } from "./components/Kbd";
+export { StickyToolbar } from "./components/StickyToolbar";
+export { Show, Hide } from "./components/Responsive";
+export { CollapsibleSection } from "./components/CollapsibleSection";

package/dist/ui/rich-text/RichText.style.css

@@ -56,14 +56,14 @@
   border-radius: 0.25rem;
   font-size: 0.875em;
   font-weight: 500;
-  background-color: rgba(53, 112, 252, 0.08);   /* primary cobalt /8 */
-  color: #1343de;                                /* primary-700 cobalt */
-  border: 1px solid rgba(53, 112, 252, 0.18);
+  background-color: color-mix(in srgb, var(--appkit-color-primary) 8%, transparent);
+  color: var(--appkit-color-primary-700);
+  border: 1px solid color-mix(in srgb, var(--appkit-color-primary) 18%, transparent);
 }
 
 .dark .appkit-rich-text :not(pre) > code {
   background-color: rgba(51, 65, 85, 0.6);      /* slate-700/60 */
-  color: #84e122;                                /* lime green — high contrast on dark */
+  color: var(--appkit-color-secondary-400);
   border-color: rgba(71, 85, 105, 0.5);
 }
 
@@ -86,31 +86,31 @@
 
 /* --- Blockquote ----------------------------------------------------------- */
 .appkit-rich-text blockquote {
-  border-left: 3px solid #3570fc;               /* primary cobalt */
+  border-left: 3px solid var(--appkit-color-primary);
   padding: 0.5rem 1rem;
   margin: 1.25rem 0;
   border-radius: 0 0.375rem 0.375rem 0;
-  background-color: rgba(53, 112, 252, 0.06);
+  background-color: color-mix(in srgb, var(--appkit-color-primary) 6%, transparent);
   color: var(--appkit-color-zinc-700);
   font-style: italic;
 }
 
 .dark .appkit-rich-text blockquote {
-  border-left-color: #f063b9;                    /* secondary-400 */
-  background-color: rgba(240, 99, 185, 0.06);
+  border-left-color: var(--appkit-color-secondary-400);
+  background-color: color-mix(in srgb, var(--appkit-color-secondary) 6%, transparent);
   color: var(--appkit-color-text-faint);
 }
 
 /* --- Mark / Highlight ----------------------------------------------------- */
 .appkit-rich-text mark {
-  background-color: rgba(101, 196, 8, 0.25);
+  background-color: color-mix(in srgb, var(--appkit-color-secondary) 25%, transparent);
   color: inherit;
   border-radius: 0.125rem;
   padding: 0 0.1em;
 }
 
 .dark .appkit-rich-text mark {
-  background-color: rgba(101, 196, 8, 0.35);
+  background-color: color-mix(in srgb, var(--appkit-color-secondary) 35%, transparent);
   color: var(--appkit-color-zinc-100);
 }
 
@@ -128,26 +128,26 @@
 
 /* --- Links ---------------------------------------------------------------- */
 .appkit-rich-text a {
-  color: #1a55f2;                               /* primary-600 cobalt */
+  color: var(--appkit-color-primary-600);
   text-decoration: underline;
-  text-decoration-color: rgba(26, 85, 242, 0.6);
+  text-decoration-color: color-mix(in srgb, var(--appkit-color-primary-600) 60%, transparent);
   text-underline-offset: 2px;
   transition: color 150ms, text-decoration-color 150ms;
 }
 
 .appkit-rich-text a:hover {
-  color: #1343de;                               /* primary-700 cobalt */
-  text-decoration-color: rgba(19, 67, 222, 0.7);
+  color: var(--appkit-color-primary-700);
+  text-decoration-color: color-mix(in srgb, var(--appkit-color-primary-700) 70%, transparent);
 }
 
 .dark .appkit-rich-text a {
-  color: #84e122;                               /* lime green — high contrast on dark bg */
-  text-decoration-color: rgba(132, 225, 34, 0.6);
+  color: var(--appkit-color-secondary-400);
+  text-decoration-color: color-mix(in srgb, var(--appkit-color-secondary-400) 60%, transparent);
 }
 
 .dark .appkit-rich-text a:hover {
-  color: #a3f550;                               /* lighter lime green */
-  text-decoration-color: rgba(163, 245, 80, 0.6);
+  color: var(--appkit-color-secondary-300);
+  text-decoration-color: color-mix(in srgb, var(--appkit-color-secondary-300) 60%, transparent);
 }
 
 /* --- Tables --------------------------------------------------------------- */
@@ -274,11 +274,11 @@
 .appkit-rich-text ins {
   text-decoration: underline;
   text-decoration-style: wavy;
-  text-decoration-color: #3570fc;               /* primary cobalt */
+  text-decoration-color: var(--appkit-color-primary);
 }
 
 .dark .appkit-rich-text ins {
-  text-decoration-color: #84e122;               /* lime green on dark */
+  text-decoration-color: var(--appkit-color-secondary-400);
 }
 
 .appkit-rich-text del {

package/dist/utils/id-generators.d.ts

@@ -65,6 +65,13 @@ export interface GenerateFAQIdInput {
     customId?: string;
 }
 export declare function generateFAQId(input: GenerateFAQIdInput): string;
+export interface GenerateChecklistItemIdInput {
+    groupKey: string;
+    pageKey: string;
+    label: string;
+    customId?: string;
+}
+export declare function generateChecklistItemId(input: GenerateChecklistItemIdInput): string;
 export declare function generateCouponId(code: string, customId?: string): string;
 export interface GenerateCarouselIdInput {
     title: string;
@@ -266,6 +273,12 @@ export type MediaFilenameContext = ({
     buyerName: string;
     ext?: string;
     date?: Date;
+} | {
+    type: "tester-screenshot";
+    testerName: string;
+    checklistItemId: string;
+    ext?: string;
+    date?: Date;
 };
 export declare function generateMediaFilename(ctx: MediaFilenameContext): string;
 export declare function validateMediaFilename(filename: string): boolean;

package/dist/utils/id-generators.js

@@ -77,6 +77,12 @@ export function generateFAQId(input) {
     const questionSlug = slugify(input.question).substring(0, 50).replace(/-+$/, "");
     return `faq-${slugify(input.category)}-${questionSlug}`;
 }
+export function generateChecklistItemId(input) {
+    if (input.customId?.trim())
+        return input.customId.trim();
+    const labelSlug = slugify(input.label).substring(0, 40).replace(/-+$/, "");
+    return `checklist-${slugify(input.groupKey)}-${slugify(input.pageKey)}-${labelSlug}`;
+}
 // ─── Coupon ───────────────────────────────────────────────────────────────────
 export function generateCouponId(code, customId) {
     if (customId?.trim())
@@ -425,6 +431,16 @@ export function generateMediaFilename(ctx) {
             const name = ctx.buyerName.toLowerCase().replace(/\s+/g, "-").replace(/[^a-z0-9-]/g, "").slice(0, 20);
             return `payment-proof-${ctx.orderId}-${name}-${y}${m}${day}.${ext}`;
         }
+        case "tester-screenshot": {
+            const d = ctx.date ?? new Date();
+            const y = d.getFullYear();
+            const m = String(d.getMonth() + 1).padStart(2, "0");
+            const day = String(d.getDate()).padStart(2, "0");
+            const ext = ctx.ext ?? "jpg";
+            const name = ctx.testerName.toLowerCase().replace(/\s+/g, "-").replace(/[^a-z0-9-]/g, "").slice(0, 20);
+            const item = ctx.checklistItemId.toLowerCase().replace(/[^a-z0-9-]/g, "").slice(0, 40);
+            return `tester-screenshot-${item}-${name}-${y}${m}${day}.${ext}`;
+        }
     }
 }
 /**
@@ -475,6 +491,7 @@ const MEDIA_FILENAME_PATTERNS = [
     { context: "shipping-proof", pattern: new RegExp(`^shipping-proof-${SLUG_PART}-${DATE_PART}\\.${EXT_PART}$`) },
     { context: "refund-proof", pattern: new RegExp(`^refund-proof-${SLUG_PART}-${SLUG_PART}-${DATE_PART}\\.${EXT_PART}$`) },
     { context: "payment-proof", pattern: new RegExp(`^payment-proof-${SLUG_PART}-${SLUG_PART}-${DATE_PART}\\.${EXT_PART}$`) },
+    { context: "tester-screenshot", pattern: new RegExp(`^tester-screenshot-${SLUG_PART}-${SLUG_PART}-${DATE_PART}\\.${EXT_PART}$`) },
 ];
 export function validateMediaFilename(filename) {
     if (!filename || filename.length > 256)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mohasinac/appkit",
-  "version": "3.6.4",
+  "version": "3.7.0",
   "license": "MIT",
   "publishConfig": {
     "access": "public"

package/scripts/seed-cli-loader.mjs

@@ -11,6 +11,18 @@
 // `import "./foo.css"` side-effect statements that Node ESM can't load.
 const STUB_EXTENSIONS = [".css", ".scss", ".sass", ".png", ".jpg", ".jpeg", ".svg", ".webp", ".gif"];
 
+// server-only / client-only are Next.js-specific sentinel packages — their
+// entire module body unconditionally throws, because their whole purpose is
+// a Next.js-compiler-time + Next.js-runtime guard against importing a
+// server-only (or client-only) module from the wrong side of the boundary.
+// A raw Node script (this CLI) is neither a Next.js Server Component nor a
+// Client Component, so the guard is meaningless here — the main
+// @mohasinac/appkit barrel transitively reaches a module (e.g.
+// features/contact/email.tsx) that imports "server-only" at the top level,
+// which crashes the whole CLI on load. Stub both to a no-op module. Found
+// 2026-08-17 debugging the CLI seed tool being unable to import appkit at all.
+const SENTINEL_SPECIFIERS = new Set(["server-only", "client-only"]);
+
 export async function load(url, context, nextLoad) {
   if (STUB_EXTENSIONS.some((ext) => url.endsWith(ext))) {
     return { format: "module", shortCircuit: true, source: "export default undefined;" };
@@ -19,6 +31,9 @@ export async function load(url, context, nextLoad) {
 }
 
 export async function resolve(specifier, context, nextResolve) {
+  if (SENTINEL_SPECIFIERS.has(specifier)) {
+    return { url: `data:text/javascript,export default undefined;`, shortCircuit: true };
+  }
   try {
     return await nextResolve(specifier, context);
   } catch (err) {