@arcote.tech/platform 0.7.16 → 0.7.17

package/package.json

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

package/src/arc.ts

@@ -141,6 +141,8 @@ export function contextFragments(
 // module() — primary API for creating Arc modules
 // ---------------------------------------------------------------------------
 
+type ModuleContext = { elements: readonly ArcContextElementAny[] };
+
 class ModuleBuilder<
   TPages = {},
   TCtx = undefined,
@@ -149,7 +151,7 @@ class ModuleBuilder<
   private _public: ArcFragment[] = [];
   private _private: ArcFragment[] = [];
   private _pages: Record<string, string> | undefined;
-  private _ctx: { elements: readonly ArcContextElementAny[] } | undefined;
+  private _ctx: ModuleContext | (() => ModuleContext) | undefined;
   private _scope: string | undefined;
   private _protectedBy: ModuleAccessRule[] = [];
 
@@ -170,9 +172,15 @@ class ModuleBuilder<
   /**
    * Register the module's ArcContext and scope name.
    * Context element fragments are auto-injected in build().
+   *
+   * Accepts the context directly or as a thunk (`() => ctx`). The thunk form
+   * is resilient to circular imports between module packages: at build()
+   * time a cycle can leave the context binding still `undefined` (ESM `var`
+   * hoisting); the thunk re-reads the live binding after the whole import
+   * graph has evaluated.
    */
-  context<C extends { elements: readonly ArcContextElementAny[] }, S extends string>(
-    ctx: C,
+  context<C extends ModuleContext, S extends string>(
+    ctx: C | (() => C),
     scope: S,
   ): ModuleBuilder<TPages, C, S> {
     this._ctx = ctx;
@@ -211,47 +219,95 @@ class ModuleBuilder<
     return this;
   }
 
+  /** Resolve the declared context — unwraps the thunk form. Returns
+   *  undefined when the binding has not evaluated yet (import cycle). */
+  private resolveCtx(): ModuleContext | undefined {
+    if (typeof this._ctx === "function") {
+      try {
+        return (this._ctx as () => ModuleContext)();
+      } catch {
+        // TDZ / not yet evaluated — caller retries after the graph settles
+        return undefined;
+      }
+    }
+    return this._ctx;
+  }
+
   build(): BuiltModule<TPages, TCtx, TScope>;
   build<D extends Record<string, unknown>>(domain: D): BuiltModule<TPages, TCtx, TScope> & Readonly<D>;
   build(domain?: Record<string, unknown>) {
     const moduleId = nextModuleId();
 
-    // Auto-inject context element fragments when .context() was called
-    if (this._ctx) {
-      const ctxFrags = contextFragments(this._ctx);
-      this._private = [...ctxFrags, ...this._private];
-    }
-
-    const allFragments = [...this._public, ...this._private];
-
-    // Assign moduleId to all fragments
-    for (const f of allFragments) {
-      (f as { moduleId: string }).moduleId = moduleId;
-    }
-
-    // Auto-extract and register context from context-element fragments
-    const contextElements = allFragments
-      .filter((f): f is ContextElementFragment => f.is("context-element"))
-      .map((f) => f.element);
-
-    if (contextElements.length > 0) {
-      const ctx = createContext(contextElements);
-      setContext(ctx);
-    }
-
     const mod: Record<string, unknown> = {
       id: moduleId,
       name: this.name,
-      fragments: allFragments,
+      fragments: [] as ArcFragment[],
       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);
+    const finalize = (resolvedCtx: ModuleContext | undefined) => {
+      // Auto-inject context element fragments when .context() was called
+      let privateFragments = this._private;
+      if (resolvedCtx) {
+        privateFragments = [
+          ...contextFragments(resolvedCtx),
+          ...this._private,
+        ];
+      }
+
+      const allFragments = [...this._public, ...privateFragments];
+
+      // Assign moduleId to all fragments
+      for (const f of allFragments) {
+        (f as { moduleId: string }).moduleId = moduleId;
+      }
+
+      // Auto-extract and register context from context-element fragments
+      const contextElements = allFragments
+        .filter((f): f is ContextElementFragment => f.is("context-element"))
+        .map((f) => f.element);
+
+      if (contextElements.length > 0) {
+        const ctx = createContext(contextElements);
+        setContext(ctx);
+      }
+
+      mod.fragments = allFragments;
+      if (resolvedCtx !== undefined) mod.context = resolvedCtx;
+
+      registerModule(mod as unknown as ArcModule);
+    };
+
+    const resolved = this.resolveCtx();
+    if (this._ctx !== undefined && !resolved) {
+      // `.context()` was declared but the binding has not evaluated yet —
+      // we are inside an import cycle between module packages (bundled ESM
+      // `var` hoisting yields `undefined` instead of a TDZ error). Defer the
+      // WHOLE registration to a microtask: it runs after the entire import
+      // graph has evaluated, so the module appears atomically WITH its
+      // context elements — no window where its wrappers/pages render
+      // against a context that is missing this module's elements.
+      queueMicrotask(() => {
+        const late = this.resolveCtx();
+        if (!late) {
+          console.error(
+            `[arc] module "${this.name}": context is still undefined after ` +
+              `the import graph evaluated — circular import between module ` +
+              `packages. Pass a thunk to survive the cycle: ` +
+              `module("${this.name}").context(() => ctx, scope). ` +
+              `Registering the module WITHOUT its context elements.`,
+          );
+        }
+        finalize(late);
+      });
+      return mod;
+    }
+
+    finalize(resolved);
     return mod;
   }
 }

package/src/index.ts

@@ -93,7 +93,7 @@ export type { LocaleProviderProps } from "./locale";
 export { useTitle } from "./hooks/use-title";
 
 // Platform
-export { loadModules, reloadModules, syncModules, useModuleLoader } from "./module-loader";
+export { loadModules, reloadModules, syncModules, useModuleLoader, useModulesReady } 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,5 +1,5 @@
 import { AnimatePresence, motion } from "framer-motion";
-import { Suspense, useEffect } from "react";
+import { Suspense, useEffect, useRef } from "react";
 import { getDefaultLayout } from "../registry";
 import { usePageFragments } from "./use-page-fragments";
 import { useArcNavigate, useArcRoute, matchRoutePath, hasRouteParams } from "../router";
@@ -81,6 +81,13 @@ function matchPage(path: string, pages: PageFragment[]): MatchResult | undefined
  * Renders the current page fragment inside its layout.
  * Supports parent pages with children — renders shell with tabs prop.
  */
+// A route that never matches must not be redirected away from more than this
+// many times. Beyond it, an app-level guard is almost certainly bouncing the
+// user straight back (e.g. a provider redirects to a page whose chunk is not
+// loaded for the current token) — redirecting again just spins, remounting the
+// whole tree until React throws #185. Stop, render blank, log a diagnosable error.
+const MAX_REDIRECTS_PER_ROUTE = 3;
+
 export function PageRouter() {
   const route = useArcRoute();
   const navigate = useArcNavigate();
@@ -89,6 +96,11 @@ export function PageRouter() {
   const match = matchPage(route, pages);
   const DefaultLayout = getDefaultLayout();
 
+  // Per-route count of fallback redirects we've issued from an unmatched path.
+  // Persists across the redirect ping-pong (cleared per route once it matches).
+  const redirectCounts = useRef<Map<string, number>>(new Map());
+  const loopedRoutes = useRef<Set<string>>(new Set());
+
   // Sync matched params to router context
   useEffect(() => {
     const newParams = match?.params ?? {};
@@ -104,10 +116,30 @@ export function PageRouter() {
 
   // 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 ?? "/");
+    if (match) {
+      // A route resolving clears its redirect budget so a later genuine
+      // visit (e.g. once a token-gated chunk loads) starts fresh.
+      redirectCounts.current.delete(route);
+      return;
+    }
+    if (pages.length === 0 || route === "/") return;
+    if (loopedRoutes.current.has(route)) return; // already gave up on this route
+
+    const count = redirectCounts.current.get(route) ?? 0;
+    if (count >= MAX_REDIRECTS_PER_ROUTE) {
+      loopedRoutes.current.add(route);
+      console.error(
+        `[arc] PageRouter: route "${route}" has no registered page and the ` +
+          `fallback redirect is looping — an app guard keeps sending the user ` +
+          `back here. Stopping on a blank screen. Likely cause: the page for ` +
+          `this route lives in a token-gated chunk not loaded for the current ` +
+          `token (check protectedBy / module chunk grouping).`,
+      );
+      return;
     }
+    redirectCounts.current.set(route, count + 1);
+    const firstNav = pages.find((p) => p.icon && p.label && !p.path.includes("/:"));
+    navigate(firstNav?.path ?? "/");
   }, [match, pages, route, navigate]);
 
   if (!match) {

package/src/module-loader.ts

@@ -1,12 +1,50 @@
+import { registerModuleSyncProvider } from "@arcote.tech/arc";
 import { clearModules, getAllRegisteredModules, getContext, setActiveModules } from "./registry";
 import type { BuildManifest, BuildManifestGroup } from "./types";
-import { useCallback, useEffect, useRef, useState } from "react";
+import {
+  useCallback,
+  useEffect,
+  useRef,
+  useState,
+  useSyncExternalStore,
+} from "react";
 
 /** @deprecated Use BuildManifest from "./types" */
 export type ModuleManifest = BuildManifest;
 
 export type ModuleLoaderState = "loading" | "ready" | "error";
 
+// ---------------------------------------------------------------------------
+// modulesReady store — module-level so `useModulesReady()` is callable from
+// anywhere in the tree without prop-drilling. False while a sync/load is in
+// flight, true otherwise (including on error — no longer "in flight").
+// ---------------------------------------------------------------------------
+
+let modulesReady = true;
+const readyListeners = new Set<() => void>();
+
+function setModulesReady(value: boolean): void {
+  if (modulesReady === value) return;
+  modulesReady = value;
+  for (const listener of readyListeners) listener();
+}
+
+/**
+ * Reactive flag: `false` while module chunks are being (re)loaded after a
+ * token change / initial load / dev reload, `true` otherwise. For declarative
+ * "loading workspace…" UI. SSR snapshot is `true` (no chunks to wait for).
+ */
+export function useModulesReady(): boolean {
+  return useSyncExternalStore(
+    (cb) => {
+      readyListeners.add(cb);
+      return () => readyListeners.delete(cb);
+    },
+    () => modulesReady,
+    () => true,
+  );
+}
+
 /**
  * URL for a token-group bundle. Server-filtered manifests carry a signed
  * `group.url`; we use that directly. The signed URL is intentionally
@@ -234,37 +272,52 @@ export function useModuleLoader(
 
   // Full reload — for dev-mode file changes (re-import all JS)
   const fullReload = useCallback(async () => {
+    setModulesReady(false);
     try {
       await reloadModules(baseUrl);
       setState("ready");
     } catch (e) {
       setError(e instanceof Error ? e : new Error(String(e)));
       setState("error");
+    } finally {
+      setModulesReady(true);
     }
   }, [baseUrl]);
 
   // Sync — for token changes (only fetch manifest, import new, remove stale)
   const sync = useCallback(async () => {
+    setModulesReady(false);
     try {
       await syncModules(baseUrl);
       setState("ready");
     } catch (e) {
       setError(e instanceof Error ? e : new Error(String(e)));
       setState("error");
+    } finally {
+      setModulesReady(true);
     }
   }, [baseUrl]);
 
+  // Register the module-sync provider so `scope.setToken()` can await chunk
+  // loading through the core coordinator (no platform→core back-dependency).
+  useEffect(() => {
+    if (options.skip) return;
+    return registerModuleSyncProvider(() => sync());
+  }, [sync, options.skip]);
+
   // Initial load
   useEffect(() => {
     if (options.skip || loaded.current) return;
     loaded.current = true;
 
+    setModulesReady(false);
     loadModules(baseUrl)
       .then(() => setState("ready"))
       .catch((e) => {
         setError(e instanceof Error ? e : new Error(String(e)));
         setState("error");
-      });
+      })
+      .finally(() => setModulesReady(true));
 
     // Listen for SSE reload events from CLI (code changed on disk → full reload)
     const evtSource = new EventSource(`${baseUrl}/api/reload-stream`);
@@ -280,13 +333,14 @@ export function useModuleLoader(
     return () => evtSource.close();
   }, [baseUrl, fullReload, options.skip]);
 
-  // Listen for token changes → sync (not full reload)
+  // Cross-tab token changes (another tab logged in/out → localStorage write)
+  // → sync. Same-tab changes are driven directly through the module-sync
+  // coordinator (scope.setToken → triggerModuleSync → registered provider),
+  // so we deliberately do NOT listen for the same-tab "arc:token-change"
+  // CustomEvent here — that would double-sync.
   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);
@@ -295,7 +349,6 @@ export function useModuleLoader(
     window.addEventListener("storage", onStorage);
 
     return () => {
-      window.removeEventListener("arc:token-change", onTokenChange);
       window.removeEventListener("storage", onStorage);
     };
   }, []);