@arcote.tech/platform 0.4.7 → 0.4.9

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@arcote.tech/platform",
   "type": "module",
-  "version": "0.4.7",
+  "version": "0.4.9",
   "private": false,
   "author": "Przemysław Krasiński [arcote.tech]",
   "description": "Arc Platform — module system, router, layout, theme, i18n, platform app shell",
@@ -18,11 +18,11 @@
     "type-check": "tsc --noEmit"
   },
   "dependencies": {
-    "@arcote.tech/arc-ds": "^0.4.7",
-    "@arcote.tech/arc-react": "^0.4.7"
+    "@arcote.tech/arc-ds": "^0.4.9",
+    "@arcote.tech/arc-react": "^0.4.9"
   },
   "peerDependencies": {
-    "@arcote.tech/arc": "^0.4.7",
+    "@arcote.tech/arc": "^0.4.9",
     "@lingui/core": "^5.0.0",
     "@lingui/react": "^5.0.0",
     "framer-motion": "^12.0.0",

package/src/arc.ts

@@ -67,6 +67,8 @@ export function page<TPath extends string>(
     label: options.label,
     tooltip: options.tooltip,
     children: options.children,
+    ordering: { order: options.order ?? 0, after: options.after, before: options.before },
+    nav: options.nav,
   };
 }
 

package/src/index.ts

@@ -7,9 +7,11 @@ export { arc } from "./arc";
 export {
   clearModules,
   clearRegistry,
+  forceRegisterModule,
   getAllFragments,
   getAllModuleAccess,
   getAllModules,
+  getAllRegisteredModules,
   getContext,
   getModuleAccess,
   getContextElementFragments,
@@ -62,6 +64,7 @@ export { PageRouter } from "./layout/page-router";
 export { PageSubNavShell } from "./layout/page-sub-nav-shell";
 export { SlotRenderer } from "./layout/slot-renderer";
 export type { SlotRendererProps } from "./layout/slot-renderer";
+export { usePageFragments } from "./layout/use-page-fragments";
 export { useSlotFragments } from "./layout/use-slot-fragments";
 
 // Router
@@ -88,7 +91,7 @@ export type { LocaleProviderProps } from "./locale";
 export { useTitle } from "./hooks/use-title";
 
 // Platform
-export { loadModules, reloadModules, useModuleLoader } from "./module-loader";
+export { loadModules, reloadModules, syncModules, useModuleLoader } from "./module-loader";
 export type { ModuleLoaderState, ModuleManifest } from "./module-loader";
 export { PlatformApp } from "./platform-app";
 export type { PlatformAppProps } from "./platform-app";

package/src/layout/page-router.tsx

@@ -1,6 +1,7 @@
 import { AnimatePresence, motion } from "framer-motion";
 import { Suspense, useEffect } from "react";
-import { getDefaultLayout, getPageFragments } from "../registry";
+import { getDefaultLayout } from "../registry";
+import { usePageFragments } from "./use-page-fragments";
 import { useArcNavigate, useArcRoute, matchRoutePath, hasRouteParams } from "../router";
 import { useArcRouter } from "@arcote.tech/arc-ds";
 import type { PageFragment } from "../types";
@@ -11,8 +12,7 @@ type MatchResult = {
   params: Record<string, string>;
 };
 
-function matchPage(path: string): MatchResult | undefined {
-  const pages = getPageFragments();
+function matchPage(path: string, pages: PageFragment[]): MatchResult | undefined {
 
   // 1. Exact match (non-parent pages only)
   const exact = pages.find((p) => p.path === path && !p.children?.length);
@@ -64,7 +64,8 @@ export function PageRouter() {
   const route = useArcRoute();
   const navigate = useArcNavigate();
   const router = useArcRouter();
-  const match = matchPage(route);
+  const pages = usePageFragments();
+  const match = matchPage(route, pages);
   const DefaultLayout = getDefaultLayout();
 
   // Sync matched params to router context
@@ -80,6 +81,14 @@ export function PageRouter() {
     }
   }, [route, match?.params]);
 
+  // Redirect to first available page when current route is no longer registered
+  useEffect(() => {
+    if (!match && pages.length > 0 && route !== "/") {
+      const firstNav = pages.find((p) => p.icon && p.label && !p.path.includes("/:"));
+      navigate(firstNav?.path ?? "/");
+    }
+  }, [match, pages, route, navigate]);
+
   if (!match) {
     if (DefaultLayout) return <DefaultLayout>{null}</DefaultLayout>;
     return null;

package/src/layout/use-page-fragments.ts

@@ -0,0 +1,20 @@
+import { useRef, useSyncExternalStore } from "react";
+import { getPageFragments, subscribe } from "../registry";
+import type { PageFragment } from "../types";
+
+export function usePageFragments(): PageFragment[] {
+  const cacheRef = useRef<PageFragment[]>([]);
+
+  const getSnapshot = () => {
+    const next = getPageFragments();
+    const prev = cacheRef.current;
+
+    const changed =
+      next.length !== prev.length || next.some((f, i) => f.id !== prev[i]?.id);
+
+    if (changed) cacheRef.current = next;
+    return cacheRef.current;
+  };
+
+  return useSyncExternalStore(subscribe, getSnapshot);
+}

package/src/module-loader.ts

@@ -1,4 +1,4 @@
-import { clearModules, getContext } from "./registry";
+import { clearModules, getAllRegisteredModules, getContext, setActiveModules } from "./registry";
 import type { ModuleDescriptor } from "./types";
 import { useCallback, useEffect, useRef, useState } from "react";
 
@@ -14,34 +14,58 @@ function moduleUrl(baseUrl: string, mod: ModuleDescriptor, bust?: string): strin
   return bust ? `${base}${base.includes("?") ? "&" : "?"}t=${bust}` : base;
 }
 
-/** Read first available arc token from localStorage */
-function getPersistedToken(): string | null {
-  if (typeof localStorage === "undefined") return null;
+/** Read all persisted arc tokens from localStorage */
+function getAllPersistedTokens(): Record<string, string> {
+  if (typeof localStorage === "undefined") return {};
+  const tokens: Record<string, string> = {};
   for (let i = 0; i < localStorage.length; i++) {
     const key = localStorage.key(i);
     if (key?.startsWith("arc:token:")) {
-      return localStorage.getItem(key);
+      const raw = localStorage.getItem(key);
+      if (raw) tokens[key.slice(10)] = raw;
     }
   }
-  return null;
+  return tokens;
 }
 
-/**
- * Load all modules from manifest. Each module auto-registers via module().build().
- */
-export async function loadModules(
-  baseUrl: string,
-  token?: string | null,
-): Promise<ModuleManifest> {
-  const resolvedToken = token ?? getPersistedToken();
+/** Build X-Arc-Tokens header value from token map */
+function buildTokensHeader(tokens: Record<string, string>): string {
+  return Object.entries(tokens)
+    .map(([scope, jwt]) => `${scope}:${jwt}`)
+    .join(",");
+}
+
+function buildHeaders(tokens?: Record<string, string>): HeadersInit {
+  const resolved = tokens ?? getAllPersistedTokens();
   const headers: HeadersInit = {};
-  if (resolvedToken) headers["Authorization"] = `Bearer ${resolvedToken}`;
+  const tokensHeader = buildTokensHeader(resolved);
+  if (tokensHeader) headers["X-Arc-Tokens"] = tokensHeader;
+  // Also send first token as Authorization for backwards compatibility
+  const firstToken = Object.values(resolved)[0];
+  if (firstToken) headers["Authorization"] = `Bearer ${firstToken}`;
+  return headers;
+}
 
+/** Fetch manifest from server */
+async function fetchManifest(
+  baseUrl: string,
+  tokens?: Record<string, string>,
+): Promise<ModuleManifest> {
+  const headers = buildHeaders(tokens);
   const res = await fetch(`${baseUrl}/api/modules`, { headers });
   if (!res.ok)
     throw new Error(`Failed to fetch module manifest: ${res.status}`);
+  return res.json();
+}
 
-  const manifest: ModuleManifest = await res.json();
+/**
+ * Load all modules from manifest. Each module auto-registers via module().build().
+ */
+export async function loadModules(
+  baseUrl: string,
+  tokens?: Record<string, string>,
+): Promise<ModuleManifest> {
+  const manifest = await fetchManifest(baseUrl, tokens);
 
   await Promise.all(
     manifest.modules.map(
@@ -53,25 +77,49 @@ export async function loadModules(
 }
 
 /**
- * Reload modules — clear registry, re-import with cache bust.
+ * Sync modules with server — import any NEW modules, then set active filter.
+ * Modules are never unregistered (ES module cache prevents re-execution).
+ * Instead, visibility is controlled via an active set.
  */
-export async function reloadModules(
+export async function syncModules(
   baseUrl: string,
-  token?: string | null,
+  tokens?: Record<string, string>,
 ): Promise<ModuleManifest> {
-  clearModules();
+  const manifest = await fetchManifest(baseUrl, tokens);
 
-  const resolvedToken = token ?? getPersistedToken();
-  const headers: HeadersInit = {};
-  if (resolvedToken) headers["Authorization"] = `Bearer ${resolvedToken}`;
+  const manifestNames = new Set(manifest.modules.map((m) => m.name));
+  // Check against ALL registered modules (not just active ones)
+  const registeredNames = new Set(getAllRegisteredModules().map((m) => m.name));
 
-  const res = await fetch(`${baseUrl}/api/modules`, { headers });
-  if (!res.ok)
-    throw new Error(`Failed to fetch module manifest: ${res.status}`);
+  // Import only truly new modules (never imported before)
+  const newModules = manifest.modules.filter((m) => !registeredNames.has(m.name));
+
+  if (newModules.length > 0) {
+    await Promise.all(
+      newModules.map((mod) => import(/* @vite-ignore */ moduleUrl(baseUrl, mod))),
+    );
+  }
+
+  // Set active filter — only modules in the manifest are visible
+  setActiveModules(manifestNames);
+
+  return manifest;
+}
 
-  const manifest: ModuleManifest = await res.json();
+/**
+ * Full reload — clear all modules, re-import with cache bust.
+ * Used for dev-mode file changes (code actually changed on disk).
+ */
+export async function reloadModules(
+  baseUrl: string,
+  tokens?: Record<string, string>,
+): Promise<ModuleManifest> {
+  const manifest = await fetchManifest(baseUrl, tokens);
   const bust = String(Date.now());
 
+  // Clear all modules — fresh code will re-register them
+  clearModules();
+
   await Promise.all(
     manifest.modules.map(
       (mod) => import(/* @vite-ignore */ moduleUrl(baseUrl, mod, bust)),
@@ -83,7 +131,7 @@ export async function reloadModules(
 
 /**
  * Hook: loads modules on mount, provides state + context.
- * Re-fetches manifest when token changes (login/logout).
+ * Syncs modules when tokens change (login/logout/workspace switch).
  */
 export function useModuleLoader(
   baseUrl: string,
@@ -94,51 +142,91 @@ export function useModuleLoader(
   );
   const [error, setError] = useState<Error | null>(null);
   const loaded = useRef(false);
-  const prevToken = useRef(options.token);
+  const [tokenVersion, setTokenVersion] = useState(0);
+
+  // Full reload — for dev-mode file changes (re-import all JS)
+  const fullReload = useCallback(async () => {
+    try {
+      await reloadModules(baseUrl);
+      setState("ready");
+    } catch (e) {
+      setError(e instanceof Error ? e : new Error(String(e)));
+      setState("error");
+    }
+  }, [baseUrl]);
 
-  const reload = useCallback(async () => {
+  // Sync — for token changes (only fetch manifest, import new, remove stale)
+  const sync = useCallback(async () => {
     try {
-      await reloadModules(baseUrl, options.token);
+      await syncModules(baseUrl);
       setState("ready");
     } catch (e) {
       setError(e instanceof Error ? e : new Error(String(e)));
       setState("error");
     }
-  }, [baseUrl, options.token]);
+  }, [baseUrl]);
 
   // Initial load
   useEffect(() => {
     if (options.skip || loaded.current) return;
     loaded.current = true;
 
-    loadModules(baseUrl, options.token)
+    loadModules(baseUrl)
       .then(() => setState("ready"))
       .catch((e) => {
         setError(e instanceof Error ? e : new Error(String(e)));
         setState("error");
       });
 
-    // Listen for SSE reload events from CLI
+    // Listen for SSE reload events from CLI (code changed on disk → full reload)
     const evtSource = new EventSource(`${baseUrl}/api/reload-stream`);
     evtSource.onmessage = (event) => {
       if (event.data === "connected") return;
       console.log("[arc] Modules changed, reloading...");
-      reload();
+      fullReload();
     };
     evtSource.onerror = () => {
       // SSE disconnected — will auto-reconnect
     };
 
     return () => evtSource.close();
-  }, [baseUrl, reload, options.skip, options.token]);
+  }, [baseUrl, fullReload, options.skip]);
+
+  // Listen for token changes → sync (not full reload)
+  useEffect(() => {
+    if (typeof window === "undefined") return;
+
+    const onTokenChange = () => setTokenVersion((v) => v + 1);
+    window.addEventListener("arc:token-change", onTokenChange);
+
+    const onStorage = (e: StorageEvent) => {
+      if (e.key?.startsWith("arc:token:")) {
+        setTokenVersion((v) => v + 1);
+      }
+    };
+    window.addEventListener("storage", onStorage);
+
+    return () => {
+      window.removeEventListener("arc:token-change", onTokenChange);
+      window.removeEventListener("storage", onStorage);
+    };
+  }, []);
 
-  // Reload on token change (login/logout)
+  // Token changed → sync modules (import new, remove stale, don't re-import existing)
+  useEffect(() => {
+    if (!loaded.current) return;
+    if (tokenVersion === 0) return;
+    sync();
+  }, [tokenVersion, sync]);
+
+  // Legacy: sync when explicit token prop changes
+  const prevToken = useRef(options.token);
   useEffect(() => {
     if (!loaded.current) return;
     if (prevToken.current === options.token) return;
     prevToken.current = options.token;
-    reload();
-  }, [options.token, reload]);
+    sync();
+  }, [options.token, sync]);
 
-  return { state, error, context: getContext(), reload };
+  return { state, error, context: getContext(), reload: fullReload };
 }

package/src/platform-app.tsx

@@ -13,7 +13,7 @@ import {
   setDefaultLayout,
 } from "./registry";
 import { ThemeProvider } from "./theme";
-import { useEffect, useMemo, useState } from "react";
+import { useEffect, useMemo, useRef, useState } from "react";
 import { useModuleLoader } from "./module-loader";
 import { PlatformModelProvider } from "./platform-context";
 
@@ -176,7 +176,16 @@ export function PlatformApp({
   // If context is pre-loaded (modules imported statically in main.tsx),
   // skip dynamic module loading entirely.
   const loader = useModuleLoader(apiUrl, { skip: !!preloadedContext });
-  const context = preloadedContext ?? loader.context ?? getContext();
+
+  // Stabilize context reference — once set, don't change it.
+  // New context elements from synced modules merge into the global registry
+  // but we must NOT recreate the model (would remount the entire tree).
+  const contextRef = useRef<ArcContextAny | null>(preloadedContext ?? null);
+  if (!contextRef.current) {
+    const resolved = loader.context ?? getContext();
+    if (resolved) contextRef.current = resolved;
+  }
+  const context = contextRef.current;
 
   const resolvedWsUrl = wsUrl ?? `${location.protocol}//${location.host}`;
 

package/src/registry.ts

@@ -15,6 +15,8 @@ import type {
 // ---------------------------------------------------------------------------
 
 const modules: Map<string, ArcModule> = new Map();
+/** Set of module names currently active (visible). Managed by syncModules. */
+let activeModuleNames: Set<string> | null = null; // null = all active (no filtering)
 const listeners: Set<() => void> = new Set();
 
 function notify(): void {
@@ -26,8 +28,32 @@ export function subscribe(listener: () => void): () => void {
   return () => listeners.delete(listener);
 }
 
-/** Register module. Overwrites if already registered (needed for reload). */
+/**
+ * Register module. Skips if a module with the same name already exists
+ * (prevents duplicates from bundled dependencies importing the same module).
+ * Use `forceRegisterModule` for dev reloads where code has actually changed.
+ */
 export function registerModule(mod: ArcModule): void {
+  for (const existing of modules.values()) {
+    if (existing.name === mod.name) {
+      console.log(`[arc:registry] SKIP ${mod.name} (already registered as ${existing.id})`);
+      return;
+    }
+  }
+  console.log(`[arc:registry] REGISTER ${mod.name} as ${mod.id} (fragments: ${mod.fragments.length})`);
+  modules.set(mod.id, mod);
+  notify();
+}
+
+/** Force-register module, replacing any existing module with the same name.
+ *  Used for dev reloads where code has changed on disk. */
+export function forceRegisterModule(mod: ArcModule): void {
+  for (const [id, existing] of modules) {
+    if (existing.name === mod.name && id !== mod.id) {
+      modules.delete(id);
+      break;
+    }
+  }
   modules.set(mod.id, mod);
   notify();
 }
@@ -42,9 +68,22 @@ export function getModule(moduleId: string): ArcModule | undefined {
 }
 
 export function getAllModules(): ArcModule[] {
+  if (!activeModuleNames) return [...modules.values()];
+  return [...modules.values()].filter((m) => activeModuleNames!.has(m.name));
+}
+
+/** Get ALL registered modules (ignoring active filter). */
+export function getAllRegisteredModules(): ArcModule[] {
   return [...modules.values()];
 }
 
+/** Set which modules are currently active (visible in queries).
+ *  Pass null to show all. Triggers re-render of slot/page subscribers. */
+export function setActiveModules(names: Set<string> | null): void {
+  activeModuleNames = names;
+  notify();
+}
+
 // ---------------------------------------------------------------------------
 // Context store — dynamiczny context rejestrowany przez pakiety
 // ---------------------------------------------------------------------------
@@ -167,7 +206,8 @@ export function getSlotFragments(slotId: SlotId | string): SlotFragment[] {
 }
 
 export function getPageFragments(): PageFragment[] {
-  return getAllFragments().filter((f): f is PageFragment => f.is("page"));
+  const fragments = getAllFragments().filter((f): f is PageFragment => f.is("page"));
+  return sortByOrdering(fragments);
 }
 
 export function getContextElementFragments(): ContextElementFragment[] {

package/src/types.ts

@@ -57,6 +57,9 @@ export interface PageFragment<
   readonly label?: string | ReactNode;
   readonly tooltip?: string | ReactNode;
   readonly children?: readonly PageFragment[];
+  readonly ordering: FragmentOrdering;
+  /** Show in main navigation. Defaults to auto-detect (has icon + label). */
+  readonly nav?: boolean;
 }
 
 export type PageShellProps = {
@@ -158,6 +161,12 @@ export interface PageOptions {
   label?: string | ReactNode;
   tooltip?: string | ReactNode;
   children?: PageFragment[];
+  /** Navigation ordering. Lower = earlier. Default 0. */
+  order?: number;
+  after?: string;
+  before?: string;
+  /** Explicitly include/exclude from main navigation. Default: auto (has icon + label). */
+  nav?: boolean;
 }
 
 export interface WrapperOptions extends FragmentOrdering {