@nsxbet/admin-sdk 0.5.1 → 0.6.0

package/dist/registry/client/in-memory.js

@@ -11,8 +11,37 @@ const DEFAULT_STORAGE_KEY = '@nsxbet/registry';
  */
 export function createInMemoryRegistryClient(options = {}) {
     const storageKey = options.storageKey ?? DEFAULT_STORAGE_KEY;
+    const versionsKey = `${storageKey}-versions`;
     // Initialize or load storage
     let data = loadStorage(storageKey);
+    function loadVersions() {
+        try {
+            const stored = localStorage.getItem(versionsKey);
+            if (stored)
+                return JSON.parse(stored);
+        }
+        catch { /* ignore */ }
+        return { versions: [], autoIncrement: 0 };
+    }
+    function saveVersions(vData) {
+        try {
+            localStorage.setItem(versionsKey, JSON.stringify(vData));
+        }
+        catch { /* ignore */ }
+    }
+    function recordVersion(registeredModuleId, version, baseUrl, metadata) {
+        const vData = loadVersions();
+        vData.versions.push({
+            id: ++vData.autoIncrement,
+            registeredModuleId,
+            version,
+            baseUrl,
+            publishedAt: new Date().toISOString(),
+            active: false,
+            metadata,
+        });
+        saveVersions(vData);
+    }
     // Apply seed if provided and storage is empty
     // Note: seed is for standalone mode where modules are imported directly (no baseUrl needed)
     if (options.seed && data.modules.length === 0) {
@@ -24,7 +53,7 @@ export function createInMemoryRegistryClient(options = {}) {
                 moduleId: validated.id,
                 baseUrl: '',
                 manifest: validated,
-                navOrder: validated.navOrder ?? data.autoIncrement * 10,
+                navigationOrder: validated.navigationOrder ?? data.autoIncrement * 10,
                 enabled: true,
                 registeredAt: now,
                 updatedAt: now,
@@ -43,7 +72,7 @@ export function createInMemoryRegistryClient(options = {}) {
                 moduleId: validated.id,
                 baseUrl,
                 manifest: validated,
-                navOrder: validated.navOrder ?? data.autoIncrement * 10,
+                navigationOrder: validated.navigationOrder ?? data.autoIncrement * 10,
                 enabled: true,
                 registeredAt: now,
                 updatedAt: now,
@@ -63,10 +92,10 @@ export function createInMemoryRegistryClient(options = {}) {
                 result = result.filter((m) => m.manifest.category === filters.category);
             }
             if (filters?.status) {
-                result = result.filter((m) => m.manifest.status === filters.status);
+                result = result.filter(() => filters.status === 'active');
             }
-            // Sort by navOrder
-            result.sort((a, b) => a.navOrder - b.navOrder);
+            // Sort by navigationOrder
+            result.sort((a, b) => a.navigationOrder - b.navigationOrder);
             return result;
         },
         async find(id) {
@@ -107,7 +136,7 @@ export function createInMemoryRegistryClient(options = {}) {
                 moduleId: validated.id,
                 baseUrl,
                 manifest: validated,
-                navOrder: validated.navOrder ?? data.autoIncrement * 10,
+                navigationOrder: validated.navigationOrder ?? data.autoIncrement * 10,
                 enabled: true,
                 registeredAt: now,
                 updatedAt: now,
@@ -125,12 +154,17 @@ export function createInMemoryRegistryClient(options = {}) {
             const module = data.modules[index];
             const updated = {
                 ...module,
-                ...(updateData.navOrder !== undefined && { navOrder: updateData.navOrder }),
+                ...(updateData.navigationOrder !== undefined && { navigationOrder: updateData.navigationOrder }),
                 ...(updateData.enabled !== undefined && { enabled: updateData.enabled }),
+                ...(updateData.baseUrl !== undefined && { baseUrl: updateData.baseUrl }),
+                ...(updateData.version !== undefined && { version: updateData.version }),
                 updatedAt: new Date().toISOString(),
             };
             data.modules[index] = updated;
             saveStorage(storageKey, data);
+            if (updateData.version !== undefined) {
+                recordVersion(id, updated.version, updated.baseUrl);
+            }
             return updated;
         },
         async delete(id) {
@@ -145,16 +179,71 @@ export function createInMemoryRegistryClient(options = {}) {
         async reorder(order) {
             data = loadStorage(storageKey);
             const now = new Date().toISOString();
-            for (const { id, navOrder } of order) {
+            for (const { id, navigationOrder } of order) {
                 const module = data.modules.find((m) => m.id === id);
                 if (module) {
-                    module.navOrder = navOrder;
+                    module.navigationOrder = navigationOrder;
                     module.updatedAt = now;
                 }
             }
             saveStorage(storageKey, data);
         },
+        async listVersions(id) {
+            data = loadStorage(storageKey);
+            const module = data.modules.find((m) => m.id === id);
+            if (!module) {
+                throw new Error(`Module with id ${id} not found`);
+            }
+            const vData = loadVersions();
+            return vData.versions
+                .filter((v) => v.registeredModuleId === id)
+                .sort((a, b) => new Date(b.publishedAt).getTime() - new Date(a.publishedAt).getTime())
+                .map(({ registeredModuleId: _, ...v }) => ({
+                ...v,
+                active: v.version === module.version,
+            }));
+        },
+        async rollback(id, targetVersion) {
+            data = loadStorage(storageKey);
+            const index = data.modules.findIndex((m) => m.id === id);
+            if (index === -1) {
+                throw new Error(`Module with id ${id} not found`);
+            }
+            const module = data.modules[index];
+            if (module.version === targetVersion) {
+                return module;
+            }
+            const vData = loadVersions();
+            const versionEntry = vData.versions.find((v) => v.registeredModuleId === id && v.version === targetVersion);
+            if (!versionEntry) {
+                throw new Error(`Version ${targetVersion} not found for module ${module.moduleId}`);
+            }
+            const previousVersion = module.version;
+            const updated = {
+                ...module,
+                version: targetVersion,
+                baseUrl: versionEntry.baseUrl,
+                updatedAt: new Date().toISOString(),
+            };
+            data.modules[index] = updated;
+            saveStorage(storageKey, data);
+            recordVersion(id, targetVersion, versionEntry.baseUrl, {
+                rolledBackFrom: previousVersion,
+            });
+            return updated;
+        },
     };
+    function computeLocalVersion(storageData) {
+        const enabledModules = storageData.modules.filter((m) => m.enabled);
+        const maxUpdatedAt = enabledModules.reduce((max, m) => (m.updatedAt > max ? m.updatedAt : max), '');
+        const raw = `${maxUpdatedAt}:${enabledModules.length}`;
+        let hash = 0;
+        for (let i = 0; i < raw.length; i++) {
+            const chr = raw.charCodeAt(i);
+            hash = ((hash << 5) - hash + chr) | 0;
+        }
+        return Math.abs(hash).toString(16).padStart(8, '0');
+    }
     // Catalog operations
     const catalog = {
         async get() {
@@ -175,23 +264,39 @@ export function createInMemoryRegistryClient(options = {}) {
                     team: m.manifest.owners?.team ?? 'unknown',
                     supportChannel: m.manifest.owners?.supportChannel ?? '#general',
                 },
-                status: m.manifest.status ?? 'active',
-                navOrder: m.navOrder,
+                status: 'active',
+                navigationOrder: m.navigationOrder,
                 icon: m.manifest.icon,
+                navigation: m.manifest.navigation ? {
+                    style: m.manifest.navigation.style,
+                    sections: m.manifest.navigation.sections?.map(s => ({
+                        id: s.id,
+                        title: s.label,
+                    })),
+                } : undefined,
                 commands: m.manifest.commands?.map((cmd) => ({
                     id: cmd.id,
                     title: cmd.title,
                     keywords: cmd.keywords,
                     route: cmd.route,
                     icon: cmd.icon,
+                    section: cmd.section,
                 })),
             }));
+            data = loadStorage(storageKey);
             return {
-                version: '1.0.0',
+                version: computeLocalVersion(data),
                 generatedAt: new Date().toISOString(),
                 modules: catalogModules,
             };
         },
+        async version() {
+            data = loadStorage(storageKey);
+            return {
+                version: computeLocalVersion(data),
+                generatedAt: new Date().toISOString(),
+            };
+        },
         // eslint-disable-next-line @typescript-eslint/no-unused-vars
         async getImportMap(_environment) {
             const allModules = await modules.findAll({ enabled: true });

package/dist/registry/client/index.d.ts

@@ -4,4 +4,3 @@
 export type { RegistryClient, ModuleOperations, CatalogOperations } from './interface';
 export { createInMemoryRegistryClient, clearInMemoryRegistry, type InMemoryRegistryOptions, type PreConfiguredModule, } from './in-memory';
 export { createHttpRegistryClient, type HttpRegistryOptions, } from './http';
-//# sourceMappingURL=index.d.ts.map

package/dist/registry/client/interface.d.ts

@@ -4,7 +4,7 @@
  * Defines the interface for registry operations.
  * Can be implemented by in-memory (localStorage) or HTTP clients.
  */
-import type { RegisteredModule, UpdateModuleDto, ReorderModuleDto, ModuleFilters, Catalog, ImportMap, AdminModuleManifest } from '../types';
+import type { RegisteredModule, UpdateModuleDto, ReorderModuleDto, ModuleFilters, Catalog, CatalogVersion, ImportMap, AdminModuleManifest, ModuleVersion } from '../types';
 /**
  * Module operations interface
  */
@@ -42,10 +42,21 @@ export interface ModuleOperations {
      */
     delete(id: number): Promise<void>;
     /**
-     * Reorder modules (batch update navOrder)
-     * @param order Array of id and navOrder pairs
+     * Reorder modules (batch update navigationOrder)
+     * @param order Array of id and navigationOrder pairs
      */
     reorder(order: ReorderModuleDto[]): Promise<void>;
+    /**
+     * List published versions for a module
+     * @param id Module ID
+     */
+    listVersions(id: number): Promise<ModuleVersion[]>;
+    /**
+     * Rollback a module to a previously published version
+     * @param id Module ID
+     * @param targetVersion Version string to roll back to
+     */
+    rollback(id: number, targetVersion: string): Promise<RegisteredModule>;
 }
 /**
  * Catalog operations interface (read-only)
@@ -55,6 +66,11 @@ export interface CatalogOperations {
      * Get the full catalog (denormalized for shell consumption)
      */
     get(): Promise<Catalog>;
+    /**
+     * Get the current catalog version without fetching the full catalog.
+     * Used for lightweight polling to detect changes.
+     */
+    version(): Promise<CatalogVersion>;
     /**
      * Get the import map for a specific environment
      * @param environment Environment name (e.g., 'production', 'local')
@@ -79,8 +95,8 @@ export interface CatalogOperations {
  *
  * // Reorder
  * await registry.modules.reorder([
- *   { id: 1, navOrder: 2 },
- *   { id: 2, navOrder: 1 },
+ *   { id: 1, navigationOrder: 2 },
+ *   { id: 2, navigationOrder: 1 },
  * ]);
  *
  * // Get catalog
@@ -93,4 +109,3 @@ export interface RegistryClient {
     /** Catalog operations (read-only) */
     catalog: CatalogOperations;
 }
-//# sourceMappingURL=interface.d.ts.map

package/dist/registry/index.d.ts

@@ -3,10 +3,13 @@
  *
  * Provides types and clients for module registry management.
  */
-export type { AdminModuleManifest, ModuleCommand, ModulePermissions, ModuleOwners, ModuleStatus, RegisteredModule, UpdateModuleDto, ReorderModuleDto, ModuleFilters, Catalog, CatalogModule, ImportMap, } from './types';
+export type { AdminModuleManifest, ModuleCommand, ModulePermissions, ModuleOwners, RegisteredModule, UpdateModuleDto, ReorderModuleDto, ModuleFilters, Catalog, CatalogModule, CatalogVersion, ImportMap, ModuleVersion, } from './types';
 export { validateManifest, parseManifest } from './types';
 export type { RegistryClient, ModuleOperations, CatalogOperations } from './client';
 export { createInMemoryRegistryClient, clearInMemoryRegistry, createHttpRegistryClient, type InMemoryRegistryOptions, type PreConfiguredModule, type HttpRegistryOptions, } from './client';
+export { CatalogCache, createCachedCatalog, CACHE_SCHEMA_VERSION, CACHE_STORAGE_KEY, DEFAULT_STALE_THRESHOLD_MS, } from './cache';
+export type { CachedCatalogOperations, CachedCatalogOptions, CachedCatalog, RegistryCacheStatus, } from './cache';
+export { useRegistryPolling } from './useRegistryPolling';
+export type { RegistryPollingState, UseRegistryPollingOptions } from './useRegistryPolling';
 export type { RegistryContextValue, AdminShellRegistryProps, } from './AdminShellRegistry';
 export { AdminShellRegistry, useRegistry, useRegistryClient, } from './AdminShellRegistry';
-//# sourceMappingURL=index.d.ts.map

package/dist/registry/index.js

@@ -5,4 +5,8 @@
  */
 export { validateManifest, parseManifest } from './types';
 export { createInMemoryRegistryClient, clearInMemoryRegistry, createHttpRegistryClient, } from './client';
+// Cache
+export { CatalogCache, createCachedCatalog, CACHE_SCHEMA_VERSION, CACHE_STORAGE_KEY, DEFAULT_STALE_THRESHOLD_MS, } from './cache';
+// Polling
+export { useRegistryPolling } from './useRegistryPolling';
 export { AdminShellRegistry, useRegistry, useRegistryClient, } from './AdminShellRegistry';

package/dist/registry/types/index.d.ts

@@ -3,7 +3,6 @@
  *
  * Re-exports all registry-related types.
  */
-export type { AdminModuleManifest, ModuleCommand, ModulePermissions, ModuleOwners, ModuleStatus, } from './manifest';
+export type { AdminModuleManifest, ModuleCommand, ModulePermissions, ModuleOwners, } from './manifest';
 export { validateManifest, parseManifest } from './manifest';
-export type { RegisteredModule, UpdateModuleDto, ReorderModuleDto, ModuleFilters, Catalog, CatalogModule, ImportMap, } from './module';
-//# sourceMappingURL=index.d.ts.map
+export type { RegisteredModule, UpdateModuleDto, ReorderModuleDto, ModuleFilters, Catalog, CatalogModule, CatalogVersion, ImportMap, ModuleVersion, } from './module';

package/dist/registry/types/manifest.d.ts

@@ -4,22 +4,23 @@
  * This interface defines the structure of admin.module.json files
  * that module developers create to register their modules.
  */
+import type { LocalizedField } from '../../i18n/config.js';
 /**
  * Command within a module that can be searched and invoked
  */
 export interface ModuleCommand {
     /** Unique identifier for the command within the module */
     id: string;
-    /** Human-readable title */
-    title: string;
-    /** i18n key for the title (for translation) */
-    titleKey?: string;
+    /** Human-readable title (localized per locale) */
+    title: LocalizedField;
     /** Route path for this command */
     route: string;
     /** Optional Lucide icon name in kebab-case (e.g., "clipboard-list", "file-text") */
     icon?: string;
     /** Keywords for search */
     keywords?: string[];
+    /** Section ID for grouping in stacked navigation */
+    section?: string;
 }
 /**
  * Permission configuration for a module
@@ -43,10 +44,6 @@ export interface ModuleOwners {
     /** Support channel (e.g., Slack channel) */
     supportChannel?: string;
 }
-/**
- * Module status
- */
-export type ModuleStatus = 'active' | 'deprecated' | 'disabled';
 /**
  * Admin Module Manifest
  *
@@ -55,30 +52,30 @@ export type ModuleStatus = 'active' | 'deprecated' | 'disabled';
 export interface AdminModuleManifest {
     /** Unique identifier for the module (e.g., "@admin/tasks") */
     id: string;
-    /** Human-readable title */
-    title: string;
+    /** Human-readable title (localized per locale) */
+    title: LocalizedField;
     /** Base route where module is mounted (e.g., "/admin/tasks") */
     routeBase: string;
-    /** i18n key for the title (for translation) */
-    titleKey?: string;
-    /** URL slug (derived from id if not provided) */
-    slug?: string;
-    /** Description of what the module does */
-    description?: string;
-    /** i18n key for the description (for translation) */
-    descriptionKey?: string;
+    /** Description of what the module does (localized per locale, required) */
+    description: LocalizedField;
     /** Category for navigation grouping (e.g., "Tools", "Customer") */
     category?: string;
-    /** Semantic version */
-    version?: string;
     /** Lucide icon name in kebab-case (e.g., "users", "clipboard-list") */
     icon?: string;
     /** Keywords for search */
     keywords?: string[];
     /** Navigation order (lower = higher priority) */
-    navOrder?: number;
-    /** Module status */
-    status?: ModuleStatus;
+    navigationOrder?: number;
+    /** Navigation configuration */
+    navigation?: {
+        /** Navigation style: "collapsible" (default) or "stacked" (dedicated panel) */
+        style: "collapsible" | "stacked";
+        /** Sections for grouping commands in stacked mode */
+        sections?: Array<{
+            id: string;
+            label: LocalizedField;
+        }>;
+    };
     /** Commands/actions available in this module */
     commands?: ModuleCommand[];
     /** Permission configuration */
@@ -95,4 +92,3 @@ export declare function validateManifest(value: unknown): value is AdminModuleMa
  * @throws Error if validation fails
  */
 export declare function parseManifest(value: unknown): AdminModuleManifest;
-//# sourceMappingURL=manifest.d.ts.map

package/dist/registry/types/manifest.js

@@ -4,6 +4,17 @@
  * This interface defines the structure of admin.module.json files
  * that module developers create to register their modules.
  */
+import { SUPPORTED_LOCALES } from '../../i18n/config.js';
+function isLocalizedField(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const obj = value;
+    for (const locale of SUPPORTED_LOCALES) {
+        if (typeof obj[locale] !== 'string')
+            return false;
+    }
+    return true;
+}
 /**
  * Validates that an object is a valid AdminModuleManifest
  */
@@ -16,35 +27,23 @@ export function validateManifest(value) {
     if (typeof obj.id !== 'string' || obj.id.trim() === '') {
         return false;
     }
-    if (typeof obj.title !== 'string' || obj.title.trim() === '') {
+    if (!isLocalizedField(obj.title)) {
         return false;
     }
     if (typeof obj.routeBase !== 'string' || !obj.routeBase.startsWith('/')) {
         return false;
     }
-    // Optional field validations
-    if (obj.slug !== undefined && typeof obj.slug !== 'string') {
-        return false;
-    }
-    if (obj.description !== undefined && typeof obj.description !== 'string') {
+    if (!isLocalizedField(obj.description)) {
         return false;
     }
+    // Optional field validations
     if (obj.category !== undefined && typeof obj.category !== 'string') {
         return false;
     }
-    if (obj.version !== undefined && typeof obj.version !== 'string') {
-        return false;
-    }
     if (obj.icon !== undefined && typeof obj.icon !== 'string') {
         return false;
     }
-    if (obj.navOrder !== undefined && typeof obj.navOrder !== 'number') {
-        return false;
-    }
-    if (obj.status !== undefined &&
-        obj.status !== 'active' &&
-        obj.status !== 'deprecated' &&
-        obj.status !== 'disabled') {
+    if (obj.navigationOrder !== undefined && typeof obj.navigationOrder !== 'number') {
         return false;
     }
     if (obj.keywords !== undefined) {
@@ -61,7 +60,7 @@ export function validateManifest(value) {
                 return false;
             if (typeof cmd.id !== 'string')
                 return false;
-            if (typeof cmd.title !== 'string')
+            if (!isLocalizedField(cmd.title))
                 return false;
             if (typeof cmd.route !== 'string')
                 return false;
@@ -75,7 +74,7 @@ export function validateManifest(value) {
  */
 export function parseManifest(value) {
     if (!validateManifest(value)) {
-        throw new Error('Invalid manifest: must have id, title, and routeBase (starting with /)');
+        throw new Error('Invalid manifest: must have id, title (localized), description (localized), and routeBase (starting with /). Title and description must be objects with all 4 locales: en-US, pt-BR, es, ro.');
     }
     return value;
 }

package/dist/registry/types/module.d.ts

@@ -14,10 +14,12 @@ export interface RegisteredModule {
     moduleId: string;
     /** Base URL where the module is hosted */
     baseUrl: string;
+    /** Currently active version (semver) */
+    version?: string;
     /** Full parsed module.manifest.json (without entry - fetched at runtime) */
     manifest: AdminModuleManifest;
     /** Admin-controlled navigation order */
-    navOrder: number;
+    navigationOrder: number;
     /** Whether the module is enabled */
     enabled: boolean;
     /** ISO timestamp when registered */
@@ -31,9 +33,13 @@ export interface RegisteredModule {
  */
 export interface UpdateModuleDto {
     /** Update navigation order */
-    navOrder?: number;
+    navigationOrder?: number;
     /** Enable or disable the module */
     enabled?: boolean;
+    /** Update base URL */
+    baseUrl?: string;
+    /** Update active version */
+    version?: string;
 }
 /**
  * DTO for reordering modules
@@ -42,7 +48,7 @@ export interface ReorderModuleDto {
     /** Module ID */
     id: number;
     /** New navigation order */
-    navOrder: number;
+    navigationOrder: number;
 }
 /**
  * Filters for listing modules
@@ -66,18 +72,17 @@ export interface Catalog {
     /** Array of modules in catalog format */
     modules: CatalogModule[];
 }
+import type { LocalizedField } from '../../i18n/config.js';
 /**
  * Module in catalog format (denormalized for shell)
  * Note: entry is not included - DynamicModule fetches module.manifest.json at runtime
  */
 export interface CatalogModule {
     id: string;
-    title: string;
-    /** i18n key for the title (for translation) */
-    titleKey?: string;
-    description: string;
-    /** i18n key for the description (for translation) */
-    descriptionKey?: string;
+    /** Human-readable title (localized per locale) */
+    title: LocalizedField;
+    /** Description of what the module does (localized per locale) */
+    description: LocalizedField;
     category: string;
     routeBase: string;
     /** Base URL where the module is hosted */
@@ -92,18 +97,32 @@ export interface CatalogModule {
         supportChannel: string;
     };
     status: 'active' | 'deprecated' | 'disabled';
-    navOrder?: number;
+    navigationOrder?: number;
     icon?: string;
+    navigation?: {
+        style: "collapsible" | "stacked";
+        sections?: Array<{
+            id: string;
+            title: LocalizedField;
+        }>;
+    };
     commands?: Array<{
         id: string;
-        title: string;
-        /** i18n key for the title (for translation) */
-        titleKey?: string;
+        /** Human-readable title (localized per locale) */
+        title: LocalizedField;
         keywords?: string[];
         route: string;
         icon?: string;
+        section?: string;
     }>;
 }
+/**
+ * Lightweight catalog version (no full payload)
+ */
+export interface CatalogVersion {
+    version: string;
+    generatedAt: string;
+}
 /**
  * Import map structure for dynamic module loading
  */
@@ -112,4 +131,14 @@ export interface ImportMap {
         [moduleName: string]: string;
     };
 }
-//# sourceMappingURL=module.d.ts.map
+/**
+ * A published version entry from the version history
+ */
+export interface ModuleVersion {
+    id: number;
+    version: string;
+    baseUrl: string;
+    publishedAt: string;
+    active: boolean;
+    metadata?: Record<string, unknown>;
+}

package/dist/registry/useRegistryPolling.d.ts

@@ -0,0 +1,15 @@
+import type { RegistryClient } from './client/interface';
+export interface RegistryPollingState {
+    /** Whether newer catalog version is available */
+    hasUpdates: boolean;
+    /** Dismiss the current banner; re-shows on a subsequent newer version */
+    dismiss: () => void;
+}
+export interface UseRegistryPollingOptions {
+    registryClient: RegistryClient;
+    /** Version string from the initial catalog.get() response */
+    initialVersion: string;
+    /** Polling interval in milliseconds. 0 or undefined disables polling. */
+    interval: number | undefined;
+}
+export declare function useRegistryPolling({ registryClient, initialVersion, interval, }: UseRegistryPollingOptions): RegistryPollingState;

package/dist/registry/useRegistryPolling.js

@@ -0,0 +1,66 @@
+import { useState, useEffect, useRef, useCallback } from 'react';
+export function useRegistryPolling({ registryClient, initialVersion, interval, }) {
+    const [hasUpdates, setHasUpdates] = useState(false);
+    const dismissedVersionRef = useRef(null);
+    const latestServerVersionRef = useRef(initialVersion);
+    const loadedVersionRef = useRef(initialVersion);
+    useEffect(() => {
+        loadedVersionRef.current = initialVersion;
+        latestServerVersionRef.current = initialVersion;
+        dismissedVersionRef.current = null;
+        setHasUpdates(false);
+    }, [initialVersion]);
+    const dismiss = useCallback(() => {
+        dismissedVersionRef.current = latestServerVersionRef.current;
+        setHasUpdates(false);
+    }, []);
+    useEffect(() => {
+        if (!interval || interval <= 0)
+            return;
+        let timerId = null;
+        let destroyed = false;
+        async function check() {
+            try {
+                const { version } = await registryClient.catalog.version();
+                if (destroyed)
+                    return;
+                latestServerVersionRef.current = version;
+                const changed = version !== loadedVersionRef.current;
+                const dismissed = version === dismissedVersionRef.current;
+                setHasUpdates(changed && !dismissed);
+            }
+            catch {
+                // Network errors are silently ignored per spec
+            }
+        }
+        function scheduleNext() {
+            if (destroyed)
+                return;
+            timerId = setTimeout(async () => {
+                await check();
+                scheduleNext();
+            }, interval);
+        }
+        function handleVisibilityChange() {
+            if (document.hidden) {
+                if (timerId !== null) {
+                    clearTimeout(timerId);
+                    timerId = null;
+                }
+            }
+            else {
+                check();
+                scheduleNext();
+            }
+        }
+        scheduleNext();
+        document.addEventListener('visibilitychange', handleVisibilityChange);
+        return () => {
+            destroyed = true;
+            if (timerId !== null)
+                clearTimeout(timerId);
+            document.removeEventListener('visibilitychange', handleVisibilityChange);
+        };
+    }, [registryClient, interval]);
+    return { hasUpdates, dismiss };
+}