@mohasinac/appkit 4.71.0 → 4.71.2

package/dist/features/dashboard/components/DashboardQuickJump.js

@@ -0,0 +1,255 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { useMemo, useState } from "react";
+import { useRouter } from "next/navigation.js";
+import { Button } from "../../../ui/components/Button.js";
+import { Div } from "../../../ui/components/Div.js";
+import { Icon } from "../../../ui/components/Icon.js";
+import { IconButton } from "../../../ui/components/IconButton.js";
+import { Grid, Row, Stack } from "../../../ui/components/Layout.js";
+import { Input } from "../../../ui/components/Input.js";
+import { Modal } from "../../../ui/components/Modal.js";
+import { Span, Text } from "../../../ui/components/Typography.js";
+import { DashboardCardView } from "./DashboardCardRenderer.js";
+import { TextLink } from "../../../ui/components/TextLink.js";
+import { Toggle } from "../../../ui/components/Toggle.js";
+import { normalizeError } from "../../../errors/normalize.js";
+import { useToastSafe } from "../../../ui/components/toast-context.js";
+import { rankNavSearchResults } from "../../shell/searchNavItems.js";
+import { useRecentlyVisited } from "../hooks/useRecentlyVisited.js";
+import { useSavedCards } from "../hooks/useSavedCards.js";
+import { ROUTES } from "../../../next/routing/route-map.js";
+import { ADMIN_ROW_HREF_BY_RESOURCE, ADMIN_ROW_RESOURCE_LABEL } from "../../../_internal/shared/features/admin/row-widget-resources.js";
+function searchItemKey(item) {
+    if (item.kind === "page")
+        return `page:${item.href}`;
+    if (item.kind === "toggle")
+        return `toggle:${item.toggleId}`;
+    if (item.kind === "settingPreview")
+        return `settingPreview:${item.settingId}`;
+    return `chart:${item.chartId}`;
+}
+/**
+ * Phase 10 — `adminRow`/`productCard`/`pdpSection` are never ranked by
+ * search (§4 of the plan's Phase 10 section: their candidate sets are not
+ * small/static the way toggles/charts/settingPreviews are). This resolves
+ * ONLY the href for a card already in the recency/default list — never
+ * called from the search path.
+ */
+function resolveCardHref(card) {
+    if (card.kind === "page" || card.kind === "productCard")
+        return card.href;
+    if (card.kind === "adminRow")
+        return ADMIN_ROW_HREF_BY_RESOURCE[card.resource]?.(card.rowId) ?? null;
+    if (card.kind === "pdpSection")
+        return `${String(ROUTES.PUBLIC.PRODUCT_DETAIL(card.productId))}#section-${card.sectionId}`;
+    return null;
+}
+function cardKey(card) {
+    switch (card.kind) {
+        case "page":
+            return `page:${card.href}`;
+        case "toggle":
+            return `toggle:${card.toggleId}`;
+        case "chart":
+            return `chart:${card.chartId}`;
+        case "settingPreview":
+            return `settingPreview:${card.settingId}`;
+        case "adminRow":
+            return `adminRow:${card.resource}:${card.rowId}`;
+        case "productCard":
+            return `productCard:${card.productId}`;
+        case "pdpSection":
+            return `pdpSection:${card.productId}:${card.sectionId}`;
+    }
+}
+export function DashboardQuickJump({ scope, groups, defaultCards, toggles = [], charts = [], settingsPreviews = [], placeholder = "What do you want to do?", }) {
+    const { items: recentItems, recordVisit } = useRecentlyVisited(scope);
+    const { items: savedItems, saveFromRecent, createCard, removeCard, updateCard } = useSavedCards(scope);
+    const toast = useToastSafe();
+    const router = useRouter();
+    const [query, setQuery] = useState("");
+    const [togglingId, setTogglingId] = useState(null);
+    const savedIds = useMemo(() => new Set(savedItems.map((c) => c.id)), [savedItems]);
+    // 9K — a toggle carrying a `confirmation` parks here instead of firing
+    // immediately; the shared modal rendered at the bottom of this component
+    // resolves it on confirm/cancel. One piece of state serves all 3 toggle
+    // surfaces (search results, recent/default cards, saved cards) rather than
+    // duplicating the dialog three times.
+    const [pendingConfirm, setPendingConfirm] = useState(null);
+    const searchItems = useMemo(() => {
+        const pageItems = groups.flatMap((g) => g.items.map((item) => ({
+            kind: "page",
+            href: item.href,
+            label: item.label,
+            description: item.description,
+            keywords: item.keywords,
+            groupTitle: g.title,
+        })));
+        const toggleItems = toggles.map((t) => ({
+            kind: "toggle",
+            toggleId: t.toggleId,
+            label: t.label,
+            keywords: t.keywords,
+            isOn: t.isOn,
+            onToggle: t.onToggle,
+            groupTitle: "Settings",
+            priority: t.priority,
+        }));
+        const chartItems = charts.map((c) => ({
+            kind: "chart",
+            chartId: c.chartId,
+            label: c.label,
+            keywords: c.keywords,
+            value: c.value,
+            groupTitle: "Stats",
+        }));
+        const settingPreviewItems = settingsPreviews.map((s) => ({
+            kind: "settingPreview",
+            settingId: s.settingId,
+            label: s.label,
+            keywords: s.keywords,
+            value: s.value,
+            href: s.href,
+            groupTitle: "Settings",
+            priority: s.priority,
+        }));
+        return [...pageItems, ...toggleItems, ...chartItems, ...settingPreviewItems];
+    }, [groups, toggles, charts, settingsPreviews]);
+    const results = useMemo(() => rankNavSearchResults(searchItems, query).slice(0, 8), [searchItems, query]);
+    const isSearching = query.trim().length > 0;
+    // Newest-first recent entries when any exist; otherwise the curated per-portal defaults.
+    const cards = recentItems.length > 0 ? recentItems : defaultCards;
+    async function runToggle(toggleId, label) {
+        const toggle = toggles.find((t) => t.toggleId === toggleId);
+        if (!toggle || togglingId)
+            return;
+        setTogglingId(toggleId);
+        try {
+            await toggle.onToggle();
+            recordVisit({ kind: "toggle", toggleId: toggle.toggleId, label });
+        }
+        catch (err) {
+            void normalizeError(err);
+            toast?.showToast(`Couldn't update "${label}" — please try again.`, "error");
+        }
+        finally {
+            setTogglingId(null);
+        }
+    }
+    /**
+     * 9K's actual gate — every toggle call site goes through THIS, never
+     * `runToggle` directly. A toggle with no `confirmation` behaves exactly as
+     * before (fires immediately); one that carries `confirmation` parks the
+     * request and opens the shared modal instead.
+     */
+    async function requestToggle(toggleId, label) {
+        const toggle = toggles.find((t) => t.toggleId === toggleId);
+        if (toggle?.confirmation) {
+            setPendingConfirm({ confirmation: toggle.confirmation, toggleId, label });
+            return;
+        }
+        await runToggle(toggleId, label);
+    }
+    async function confirmPendingToggle() {
+        if (!pendingConfirm)
+            return;
+        const { toggleId, label } = pendingConfirm;
+        setPendingConfirm(null);
+        await runToggle(toggleId, label);
+    }
+    function saveCard(card) {
+        const entry = "visitedAt" in card ? card : { ...card, visitedAt: new Date().toISOString() };
+        saveFromRecent(entry);
+        toast?.showToast(`Saved "${card.label}" to your dashboard.`, "success");
+    }
+    function selectResult(item) {
+        if (item.kind === "page") {
+            recordVisit({ kind: "page", href: item.href, label: item.label });
+            return;
+        }
+        if (item.kind === "toggle") {
+            void requestToggle(item.toggleId, item.label);
+            return;
+        }
+        if (item.kind === "settingPreview") {
+            recordVisit({ kind: "settingPreview", settingId: item.settingId, label: item.label });
+            return;
+        }
+        recordVisit({ kind: "chart", chartId: item.chartId, label: item.label });
+    }
+    function handleKeyDown(e) {
+        if (e.key !== "Enter")
+            return;
+        const top = results[0];
+        if (!top)
+            return;
+        if (top.kind === "page" || top.kind === "settingPreview") {
+            e.preventDefault();
+            recordVisit(top.kind === "page"
+                ? { kind: "page", href: top.href, label: top.label }
+                : { kind: "settingPreview", settingId: top.settingId, label: top.label });
+            router.push(top.href);
+            return;
+        }
+        selectResult(top);
+    }
+    return (_jsxs(Stack, { gap: "md", children: [_jsx(Input, { value: query, onChange: (e) => setQuery(e.target.value), onKeyDown: handleKeyDown, placeholder: placeholder, "aria-label": placeholder }), isSearching ? (_jsx(Stack, { gap: "none", children: results.length === 0 ? (_jsxs(Text, { size: "sm", color: "muted", paddingY: "md", children: ["No matches for \u201C", query, "\u201D."] })) : (results.map((item) => (_jsx(QuickJumpResultRow, { item: item, busy: item.kind === "toggle" && togglingId === item.toggleId, onSelect: () => selectResult(item) }, searchItemKey(item))))) })) : (_jsxs(_Fragment, { children: [_jsx(Grid, { cols: "cards", gap: "md", children: cards.map((card) => (_jsx(QuickJumpCard, { card: card, toggles: toggles, charts: charts, settingsPreviews: settingsPreviews, busy: card.kind === "toggle" && togglingId === card.toggleId, isSaved: savedIds.has(cardKey(card)), onToggle: requestToggle, onSave: () => saveCard(card) }, cardKey(card)))) }), _jsxs(Stack, { gap: "sm", children: [_jsxs(Row, { align: "center", justify: "between", children: [_jsx(Span, { size: "xs", weight: "semibold", color: "muted", className: "uppercase tracking-widest", children: "Saved" }), _jsxs(Button, { variant: "ghost", size: "sm", type: "button", onClick: () => {
+                                            createCard();
+                                            toast?.showToast("New card added — edit it to fill it in.", "success");
+                                        }, children: [_jsx(Icon, { name: "create", size: "sm" }), " New card"] })] }), savedItems.length > 0 && (_jsx(Grid, { cols: "cards", gap: "md", children: savedItems.map((card) => (_jsx(DashboardCardView, { card: card, toggles: toggles, charts: charts, settingsPreviews: settingsPreviews, onToggle: requestToggle, onRemove: () => removeCard(card.id), onUpdate: (patch) => updateCard(card.id, patch) }, card.id))) }))] })] })), pendingConfirm && (_jsx(Modal, { isOpen: true, onClose: () => setPendingConfirm(null), title: pendingConfirm.confirmation.title, actions: _jsxs(Row, { gap: "sm", justify: "end", children: [_jsx(Button, { variant: "ghost", type: "button", onClick: () => setPendingConfirm(null), children: pendingConfirm.confirmation.cancelLabel ?? "Cancel" }), _jsx(Button, { variant: pendingConfirm.confirmation.confirmKind === "danger" ? "danger" : "primary", type: "button", onClick: () => void confirmPendingToggle(), children: pendingConfirm.confirmation.confirmLabel })] }), children: _jsx(Text, { size: "sm", children: pendingConfirm.confirmation.body }) }))] }));
+}
+function QuickJumpResultRow({ item, busy, onSelect, }) {
+    if (item.kind === "page" || item.kind === "settingPreview") {
+        return (_jsx(TextLink, { variant: "bare", href: item.href, onClick: onSelect, rounded: "md", paddingX: "sm", paddingY: "xs", className: "w-full hover:bg-[var(--appkit-color-surface-elevated)] transition-colors", children: _jsxs(Row, { align: "center", justify: "between", gap: "sm", children: [_jsx(Span, { size: "sm", children: item.label }), _jsx(Span, { size: "xs", color: "muted", children: item.kind === "settingPreview" ? item.value : item.groupTitle })] }) }));
+    }
+    return (_jsxs(Button, { variant: "ghost", type: "button", onClick: onSelect, disabled: busy, justify: "between", rounded: "md", paddingX: "sm", paddingY: "xs", className: "w-full text-left hover:bg-[var(--appkit-color-surface-elevated)]", children: [_jsx(Span, { size: "sm", children: item.label }), item.kind === "toggle" ? (_jsx(Span, { size: "xs", color: item.isOn ? "success" : "muted", children: busy ? "Saving…" : item.isOn ? "On" : "Off" })) : (_jsx(Span, { size: "xs", color: "muted", numeric: true, children: item.value }))] }));
+}
+function QuickJumpCard({ card, toggles, charts, settingsPreviews, busy, isSaved, onToggle, onSave, }) {
+    const baseClass = "border border-[var(--appkit-color-border)] bg-[var(--appkit-color-surface)] hover:border-[var(--appkit-color-primary)] transition-all";
+    /*
+     * Phase 10 — `adminRow`/`productCard`/`pdpSection` render identically to
+     * `page`: a bookmark (label + link), no live column/badge/price/stock
+     * preview. This is the named escape hatch from the plan's Phase 10
+     * section, not an oversight — each source system is too structurally
+     * different from the dashboard's own data to mirror live.
+     */
+    let cardBody;
+    if (card.kind === "page" || card.kind === "adminRow" || card.kind === "productCard" || card.kind === "pdpSection") {
+        const href = resolveCardHref(card);
+        if (!href)
+            return null;
+        cardBody = (_jsxs(TextLink, { variant: "bare", href: href, rounded: "xl", layout: "flex-col", gap: "sm", paddingX: "lg", paddingY: "lg", shadow: "hover-md", className: `group ${baseClass}`, children: [_jsx(Text, { weight: "semibold", className: "text-[var(--appkit-color-text)] group-hover:text-[var(--appkit-color-primary)] transition-colors", children: card.label }), card.kind === "adminRow" && (_jsx(Text, { size: "xs", color: "muted", children: ADMIN_ROW_RESOURCE_LABEL[card.resource] }))] }));
+    }
+    else if (card.kind === "settingPreview") {
+        // Live value comes from the `settingsPreviews` prop (the caller's own, always-current data), never from the card record itself.
+        const live = settingsPreviews.find((s) => s.settingId === card.settingId);
+        cardBody = (_jsxs(TextLink, { variant: "bare", href: live?.href ?? "#", rounded: "xl", layout: "flex-col", gap: "sm", paddingX: "lg", paddingY: "lg", shadow: "hover-md", className: `group ${baseClass}`, children: [_jsx(Text, { size: "xs", weight: "semibold", className: "uppercase tracking-widest text-[var(--appkit-color-text-muted)]", children: card.label }), _jsx(Text, { weight: "bold", className: "text-[var(--appkit-color-text)] group-hover:text-[var(--appkit-color-primary)] transition-colors", children: live ? live.value : "—" })] }));
+    }
+    else if (card.kind === "toggle") {
+        // Live state comes from the `toggles` prop (the caller's own, always-current data), never from the card record itself.
+        const live = toggles.find((t) => t.toggleId === card.toggleId);
+        const isOn = live?.isOn ?? false;
+        cardBody = (_jsx(Div, { rounded: "xl", paddingX: "x-lg", paddingY: "y-lg", shadow: "sm", className: baseClass, children: _jsxs(Row, { align: "center", justify: "between", gap: "sm", children: [_jsx(Text, { weight: "semibold", className: "text-[var(--appkit-color-text)]", children: card.label }), _jsx(Toggle, { checked: isOn, disabled: busy || !live, ariaLabel: card.label, onChange: () => void onToggle(card.toggleId, card.label) })] }) }));
+    }
+    else {
+        // chart — live value comes from the `charts` prop (the caller's own, always-current data), never from the card record itself.
+        const liveChart = charts.find((c) => c.chartId === card.chartId);
+        cardBody = (_jsxs(Div, { rounded: "xl", paddingX: "x-lg", paddingY: "y-lg", shadow: "sm", className: baseClass, children: [_jsx(Text, { size: "xs", weight: "semibold", className: "uppercase tracking-widest text-[var(--appkit-color-text-muted)]", children: card.label }), _jsx(Text, { size: "2xl", weight: "bold", numeric: true, className: "mt-2 text-[var(--appkit-color-text)] leading-none", children: liveChart ? liveChart.value : "—" })] }));
+    }
+    /*
+     * Phase 9-ii (9G's remaining client piece) — "Save" promotes a recent/
+     * default card into the user-curated, uncapped `savedCards` tier. Rendered
+     * as a SIBLING of the card's own link/toggle, never nested inside —
+     * a `<button>` inside an `<a>` is invalid HTML that browsers resolve by
+     * closing the anchor early, breaking the CARD's navigation rather than
+     * just the button's (same reasoning as `BlogFeaturedCard`'s owner-actions
+     * placement). Hidden once already saved — no "unsave from here" affordance
+     * yet; that's the saved-card list's own remove button (below).
+     */
+    return (_jsxs(Div, { className: "relative h-full", children: [cardBody, !isSaved && (_jsx(IconButton, { "aria-label": `Save "${card.label}" to your dashboard`, icon: _jsx(Icon, { name: "save", size: "sm" }), size: "sm", variant: "ghost", rounded: "full", className: "absolute right-2 top-2 z-10 bg-[var(--appkit-color-surface)]/90 backdrop-blur-sm", onClick: (e) => {
+                    e.preventDefault();
+                    e.stopPropagation();
+                    onSave();
+                } }))] }));
+}

package/dist/features/dashboard/components/DashboardSectionsClient.js

@@ -56,6 +56,13 @@ export function DashboardSectionsClient({ portal, groups, permissions, title, de
     const sections = useMemo(() => hubSections(filterNavGroups([...groups], settings?.navConfig, permissions)), [groups, settings?.navConfig, permissions]);
     const sectionHrefs = useMemo(() => Object.fromEntries(sections.map((s) => [s.slug, SECTION_ROUTE[portal](s.slug)])), [sections, portal]);
     return (_jsx(DashboardHubView, { title: title, description: description, mode: "sections", sections: sections, sectionHrefs: sectionHrefs, counts: {}, above: above, emptyMessage: emptyMessage, 
+        // Phase 12 — `portal` already uniquely identifies this component's two
+        // real callers (`/store`, `/user`; admin never renders this client
+        // variant), so the id is derived here rather than asking both callers
+        // to invent and pass one. Distinct from each page's OWN top-level
+        // region id ("store"/"user", wired directly in page.tsx) — this one
+        // scopes to the section-cards grid specifically, not the whole page.
+        pageId: `${portal}-sections-grid`, 
         /*
          * 🛑 Withheld deliberately. `/store`'s entitlement filter lives in the
          * layout and on the hub pages, not here, so a count rendered from these

package/dist/features/dashboard/components/EditableWidget.d.ts

@@ -0,0 +1,51 @@
+import type { ResolvedWidget, WidgetInstance } from "../../../ui/widgets/types";
+import type { ReactNode } from "react";
+/**
+ * The client boundary for in-place widget editing.
+ *
+ * ---------------------------------------------------------------------------
+ * WHY THIS FILE EXISTS AT ALL
+ * ---------------------------------------------------------------------------
+ *
+ * `WidgetInstanceEditor` needs an `onPatch` callback, and a SERVER component
+ * cannot hand a function to a client component — it throws at serialization.
+ * `RelatedItemsSection` is a server component (it awaits
+ * `getWidgetInstances`). So the write has to be owned on the client side of
+ * the boundary, which is this file.
+ *
+ * `children` is still server-rendered content passed INTO a client component,
+ * which is allowed and is the whole point: the rails keep rendering on the
+ * server (crawlable `<h2>`s, no hydration cost for a visitor) and only the
+ * edit affordance is client-side. A visitor who cannot edit gets
+ * `editMode === false`, and `WidgetInstanceEditor` then returns `children`
+ * untouched — no wrapper, no layout shift.
+ *
+ * ---------------------------------------------------------------------------
+ * 🛑 PLAIN `fetch` WITH A RELATIVE URL, DELIBERATELY NOT `ApiClient`
+ * ---------------------------------------------------------------------------
+ *
+ * W-TEST found that `ApiClient` uses `process.env.NEXT_PUBLIC_APP_URL` as its
+ * `baseURL`, so its documented `window.location.origin` fallback is dead
+ * whenever that variable is set. On a portal host (`seller.localhost:3001`)
+ * every `ApiClient` call is then cross-origin and CORS-blocked, and the page
+ * cannot hydrate. An in-place editor is client-side by nature, so going
+ * through `ApiClient` would make this feature fail entirely on exactly the
+ * hosts an admin is most likely to be editing from.
+ *
+ * A relative URL is always same-origin by construction, so it works on the
+ * canonical host AND on every portal host without depending on an env var
+ * being right. 🚩 The underlying `ApiClient` bug is still real and still
+ * unowned — reported, not worked around silently.
+ */
+export interface EditableWidgetProps {
+    /** The resolved node. Plain data — crosses the server/client boundary safely. */
+    node: ResolvedWidget;
+    /** Every instance in this region, so a patch can be sent as a whole-region PUT. */
+    instances: readonly WidgetInstance[];
+    /** The region being edited. Also the authorised scope server-side. */
+    regionId: string;
+    /** Human-readable blast radius, e.g. "every product page". */
+    scopeLabel: string;
+    children: ReactNode;
+}
+export declare function EditableWidget({ node, instances, regionId, scopeLabel, children, }: EditableWidgetProps): import("react").JSX.Element;

package/dist/features/dashboard/components/EditableWidget.js

@@ -0,0 +1,44 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useCallback, useState } from "react";
+import { WidgetInstanceEditor, applyEditPatch } from "./WidgetInstanceEditor.js";
+export function EditableWidget({ node, instances, regionId, scopeLabel, children, }) {
+    /*
+     * Held locally so a second edit in the same session builds on the first
+     * without a round trip. Seeded from the server-resolved list.
+     */
+    const [local, setLocal] = useState(instances);
+    const onPatch = useCallback(async (id, patch) => {
+        const next = applyEditPatch(local, id, patch);
+        const res = await fetch(`/api/admin/widget-instances/${encodeURIComponent(regionId)}`, {
+            method: "PUT",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ instances: next }),
+        });
+        if (!res.ok) {
+            /*
+             * Surfaced to the operator by `WidgetInstanceEditor`'s catch, never
+             * swallowed — a 403 from the permission gate has to read as "you may
+             * not do that", not as a silently unsaved edit. Local state is NOT
+             * advanced on failure, so the UI keeps showing the true stored state.
+             */
+            const detail = res.status === 403
+                ? "You do not have permission to change this page's composition."
+                : `Save failed (${res.status}).`;
+            throw new Error(detail);
+        }
+        setLocal(next);
+        /*
+         * A full reload rather than a client-side re-render: the rails are
+         * SERVER-rendered from the stored config, so the only way to see the
+         * real new output — including anything the resolver's precedence rules
+         * changed about siblings — is to re-render on the server. Optimistically
+         * patching the DOM here would show the admin a composition the server
+         * might not agree with, which is the one thing an in-place editor must
+         * never do.
+         */
+        if (typeof window !== "undefined")
+            window.location.reload();
+    }, [local, regionId]);
+    return (_jsx(WidgetInstanceEditor, { node: node, scopeLabel: scopeLabel, onPatch: onPatch, children: children }));
+}

package/dist/features/dashboard/components/HiddenHubCardGate.d.ts

@@ -0,0 +1,25 @@
+import { useHiddenHubCards } from "../hooks/useHiddenHubCards";
+/**
+ * Wraps one hub card with per-user hide/unhide (Phase 4A). Same SSR/CSR
+ * tradeoff `useSectionState` already accepts elsewhere in this codebase: the
+ * server has no localStorage, so a card the user hid on this device renders
+ * once and then disappears on hydration rather than staying hidden through
+ * the first paint. The durable (profile) copy is what a NEW device reads
+ * from, with no flash at all once it has landed.
+ */
+export declare function HiddenHubCardGate({ scope, cardKey, children, }: {
+    /** `"{portal}:hub"` — must match the scope the page's own hook instance uses. */
+    scope: string;
+    cardKey: string;
+    children: React.ReactNode;
+}): import("react").JSX.Element | null;
+/**
+ * "N cards hidden — show all" for the cards THIS page actually renders —
+ * `allCardKeys` scopes the restore to what's on screen, so a stray hidden
+ * key from a since-removed card does not report a phantom count forever.
+ */
+export declare function HiddenHubCardsRestoreBar({ scope, allCardKeys, }: {
+    scope: string;
+    allCardKeys: string[];
+}): import("react").JSX.Element | null;
+export { useHiddenHubCards };

package/dist/features/dashboard/components/HiddenHubCardGate.js

@@ -0,0 +1,44 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useHiddenHubCards } from "../hooks/useHiddenHubCards.js";
+import { IconButton } from "../../../ui/components/IconButton.js";
+import { Icon } from "../../../ui/components/Icon.js";
+import { Div } from "../../../ui/components/Div.js";
+import { Row } from "../../../ui/components/Layout.js";
+import { Text } from "../../../ui/components/Typography.js";
+import { TextLink } from "../../../ui/components/TextLink.js";
+/**
+ * Wraps one hub card with per-user hide/unhide (Phase 4A). Same SSR/CSR
+ * tradeoff `useSectionState` already accepts elsewhere in this codebase: the
+ * server has no localStorage, so a card the user hid on this device renders
+ * once and then disappears on hydration rather than staying hidden through
+ * the first paint. The durable (profile) copy is what a NEW device reads
+ * from, with no flash at all once it has landed.
+ */
+export function HiddenHubCardGate({ scope, cardKey, children, }) {
+    const { isHidden, hide } = useHiddenHubCards(scope);
+    if (isHidden(cardKey))
+        return null;
+    return (_jsxs(Div, { className: "group/hub-card relative", children: [children, _jsx(IconButton, { size: "sm", "aria-label": "Hide this card", className: "absolute top-2 right-2 opacity-0 group-hover/hub-card:opacity-100 focus-visible:opacity-100 transition-opacity", onClick: (e) => {
+                    e.preventDefault();
+                    e.stopPropagation();
+                    hide(cardKey);
+                }, children: _jsx(Icon, { name: "hide", size: "sm" }) })] }));
+}
+/**
+ * "N cards hidden — show all" for the cards THIS page actually renders —
+ * `allCardKeys` scopes the restore to what's on screen, so a stray hidden
+ * key from a since-removed card does not report a phantom count forever.
+ */
+export function HiddenHubCardsRestoreBar({ scope, allCardKeys, }) {
+    const { hiddenKeys, unhide } = useHiddenHubCards(scope);
+    const hiddenHere = hiddenKeys.filter((k) => allCardKeys.includes(k));
+    if (hiddenHere.length === 0)
+        return null;
+    return (_jsxs(Row, { gap: "xs", align: "center", children: [_jsxs(Text, { size: "sm", color: "muted", children: [hiddenHere.length, " card", hiddenHere.length === 1 ? "" : "s", " hidden."] }), _jsx(TextLink, { href: "#", onClick: (e) => {
+                    e.preventDefault();
+                    for (const key of hiddenHere)
+                        unhide(key);
+                }, children: "Show all" })] }));
+}
+export { useHiddenHubCards };

package/dist/features/dashboard/components/RecentVisitTracker.d.ts

@@ -0,0 +1,35 @@
+export interface RecentVisitTrackerGroup {
+    title: string;
+    items: {
+        href: string;
+        label: string;
+    }[];
+}
+export interface RecentVisitTrackerProps {
+    /** `"{portal}:hub"` — same scope convention as `useHiddenHubCards` / `DashboardQuickJump`. */
+    scope: string;
+    /** The portal's full nav — used only to confirm the current path IS a tagged screen. */
+    groups: RecentVisitTrackerGroup[];
+    /**
+     * The portal's OWN dashboard-landing href (`/admin`, `/store`, `/user`) —
+     * never recorded, even though it is also a real nav item (admin's "All
+     * sections" points at `/admin`). Landing on the search page is not a
+     * deliberate "jump to X"; recording it anyway meant a completely fresh
+     * profile's first-ever visit silently overrode the curated cold-start
+     * defaults with a single, circular "All sections → /admin" card instead
+     * of the intended starting set. Found live, 2026-11-01.
+     */
+    excludeHref: string;
+}
+/**
+ * Render-nothing. Mounted once per portal layout (beside `CommandPaletteMount`
+ * / `AdminCommandPaletteMount`), it records a `kind: "page"` entry whenever
+ * the pathname EXACTLY matches a tagged nav item's `href` — Phase 9, overhaul
+ * brief.
+ *
+ * 🛑 An exact match only, on purpose. A dynamic detail page (`/admin/users/abc123`,
+ * `/store/products/xyz`) is not itself a nav item — recording every one of
+ * those would flood the ten-card cap with one-off visits instead of the
+ * screens the owner actually meant: *"save the last visited as a card…"*.
+ */
+export declare function RecentVisitTracker({ scope, groups, excludeHref }: RecentVisitTrackerProps): null;

package/dist/features/dashboard/components/RecentVisitTracker.js

@@ -0,0 +1,33 @@
+"use client";
+import { useEffect, useRef } from "react";
+import { usePathname } from "next/navigation.js";
+import { useRecentlyVisited } from "../hooks/useRecentlyVisited.js";
+/**
+ * Render-nothing. Mounted once per portal layout (beside `CommandPaletteMount`
+ * / `AdminCommandPaletteMount`), it records a `kind: "page"` entry whenever
+ * the pathname EXACTLY matches a tagged nav item's `href` — Phase 9, overhaul
+ * brief.
+ *
+ * 🛑 An exact match only, on purpose. A dynamic detail page (`/admin/users/abc123`,
+ * `/store/products/xyz`) is not itself a nav item — recording every one of
+ * those would flood the ten-card cap with one-off visits instead of the
+ * screens the owner actually meant: *"save the last visited as a card…"*.
+ */
+export function RecentVisitTracker({ scope, groups, excludeHref }) {
+    const pathname = usePathname();
+    const { recordVisit } = useRecentlyVisited(scope);
+    const lastRecorded = useRef(null);
+    useEffect(() => {
+        if (!pathname || pathname === lastRecorded.current || pathname === excludeHref)
+            return;
+        for (const group of groups) {
+            const match = group.items.find((item) => item.href === pathname);
+            if (match) {
+                recordVisit({ kind: "page", href: match.href, label: match.label });
+                lastRecorded.current = pathname;
+                return;
+            }
+        }
+    }, [pathname, groups, excludeHref, recordVisit]);
+    return null;
+}

package/dist/features/dashboard/components/WidgetInstanceEditor.d.ts

@@ -0,0 +1,91 @@
+import type { ResolvedWidget, WidgetInstance } from "../../../ui/widgets/types";
+import type { ReactNode } from "react";
+/**
+ * In-place widget editing — the owner's requirement, 2026-11-08:
+ * *"i need a homepage edit mode as well where the admin can flip a toggle on
+ * the navbar to edit the site in place"*.
+ *
+ * ---------------------------------------------------------------------------
+ * 🛑 THIS IS NOT A NEW EDIT MODE. IT EXTENDS THE ONE THAT ALREADY EXISTS.
+ * ---------------------------------------------------------------------------
+ *
+ * The toggle and its state machine were already built and already mounted:
+ *   - `_internal/client/edit-mode/EditModeProvider.tsx` — the state, with
+ *     `canUseEditMode` already driving whether a toggle renders at all, and
+ *     `enabled` already forcing `editMode` to false for a session that may
+ *     not edit ("a buyer cannot reach edit affordances by any client-side
+ *     code path").
+ *   - `edit-mode/index.ts` — its canonical PUBLIC barrel. It is a 12-line
+ *     re-export, deliberately, mirroring `hand-mode/index.ts` so
+ *     `audit-appkit-reexports` (no `_internal/` in public barrels) stays
+ *     green. 🚩 It is NOT an unimplemented stub, and nothing new should be
+ *     homed in it.
+ *   - `features/layout/EditModeToggle.tsx` — the navbar/titlebar toggle,
+ *     mounted via `TitleBarLayout`'s `editModeSlot` from
+ *     `LayoutShellClient.tsx`.
+ *   - `AdminComposableRegion` and `SectionVisibilityGate` already consume
+ *     `useEditMode()` and already render the dimmed "hidden" affordance.
+ *
+ * So the missing piece was never the toggle — it was that a resolved WIDGET
+ * INSTANCE had no in-place affordance. That is all this component adds.
+ *
+ * ---------------------------------------------------------------------------
+ * WHAT IT ENFORCES, AND WHY EACH ONE IS NOT OPTIONAL
+ * ---------------------------------------------------------------------------
+ *
+ * 1. `removable: false` is REFUSED WITH A REASON, never silently no-opped.
+ *    An in-place editor is precisely where someone tries to delete the price,
+ *    and A16 is explicit: price, condition, authenticity, the risk banner and
+ *    consent "may be restyled, never hidden". A disabled button with no
+ *    explanation reads as a broken UI; a button that appears to work and does
+ *    nothing is worse.
+ *
+ * 2. A child inside a BLOCKED PARENT is shown as unreachable, and its
+ *    "enable" is refused. The owner ruled parent-wins, and the rationale was
+ *    that switching a region off must GUARANTEE it is gone because this sits
+ *    next to permissions. Letting someone flip a child to `on` and believe it
+ *    worked would quietly break that guarantee — so the editor says
+ *    "its container is off" instead of pretending.
+ *
+ * 3. It states, on screen, that an edit is TEMPLATE-WIDE. This is the
+ *    invariant the whole cost model rests on (~5,210 keys bounded by code vs
+ *    ~60,000 bounded by data). An admin editing the rail on one product page
+ *    is editing it for EVERY product, and an editor that does not say so
+ *    invites exactly the per-product expectation that breaks the model.
+ */
+export interface WidgetInstanceEditorProps {
+    /** The resolved node this affordance belongs to. */
+    node: ResolvedWidget;
+    /** Human-readable scope, e.g. "every product page". Shown so template-wide editing is never a surprise. */
+    scopeLabel: string;
+    /** Persist a patch. Field-wise — see `WidgetEditPatch`. */
+    onPatch: (id: string, patch: WidgetEditPatch) => Promise<void> | void;
+    /** The widget's own rendered output. */
+    children: ReactNode;
+}
+/**
+ * A FIELD-WISE patch, never a whole row.
+ *
+ * 🛑 Omitted keys must stay untouched all the way to storage. A whole-row
+ * write is the `HomepageSectionsRepository` failure, whose own comment records
+ * that "every config key a caller omitted was silently deleted" behind an HTTP
+ * 200 — and here the partial patch is the COMMON case (switching one rail off
+ * is a single field), not an edge case.
+ */
+export interface WidgetEditPatch {
+    state?: "on" | "off";
+    order?: number;
+    config?: Record<string, unknown>;
+}
+export declare function WidgetInstanceEditor({ node, scopeLabel, onPatch, children, }: WidgetInstanceEditorProps): import("react").JSX.Element;
+/**
+ * Apply a field-wise patch to a client-held instance list, for optimistic
+ * rendering before the PUT lands.
+ *
+ * Kept here next to the editor rather than in `ui/widgets/merge.ts` because
+ * that module is the SERVER-side defaults⊕stored merge; this is the much
+ * narrower "one row, one patch" case the editor needs. Same field-wise rule
+ * though — `config` merges one level so a changed title keeps the row's
+ * `source`.
+ */
+export declare function applyEditPatch(instances: readonly WidgetInstance[], id: string, patch: WidgetEditPatch): WidgetInstance[];