@object-ui/app-shell 6.1.0 → 6.2.1

package/dist/console/marketplace/usePackageL10n.js

@@ -0,0 +1,110 @@
+/**
+ * usePackageL10n
+ *
+ * Resolves a marketplace package's translatable fields against the
+ * current i18n locale. Mirrors the server-side resolver
+ * `resolvePackageL10n` in @objectstack/spec/cloud but stays inline here
+ * so the app-shell doesn't pull the full spec package into its bundle.
+ *
+ * Resolution chain (first hit wins):
+ *   1. translations[<exact requested locale>]   (e.g. `zh-CN`)
+ *   2. translations[<language-only locale>]     (e.g. `zh`)
+ *   3. translations[<fallback locale>]          (default `en`)
+ *   4. base column on the package row           (snake_case from REST)
+ */
+import { useMemo } from 'react';
+import { useObjectTranslation } from '@object-ui/i18n';
+const FALLBACK_LOCALE = 'en';
+function languageOf(locale) {
+    const dash = locale.indexOf('-');
+    return dash === -1 ? locale : locale.slice(0, dash);
+}
+function uniqueLocales(codes) {
+    const seen = new Set();
+    const out = [];
+    for (const c of codes) {
+        if (!c || seen.has(c))
+            continue;
+        seen.add(c);
+        out.push(c);
+    }
+    return out;
+}
+function pickFromTranslations(translations, locale, field) {
+    if (!translations)
+        return undefined;
+    const lang = languageOf(locale);
+    // Build chain: exact → language-only → any regional variant matching the
+    // language (e.g. 'zh' → 'zh-CN' / 'zh-Hans') → fallback. The regional
+    // expansion covers the common case where the i18n provider returns a
+    // bare language code ('zh') but package manifests ship region-tagged
+    // translations ('zh-CN').
+    const variants = Object.keys(translations).filter((code) => code === lang || code.startsWith(`${lang}-`));
+    const chain = uniqueLocales([locale, lang, ...variants, FALLBACK_LOCALE]);
+    for (const code of chain) {
+        const entry = translations[code];
+        if (!entry)
+            continue;
+        const value = entry[field];
+        if (typeof value === 'string' && value.length > 0)
+            return value;
+    }
+    return undefined;
+}
+function baseColumn(pkg, field) {
+    // Map camelCase L10n field → REST snake_case column.
+    const SNAKE = {
+        displayName: 'display_name',
+        description: 'description',
+        readme: 'readme',
+        tagline: 'tagline',
+        // Captions live only inside translations on the wire — no base column.
+        screenshotCaptions: 'screenshotCaptions',
+    };
+    const v = pkg[SNAKE[field]] ?? pkg[field];
+    return typeof v === 'string' && v.length > 0 ? v : undefined;
+}
+/**
+ * Resolve `displayName`, `description`, `readme`, and `tagline` for a
+ * package against the active locale. `displayName` is guaranteed to be
+ * a non-empty string (falls back to `manifest_id` as a last resort) so
+ * callers can render it without further guards.
+ */
+export function usePackageL10n(pkg) {
+    const { language } = useObjectTranslation();
+    return useMemo(() => {
+        if (!pkg) {
+            return { displayName: '', description: undefined, readme: undefined, tagline: undefined };
+        }
+        const locale = language || FALLBACK_LOCALE;
+        const displayName = pickFromTranslations(pkg.translations ?? undefined, locale, 'displayName')
+            ?? baseColumn(pkg, 'displayName')
+            ?? pkg.manifest_id;
+        const description = pickFromTranslations(pkg.translations ?? undefined, locale, 'description')
+            ?? baseColumn(pkg, 'description');
+        const readme = pickFromTranslations(pkg.translations ?? undefined, locale, 'readme')
+            ?? baseColumn(pkg, 'readme');
+        const tagline = pickFromTranslations(pkg.translations ?? undefined, locale, 'tagline')
+            ?? baseColumn(pkg, 'tagline');
+        return { displayName, description, readme, tagline };
+    }, [pkg, language]);
+}
+/**
+ * Stateless variant for use in `.map()` over a list of packages where
+ * calling `usePackageL10n` per row would violate the rules of hooks.
+ * The caller passes the language they obtained once from
+ * `useObjectTranslation()` at the top of the component.
+ */
+export function localizePackage(pkg, language) {
+    const locale = language || FALLBACK_LOCALE;
+    const displayName = pickFromTranslations(pkg.translations ?? undefined, locale, 'displayName')
+        ?? baseColumn(pkg, 'displayName')
+        ?? pkg.manifest_id;
+    const description = pickFromTranslations(pkg.translations ?? undefined, locale, 'description')
+        ?? baseColumn(pkg, 'description');
+    const readme = pickFromTranslations(pkg.translations ?? undefined, locale, 'readme')
+        ?? baseColumn(pkg, 'readme');
+    const tagline = pickFromTranslations(pkg.translations ?? undefined, locale, 'tagline')
+        ?? baseColumn(pkg, 'tagline');
+    return { displayName, description, readme, tagline };
+}

package/dist/console/organizations/CreateWorkspaceDialog.js

@@ -24,12 +24,34 @@ function nameToSlug(name) {
 }
 export function CreateWorkspaceDialog({ open, onOpenChange, onCreated, }) {
     const { t } = useObjectTranslation();
-    const { createOrganization } = useAuth();
+    const { createOrganization, getAuthConfig } = useAuth();
     const [name, setName] = useState('');
     const [slug, setSlug] = useState('');
     const [slugManuallyEdited, setSlugManuallyEdited] = useState(false);
     const [isSubmitting, setIsSubmitting] = useState(false);
     const [error, setError] = useState(null);
+    // Defense-in-depth: the toolbar button that opens this dialog is already
+    // hidden when `multiOrgEnabled === false`, but if a future caller opens the
+    // dialog by another path we still want to fail fast with a friendly message
+    // instead of bouncing off the server's FORBIDDEN.
+    const [multiOrgDisabled, setMultiOrgDisabled] = useState(false);
+    useEffect(() => {
+        if (!open)
+            return;
+        let cancelled = false;
+        getAuthConfig()
+            .then((cfg) => {
+            if (cancelled)
+                return;
+            setMultiOrgDisabled(cfg?.features?.multiOrgEnabled === false);
+        })
+            .catch(() => {
+            /* leave default — server still enforces */
+        });
+        return () => {
+            cancelled = true;
+        };
+    }, [open, getAuthConfig]);
     // Auto-generate slug from name (unless manually edited)
     useEffect(() => {
         if (!slugManuallyEdited) {
@@ -49,6 +71,12 @@ export function CreateWorkspaceDialog({ open, onOpenChange, onCreated, }) {
         e.preventDefault();
         if (!name.trim() || !slug.trim())
             return;
+        if (multiOrgDisabled) {
+            setError(t('workspace.multiOrgDisabled', {
+                defaultValue: 'Creating new organizations is disabled on this instance.',
+            }));
+            return;
+        }
         setIsSubmitting(true);
         setError(null);
         try {

package/dist/console/organizations/OrganizationsPage.js

@@ -26,10 +26,31 @@ function getOrgInitials(name) {
 export function OrganizationsPage() {
     const { t } = useObjectTranslation();
     const navigate = useNavigate();
-    const { organizations, activeOrganization, isOrganizationsLoading, switchOrganization, } = useAuth();
+    const { organizations, activeOrganization, isOrganizationsLoading, switchOrganization, getAuthConfig, } = useAuth();
     const [query, setQuery] = useState('');
     const [isCreateOpen, setIsCreateOpen] = useState(false);
     const [switchingId, setSwitchingId] = useState(null);
+    // `multiOrgEnabled === false` ⇒ server-side `beforeCreateOrganization` hook
+    // blocks creation. Mirror that in the UI so users don't see a button that
+    // only ever fails. Default to allowing creation until we've heard back so
+    // we don't briefly hide the button on slow networks.
+    const [canCreateOrg, setCanCreateOrg] = useState(true);
+    useEffect(() => {
+        let cancelled = false;
+        getAuthConfig()
+            .then((cfg) => {
+            if (cancelled)
+                return;
+            if (cfg?.features?.multiOrgEnabled === false)
+                setCanCreateOrg(false);
+        })
+            .catch(() => {
+            /* leave default — server will still enforce */
+        });
+        return () => {
+            cancelled = true;
+        };
+    }, [getAuthConfig]);
     const orgList = organizations ?? [];
     const filtered = useMemo(() => {
         const q = query.trim().toLowerCase();
@@ -87,9 +108,9 @@ export function OrganizationsPage() {
                             defaultValue: 'Select an organization to continue, or create a new one.',
                         }) })] }), _jsxs("div", { className: "mb-6 flex flex-col gap-3 sm:flex-row sm:items-center sm:justify-between", children: [_jsxs("div", { className: "relative w-full sm:max-w-sm", children: [_jsx(Search, { className: "pointer-events-none absolute left-3 top-1/2 h-4 w-4 -translate-y-1/2 text-muted-foreground" }), _jsx(Input, { value: query, onChange: (e) => setQuery(e.target.value), placeholder: t('organizations.searchPlaceholder', {
                                     defaultValue: 'Search for an organization',
-                                }), className: "pl-9", "data-testid": "organizations-search" })] }), _jsxs(Button, { onClick: () => setIsCreateOpen(true), "data-testid": "organizations-new", children: [_jsx(Plus, { className: "mr-2 h-4 w-4" }), t('organizations.new', { defaultValue: 'New organization' })] })] }), orgList.length === 0 ? (_jsxs(Empty, { children: [_jsx(EmptyTitle, { children: t('organizations.emptyTitle', { defaultValue: 'No organizations yet' }) }), _jsx(EmptyDescription, { children: t('organizations.emptyDescription', {
+                                }), className: "pl-9", "data-testid": "organizations-search" })] }), canCreateOrg && (_jsxs(Button, { onClick: () => setIsCreateOpen(true), "data-testid": "organizations-new", children: [_jsx(Plus, { className: "mr-2 h-4 w-4" }), t('organizations.new', { defaultValue: 'New organization' })] }))] }), orgList.length === 0 ? (_jsxs(Empty, { children: [_jsx(EmptyTitle, { children: t('organizations.emptyTitle', { defaultValue: 'No organizations yet' }) }), _jsx(EmptyDescription, { children: t('organizations.emptyDescription', {
                             defaultValue: 'Create your first organization to get started.',
-                        }) }), _jsxs(Button, { className: "mt-6", onClick: () => setIsCreateOpen(true), children: [_jsx(Plus, { className: "mr-2 h-4 w-4" }), t('organizations.new', { defaultValue: 'New organization' })] })] })) : filtered.length === 0 ? (_jsx("div", { className: "rounded-lg border border-dashed p-8 text-center text-sm text-muted-foreground", children: t('organizations.noMatches', {
+                        }) }), canCreateOrg && (_jsxs(Button, { className: "mt-6", onClick: () => setIsCreateOpen(true), children: [_jsx(Plus, { className: "mr-2 h-4 w-4" }), t('organizations.new', { defaultValue: 'New organization' })] }))] })) : filtered.length === 0 ? (_jsx("div", { className: "rounded-lg border border-dashed p-8 text-center text-sm text-muted-foreground", children: t('organizations.noMatches', {
                     defaultValue: 'No organizations match your search.',
                 }) })) : (_jsx("div", { className: "grid grid-cols-1 gap-3 sm:grid-cols-2", children: filtered.map((org) => {
                     const isActive = org.id === activeOrganization?.id;

package/dist/context/FavoritesProvider.d.ts

@@ -18,13 +18,35 @@
  */
 import { type ReactNode } from 'react';
 export interface FavoriteItem {
-    /** Unique key, e.g. "object:contact" or "dashboard:sales_overview" */
+    /** Unique key, e.g. "object:contact" or "dashboard:sales_overview" or "nav:<navId>" */
     id: string;
     label: string;
     href: string;
-    type: 'object' | 'dashboard' | 'page' | 'report' | 'record';
+    /**
+     * Item kind.
+     *
+     * - `object` / `dashboard` / `page` / `report` / `record` — content favorites
+     *   surfaced on Home (Starred Apps) and the sidebar Favorites section.
+     * - `nav` — a sidebar navigation entry promoted to the "Pinned" position via
+     *   the in-tree pin toggle (see `useNavPins`). Excluded from Home/Starred and
+     *   from the generic sidebar Favorites list so it doesn't render twice.
+     */
+    type: 'object' | 'dashboard' | 'page' | 'report' | 'record' | 'nav';
     /** ISO timestamp of when the item was favorited */
     favoritedAt: string;
+    /**
+     * When true, the item is pinned to the top of the sidebar (Pinned section).
+     * `nav`-type items are always pinned by construction; other types may also
+     * carry this flag if the user explicitly promotes a content favorite — that
+     * behaviour is reserved for a future iteration.
+     */
+    pinned?: boolean;
+    /**
+     * For `type === 'nav'` items: the originating `NavigationItem.id` in the
+     * application's nav tree. Used by `useNavPins.applyPins` to flag the live
+     * tree node without leaking the synthesized favorite into other UIs.
+     */
+    navId?: string;
 }
 interface FavoritesContextValue {
     favorites: FavoriteItem[];
@@ -40,6 +62,22 @@ interface FavoritesContextValue {
      * loaded) get rewritten transparently on the next visit.
      */
     refreshLabel: (id: string, label: string) => void;
+    /**
+     * Flip the `pinned` flag on an existing favorite. No-op if the id is not
+     * present. Used by `useNavPins` for nav-tree pin toggles backed by the
+     * unified favorites store (same backend sync channel).
+     */
+    setPinned: (id: string, pinned: boolean) => void;
+    /**
+     * Returns true when a favorite with the given id is currently `pinned`.
+     * Use `isFavorite` for membership-only queries.
+     */
+    isPinned: (id: string) => boolean;
+    /**
+     * Set of NavigationItem ids that are currently pinned via a `type === 'nav'`
+     * favorite. Memoised; safe to use as a dependency.
+     */
+    pinnedNavIds: Set<string>;
 }
 interface FavoritesProviderProps {
     children: ReactNode;

package/dist/context/FavoritesProvider.js

@@ -24,7 +24,55 @@ import { createDebouncedFlush, scopedKey, useStorageSync, useUserStateAdapter, }
 // Storage helpers
 // ---------------------------------------------------------------------------
 const STORAGE_BASE_KEY = 'objectui-favorites';
+/** Legacy key used by the standalone `useNavPins` hook before it was merged
+ * into Favorites. Migrated once at provider mount, then deleted. */
+const LEGACY_NAV_PINS_KEY = 'objectui-nav-pins';
+/** Cap for user-visible content favorites (object/dashboard/page/report/record). */
 const MAX_FAVORITES = 20;
+/** Independent cap for nav-pin favorites — they live in a separate bucket. */
+const MAX_NAV_PINS = 20;
+/**
+ * Enforce per-bucket caps while preserving order within each bucket. Content
+ * favorites (`type !== 'nav'`) cap at `MAX_FAVORITES`; nav-pin favorites
+ * (`type === 'nav'`) cap at `MAX_NAV_PINS`. Returns the original array when
+ * neither bucket overflows so memoized consumers aren't invalidated.
+ */
+function capByBucket(items) {
+    let contentCount = 0;
+    let navCount = 0;
+    let overflowed = false;
+    for (const it of items) {
+        if (it.type === 'nav') {
+            navCount++;
+            if (navCount > MAX_NAV_PINS)
+                overflowed = true;
+        }
+        else {
+            contentCount++;
+            if (contentCount > MAX_FAVORITES)
+                overflowed = true;
+        }
+    }
+    if (!overflowed)
+        return items;
+    const result = [];
+    let c = 0, n = 0;
+    for (const it of items) {
+        if (it.type === 'nav') {
+            if (n < MAX_NAV_PINS) {
+                result.push(it);
+                n++;
+            }
+        }
+        else {
+            if (c < MAX_FAVORITES) {
+                result.push(it);
+                c++;
+            }
+        }
+    }
+    return result;
+}
 function loadFavorites(userId) {
     try {
         const raw = localStorage.getItem(scopedKey(STORAGE_BASE_KEY, userId));
@@ -42,6 +90,69 @@ function saveFavorites(items, userId) {
         // Storage full — silently ignore
     }
 }
+/**
+ * One-shot migration of legacy `objectui-nav-pins` (a `string[]` of
+ * NavigationItem ids) into the unified favorites list as `type: 'nav'`
+ * entries. The label/href fields are placeholders because at migration time
+ * we only have the raw nav id — the live nav tree resolves the real label
+ * when it renders the Pinned section (see `useNavPins.applyPins`).
+ *
+ * Idempotent: runs only when the legacy key exists. Once consumed, the
+ * legacy key is removed so the next launch is a no-op. Existing nav-pinned
+ * favorites (e.g. on a subsequent device after backend hydration) are not
+ * duplicated.
+ */
+function migrateLegacyNavPins(current) {
+    let raw;
+    try {
+        raw = localStorage.getItem(LEGACY_NAV_PINS_KEY);
+    }
+    catch {
+        return { migrated: current, didMigrate: false };
+    }
+    if (!raw)
+        return { migrated: current, didMigrate: false };
+    let legacyIds = [];
+    try {
+        const parsed = JSON.parse(raw);
+        if (Array.isArray(parsed)) {
+            legacyIds = parsed.filter((id) => typeof id === 'string');
+        }
+    }
+    catch {
+        /* fall through — treat as empty */
+    }
+    // Always clear the legacy key, even on empty/corrupt payload, so we never
+    // re-enter this branch on the next mount.
+    try {
+        localStorage.removeItem(LEGACY_NAV_PINS_KEY);
+    }
+    catch { /* noop */ }
+    if (legacyIds.length === 0)
+        return { migrated: current, didMigrate: false };
+    const existingNavIds = new Set(current.filter(f => f.type === 'nav' && f.navId).map(f => f.navId));
+    const now = new Date().toISOString();
+    const additions = [];
+    for (const navId of legacyIds) {
+        if (existingNavIds.has(navId))
+            continue;
+        additions.push({
+            id: `nav:${navId}`,
+            label: navId, // placeholder — sidebar uses live nav tree label
+            href: '', // placeholder — sidebar uses live nav tree href
+            type: 'nav',
+            navId,
+            pinned: true,
+            favoritedAt: now,
+        });
+    }
+    if (additions.length === 0)
+        return { migrated: current, didMigrate: true };
+    // Nav pins do not count against the user-visible favorites cap — they are
+    // a separate logical bucket. Append after content favorites so a user with
+    // 20 stars keeps them all visible on Home/Starred.
+    return { migrated: [...current, ...additions], didMigrate: true };
+}
 // ---------------------------------------------------------------------------
 // Context
 // ---------------------------------------------------------------------------
@@ -61,12 +172,15 @@ export function FavoritesProvider({ children }) {
     // so this never echoes our own mutations.
     useStorageSync(scopedKey(STORAGE_BASE_KEY, userId), value => {
         setFavorites(Array.isArray(value)
-            ? value.filter(it => it && typeof it.id === 'string').slice(0, MAX_FAVORITES)
+            ? capByBucket(value.filter(it => it && typeof it.id === 'string'))
             : []);
     });
     // Hydrate from backend whenever an adapter is attached (or user changes).
-    // Backend wins on conflict; we then write through to localStorage so the
-    // next reload is instant.
+    // Backend is the baseline, but we *merge in* any locally-known nav-pin
+    // favorites the backend doesn't have yet — this preserves pins added
+    // offline / pre-auth, and pins recovered from the legacy `objectui-nav-pins`
+    // key by the offline migration effect below. Legacy migration also runs
+    // here as a safety net if the offline effect hasn't yet fired in time.
     const hydrationToken = useRef(0);
     useEffect(() => {
         if (!adapter)
@@ -79,11 +193,28 @@ export function FavoritesProvider({ children }) {
                 if (cancelled || token !== hydrationToken.current)
                     return;
                 // Defensive sanitize: drop unparseable shapes, enforce cap.
-                const sane = (Array.isArray(remote) ? remote : [])
-                    .filter(it => it && typeof it.id === 'string')
-                    .slice(0, MAX_FAVORITES);
-                setFavorites(sane);
-                saveFavorites(sane, userId);
+                const sane = capByBucket((Array.isArray(remote) ? remote : []).filter(it => it && typeof it.id === 'string'));
+                // Re-read the local snapshot — it may contain nav-pin favorites that
+                // were added (or migrated) before the adapter arrived. Without this
+                // merge, signing in would silently wipe a user's offline pins.
+                const local = loadFavorites(userId);
+                const remoteNavIds = new Set(sane.filter(f => f.type === 'nav' && f.navId).map(f => f.navId));
+                const localNavExtras = local.filter(f => f.type === 'nav' && f.navId && !remoteNavIds.has(f.navId));
+                let merged = sane;
+                let pushBack = false;
+                if (localNavExtras.length > 0) {
+                    merged = capByBucket([...sane, ...localNavExtras]);
+                    pushBack = true;
+                }
+                const { migrated, didMigrate } = migrateLegacyNavPins(merged);
+                if (didMigrate) {
+                    merged = capByBucket(migrated);
+                    pushBack = true;
+                }
+                setFavorites(merged);
+                saveFavorites(merged, userId);
+                if (pushBack)
+                    flusher.schedule(merged);
             }
             catch {
                 // Keep localStorage state — adapter degrade-to-noop is acceptable.
@@ -93,6 +224,22 @@ export function FavoritesProvider({ children }) {
             cancelled = true;
         };
     }, [adapter, userId]);
+    // Offline / pre-auth migration: when there is no adapter to push to, fold
+    // legacy nav-pins into the localStorage baseline immediately so the very
+    // first render after upgrade already includes them. If an adapter later
+    // attaches, the hydrate effect above merges these into the backend.
+    useEffect(() => {
+        if (adapter)
+            return; // adapter path handles migration above
+        setFavorites(prev => {
+            const { migrated, didMigrate } = migrateLegacyNavPins(prev);
+            if (!didMigrate)
+                return prev;
+            const next = capByBucket(migrated);
+            saveFavorites(next, userId);
+            return next;
+        });
+    }, [adapter, userId]);
     // Debounced write-through to backend.
     const flusher = useMemo(() => createDebouncedFlush(async (items) => {
         if (adapter)
@@ -109,10 +256,10 @@ export function FavoritesProvider({ children }) {
         setFavorites(prev => {
             if (prev.some(f => f.id === item.id))
                 return prev;
-            const updated = [
+            const updated = capByBucket([
                 { ...item, favoritedAt: new Date().toISOString() },
                 ...prev,
-            ].slice(0, MAX_FAVORITES);
+            ]);
             commit(updated);
             return updated;
         });
@@ -129,7 +276,10 @@ export function FavoritesProvider({ children }) {
             const exists = prev.some(f => f.id === item.id);
             const updated = exists
                 ? prev.filter(f => f.id !== item.id)
-                : [{ ...item, favoritedAt: new Date().toISOString() }, ...prev].slice(0, MAX_FAVORITES);
+                : capByBucket([
+                    { ...item, favoritedAt: new Date().toISOString() },
+                    ...prev,
+                ]);
             commit(updated);
             return updated;
         });
@@ -156,15 +306,43 @@ export function FavoritesProvider({ children }) {
             return updated;
         });
     }, [commit]);
-    const value = useMemo(() => ({
-        favorites,
-        addFavorite,
-        removeFavorite,
-        toggleFavorite,
-        isFavorite: (id) => favorites.some(f => f.id === id),
-        clearFavorites,
-        refreshLabel,
-    }), [favorites, addFavorite, removeFavorite, toggleFavorite, clearFavorites, refreshLabel]);
+    const setPinned = useCallback((id, pinned) => {
+        setFavorites(prev => {
+            let changed = false;
+            const updated = prev.map(f => {
+                if (f.id !== id)
+                    return f;
+                const cur = !!f.pinned;
+                if (cur === pinned)
+                    return f;
+                changed = true;
+                return { ...f, pinned };
+            });
+            if (!changed)
+                return prev;
+            commit(updated);
+            return updated;
+        });
+    }, [commit]);
+    const value = useMemo(() => {
+        const pinnedNavIds = new Set();
+        for (const f of favorites) {
+            if (f.pinned && f.type === 'nav' && f.navId)
+                pinnedNavIds.add(f.navId);
+        }
+        return {
+            favorites,
+            addFavorite,
+            removeFavorite,
+            toggleFavorite,
+            isFavorite: (id) => favorites.some(f => f.id === id),
+            clearFavorites,
+            refreshLabel,
+            setPinned,
+            isPinned: (id) => favorites.some(f => f.id === id && !!f.pinned),
+            pinnedNavIds,
+        };
+    }, [favorites, addFavorite, removeFavorite, toggleFavorite, clearFavorites, refreshLabel, setPinned]);
     return (_jsx(FavoritesContext.Provider, { value: value, children: children }));
 }
 // ---------------------------------------------------------------------------
@@ -189,6 +367,9 @@ export function useFavorites() {
             isFavorite: () => false,
             clearFavorites: () => { },
             refreshLabel: () => { },
+            setPinned: () => { },
+            isPinned: () => false,
+            pinnedNavIds: new Set(),
         };
     }
     return ctx;

package/dist/hooks/index.d.ts

@@ -8,3 +8,4 @@ export { useRecordApprovals, type ApprovalProcessLite, type ApprovalRequestLite
 export { useResponsiveSidebar } from './useResponsiveSidebar';
 export { useTrackRouteAsRecent, type UseTrackRouteAsRecentOptions } from './useTrackRouteAsRecent';
 export { useChatConversation, type HydratedUIMessage, type UseChatConversationOptions, type UseChatConversationReturn, } from './useChatConversation';
+export { useConversationList, type ConversationSummary, type UseConversationListOptions, type UseConversationListReturn, } from './useConversationList';

package/dist/hooks/index.js

@@ -8,3 +8,4 @@ export { useRecordApprovals } from './useRecordApprovals';
 export { useResponsiveSidebar } from './useResponsiveSidebar';
 export { useTrackRouteAsRecent } from './useTrackRouteAsRecent';
 export { useChatConversation, } from './useChatConversation';
+export { useConversationList, } from './useConversationList';

package/dist/hooks/useChatConversation.d.ts

@@ -20,6 +20,13 @@ export interface UseChatConversationOptions {
      * `${apiBase}/conversations[/...]`. Required.
      */
     apiBase: string;
+    /**
+     * Explicit conversation id to hydrate. When provided the cache is bypassed
+     * and the hook fetches this conversation directly; falls back to creating a
+     * fresh one if the server returns 404/403. When omitted the hook keeps its
+     * original cache-first / create-on-miss behaviour.
+     */
+    activeId?: string;
 }
 export interface UseChatConversationReturn {
     conversationId: string | undefined;

package/dist/hooks/useChatConversation.js

@@ -100,11 +100,15 @@ async function deleteConversation(apiBase, id) {
     });
 }
 export function useChatConversation(options) {
-    const { userId, scope, apiBase } = options;
+    const { userId, scope, apiBase, activeId } = options;
     const [conversationId, setConversationId] = useState(undefined);
     const [initialMessages, setInitialMessages] = useState([]);
     const [isLoading, setIsLoading] = useState(Boolean(userId));
     const mountedRef = useRef(true);
+    // Tracks "we have already resolved a no-activeId conversation for this user".
+    // Prevents creating duplicate conversations when sibling state (e.g. the
+    // page's selected agent / `scope`) transitions during the same /ai visit.
+    const resolvedForUserRef = useRef(undefined);
     useEffect(() => {
         mountedRef.current = true;
         return () => {
@@ -116,6 +120,12 @@ export function useChatConversation(options) {
             setConversationId(undefined);
             setInitialMessages([]);
             setIsLoading(false);
+            resolvedForUserRef.current = undefined;
+            return;
+        }
+        // Already resolved a conversation for this user during the no-activeId
+        // window — don't re-create just because `scope` or another dep changed.
+        if (!activeId && resolvedForUserRef.current === userId && conversationId) {
             return;
         }
         let cancelled = false;
@@ -123,24 +133,42 @@ export function useChatConversation(options) {
         setIsLoading(true);
         (async () => {
             try {
-                const cached = readCache(key);
-                if (cached) {
-                    const existing = await fetchConversation(apiBase, cached);
+                if (activeId) {
+                    const existing = await fetchConversation(apiBase, activeId);
                     if (cancelled)
                         return;
                     if (existing) {
+                        writeCache(key, existing.id);
                         setConversationId(existing.id);
                         setInitialMessages(toUIMessages(existing.messages));
+                        resolvedForUserRef.current = userId;
                         return;
                     }
+                    // Requested id is gone — fall through to create a fresh one.
                     writeCache(key, undefined);
                 }
+                else {
+                    const cached = readCache(key);
+                    if (cached) {
+                        const existing = await fetchConversation(apiBase, cached);
+                        if (cancelled)
+                            return;
+                        if (existing) {
+                            setConversationId(existing.id);
+                            setInitialMessages(toUIMessages(existing.messages));
+                            resolvedForUserRef.current = userId;
+                            return;
+                        }
+                        writeCache(key, undefined);
+                    }
+                }
                 const fresh = await createConversation(apiBase);
                 if (cancelled)
                     return;
                 writeCache(key, fresh.id);
                 setConversationId(fresh.id);
                 setInitialMessages(toUIMessages(fresh.messages));
+                resolvedForUserRef.current = userId;
             }
             catch {
                 if (!cancelled) {
@@ -156,7 +184,11 @@ export function useChatConversation(options) {
         return () => {
             cancelled = true;
         };
-    }, [userId, scope, apiBase]);
+        // `conversationId` intentionally omitted: it's only read inside the
+        // short-circuit guard, which is governed by the ref. Including it would
+        // re-run the effect after we successfully resolved an id.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [userId, scope, apiBase, activeId]);
     const reset = useCallback(async () => {
         if (!userId)
             return;