@arcote.tech/platform 0.7.32 → 0.8.1

package/package.json

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

package/src/app-mount.tsx

@@ -0,0 +1,61 @@
+/**
+ * Standard routingu aplikacji montowanych pod prefiksem (spec/app-routing.md).
+ *
+ * Strony aplikacji deklarują ścieżki ABSOLUTNE WEWNĄTRZ aplikacji
+ * (`page("/tasks", ...)`, `page("/", Landing)`). Host montuje aplikację pod
+ * `basePath` (np. "/a/ndt") — przepisanie ścieżek robi rejestracja federowana
+ * (federation.ts), a KOD aplikacji zna swój prefiks wyłącznie przez helpery:
+ *
+ *   const href = useAppHref("/tasks");        // "/a/ndt/tasks" | "/tasks"
+ *   const nav  = useAppNavigate();
+ *   nav("/tasks/" + id);                       // redirect po akcji
+ *
+ * Reguła: KAŻDA nawigacja/link WEWNĄTRZ aplikacji idzie przez helpery — ten
+ * sam kod działa standalone (basePath = "") i w hoście. Linki do stron HOSTA
+ * to zwykłe `useArcNavigate` z pełną ścieżką hosta.
+ */
+
+import { createContext, useCallback, useContext, type ReactNode } from "react";
+import { useArcNavigate } from "./router";
+
+const AppMountContext = createContext<{ basePath: string }>({ basePath: "" });
+
+export function AppMountProvider({
+  basePath,
+  children,
+}: {
+  basePath: string;
+  children: ReactNode;
+}) {
+  return (
+    <AppMountContext.Provider value={{ basePath }}>
+      {children}
+    </AppMountContext.Provider>
+  );
+}
+
+/** Prefiks montowania bieżącej aplikacji ("" gdy standalone). */
+export function useAppBasePath(): string {
+  return useContext(AppMountContext).basePath;
+}
+
+/** Wersja nie-hook — do callbacków/utili z już znanym basePath. */
+export function appHref(basePath: string, path: string): string {
+  if (path === "/") return basePath || "/";
+  return basePath + path;
+}
+
+/** Adres strony TEJ aplikacji (path absolutny wewnątrz aplikacji). */
+export function useAppHref(path: string): string {
+  return appHref(useAppBasePath(), path);
+}
+
+/** Nawigacja wewnątrz TEJ aplikacji (redirecty po akcjach, linki). */
+export function useAppNavigate(): (path: string) => void {
+  const basePath = useAppBasePath();
+  const navigate = useArcNavigate();
+  return useCallback(
+    (path: string) => navigate(appHref(basePath, path)),
+    [basePath, navigate],
+  );
+}

package/src/arc.ts

@@ -9,6 +9,7 @@ import type {
   ContextElementFragment,
   ExtractPages,
   ModuleAccessRule,
+  ModuleExposure,
   PageFragment,
   PageOptions,
   SlotFragment,
@@ -154,9 +155,41 @@ class ModuleBuilder<
   private _ctx: ModuleContext | (() => ModuleContext) | undefined;
   private _scope: string | undefined;
   private _protectedBy: ModuleAccessRule[] = [];
+  private _expose: ModuleExposure | undefined;
 
   constructor(readonly name: string) {}
 
+  /**
+   * Wystaw ten moduł do ZEWNĘTRZNYCH hostów federacji
+   * (spec/module-federation.md). Domyślnie moduł jest lokalny (tylko własna
+   * platforma). Oznaczenie steruje BUILDEM: moduł `external`/`both` dostaje
+   * dodatkowy browser build federowany (framework peers external → import
+   * mapa hosta), a `local`/`both` normalny build (bundled) dla własnej
+   * platformy. Wykrywane build-time przez access-extractor (który i tak
+   * wykonuje moduły), więc deklaracja żyje TU, przy module.
+   *
+   *  - `local`    — tylko własna platforma (domyślnie, gdy nie wołasz metody),
+   *  - `external` — tylko zewnętrzny host (ukryty w macierzystej platformie),
+   *  - `both`     — i tu, i tam.
+   *
+   * `permissions`/`slots` to żądania per-moduł względem hosta (zgoda przy
+   * instalacji); `slug`/`auth` aplikacji idą z root package.json arc.federation.
+   */
+  exposeToHosts(
+    options: {
+      exposure?: "local" | "external" | "both";
+      permissions?: string[];
+      slots?: string[];
+    } = {},
+  ): this {
+    this._expose = {
+      exposure: options.exposure ?? "external",
+      permissions: options.permissions,
+      slots: options.slots,
+    };
+    return this;
+  }
+
   /**
    * Restrict module loading to users holding the given token.
    * Optional check function for granular access control.
@@ -247,6 +280,7 @@ class ModuleBuilder<
     };
     if (this._scope !== undefined) mod.scope = this._scope;
     if (this._protectedBy.length > 0) mod.access = { rules: this._protectedBy };
+    if (this._expose !== undefined) mod.expose = this._expose;
     if (domain) Object.assign(mod, domain);
 
     const finalize = (resolvedCtx: ModuleContext | undefined) => {

package/src/federated-app.tsx

@@ -0,0 +1,113 @@
+/**
+ * Per-aplikacyjny model dla modułów FEDEROWANYCH (spec/module-federation.md).
+ *
+ * Fragmenty modułu partnera renderują się wewnątrz `FederatedAppProvider`:
+ * provider trzyma (per slug, globalnie — nie per mount; StrictMode/podwójny
+ * WS) własną instancję `reactModel` wskazującą serwer PARTNERA
+ * (`remoteUrl = binding.baseUrl`) z izolowaną persystencją tokenów
+ * (`tokenStorageNamespace = slug`). Dzięki temu `usePlatformScope` w kodzie
+ * aplikacji — NIEZMIENIONYM względem standalone — trafia w model partnera,
+ * a nie hosta (patrz platform-context.tsx).
+ */
+
+import { createContext, useContext, type ReactNode } from "react";
+import { reactModel } from "@arcote.tech/arc-react";
+import type { ScopeAPI } from "@arcote.tech/arc-react";
+import { getFederatedContext } from "./federation";
+import { getFederatedWrapperFragments } from "./registry";
+import { AppMountProvider } from "./app-mount";
+import type { FederatedBinding } from "./types";
+
+interface FederatedModelHooks {
+  useModel: any;
+  createScope: (name: string) => ScopeAPI;
+  resetModel: () => void;
+  ModelProvider: (props: { children: ReactNode }) => ReactNode;
+}
+
+/** Model bieżącej aplikacji federowanej (null = renderujemy kod hosta). */
+export const FederatedAppContext = createContext<FederatedModelHooks | null>(
+  null,
+);
+
+export function useFederatedAppModel(): FederatedModelHooks | null {
+  return useContext(FederatedAppContext);
+}
+
+// Cache modeli per slug — instancja modelu (wire'y, WS, StreamingQueryCache,
+// AuthAdapter) MUSI przeżyć remounty (StrictMode podwaja mount) i być jedna
+// dla wszystkich punktów montowania aplikacji (strony + sloty + node'y).
+const models = new Map<string, FederatedModelHooks>();
+
+function getOrCreateModel(binding: FederatedBinding): FederatedModelHooks {
+  const cached = models.get(binding.slug);
+  if (cached) return cached;
+  const ctx = getFederatedContext(binding.slug);
+  if (!ctx) {
+    throw new Error(
+      `[arc] FederatedAppProvider("${binding.slug}"): no federated context — ` +
+        `load the app's modules first (federation loader) before rendering ` +
+        `its fragments.`,
+    );
+  }
+  const model = reactModel(ctx, {
+    remoteUrl: binding.baseUrl,
+    tokenStorageNamespace: binding.slug,
+  });
+  const hooks: FederatedModelHooks = {
+    useModel: model.useModel,
+    createScope: model.createScope,
+    resetModel: model.resetModel,
+    ModelProvider: model.ModelProvider as unknown as FederatedModelHooks["ModelProvider"],
+  };
+  models.set(binding.slug, hooks);
+  return hooks;
+}
+
+/** Usuwa model aplikacji (odinstalowanie / dev reload z nowym adresem). */
+export function resetFederatedAppModel(slug: string): void {
+  const hooks = models.get(slug);
+  models.delete(slug);
+  try {
+    hooks?.resetModel();
+  } catch {
+    // Model mógł nie być zainicjalizowany — nic do sprzątania.
+  }
+}
+
+export function FederatedAppProvider({
+  binding,
+  children,
+}: {
+  binding: FederatedBinding;
+  children: ReactNode;
+}) {
+  const hooks = getOrCreateModel(binding);
+  const { ModelProvider } = hooks;
+  // Wrappery APLIKACJI (np. jej AuthProvider) — wyłączone z globalnego
+  // renderu hosta (registry.getWrapperFragments), owijają tylko jej obszar.
+  let content: ReactNode = children;
+  const appWrappers = getFederatedWrapperFragments(binding.slug);
+  for (let i = appWrappers.length - 1; i >= 0; i--) {
+    const Wrapper = appWrappers[i].component;
+    content = <Wrapper>{content}</Wrapper>;
+  }
+  // Wrapper sesji hosta (wymiana asercji tożsamości → token aplikacji) —
+  // NA ZEWNĄTRZ wrapperów aplikacji (sesja gotowa zanim jej ProtectedRoute
+  // sprawdzi token), WEWNĄTRZ FederatedAppContext (scope'y modelu aplikacji).
+  const Session = binding.sessionWrapper;
+  content = Session ? (
+    <Session binding={binding}>{content}</Session>
+  ) : (
+    content
+  );
+  return (
+    <ModelProvider>
+      <FederatedAppContext.Provider value={hooks}>
+        <AppMountProvider basePath={binding.basePath}>
+          {content}
+        </AppMountProvider>
+      </FederatedAppContext.Provider>
+    </ModelProvider>
+  );
+}

package/src/federation.ts

@@ -0,0 +1,181 @@
+/**
+ * Federacja modułów — rejestracja modułów aplikacji PARTNERSKIEJ w hoście
+ * (spec/module-federation.md).
+ *
+ * Chunki aplikacji importowane z originu partnera wykonują przy imporcie
+ * zwykłe side-effecty `module().build()` → `registerModule`/`setContext`.
+ * Żeby moduł partnera nie zderzył się z modułami hosta (rejestr deduplikuje
+ * po NAZWIE, cicho — registry.ts) ani nie zmergował swoich elementów do
+ * globalnego kontekstu hosta, loader hosta otacza import oknem:
+ *
+ *   beginFederatedRegistration(binding)
+ *   await import(chunkUrl)
+ *   await tick()   // module().build() bywa odroczone do mikrotaska (arc.ts)
+ *   endFederatedRegistration()
+ *
+ * W oknie interceptor (wywoływany z registry.ts):
+ *  - prefiksuje nazwę modułu: `<slug>:<name>`,
+ *  - przepisuje ścieżki stron pod `basePath` (rekurencyjnie children),
+ *  - filtruje sloty do `allowedSlots` (grant z instalacji),
+ *  - stempluje `federation` na module i fragmentach (PageRouter/SlotRenderer
+ *    owijają je w FederatedAppProvider),
+ *  - kieruje elementy kontekstu do KONTEKSTU PER-APLIKACJA (globalny model
+ *    hosta nigdy nie widzi elementów partnera).
+ *
+ * KONTRAKT dla loadera: `endFederatedRegistration()` wolno wywołać dopiero po
+ * tiku (`await new Promise(r => setTimeout(r))`) — inaczej odroczona
+ * rejestracja wykona się POZA oknem i moduł wpadnie do hosta bez namespace.
+ */
+
+import type { ArcFragment, ArcModule, FederatedBinding, PageFragment } from "./types";
+
+let activeBinding: FederatedBinding | null = null;
+
+/** Konteksty per aplikacja (slug → ArcContext) — patrz FederatedAppProvider. */
+const federatedContexts = new Map<string, any>();
+
+/** Zarejestrowane wiązania (slug → binding) — dla UI hosta i providera. */
+const federatedApps = new Map<string, FederatedBinding>();
+const appListeners = new Set<() => void>();
+
+export function beginFederatedRegistration(binding: FederatedBinding): void {
+  if (activeBinding) {
+    throw new Error(
+      `[arc] beginFederatedRegistration("${binding.slug}") while ` +
+        `"${activeBinding.slug}" is still open — federated imports must not ` +
+        `overlap (await the tick + endFederatedRegistration() first).`,
+    );
+  }
+  activeBinding = binding;
+}
+
+export function endFederatedRegistration(): void {
+  activeBinding = null;
+}
+
+/** Aktywne wiązanie okna rejestracji (dla registry.ts). */
+export function getActiveFederatedBinding(): FederatedBinding | null {
+  return activeBinding;
+}
+
+/**
+ * Nadaje modułowi tożsamość federowaną — wołane z registerModule/
+ * forceRegisterModule PRZED wstawieniem do rejestru, tylko w otwartym oknie.
+ * Mutuje obiekt modułu/fragmentów in-place (fragmenty są współdzielone przez
+ * referencję z komponentami — kopiowanie zrywałoby tożsamość).
+ *
+ * Zwraca `false`, gdy moduł NIE MOŻE trafić do rejestru hosta — wtedy
+ * `registerModule` musi go pominąć.
+ */
+export function applyFederationToModule(mod: ArcModule): boolean {
+  const binding = activeBinding;
+  if (!binding) return true;
+  if (mod.federation) return true; // już przepisany (re-import w dev)
+
+  // KONTRAKT `exposeToHosts`: host przyjmuje WYŁĄCZNIE moduły, które partner
+  // jawnie wystawił (`manifest.app.modules`). Chunk wystawionego modułu wciąga
+  // transitywnie inne pakiety aplikacji, a ich `module().build()` odpala się
+  // przy imporcie — czyli WEWNĄTRZ tego okna. Bez tego filtra cała nawigacja
+  // partnera (strategia, treści, inspiracje…) wjeżdżałaby do hosta, mimo że
+  // wystawiony był jeden moduł.
+  if (binding.allowedModules && !binding.allowedModules.includes(mod.name)) {
+    return false;
+  }
+
+  (mod as { name: string }).name = `${binding.slug}:${mod.name}`;
+  mod.federation = binding;
+
+  const seenPages = new Set<PageFragment>();
+  const rewritePage = (page: PageFragment): void => {
+    if (seenPages.has(page)) return;
+    seenPages.add(page);
+    // basePath + "/" → basePath (root aplikacji), reszta prefiksowana wprost.
+    const mounted =
+      page.path === "/" ? binding.basePath || "/" : binding.basePath + page.path;
+    (page as { path: string }).path = mounted;
+    page.federation = binding;
+    for (const child of page.children ?? []) rewritePage(child);
+  };
+
+  const applyToFragments = (fragments: readonly ArcFragment[]): ArcFragment[] => {
+    const kept: ArcFragment[] = [];
+    for (const fragment of fragments) {
+      fragment.federation = binding;
+      if (fragment.is("page")) {
+        rewritePage(fragment as PageFragment);
+      } else if (fragment.is("slot")) {
+        const slotId = (fragment as { slotId?: string }).slotId ?? "";
+        // Sloty hosta tylko z grantu instalacji — reszta cicho odpada
+        // (deweloper widzi to w discovery/instalacji, nie w runtime hosta).
+        if (!binding.allowedSlots?.includes(slotId)) continue;
+      }
+      kept.push(fragment);
+    }
+    return kept;
+  };
+
+  (mod as { fragments: readonly ArcFragment[] }).fragments = applyToFragments(
+    mod.fragments,
+  );
+  (mod as { publicFragments: readonly ArcFragment[] }).publicFragments =
+    applyToFragments(mod.publicFragments);
+  return true;
+}
+
+/**
+ * Kierowanie elementów kontekstu w oknie federacji: elementy partnera trafiają
+ * do kontekstu per-aplikacja zamiast do globalnego kontekstu hosta. Zwraca
+ * true, gdy przejęło rejestrację (registry.setContext ma nie mergować).
+ */
+export function interceptSetContext(ctx: any): boolean {
+  const binding = activeBinding;
+  if (!binding || !ctx) return false;
+  const existing = federatedContexts.get(binding.slug);
+  if (!existing || existing === ctx) {
+    federatedContexts.set(binding.slug, ctx);
+    return true;
+  }
+  // Merge elementów kolejnych modułów tej samej aplikacji (dedup po name —
+  // lustro registry.setContext, ale w obrębie kontekstu aplikacji).
+  const names = new Set(existing.elements.map((e: any) => e.name ?? e.id ?? e));
+  for (const el of ctx.elements) {
+    const key = el.name ?? el.id ?? el;
+    if (names.has(key)) continue;
+    names.add(key);
+    existing.elements.push(el);
+    if (typeof el.name === "string" && existing.elementMap) {
+      existing.elementMap.set(el.name, el);
+    }
+  }
+  return true;
+}
+
+/** Kontekst aplikacji (elementy jej modułów) — dla FederatedAppProvider. */
+export function getFederatedContext(slug: string): any {
+  return federatedContexts.get(slug) ?? null;
+}
+
+/** Rejestruje aplikację po udanym załadowaniu jej modułów. */
+export function registerFederatedApp(binding: FederatedBinding): void {
+  federatedApps.set(binding.slug, binding);
+  for (const l of appListeners) l();
+}
+
+export function unregisterFederatedApp(slug: string): void {
+  federatedApps.delete(slug);
+  federatedContexts.delete(slug);
+  for (const l of appListeners) l();
+}
+
+export function getFederatedApp(slug: string): FederatedBinding | undefined {
+  return federatedApps.get(slug);
+}
+
+export function getFederatedApps(): FederatedBinding[] {
+  return [...federatedApps.values()];
+}
+
+export function subscribeFederatedApps(listener: () => void): () => void {
+  appListeners.add(listener);
+  return () => appListeners.delete(listener);
+}

package/src/index.ts

@@ -10,6 +10,7 @@ export {
   forceRegisterModule,
   getAllFragments,
   getAllModuleAccess,
+  getAllModuleExposure,
   getAllModules,
   getAllRegisteredModules,
   getContext,
@@ -58,6 +59,34 @@ export type {
   UseExpandableReturn,
 } from "@arcote.tech/arc-ds";
 
+// Module federation (spec/module-federation.md) — rejestracja modułów
+// aplikacji partnerskich pod namespace + per-app model + standard routingu.
+export {
+  beginFederatedRegistration,
+  endFederatedRegistration,
+  registerFederatedApp,
+  unregisterFederatedApp,
+  getFederatedApp,
+  getFederatedApps,
+  getFederatedContext,
+  subscribeFederatedApps,
+} from "./federation";
+export {
+  FederatedAppProvider,
+  FederatedAppContext,
+  useFederatedAppModel,
+  resetFederatedAppModel,
+} from "./federated-app";
+export {
+  AppMountProvider,
+  useAppBasePath,
+  useAppHref,
+  useAppNavigate,
+  appHref,
+} from "./app-mount";
+export { usePlatformHostScope } from "./platform-context";
+export type { FederatedBinding, FederationConfig } from "./types";
+
 // Layout (platform-specific — depends on registry/router)
 export { BlankLayout } from "./layout/blank-layout";
 export { ArcLayoutProvider } from "./layout/layout-provider";

package/src/layout/page-router.tsx

@@ -1,11 +1,24 @@
 import { AnimatePresence, motion } from "framer-motion";
-import { Suspense, useEffect, useRef } from "react";
+import { Suspense, useEffect, useRef, type ReactNode } from "react";
 import { getDefaultLayout } from "../registry";
+import { useModulesReady } from "../module-loader";
 import { usePageFragments } from "./use-page-fragments";
 import { useArcNavigate, useArcRoute, matchRoutePath, hasRouteParams } from "../router";
 import { useArcRouter } from "@arcote.tech/arc-ds";
+import { FederatedAppProvider } from "../federated-app";
 import type { PageFragment } from "../types";
 
+/** Strony modułów federowanych renderują się w modelu SWOJEJ aplikacji. */
+function withFederation(page: PageFragment, content: ReactNode): ReactNode {
+  return page.federation ? (
+    <FederatedAppProvider binding={page.federation}>
+      {content}
+    </FederatedAppProvider>
+  ) : (
+    content
+  );
+}
+
 type MatchResult = {
   page: PageFragment;
   child?: PageFragment;
@@ -95,6 +108,7 @@ export function PageRouter() {
   const pages = usePageFragments();
   const match = matchPage(route, pages);
   const DefaultLayout = getDefaultLayout();
+  const modulesReady = useModulesReady();
 
   // 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).
@@ -122,25 +136,45 @@ export function PageRouter() {
       redirectCounts.current.delete(route);
       return;
     }
+    // Modules still arriving → the page for this route may simply not be
+    // registered YET. `modulesReady` defaults to true, so apps without a
+    // module loader are unaffected.
+    if (!modulesReady) 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).`,
+    // DEFER the fallback by one macrotask. On a cold deep link the first
+    // render happens before the app is warm: initial chunks are in (so
+    // `pages.length > 0` and `modulesReady` is already true), but the auth
+    // provider has not applied the persisted token yet — and React runs child
+    // effects BEFORE parent ones, so this effect sees a state that is about to
+    // change. Redirecting synchronously would `pushState` over the URL and no
+    // later registration could bring the user back (token-gated chunks,
+    // federated `/a/<slug>` routes). Setting the token flips `modulesReady`
+    // to false within the same commit, which re-runs this effect and cancels
+    // the timer below. A route that is genuinely absent still redirects — just
+    // one tick later, once everything has settled.
+    const id = setTimeout(() => {
+      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("/:"),
       );
-      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]);
+      navigate(firstNav?.path ?? "/");
+    }, 0);
+    return () => clearTimeout(id);
+  }, [match, pages, route, navigate, modulesReady]);
 
   if (!match) {
     if (DefaultLayout) return <DefaultLayout>{null}</DefaultLayout>;
@@ -161,14 +195,15 @@ export function PageRouter() {
     const OuterShell = page.component;
     const InnerShell = child.component;
     const GrandchildComponent = grandchild.component;
-    const content = (
+    const content = withFederation(
+      page,
       <OuterShell tabs={page.children}>
         <InnerShell tabs={child.children}>
           <Suspense fallback={null}>
             <GrandchildComponent />
           </Suspense>
         </InnerShell>
-      </OuterShell>
+      </OuterShell>,
     );
     return Layout ? <Layout>{content}</Layout> : content;
   }
@@ -183,19 +218,21 @@ export function PageRouter() {
   if (page.children?.length && child) {
     const Shell = page.component;
     const ChildComponent = child.component;
-    const content = (
+    const content = withFederation(
+      page,
       <Shell tabs={page.children}>
         <Suspense fallback={null}>
           <ChildComponent />
         </Suspense>
-      </Shell>
+      </Shell>,
     );
     return Layout ? <Layout>{content}</Layout> : content;
   }
 
   // Regular page (no children)
   const PageComponent = page.component;
-  const pageContent = (
+  const pageContent = withFederation(
+    page,
     <AnimatePresence mode="wait">
       <motion.div
         key={page.path}
@@ -208,7 +245,7 @@ export function PageRouter() {
           <PageComponent />
         </Suspense>
       </motion.div>
-    </AnimatePresence>
+    </AnimatePresence>,
   );
 
   return Layout ? <Layout>{pageContent}</Layout> : pageContent;

package/src/layout/slot-renderer.tsx

@@ -1,6 +1,7 @@
 import type { DisplayMode } from "@arcote.tech/arc-ds";
 import { DisplayModeProvider, useDynamicSlotContent } from "@arcote.tech/arc-ds";
 import { Suspense } from "react";
+import { FederatedAppProvider } from "../federated-app";
 import type { SlotId } from "../types";
 import { useSlotFragments } from "./use-slot-fragments";
 
@@ -44,6 +45,14 @@ export function SlotRenderer({
       <div className={className}>
         {fragments.map((fragment, index) => {
           const Component = fragment.component;
+          // Slot modułu federowanego renderuje się w modelu SWOJEJ aplikacji.
+          const rendered = fragment.federation ? (
+            <FederatedAppProvider binding={fragment.federation}>
+              <Component />
+            </FederatedAppProvider>
+          ) : (
+            <Component />
+          );
           return (
             <div key={fragment.id} className="contents">
               {index > 0 && (
@@ -55,7 +64,7 @@ export function SlotRenderer({
                 />
               )}
               <Suspense fallback={suspenseFallback ?? null}>
-                <Component />
+                {rendered}
               </Suspense>
             </div>
           );

package/src/module-loader.ts

@@ -81,6 +81,11 @@ function decodeJwtPayload(jwt: string): { exp?: number } | null {
  * Read all persisted arc tokens from localStorage, dropping any whose `exp`
  * claim is in the past. Stale tokens are removed from localStorage so they
  * don't keep ghosting in subsequent reads.
+ *
+ * Reads ONLY the host's (un-namespaced) tokens: keys whose scope part
+ * contains `:` belong to a federated app's model namespace
+ * (`arc:token:<ns>:<scope>`, see AuthAdapter) and must never be sent to the
+ * host in X-Arc-Tokens.
  */
 function getAllPersistedTokens(): Record<string, string> {
   if (typeof localStorage === "undefined") return {};
@@ -90,6 +95,8 @@ function getAllPersistedTokens(): Record<string, string> {
   for (let i = 0; i < localStorage.length; i++) {
     const key = localStorage.key(i);
     if (!key?.startsWith("arc:token:")) continue;
+    const scope = key.slice(10);
+    if (scope.includes(":")) continue; // namespaced = token cudzego modelu
     const raw = localStorage.getItem(key);
     if (!raw) continue;
     const payload = decodeJwtPayload(raw);
@@ -97,7 +104,7 @@ function getAllPersistedTokens(): Record<string, string> {
       stale.push(key);
       continue;
     }
-    tokens[key.slice(10)] = raw;
+    tokens[scope] = raw;
   }
   for (const key of stale) localStorage.removeItem(key);
   return tokens;
@@ -434,9 +441,11 @@ export function useModuleLoader(
     if (typeof window === "undefined") return;
 
     const onStorage = (e: StorageEvent) => {
-      if (e.key?.startsWith("arc:token:")) {
-        setTokenVersion((v) => v + 1);
-      }
+      if (!e.key?.startsWith("arc:token:")) return;
+      // Namespaced keys (`arc:token:<ns>:<scope>`) belong to federated app
+      // models — host module sync must not react to them.
+      if (e.key.slice(10).includes(":")) return;
+      setTokenVersion((v) => v + 1);
     };
     window.addEventListener("storage", onStorage);
 

package/src/platform-context.tsx

@@ -1,6 +1,7 @@
 import type { ArcContextAny } from "@arcote.tech/arc";
 import type { ScopeAPI } from "@arcote.tech/arc-react";
 import { createContext, useContext, type ReactNode } from "react";
+import { FederatedAppContext } from "./federated-app";
 
 interface PlatformModelHooks {
   useModel: any;
@@ -37,9 +38,31 @@ export function usePlatformScope<C extends ArcContextAny>(
   _ctx: C,
   name: string,
 ): ScopeAPI<C> {
-  return usePlatformModel().createScope(name) as unknown as ScopeAPI<C>;
+  // Wewnątrz modułu FEDEROWANEGO scope trafia w model PARTNERA (osobne
+  // wire'y na jego serwer) — kod aplikacji jest identyczny standalone i w
+  // hoście. Oba useContext wołane bezwarunkowo (rules-of-hooks).
+  const federated = useContext(FederatedAppContext);
+  const platform = useContext(PlatformModelContext);
+  const hooks = federated ?? platform;
+  if (!hooks)
+    throw new Error(
+      "usePlatformScope must be used within PlatformModelProvider",
+    );
+  return hooks.createScope(name) as unknown as ScopeAPI<C>;
 }
 
 export function usePlatformResetModel() {
   return usePlatformModel().resetModel;
 }
+
+/**
+ * Scope modelu HOSTA — z pominięciem kontekstu federowanego. Dla kodu hosta
+ * renderowanego wewnątrz FederatedAppProvider (np. wrapper sesji, który musi
+ * zawołać agregaty hosta o asercję tożsamości, będąc w drzewie aplikacji).
+ */
+export function usePlatformHostScope<C extends ArcContextAny>(
+  _ctx: C,
+  name: string,
+): ScopeAPI<C> {
+  return usePlatformModel().createScope(name) as unknown as ScopeAPI<C>;
+}

package/src/registry.ts

@@ -4,11 +4,16 @@ import type {
   ArcModule,
   ContextElementFragment,
   ModuleAccess,
+  ModuleExposure,
   PageFragment,
   SlotFragment,
   SlotId,
   WrapperFragment,
 } from "./types";
+import {
+  applyFederationToModule,
+  interceptSetContext,
+} from "./federation";
 
 // ---------------------------------------------------------------------------
 // Registry — globalny rejestr modułów i ich fragmentów
@@ -34,6 +39,10 @@ export function subscribe(listener: () => void): () => void {
  * Use `forceRegisterModule` for dev reloads where code has actually changed.
  */
 export function registerModule(mod: ArcModule): void {
+  // W oknie federacji moduł partnera dostaje namespace `slug:` + prefiks
+  // ścieżek PRZED dedupem po nazwie (federation.ts). `false` = moduł spoza
+  // `exposeToHosts` partnera — nie wpuszczamy go do rejestru hosta.
+  if (!applyFederationToModule(mod)) return;
   for (const existing of modules.values()) {
     if (existing.name === mod.name) return;
   }
@@ -44,6 +53,7 @@ export function registerModule(mod: ArcModule): void {
 /** 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 {
+  if (!applyFederationToModule(mod)) return;
   for (const [id, existing] of modules) {
     if (existing.name === mod.name && id !== mod.id) {
       modules.delete(id);
@@ -59,12 +69,35 @@ export function unregisterModule(moduleId: string): void {
   notify();
 }
 
+/**
+ * Dopasowanie ścieżki do wzorca trasy publicznej. Reguły:
+ * - dokładne dopasowanie,
+ * - segmenty `:param` we wzorcu to wildcard (jeden segment) — dzięki temu
+ *   parametryzowane trasy publiczne (`/invite/:token`) pokrywają `/invite/abc`,
+ * - prefiks segmentowy — wzorzec krótszy niż ścieżka pokrywa podścieżki
+ *   (`/checkout` pokrywa `/checkout/success`).
+ * Wzorzec `/` (root) dopasowuje się WYŁĄCZNIE dokładnie (nie robi wszystkiego
+ * publicznym).
+ */
+function pathMatchesPublicPattern(clean: string, pattern: string): boolean {
+  if (clean === pattern) return true;
+  const ps = pattern.split("/").filter(Boolean);
+  if (ps.length === 0) return false; // "/" — tylko dokładne (obsłużone wyżej)
+  const cs = clean.split("/").filter(Boolean);
+  if (ps.length > cs.length) return false;
+  for (let i = 0; i < ps.length; i++) {
+    if (ps[i].startsWith(":")) continue; // param = dowolny jeden segment
+    if (ps[i] !== cs[i]) return false;
+  }
+  return true;
+}
+
 /**
  * Czy ścieżka należy do strony zadeklarowanej w `.public({...})` któregokolwiek
  * zarejestrowanego modułu. Źródłem prawdy jest rejestr — wrappery ochronne
  * (np. ProtectedRoute aplikacji) NIE muszą hardcodować listy publicznych
- * ścieżek. Dopasowanie: dokładne lub prefiks segmentowy
- * (`/checkout` pokrywa `/checkout/success`); query/hash ignorowane.
+ * ścieżek. Dopasowanie: dokładne, po parametrach (`:token`) lub prefiks
+ * segmentowy (`/checkout` pokrywa `/checkout/success`); query/hash ignorowane.
  */
 export function isPublicPagePath(path: string): boolean {
   const clean = path.split("?")[0].split("#")[0] || "/";
@@ -73,8 +106,7 @@ export function isPublicPagePath(path: string): boolean {
       if (!fragment?.is?.("page")) continue;
       const pagePath = (fragment as PageFragment).path;
       if (!pagePath) continue;
-      if (clean === pagePath) return true;
-      if (pagePath !== "/" && clean.startsWith(`${pagePath}/`)) return true;
+      if (pathMatchesPublicPattern(clean, pagePath)) return true;
     }
   }
   return false;
@@ -86,7 +118,15 @@ 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));
+  // Moduły FEDEROWANE są poza filtrem aktywności: ta lista powstaje z manifestu
+  // HOSTA (module-loader → setActiveModules), a moduł partnera z definicji się
+  // w nim nie znajdzie. Bez tego wyjątku każdy sync chunków po zmianie tokena
+  // wymiatał `slug:moduł` tuż po tym, jak loader federacji go zarejestrował —
+  // trasy `/a/<slug>/*` znikały, a router odsyłał użytkownika na stronę
+  // startową. Ich cyklem życia zarządza loader federacji, nie sync hosta.
+  return [...modules.values()].filter(
+    (m) => m.federation || activeModuleNames!.has(m.name),
+  );
 }
 
 /** Get ALL registered modules (ignoring active filter). */
@@ -124,6 +164,9 @@ function notifyContext(): void {
  *  like `model.context.get("strategyConsultation")` would yield undefined
  *  for any module registered after the model was created. */
 export function setContext(ctx: any): void {
+  // W oknie federacji elementy partnera idą do kontekstu PER-APLIKACJA —
+  // globalny kontekst/model hosta nigdy ich nie widzi (federation.ts).
+  if (interceptSetContext(ctx)) return;
   if (currentContext && ctx && currentContext !== ctx) {
     const existingNames = new Set(
       currentContext.elements.map((e: any) => e.name ?? e.id ?? e),
@@ -260,7 +303,21 @@ export function getPageByPath(path: string): PageFragment | undefined {
 
 export function getWrapperFragments(): WrapperFragment[] {
   const fragments = getAllFragments().filter(
-    (f): f is WrapperFragment => f.is("wrapper"),
+    (f): f is WrapperFragment =>
+      f.is("wrapper") &&
+      // Wrappery modułów FEDEROWANYCH nie owijają hosta globalnie (np.
+      // ProtectedRoute aplikacji przekierowywałby userów hosta!) — renderuje
+      // je FederatedAppProvider wokół obszaru SWOJEJ aplikacji.
+      !f.federation,
+  );
+  return sortByOrdering(fragments);
+}
+
+/** Wrappery modułów danej aplikacji federowanej (dla FederatedAppProvider). */
+export function getFederatedWrapperFragments(slug: string): WrapperFragment[] {
+  const fragments = getAllFragments().filter(
+    (f): f is WrapperFragment =>
+      f.is("wrapper") && f.federation?.slug === slug,
   );
   return sortByOrdering(fragments);
 }
@@ -282,6 +339,19 @@ export function getAllModuleAccess(): Map<string, ModuleAccess> {
   return result;
 }
 
+/**
+ * Deklaracje `exposeToHosts()` wszystkich modułów (federacja per-moduł) —
+ * czytane build-time przez access-extractor, żeby build wiedział, które
+ * moduły federować (spec/module-federation.md).
+ */
+export function getAllModuleExposure(): Map<string, ModuleExposure> {
+  const result = new Map<string, ModuleExposure>();
+  for (const mod of modules.values()) {
+    if (mod.expose) result.set(mod.name, mod.expose);
+  }
+  return result;
+}
+
 /** Clear all modules (but keep context). Used for reload. */
 export function clearModules(): void {
   modules.clear();

package/src/types.ts

@@ -26,11 +26,52 @@ export interface FragmentOrdering {
 
 export type ArcComponent = ComponentType<any> | LazyExoticComponent<ComponentType<any>>;
 
+/**
+ * Wiązanie modułu FEDEROWANEGO — modułu aplikacji partnerskiej załadowanego
+ * do hosta z innego originu (spec/module-federation.md). Ustawiane przez
+ * interceptor rejestracji (federation.ts) na module i jego fragmentach.
+ */
+export interface FederatedBinding {
+  /** Id aplikacji w hoście (np. wiersz agregatu aplikacji). */
+  readonly appId: string;
+  /** Slug aplikacji — namespace nazw modułów i tokenów ([a-z0-9-]+). */
+  readonly slug: string;
+  /** Origin serwera partnera (komendy/query/WS + chunki). */
+  readonly baseUrl: string;
+  /** Prefiks montowania stron w hoście (np. "/a/ndt"); "" = standalone. */
+  readonly basePath: string;
+  /** Dozwolone sloty hosta (grant z instalacji); undefined = żadne. */
+  readonly allowedSlots?: readonly string[];
+  /**
+   * Moduły, które partner WYSTAWIŁ (`exposeToHosts` → `manifest.app.modules`).
+   * Rejestracja przyjmuje wyłącznie te — chunk wystawionego modułu wciąga
+   * transitywnie inne pakiety aplikacji, których `module().build()` odpala się
+   * przy imporcie, więc bez tej listy cała nawigacja partnera wjeżdża do hosta.
+   * `undefined` = brak filtra (kompatybilność; host POWINIEN ją podawać).
+   */
+  readonly allowedModules?: readonly string[];
+  /** Id instalacji w hoście (kotwica tożsamości — spec/app-identity.md). */
+  readonly installId?: string;
+  /** Wymiana tożsamości aplikacji (z manifestu federacji). */
+  readonly auth?: { readonly exchangeCommand: string; readonly scope: string };
+  /**
+   * Wrapper sesji wstrzykiwany przez HOSTA — renderowany WEWNĄTRZ
+   * FederatedAppProvider (ma dostęp do modelu aplikacji), wokół fragmentów.
+   * Host realizuje tu wymianę asercji tożsamości na token aplikacji.
+   */
+  readonly sessionWrapper?: ComponentType<{
+    binding: FederatedBinding;
+    children?: ReactNode;
+  }>;
+}
+
 interface FragmentBase {
   readonly id: string;
   readonly types: readonly string[];
   moduleId: string;
   is(type: string): boolean;
+  /** Obecne, gdy fragment pochodzi z modułu federowanego (federation.ts). */
+  federation?: FederatedBinding;
 }
 
 // ---------------------------------------------------------------------------
@@ -149,18 +190,80 @@ export interface BuildManifest {
   /** sha256 hex over styles.css (+ theme.css if present). */
   readonly stylesHash: string;
   readonly buildTime: string;
+  /**
+   * Peer-shell (spec/module-federation.md): mapa specifier →
+   * `/shell/<short>.<hash>.js` (import mapa w shell HTML) + wersje peers.
+   * Obecne, gdy aplikacja jest HOSTEM (`arc.federation.host`) lub eksportuje
+   * moduły (`module().exposeToHosts()`).
+   */
+  readonly shell?: {
+    readonly imports: Readonly<Record<string, string>>;
+    readonly peers: Readonly<Record<string, string>>;
+  };
+  /**
+   * Obecne, gdy aplikacja eksportuje moduły do zewnętrznych hostów (jakiś
+   * moduł ma `exposeToHosts()` external/both). Zawiera OSOBNY build
+   * federowany (external peers, w `browser-fed/`) wystawiany przez
+   * `/api/federation/manifest`.
+   */
+  readonly federation?: {
+    /** slug + auth aplikacji z `arc.federation` (spec/app-identity.md). */
+    readonly config: FederationConfig;
+    /** Nazwy modułów wystawionych (exposeToHosts external/both). */
+    readonly modules: readonly string[];
+    /** Uprawnienia/sloty żądane przez moduły (suma). */
+    readonly permissions: readonly string[];
+    readonly slots: readonly string[];
+    /** Artefakty buildu federowanego (browser-fed/). */
+    readonly build: {
+      readonly initial: { readonly file: string; readonly hash: string };
+      readonly groups: Readonly<Record<string, BuildManifestGroup>>;
+      readonly sharedChunks: readonly string[];
+    };
+  };
+}
+
+/**
+ * `arc.federation` w root package.json (spec/module-federation.md) — tożsamość
+ * aplikacji jako całości. Które MODUŁY są wystawione, decyduje
+ * `module().exposeToHosts()` (per-moduł), nie ten obiekt.
+ */
+export interface FederationConfig {
+  /** Host federacji (np. BMF): build z external peers + import mapa. */
+  readonly host?: boolean;
+  /** Slug aplikacji ([a-z0-9-]+) — namespace modułów i tokenów w hoście. */
+  readonly slug?: string;
+  /** Wymiana tożsamości: publiczna komenda + scope (spec/app-identity.md). */
+  readonly auth?: { readonly exchangeCommand: string; readonly scope: string };
 }
 
 // ---------------------------------------------------------------------------
 // Moduł
 // ---------------------------------------------------------------------------
 
+/**
+ * Deklaracja `module().exposeToHosts(...)` — czy i jak moduł jest wystawiany
+ * zewnętrznym hostom federacji (spec/module-federation.md). Odczytywana
+ * build-time przez access-extractor.
+ */
+export interface ModuleExposure {
+  readonly exposure: "local" | "external" | "both";
+  /** Uprawnienia żądane od hosta (zgoda przy instalacji). */
+  readonly permissions?: readonly string[];
+  /** Sloty hosta, o które moduł prosi. */
+  readonly slots?: readonly string[];
+}
+
 export interface ArcModule {
   readonly id: string;
   readonly name: string;
   readonly fragments: readonly ArcFragment[];
   readonly publicFragments: readonly ArcFragment[];
   readonly access?: ModuleAccess;
+  /** Deklaracja wystawienia modułu zewnętrznym hostom (exposeToHosts). */
+  readonly expose?: ModuleExposure;
+  /** Obecne, gdy moduł został zarejestrowany jako federowany (federation.ts). */
+  federation?: FederatedBinding;
 }
 
 // ---------------------------------------------------------------------------

package/tests/federation.test.ts

@@ -0,0 +1,216 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import {
+  beginFederatedRegistration,
+  endFederatedRegistration,
+  getFederatedContext,
+  unregisterFederatedApp,
+} from "../src/federation";
+import {
+  clearRegistry,
+  getAllRegisteredModules,
+  getContext,
+  registerModule,
+  setContext,
+} from "../src/registry";
+import { appHref } from "../src/app-mount";
+import type { ArcModule, FederatedBinding, PageFragment } from "../src/types";
+
+/**
+ * Testy okna rejestracji federowanej (spec/module-federation.md): namespacing
+ * nazw modułów, przepisywanie ścieżek stron pod basePath, filtr slotów po
+ * grantach, kierowanie elementów do kontekstu per-aplikacja oraz kontrakt
+ * ticku (odroczona rejestracja przez queueMicrotask — arc.ts).
+ */
+
+const BINDING: FederatedBinding = {
+  appId: "app-1",
+  slug: "ndt",
+  baseUrl: "http://localhost:5007",
+  basePath: "/a/ndt",
+  allowedSlots: ["bmf:document-panel"],
+};
+
+function page(path: string, children?: PageFragment[]): PageFragment {
+  return {
+    id: `pg:${path}`,
+    types: ["page"] as const,
+    moduleId: "m",
+    is: (t: string) => t === "page",
+    path,
+    component: () => null,
+    children,
+    ordering: {},
+  } as unknown as PageFragment;
+}
+
+function slot(slotId: string) {
+  return {
+    id: `sl:${slotId}`,
+    types: ["slot"] as const,
+    moduleId: "m",
+    is: (t: string) => t === "slot",
+    slotId,
+    component: () => null,
+    ordering: {},
+  } as unknown as ArcModule["fragments"][number];
+}
+
+function mod(name: string, fragments: ArcModule["fragments"]): ArcModule {
+  return {
+    id: `${name}-${Math.random().toString(36).slice(2)}`,
+    name,
+    fragments,
+    publicFragments: fragments,
+  } as ArcModule;
+}
+
+function fakeCtx(names: string[]) {
+  const elements = names.map((n) => ({ name: n }));
+  return { elements, elementMap: new Map(elements.map((e) => [e.name, e])) };
+}
+
+afterEach(() => {
+  endFederatedRegistration();
+  unregisterFederatedApp("ndt");
+  clearRegistry();
+});
+
+describe("kontrakt exposeToHosts", () => {
+  // Regresja: chunk wystawionego modułu wciąga transitywnie inne pakiety
+  // aplikacji, a ich `module().build()` odpala się przy imporcie — czyli w
+  // otwartym oknie. Bez `allowedModules` cała nawigacja partnera (strategia,
+  // treści, inspiracje) wjeżdżała do hosta, mimo że wystawiony był `admin`.
+  const ONLY_ADMIN: FederatedBinding = { ...BINDING, allowedModules: ["admin"] };
+
+  test("rejestruje TYLKO moduły wystawione przez partnera", () => {
+    const admin = mod("admin", [page("/admin")]);
+    const strategia = mod("strategy", [page("/strategy")]);
+    const tresci = mod("content", [page("/content")]);
+
+    beginFederatedRegistration(ONLY_ADMIN);
+    registerModule(admin);
+    registerModule(strategia);
+    registerModule(tresci);
+    endFederatedRegistration();
+
+    const nazwy = getAllRegisteredModules().map((m) => m.name);
+    expect(nazwy).toEqual(["ndt:admin"]);
+    // Niewystawione moduły zostają NIETKNIĘTE — bez namespace'u i bez bindingu,
+    // więc nie da się ich pomylić z modułem federowanym.
+    expect(strategia.name).toBe("strategy");
+    expect(strategia.federation).toBeUndefined();
+    expect(tresci.federation).toBeUndefined();
+  });
+
+  test("bez allowedModules filtr nie obowiązuje (kompatybilność)", () => {
+    const cokolwiek = mod("strategy", [page("/strategy")]);
+    beginFederatedRegistration(BINDING);
+    registerModule(cokolwiek);
+    endFederatedRegistration();
+    expect(getAllRegisteredModules().map((m) => m.name)).toEqual([
+      "ndt:strategy",
+    ]);
+  });
+});
+
+describe("okno rejestracji federowanej", () => {
+  test("namespacing nazwy + prefiks ścieżek (rekurencyjnie) + stamp federation", () => {
+    const tasks = page("/tasks", [page("/tasks/:id")]);
+    const root = page("/");
+    const m = mod("tasks", [tasks, root]);
+
+    beginFederatedRegistration(BINDING);
+    registerModule(m);
+    endFederatedRegistration();
+
+    expect(m.name).toBe("ndt:tasks");
+    expect(m.federation).toBe(BINDING);
+    expect(tasks.path).toBe("/a/ndt/tasks");
+    expect(tasks.children?.[0].path).toBe("/a/ndt/tasks/:id");
+    expect(root.path).toBe("/a/ndt");
+    expect(tasks.federation).toBe(BINDING);
+  });
+
+  test("kolizja nazwy z modułem hosta znika (dedup widzi już ndt:...)", () => {
+    const host = mod("tasks", [page("/tasks")]);
+    registerModule(host);
+
+    const partner = mod("tasks", [page("/tasks")]);
+    beginFederatedRegistration(BINDING);
+    registerModule(partner);
+    endFederatedRegistration();
+
+    const names = getAllRegisteredModules().map((m) => m.name);
+    expect(names).toContain("tasks");
+    expect(names).toContain("ndt:tasks");
+  });
+
+  test("sloty spoza grantu odpadają; z grantu zostają", () => {
+    const allowed = slot("bmf:document-panel");
+    const denied = slot("toolbar-right");
+    const m = mod("widgets", [allowed, denied]);
+
+    beginFederatedRegistration(BINDING);
+    registerModule(m);
+    endFederatedRegistration();
+
+    const ids = m.fragments.map((f) => f.id);
+    expect(ids).toContain("sl:bmf:document-panel");
+    expect(ids).not.toContain("sl:toolbar-right");
+  });
+
+  test("setContext w oknie idzie do kontekstu per-app, nie do hosta", () => {
+    setContext(fakeCtx(["hostEl"]));
+
+    beginFederatedRegistration(BINDING);
+    setContext(fakeCtx(["order", "placeOrder"]));
+    setContext(fakeCtx(["placeOrder", "orderPlaced"])); // drugi moduł tej samej app
+    endFederatedRegistration();
+
+    const hostCtx = getContext<{ elements: { name: string }[] }>();
+    expect(hostCtx.elements.map((e) => e.name)).toEqual(["hostEl"]);
+
+    const fedCtx = getFederatedContext("ndt");
+    expect(fedCtx.elements.map((e: { name: string }) => e.name).sort()).toEqual([
+      "order",
+      "orderPlaced",
+      "placeOrder",
+    ]);
+  });
+
+  test("kontrakt ticku: rejestracja odroczona mikrotaskiem łapie się w oknie", async () => {
+    const m = mod("deferred", [page("/x")]);
+    beginFederatedRegistration(BINDING);
+    queueMicrotask(() => registerModule(m)); // jak module().build() przy cyklu
+    await new Promise((r) => setTimeout(r)); // tick loadera
+    endFederatedRegistration();
+
+    expect(m.name).toBe("ndt:deferred");
+  });
+
+  test("bez ticku moduł wpada bez namespace (dokumentacja pułapki)", async () => {
+    const m = mod("tooEarly", [page("/x")]);
+    beginFederatedRegistration(BINDING);
+    queueMicrotask(() => registerModule(m));
+    endFederatedRegistration(); // za wcześnie!
+    await new Promise((r) => setTimeout(r));
+
+    expect(m.name).toBe("tooEarly");
+  });
+
+  test("nakładające się okna rzucają", () => {
+    beginFederatedRegistration(BINDING);
+    expect(() =>
+      beginFederatedRegistration({ ...BINDING, slug: "inna" }),
+    ).toThrow();
+  });
+});
+
+describe("appHref (standard routingu)", () => {
+  test("prefiksowanie + root", () => {
+    expect(appHref("/a/ndt", "/tasks")).toBe("/a/ndt/tasks");
+    expect(appHref("/a/ndt", "/")).toBe("/a/ndt");
+    expect(appHref("", "/tasks")).toBe("/tasks");
+    expect(appHref("", "/")).toBe("/");
+  });
+});