@arcote.tech/platform 0.4.6 → 0.4.8

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@arcote.tech/platform",
   "type": "module",
-  "version": "0.4.6",
+  "version": "0.4.8",
   "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.6",
-    "@arcote.tech/arc-react": "^0.4.6"
+    "@arcote.tech/arc-ds": "^0.4.8",
+    "@arcote.tech/arc-react": "^0.4.8"
   },
   "peerDependencies": {
-    "@arcote.tech/arc": "^0.4.6",
+    "@arcote.tech/arc": "^0.4.8",
     "@lingui/core": "^5.0.0",
     "@lingui/react": "^5.0.0",
     "framer-motion": "^12.0.0",

package/src/arc.ts

@@ -8,6 +8,7 @@ import type {
   BuiltModule,
   ContextElementFragment,
   ExtractPages,
+  ModuleAccessRule,
   PageFragment,
   PageOptions,
   SlotFragment,
@@ -66,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,
   };
 }
 
@@ -148,9 +151,22 @@ class ModuleBuilder<
   private _pages: Record<string, string> | undefined;
   private _ctx: { elements: readonly ArcContextElementAny[] } | undefined;
   private _scope: string | undefined;
+  private _protectedBy: ModuleAccessRule[] = [];
 
   constructor(readonly name: string) {}
 
+  /**
+   * Restrict module loading to users holding the given token.
+   * Optional check function for granular access control.
+   */
+  protectedBy(
+    token: { name: string },
+    check?: (tokenInstance: any) => boolean | Promise<boolean>,
+  ): this {
+    this._protectedBy.push({ token, check });
+    return this;
+  }
+
   /**
    * Register the module's ArcContext and scope name.
    * Context element fragments are auto-injected in build().
@@ -225,12 +241,14 @@ class ModuleBuilder<
 
     const mod: Record<string, unknown> = {
       id: moduleId,
+      name: this.name,
       fragments: allFragments,
       publicFragments: this._public,
       pages: Object.freeze(this._pages ?? {}),
     };
     if (this._ctx !== undefined) mod.context = this._ctx;
     if (this._scope !== undefined) mod.scope = this._scope;
+    if (this._protectedBy.length > 0) mod.access = { rules: this._protectedBy };
     if (domain) Object.assign(mod, domain);
 
     registerModule(mod as unknown as ArcModule);
@@ -285,12 +303,13 @@ export function arc(
   // Context registration: factory returned an ArcContext
   if (isArcContext(result)) {
     setContext(result);
-    return { id: moduleId, fragments: [], publicFragments: [] };
+    return { id: moduleId, name: moduleId, fragments: [], publicFragments: [] };
   }
 
   const publicFragments: readonly ArcFragment[] = Array.isArray(result) ? result : [];
   const mod: ArcModule = {
     id: moduleId,
+    name: moduleId,
     fragments: allFragments,
     publicFragments,
   };

package/src/index.ts

@@ -7,9 +7,13 @@ export { arc } from "./arc";
 export {
   clearModules,
   clearRegistry,
+  forceRegisterModule,
   getAllFragments,
+  getAllModuleAccess,
   getAllModules,
+  getAllRegisteredModules,
   getContext,
+  getModuleAccess,
   getContextElementFragments,
   getDefaultLayout,
   getModule,
@@ -60,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
@@ -86,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";
@@ -106,6 +111,9 @@ export type {
   ArcModule,
   BuiltModule,
   ContextElementFragment,
+  ModuleAccess,
+  ModuleAccessRule,
+  ModuleDescriptor,
   ExtractPages,
   FragmentOrdering,
   PageFragment,

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,27 +1,75 @@
-import { clearModules, getContext } from "./registry";
+import { clearModules, getAllRegisteredModules, getContext, setActiveModules } from "./registry";
+import type { ModuleDescriptor } from "./types";
 import { useCallback, useEffect, useRef, useState } from "react";
 
 export interface ModuleManifest {
-  modules: string[];
+  modules: ModuleDescriptor[];
   buildTime: string;
 }
 
 export type ModuleLoaderState = "loading" | "ready" | "error";
 
-/**
- * Load all modules from manifest. Each module auto-registers via arc().
- */
-export async function loadModules(baseUrl: string): Promise<ModuleManifest> {
-  const res = await fetch(`${baseUrl}/api/modules`);
+function moduleUrl(baseUrl: string, mod: ModuleDescriptor, bust?: string): string {
+  const base = mod.url ?? `${baseUrl}/modules/${mod.file}`;
+  return bust ? `${base}${base.includes("?") ? "&" : "?"}t=${bust}` : base;
+}
+
+/** 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:")) {
+      const raw = localStorage.getItem(key);
+      if (raw) tokens[key.slice(10)] = raw;
+    }
+  }
+  return tokens;
+}
+
+/** 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 = {};
+  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);
 
-  // Import all modules — each calls arc() which auto-registers
   await Promise.all(
     manifest.modules.map(
-      (mod) => import(/* @vite-ignore */ `${baseUrl}/modules/${mod}`),
+      (mod) => import(/* @vite-ignore */ moduleUrl(baseUrl, mod)),
     ),
   );
 
@@ -29,21 +77,52 @@ export async function loadModules(baseUrl: string): Promise<ModuleManifest> {
 }
 
 /**
- * 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(baseUrl: string): Promise<ModuleManifest> {
-  clearModules();
+export async function syncModules(
+  baseUrl: string,
+  tokens?: Record<string, string>,
+): Promise<ModuleManifest> {
+  const manifest = await fetchManifest(baseUrl, tokens);
 
-  const res = await fetch(`${baseUrl}/api/modules`);
-  if (!res.ok)
-    throw new Error(`Failed to fetch module manifest: ${res.status}`);
+  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));
+
+  // 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();
-  const bust = `?t=${Date.now()}`;
+/**
+ * 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 */ `${baseUrl}/modules/${mod}${bust}`),
+      (mod) => import(/* @vite-ignore */ moduleUrl(baseUrl, mod, bust)),
     ),
   );
 
@@ -52,18 +131,21 @@ export async function reloadModules(baseUrl: string): Promise<ModuleManifest> {
 
 /**
  * Hook: loads modules on mount, provides state + context.
+ * Syncs modules when tokens change (login/logout/workspace switch).
  */
 export function useModuleLoader(
   baseUrl: string,
-  options: { skip?: boolean } = {},
+  options: { skip?: boolean; token?: string | null } = {},
 ) {
   const [state, setState] = useState<ModuleLoaderState>(
     options.skip ? "ready" : "loading",
   );
   const [error, setError] = useState<Error | null>(null);
   const loaded = useRef(false);
+  const [tokenVersion, setTokenVersion] = useState(0);
 
-  const reload = useCallback(async () => {
+  // Full reload — for dev-mode file changes (re-import all JS)
+  const fullReload = useCallback(async () => {
     try {
       await reloadModules(baseUrl);
       setState("ready");
@@ -73,6 +155,18 @@ export function useModuleLoader(
     }
   }, [baseUrl]);
 
+  // Sync — for token changes (only fetch manifest, import new, remove stale)
+  const sync = useCallback(async () => {
+    try {
+      await syncModules(baseUrl);
+      setState("ready");
+    } catch (e) {
+      setError(e instanceof Error ? e : new Error(String(e)));
+      setState("error");
+    }
+  }, [baseUrl]);
+
+  // Initial load
   useEffect(() => {
     if (options.skip || loaded.current) return;
     loaded.current = true;
@@ -84,19 +178,55 @@ export function useModuleLoader(
         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]);
+  }, [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);
+    };
+  }, []);
+
+  // 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;
+    sync();
+  }, [options.token, sync]);
 
-  return { state, error, context: getContext(), reload };
+  return { state, error, context: getContext(), reload: fullReload };
 }

package/src/platform-app.tsx

@@ -1,6 +1,6 @@
 import type { ArcContextAny } from "@arcote.tech/arc";
 import type { DSVariantOverrides } from "@arcote.tech/arc-ds";
-import { DesignSystemProvider } from "@arcote.tech/arc-ds";
+import { DesignSystemProvider, TooltipProvider } from "@arcote.tech/arc-ds";
 import { reactModel } from "@arcote.tech/arc-react";
 import { Layout } from "@arcote.tech/arc-ds";
 import { ArcLayoutProvider } from "./layout/layout-provider";
@@ -13,13 +13,10 @@ import {
   setDefaultLayout,
 } from "./registry";
 import { ThemeProvider } from "./theme";
-import { Tooltip as RadixTooltip } from "radix-ui";
-import { useEffect, useMemo, useState } from "react";
+import { useEffect, useMemo, useRef, useState } from "react";
 import { useModuleLoader } from "./module-loader";
 import { PlatformModelProvider } from "./platform-context";
 
-const TooltipProvider = RadixTooltip.Provider;
-
 export interface PlatformAppProps {
   apiUrl?: string;
   wsUrl?: string;
@@ -179,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

@@ -3,6 +3,7 @@ import type {
   ArcLayoutComponent,
   ArcModule,
   ContextElementFragment,
+  ModuleAccess,
   PageFragment,
   SlotFragment,
   SlotId,
@@ -14,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 {
@@ -25,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();
 }
@@ -41,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
 // ---------------------------------------------------------------------------
@@ -166,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[] {
@@ -186,6 +227,23 @@ export function getWrapperFragments(): WrapperFragment[] {
   return sortByOrdering(fragments);
 }
 
+/** Get access rules for a module by name. */
+export function getModuleAccess(name: string): ModuleAccess | undefined {
+  for (const mod of modules.values()) {
+    if (mod.name === name && mod.access) return mod.access;
+  }
+  return undefined;
+}
+
+/** Get access rules for all protected modules. */
+export function getAllModuleAccess(): Map<string, ModuleAccess> {
+  const result = new Map<string, ModuleAccess>();
+  for (const mod of modules.values()) {
+    if (mod.access) result.set(mod.name, mod.access);
+  }
+  return result;
+}
+
 /** Clear all modules (but keep context). Used for reload. */
 export function clearModules(): void {
   modules.clear();

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 = {
@@ -83,14 +86,35 @@ export type ArcFragment =
 
 export type PublicArcFragment = ArcFragment;
 
+// ---------------------------------------------------------------------------
+// Module access control
+// ---------------------------------------------------------------------------
+
+export interface ModuleAccessRule {
+  readonly token: { name: string; [key: string]: any };
+  readonly check?: (tokenInstance: any) => boolean | Promise<boolean>;
+}
+
+export interface ModuleAccess {
+  readonly rules: readonly ModuleAccessRule[];
+}
+
+export interface ModuleDescriptor {
+  readonly file: string;
+  readonly name: string;
+  readonly url?: string;
+}
+
 // ---------------------------------------------------------------------------
 // Moduł
 // ---------------------------------------------------------------------------
 
 export interface ArcModule {
   readonly id: string;
+  readonly name: string;
   readonly fragments: readonly ArcFragment[];
   readonly publicFragments: readonly ArcFragment[];
+  readonly access?: ModuleAccess;
 }
 
 // ---------------------------------------------------------------------------
@@ -137,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 {