@stardeck-customer-apps/compose 0.6.0 → 0.8.0

package/SKILL.md

@@ -9,11 +9,13 @@ Every Module in `apps/web/src/modules/*` declares its mounts, endpoints,
 enhancements, contributions, i18n layers and data stores in `module.json`.
 Compose turns that declaration into the code Next.js actually builds:
 
-- `apps/web/src/modules.gen.ts` — the Module registry and `isModuleEnabled`
+- `apps/web/src/modules.gen.ts` — the Module registry, `isModuleEnabled` and `isMountHeadless`
 - `apps/web/src/module-contributions.gen.ts`
 - `apps/web/src/module-i18n.gen.ts`
 - `apps/web/src/module-init.server.gen.ts`
 - `apps/web/src/module-datastores.gen.ts`
+- `apps/web/src/module-server.gen.ts` — `MODULE_SERVER_REGISTRATIONS`, one entry
+  per composed Module that ships `server/registrations.ts`
 - one `page.tsx` / `route.ts` stub under `apps/web/src/app/**` per declared
   mount and endpoint
 
@@ -89,6 +91,31 @@ a silent fallback. It holds deployment facts: gitignore it (`apps/web/.gitignore
   locale; the locale also needs a `lib/i18n/substrate/<locale>.json`. New keys
   go in `lib/i18n/substrate/<locale>.json`, never in an override. Needs compose
   0.6.0 or later.
+- **Headless mounts.** `NEXT_PUBLIC_STARDECK_HEADLESS_MOUNTS` (set by the
+  platform from the Modules tab) lists mount keys `<module>:<group>/<segment>`
+  from `module.json` `mounts`, comma-joined, e.g. `pos:(register)/register`.
+  The generated page for a listed mount returns not-found, and `admin.nav`
+  entries whose `href` is that mount's path (or below it) are dropped. The rest
+  of the Module keeps running: its other mounts, every endpoint, `server/`,
+  `client/`, initializers and other contributions. Build your own screen in
+  app code on the Module's `server/` entry and `client/` hooks, at a different
+  URL: the generated page still exists, so an app page at the same URL fails
+  compose as a route collision.
+  `isMountHeadless(key)` and `isHrefHeadless(href)` are exported from
+  `@/modules.gen`. Needs compose 0.7.0 or later.
+- **Server registrations.** Per-Module server wiring that the app layer runs
+  (seeds, schedule handlers, and similar) goes in the Module's
+  `server/registrations.ts`, any Module kind. Compose imports each composed
+  Module's file as a namespace into `module-server.gen.ts`:
+  `MODULE_SERVER_REGISTRATIONS` is a
+  `readonly { module: string; registrations: Readonly<Record<string, unknown>> }[]`.
+  A Module left out by `--enabled` is not imported at all, so its server code
+  drops out of the build. App code reads that array from `@/module-server.gen`
+  and narrows the exports it expects (e.g. `registrations.seed`); it must never
+  import a Module's seed or schedules directly, or a disabled Module stays in
+  the bundle. Compose does not check the export names or shapes. The file
+  counts as `server/**/*.ts`, so the Module also needs `server/index.ts`.
+  Needs compose 0.8.0 or later.
 - `@stardeck-customer-apps/compose/runtime` exports `isModuleEnabledByList`,
   the single enablement rule, and imports nothing — it is safe in client
   components.
@@ -99,5 +126,5 @@ After each run compose rewrites `apps/web/src/app/.gitignore` with one entry per
 stub it emits — stubs are scattered one-per-route and cannot be globbed. Commit
 that file: it is deterministic output, and compose rewrites it only when the set
 of stubs changes, so an unchanged compose leaves `git status` clean. It does not
-list the five `src/*.gen.ts`; a static `src/*.gen.ts` line in `apps/web/.gitignore`
+list the six `src/*.gen.ts`; a static `src/*.gen.ts` line in `apps/web/.gitignore`
 covers those. Compose refuses to touch the file if line 1 is not its own header.

package/dist/cli.js

@@ -3891,10 +3891,12 @@ function analyzeClientSafeEntryImports(sourceText, fileName) {
 var APP_WEB_PREFIX = "apps/web/";
 var MODULE_STUB_MARKER = "@stardeck-module-rail-generated";
 var ENABLED_MODULES_ENV = "NEXT_PUBLIC_STARDECK_ENABLED_MODULES";
+var HEADLESS_MOUNTS_ENV = "NEXT_PUBLIC_STARDECK_HEADLESS_MOUNTS";
 var MODULE_CONTRIBUTIONS_GEN_PATH = `${APP_WEB_PREFIX}src/module-contributions.gen.ts`;
 var MODULE_DATASTORES_GEN_PATH = `${APP_WEB_PREFIX}src/module-datastores.gen.ts`;
 var MODULE_I18N_GEN_PATH = `${APP_WEB_PREFIX}src/module-i18n.gen.ts`;
 var MODULE_INIT_SERVER_GEN_PATH = `${APP_WEB_PREFIX}src/module-init.server.gen.ts`;
+var MODULE_SERVER_GEN_PATH = `${APP_WEB_PREFIX}src/module-server.gen.ts`;
 var MODULES_GEN_PATH = `${APP_WEB_PREFIX}src/modules.gen.ts`;
 var APP_EXTENSIONS_PATH = `${APP_WEB_PREFIX}src/lib/modules/app-extensions.ts`;
 
@@ -4127,6 +4129,11 @@ function isModuleEnabledByList(raw, name, kindOf) {
   return raw.split(",").includes(name);
 }
 
+// ../../packages/lib/src/shared/module-mount-key.ts
+function mountKey(moduleName, mount) {
+  return `${moduleName}:${mount.group}/${mount.segment}`;
+}
+
 // ../../packages/lib/src/server/module-rail/composition-artifacts.ts
 var import_typescript4 = __toESM(require("typescript"), 1);
 
@@ -4135,7 +4142,8 @@ var COMPOSITION_RUNTIME_GEN_PATHS = [
   MODULE_CONTRIBUTIONS_GEN_PATH,
   MODULE_I18N_GEN_PATH,
   MODULE_INIT_SERVER_GEN_PATH,
-  MODULE_DATASTORES_GEN_PATH
+  MODULE_DATASTORES_GEN_PATH,
+  MODULE_SERVER_GEN_PATH
 ];
 function compareNames(a, b) {
   return a < b ? -1 : a > b ? 1 : 0;
@@ -4156,6 +4164,9 @@ function formatI18nMarker() {
 function formatInitMarker() {
   return `// ${MODULE_STUB_MARKER} scope=init`;
 }
+function formatServerMarker() {
+  return `// ${MODULE_STUB_MARKER} scope=server`;
+}
 function formatDatastoresMarker() {
   return `// ${MODULE_STUB_MARKER} scope=datastores`;
 }
@@ -4455,7 +4466,7 @@ function emitModuleContributionsGenTs(input) {
     "  type SurfaceSlotCatalog,",
     '} from "@/lib/modules/contributions";',
     'import { substrateSlotCatalogs } from "@/lib/modules/substrate-slots";',
-    'import { generatedModuleRegistry, isModuleEnabled } from "@/modules.gen";',
+    'import { generatedModuleRegistry, isHrefHeadless, isModuleEnabled } from "@/modules.gen";',
     ...[...moduleImportLines].sort((a, b) => {
       const pathA = a.match(/from ("[^"]+")/)?.[1] ?? a;
       const pathB = b.match(/from ("[^"]+")/)?.[1] ?? b;
@@ -4505,11 +4516,19 @@ function emitModuleContributionsGenTs(input) {
     "export function resolveModuleContributions(",
     "  registry: typeof generatedModuleRegistry = generatedModuleRegistry",
     "): ResolvedModuleContributions {",
-    "  return resolveContributions({",
+    "  const resolved = resolveContributions({",
     "    registry,",
     "    catalogs: moduleSlotCatalogs,",
     "    sources: moduleContributionSources,",
     "  });",
+    "  // A nav entry into a headless mount would link to a page that is switched off.",
+    '  const nav = resolved["admin.nav"];',
+    "  if (nav) {",
+    '    resolved["admin.nav"] = nav.filter(',
+    "      (entry) => !isHrefHeadless((entry as { href?: unknown }).href)",
+    "    );",
+    "  }",
+    "  return resolved;",
     "}",
     "",
     "export const resolvedModuleContributions: ResolvedModuleContributions =",
@@ -4791,6 +4810,42 @@ function emitModuleInitServerGenTs(input) {
     ""
   ].join("\n");
 }
+function emitModuleServerGenTs(input) {
+  const installed = new Set(input.registry.modules.map((m) => m.name));
+  const moduleNames = input.facts.filter((f) => f.hasServerRegistrations && installed.has(f.moduleName)).map((f) => f.moduleName).sort(compareNames);
+  for (const name of moduleNames) {
+    if (!isValidModuleName(name)) {
+      throw new Error(`[ModuleRail] composition artifacts: invalid module name "${name}"`);
+    }
+  }
+  const importLines = moduleNames.map(
+    (name, index) => [
+      `@/modules/${name}/server/registrations`,
+      `import * as serverRegistrations${index} from ${JSON.stringify(`@/modules/${name}/server/registrations`)};`
+    ]
+  ).sort((a, b) => compareImportSpecifiers(a[0], b[0])).map(([, line]) => line);
+  const entryLines = moduleNames.map(
+    (name, index) => `  { module: ${JSON.stringify(name)}, registrations: serverRegistrations${index} },`
+  );
+  return [
+    formatServerMarker(),
+    "/** DO NOT EDIT \u2014 owned by the module install rail. */",
+    "",
+    ...importLines,
+    ...importLines.length > 0 ? [""] : [],
+    "export type ModuleServerRegistration = {",
+    "  module: string;",
+    "  registrations: Readonly<Record<string, unknown>>;",
+    "};",
+    "",
+    ...entryLines.length === 0 ? ["export const MODULE_SERVER_REGISTRATIONS: readonly ModuleServerRegistration[] = [];"] : [
+      "export const MODULE_SERVER_REGISTRATIONS: readonly ModuleServerRegistration[] = [",
+      ...entryLines,
+      "];"
+    ],
+    ""
+  ].join("\n");
+}
 
 // ../../packages/lib/src/server/module-rail/composition-artifacts.ts
 var COMPOSITION_ARTIFACTS_GENERATED_BY = "module-rail";
@@ -4853,6 +4908,14 @@ function formatRouteMarker(owner, nextRelativePath) {
 function formatRegistryMarker() {
   return `// ${MODULE_STUB_MARKER} scope=registry`;
 }
+var OWNERLESS_MARKER_KINDS = [
+  "registry",
+  "contributions",
+  "datastores",
+  "i18n",
+  "init",
+  "server"
+];
 function parseCompositionArtifactMarker(source) {
   const firstLine = source.split(/\r?\n/, 1)[0]?.trim() ?? "";
   const match = firstLine.match(
@@ -4863,26 +4926,8 @@ function parseCompositionArtifactMarker(source) {
   if (!match) return null;
   const owner = match[1];
   const scope = match[2];
-  if (scope === "registry") {
-    if (owner) return null;
-    return { kind: "registry" };
-  }
-  if (scope === "contributions") {
-    if (owner) return null;
-    return { kind: "contributions" };
-  }
-  if (scope === "datastores") {
-    if (owner) return null;
-    return { kind: "datastores" };
-  }
-  if (scope === "i18n") {
-    if (owner) return null;
-    return { kind: "i18n" };
-  }
-  if (scope === "init") {
-    if (owner) return null;
-    return { kind: "init" };
-  }
+  const ownerless = OWNERLESS_MARKER_KINDS.find((kind) => kind === scope);
+  if (ownerless) return owner ? null : { kind: ownerless };
   if (!owner || !isValidModuleName(owner)) return null;
   if (scope === "route") {
     const nextRelativePath = match[3]?.trim();
@@ -5008,6 +5053,7 @@ function expectedMarkerKindForPath(path3) {
   if (path3 === MODULE_DATASTORES_GEN_PATH) return "datastores";
   if (path3 === MODULE_I18N_GEN_PATH) return "i18n";
   if (path3 === MODULE_INIT_SERVER_GEN_PATH) return "init";
+  if (path3 === MODULE_SERVER_GEN_PATH) return "server";
   if (path3.startsWith(API_ROUTE_DIR_PREFIX) && path3.endsWith("/route.ts")) return "endpoint";
   if (path3.startsWith(APP_DIR_PREFIX) && !path3.startsWith(API_ROUTE_DIR_PREFIX) && PAGE_FILE_SUFFIXES.some((suffix) => path3.endsWith(suffix))) {
     return "route";
@@ -5095,6 +5141,25 @@ function emitModulesGenTs(registry) {
     '  if (entry && entry.kind !== "feature") return true;',
     '  return raw.split(",").includes(name);',
     "}",
+    "",
+    "/** Headless mount keys come from the platform at build time: that page is off, its Module stays on. */",
+    "export function isMountHeadless(key: string): boolean {",
+    `  const raw = process.env.${HEADLESS_MOUNTS_ENV};`,
+    '  return raw ? raw.split(",").includes(key) : false;',
+    "}",
+    "",
+    "/** True when `href` is a headless mount's URL or below it. */",
+    "export function isHrefHeadless(href: unknown): boolean {",
+    '  if (typeof href !== "string") return false;',
+    "  const target = href.split(/[?#]/)[0];",
+    "  return generatedModuleRegistry.modules.some((mod) =>",
+    "    mod.mounts.some((mount) => {",
+    "      if (!isMountHeadless(`${mod.name}:${mount.group}/${mount.segment}`)) return false;",
+    "      const path = `/${mount.segment}`;",
+    "      return target === path || target.startsWith(`${path}/`);",
+    "    })",
+    "  );",
+    "}",
     ""
   ].join("\n");
 }
@@ -5102,6 +5167,22 @@ var STUB_PRINT_WIDTH = 100;
 function wrapAtPrintWidth(flat, broken) {
   return flat.length > STUB_PRINT_WIDTH ? broken : [flat];
 }
+function emitGuardLines(guards, body) {
+  const operands = guards.map((guard) => `${guard.call}(${emitTsString(guard.arg)})`);
+  const condition = `  if (${operands.join(" || ")})`;
+  const brokenOperands = guards.flatMap((guard, i) => {
+    const suffix = i < guards.length - 1 ? " ||" : "";
+    return wrapAtPrintWidth(`    ${operands[i]}${suffix}`, [
+      `    ${guard.call}(`,
+      `      ${emitTsString(guard.arg)}`,
+      `    )${suffix}`
+    ]);
+  });
+  return wrapAtPrintWidth(`${condition} ${body}`, [
+    ...wrapAtPrintWidth(condition, ["  if (", ...brokenOperands, "  )"]),
+    `    ${body}`
+  ]);
+}
 function buildEndpointStubContent(input) {
   const sorted = [...input.methods].sort(
     (a, b) => METHOD_ORDER[a.method] - METHOD_ORDER[b.method] || a.pairKey.localeCompare(b.pairKey)
@@ -5109,24 +5190,15 @@ function buildEndpointStubContent(input) {
   const exports2 = sorted.map((m) => {
     const pair = emitTsString(m.pairKey);
     const guards = [
-      `!isModuleEnabled(${emitTsString(input.owner)})`,
-      ...input.scope.kind === "enhancement" ? [`!isModuleEnabled(${emitTsString(input.scope.peer)})`] : []
+      { call: "!isModuleEnabled", arg: input.owner },
+      ...input.scope.kind === "enhancement" ? [{ call: "!isModuleEnabled", arg: input.scope.peer }] : []
     ];
-    const condition = `  if (${guards.join(" || ")})`;
-    const notFoundBody = "return new Response(null, { status: 404 });";
     const message = emitTsString(`Missing endpoint handler for ${m.pairKey}`);
     const importPath = emitTsString(input.importModule);
     return [
       `export async function ${m.method}(request: Request, context?: unknown): Promise<Response> {`,
       "  await initializeActiveEnhancements();",
-      ...wrapAtPrintWidth(`${condition} ${notFoundBody}`, [
-        ...wrapAtPrintWidth(condition, [
-          "  if (",
-          ...guards.map((guard, i) => `    ${guard}${i < guards.length - 1 ? " ||" : ""}`),
-          "  )"
-        ]),
-        `    ${notFoundBody}`
-      ]),
+      ...emitGuardLines(guards, "return new Response(null, { status: 404 });"),
       ...wrapAtPrintWidth(`  const { endpointHandlers } = await import(${importPath});`, [
         "  const { endpointHandlers } = await import(",
         `    ${importPath}`,
@@ -5156,12 +5228,16 @@ function buildEndpointStubContent(input) {
   ].join("\n");
 }
 function buildRouteStubContent(input) {
+  const guards = [
+    { call: "!isModuleEnabled", arg: input.owner },
+    { call: "isMountHeadless", arg: input.mountKey }
+  ];
   const lines = [
     formatRouteMarker(input.owner, input.nextRelativePath),
     'import { notFound } from "next/navigation";',
     // simple-import-sort puts packages and "@/" aliases in separate groups.
     "",
-    'import { isModuleEnabled } from "@/modules.gen";',
+    'import { isModuleEnabled, isMountHeadless } from "@/modules.gen";',
     `import Page from ${emitTsString(input.importModule)};`
   ];
   if (input.hasGenerateMetadata) {
@@ -5169,7 +5245,7 @@ function buildRouteStubContent(input) {
       `import { generateMetadata as sourceGenerateMetadata } from ${emitTsString(input.importModule)};`,
       "",
       "export async function generateMetadata(...args: Parameters<typeof sourceGenerateMetadata>) {",
-      `  if (!isModuleEnabled(${emitTsString(input.owner)})) return {};`,
+      ...emitGuardLines(guards, "return {};"),
       "  return sourceGenerateMetadata(...args);",
       "}"
     );
@@ -5180,7 +5256,7 @@ function buildRouteStubContent(input) {
     "  Parameters<typeof Page> extends [infer P, ...unknown[]] ? NonNullable<P> : Record<never, never>;",
     "",
     "export default function ModulePage(props: PageProps) {",
-    `  if (!isModuleEnabled(${emitTsString(input.owner)})) notFound();`,
+    ...emitGuardLines(guards, "notFound();"),
     "  return <Page {...props} />;",
     "}",
     ""
@@ -5382,7 +5458,6 @@ function planRouteStubs(input) {
     }
     for (const entry of entries) {
       const nextRelativePath = entry.nextRelativePath;
-      analyzeRouteEntryPath(nextRelativePath);
       const destination = normalizeAppRouterDestinationPattern(nextRelativePath);
       const path3 = routeEntryToAppPageFile(nextRelativePath);
       const existing = routeDestinationOwners.get(destination);
@@ -5397,6 +5472,8 @@ function planRouteStubs(input) {
         path: path3
       });
       const importModule = routeEntryImport(regMod.name, nextRelativePath);
+      const analyzed = analyzeRouteEntryPath(nextRelativePath);
+      const mount = mounts.find((claim) => routeEntryCoveredByMountClaim(analyzed, claim));
       routeStubs.push({
         path: path3,
         owner: regMod.name,
@@ -5406,6 +5483,7 @@ function planRouteStubs(input) {
           owner: regMod.name,
           nextRelativePath,
           importModule,
+          mountKey: mountKey(regMod.name, mount),
           hasGenerateMetadata: entry.hasGenerateMetadata
         })
       });
@@ -5575,6 +5653,7 @@ function planCompositionArtifacts(input) {
   let datastoresContent;
   let i18nContent;
   let initContent;
+  let serverContent;
   try {
     contributionsContent = emitModuleContributionsGenTs({
       registry: input.registry,
@@ -5599,6 +5678,10 @@ function planCompositionArtifacts(input) {
       registry: input.registry,
       facts: compositionEntryFacts
     });
+    serverContent = emitModuleServerGenTs({
+      registry: input.registry,
+      facts: compositionEntryFacts
+    });
   } catch (error) {
     return {
       ok: false,
@@ -5611,6 +5694,7 @@ function planCompositionArtifacts(input) {
   desired.set(MODULE_DATASTORES_GEN_PATH, datastoresContent);
   desired.set(MODULE_I18N_GEN_PATH, i18nContent);
   desired.set(MODULE_INIT_SERVER_GEN_PATH, initContent);
+  desired.set(MODULE_SERVER_GEN_PATH, serverContent);
   for (const stub of stubs.endpointStubs) desired.set(stub.path, stub.content);
   for (const stub of stubs.routeStubs) desired.set(stub.path, stub.content);
   const endpointStubByPath = new Map(stubs.endpointStubs.map((stub) => [stub.path, stub]));
@@ -6881,6 +6965,7 @@ function readFailurePath(error) {
   return typeof error === "object" && error !== null && "path" in error ? String(error.path) : "unknown";
 }
 var CONVENTIONAL_ENTRY_KIND_PROBE_TOKEN = "conventional-entry-kind";
+var SERVER_REGISTRATIONS_FILE = "server/registrations.ts";
 var COMPOSITION_ARTIFACT_KIND_PROBE_TOKEN = "composition-artifact-kind";
 async function classifyCompositionArtifactPathKind(context, path3) {
   return classifySandboxPathPresenceKind(context, path3, COMPOSITION_ARTIFACT_KIND_PROBE_TOKEN);
@@ -6918,6 +7003,10 @@ async function readConventionalEntryIfRealFile(path3, kind, presences, files) {
   }
   return source;
 }
+function hasRealServerRegistrations(modulePath, presences) {
+  const path3 = `${modulePath}/${SERVER_REGISTRATIONS_FILE}`;
+  return assertRealCompositionArtifactFilePresence(path3, presences.get(path3) ?? "unreadable") === "file";
+}
 async function readJsonObjectFile(path3, files) {
   const raw = files.get(path3);
   let parsed;
@@ -6941,6 +7030,9 @@ async function collectCompositionEntryFacts(context, registry) {
   const overridesDir = `${APP_PACKAGE_DIR}/src/lib/i18n/overrides`;
   const localeDirs = [substrateDir, overridesDir];
   const conventionalPaths = [];
+  const serverRegistrationPaths = registry.modules.map(
+    (mod) => `${MODULES_SANDBOX_DIR}/${mod.name}/${SERVER_REGISTRATIONS_FILE}`
+  );
   for (const mod of registry.modules) {
     const modulePath = `${MODULES_SANDBOX_DIR}/${mod.name}`;
     localeDirs.push(`${modulePath}/i18n`);
@@ -6969,7 +7061,7 @@ async function collectCompositionEntryFacts(context, registry) {
   const [conventionalPresences, localePresences] = await Promise.all([
     classifySandboxPathPresenceKindMany(
       context,
-      conventionalPaths,
+      [...conventionalPaths, ...serverRegistrationPaths],
       CONVENTIONAL_ENTRY_KIND_PROBE_TOKEN
     ),
     classifySandboxPathPresenceKindMany(context, localePaths, LOCALE_JSON_KIND_PROBE_TOKEN)
@@ -7031,6 +7123,7 @@ async function collectCompositionEntryFacts(context, registry) {
         );
       }
     }
+    const hasServerRegistrations = hasRealServerRegistrations(modulePath, conventionalPresences);
     const rootLocales = localesByDir.get(`${modulePath}/i18n`);
     if (rootLocales.length > 0 && !rootLocales.includes("en")) {
       throw new Error(
@@ -7070,6 +7163,7 @@ async function collectCompositionEntryFacts(context, registry) {
       moduleName: mod.name,
       hasRootContributions,
       hasRootSlots,
+      hasServerRegistrations,
       rootLocales,
       enhancements
     });
@@ -7273,6 +7367,7 @@ async function reconcileCompositionArtifacts(context, options = {}) {
     MODULE_DATASTORES_GEN_PATH,
     MODULE_I18N_GEN_PATH,
     MODULE_INIT_SERVER_GEN_PATH,
+    MODULE_SERVER_GEN_PATH,
     ...existingGeneratedPaths,
     ...Object.keys(existingAppPages),
     ...Object.keys(existingAppRoutes)

package/dist/index.d.mts

@@ -89,7 +89,7 @@ declare function assertSupportedTypescript(versionMajorMinor: string): void;
  */
 declare function escapeGitignore(pattern: string): string;
 /**
- * Regenerate the Module-rail artifacts (the five `src/*.gen.ts` files and every
+ * Regenerate the Module-rail artifacts (the six `src/*.gen.ts` files and every
  * route/endpoint stub under `src/app`) for the app rooted at `options.cwd`.
  */
 declare function compose(options: ComposeOptions): Promise<ComposeResult>;

package/dist/index.d.ts

@@ -89,7 +89,7 @@ declare function assertSupportedTypescript(versionMajorMinor: string): void;
  */
 declare function escapeGitignore(pattern: string): string;
 /**
- * Regenerate the Module-rail artifacts (the five `src/*.gen.ts` files and every
+ * Regenerate the Module-rail artifacts (the six `src/*.gen.ts` files and every
  * route/endpoint stub under `src/app`) for the app rooted at `options.cwd`.
  */
 declare function compose(options: ComposeOptions): Promise<ComposeResult>;

package/dist/index.js

@@ -4129,13 +4129,20 @@ function isModuleEnabledByList(raw, name, kindOf) {
 var APP_WEB_PREFIX = "apps/web/";
 var MODULE_STUB_MARKER = "@stardeck-module-rail-generated";
 var ENABLED_MODULES_ENV = "NEXT_PUBLIC_STARDECK_ENABLED_MODULES";
+var HEADLESS_MOUNTS_ENV = "NEXT_PUBLIC_STARDECK_HEADLESS_MOUNTS";
 var MODULE_CONTRIBUTIONS_GEN_PATH = `${APP_WEB_PREFIX}src/module-contributions.gen.ts`;
 var MODULE_DATASTORES_GEN_PATH = `${APP_WEB_PREFIX}src/module-datastores.gen.ts`;
 var MODULE_I18N_GEN_PATH = `${APP_WEB_PREFIX}src/module-i18n.gen.ts`;
 var MODULE_INIT_SERVER_GEN_PATH = `${APP_WEB_PREFIX}src/module-init.server.gen.ts`;
+var MODULE_SERVER_GEN_PATH = `${APP_WEB_PREFIX}src/module-server.gen.ts`;
 var MODULES_GEN_PATH = `${APP_WEB_PREFIX}src/modules.gen.ts`;
 var APP_EXTENSIONS_PATH = `${APP_WEB_PREFIX}src/lib/modules/app-extensions.ts`;
 
+// ../../packages/lib/src/shared/module-mount-key.ts
+function mountKey(moduleName, mount) {
+  return `${moduleName}:${mount.group}/${mount.segment}`;
+}
+
 // ../../packages/lib/src/server/module-rail/composition-artifacts.ts
 var import_typescript4 = __toESM(require("typescript"), 1);
 
@@ -4144,7 +4151,8 @@ var COMPOSITION_RUNTIME_GEN_PATHS = [
   MODULE_CONTRIBUTIONS_GEN_PATH,
   MODULE_I18N_GEN_PATH,
   MODULE_INIT_SERVER_GEN_PATH,
-  MODULE_DATASTORES_GEN_PATH
+  MODULE_DATASTORES_GEN_PATH,
+  MODULE_SERVER_GEN_PATH
 ];
 function compareNames(a, b) {
   return a < b ? -1 : a > b ? 1 : 0;
@@ -4165,6 +4173,9 @@ function formatI18nMarker() {
 function formatInitMarker() {
   return `// ${MODULE_STUB_MARKER} scope=init`;
 }
+function formatServerMarker() {
+  return `// ${MODULE_STUB_MARKER} scope=server`;
+}
 function formatDatastoresMarker() {
   return `// ${MODULE_STUB_MARKER} scope=datastores`;
 }
@@ -4464,7 +4475,7 @@ function emitModuleContributionsGenTs(input) {
     "  type SurfaceSlotCatalog,",
     '} from "@/lib/modules/contributions";',
     'import { substrateSlotCatalogs } from "@/lib/modules/substrate-slots";',
-    'import { generatedModuleRegistry, isModuleEnabled } from "@/modules.gen";',
+    'import { generatedModuleRegistry, isHrefHeadless, isModuleEnabled } from "@/modules.gen";',
     ...[...moduleImportLines].sort((a, b) => {
       const pathA = a.match(/from ("[^"]+")/)?.[1] ?? a;
       const pathB = b.match(/from ("[^"]+")/)?.[1] ?? b;
@@ -4514,11 +4525,19 @@ function emitModuleContributionsGenTs(input) {
     "export function resolveModuleContributions(",
     "  registry: typeof generatedModuleRegistry = generatedModuleRegistry",
     "): ResolvedModuleContributions {",
-    "  return resolveContributions({",
+    "  const resolved = resolveContributions({",
     "    registry,",
     "    catalogs: moduleSlotCatalogs,",
     "    sources: moduleContributionSources,",
     "  });",
+    "  // A nav entry into a headless mount would link to a page that is switched off.",
+    '  const nav = resolved["admin.nav"];',
+    "  if (nav) {",
+    '    resolved["admin.nav"] = nav.filter(',
+    "      (entry) => !isHrefHeadless((entry as { href?: unknown }).href)",
+    "    );",
+    "  }",
+    "  return resolved;",
     "}",
     "",
     "export const resolvedModuleContributions: ResolvedModuleContributions =",
@@ -4800,6 +4819,42 @@ function emitModuleInitServerGenTs(input) {
     ""
   ].join("\n");
 }
+function emitModuleServerGenTs(input) {
+  const installed = new Set(input.registry.modules.map((m) => m.name));
+  const moduleNames = input.facts.filter((f) => f.hasServerRegistrations && installed.has(f.moduleName)).map((f) => f.moduleName).sort(compareNames);
+  for (const name of moduleNames) {
+    if (!isValidModuleName(name)) {
+      throw new Error(`[ModuleRail] composition artifacts: invalid module name "${name}"`);
+    }
+  }
+  const importLines = moduleNames.map(
+    (name, index) => [
+      `@/modules/${name}/server/registrations`,
+      `import * as serverRegistrations${index} from ${JSON.stringify(`@/modules/${name}/server/registrations`)};`
+    ]
+  ).sort((a, b) => compareImportSpecifiers(a[0], b[0])).map(([, line]) => line);
+  const entryLines = moduleNames.map(
+    (name, index) => `  { module: ${JSON.stringify(name)}, registrations: serverRegistrations${index} },`
+  );
+  return [
+    formatServerMarker(),
+    "/** DO NOT EDIT \u2014 owned by the module install rail. */",
+    "",
+    ...importLines,
+    ...importLines.length > 0 ? [""] : [],
+    "export type ModuleServerRegistration = {",
+    "  module: string;",
+    "  registrations: Readonly<Record<string, unknown>>;",
+    "};",
+    "",
+    ...entryLines.length === 0 ? ["export const MODULE_SERVER_REGISTRATIONS: readonly ModuleServerRegistration[] = [];"] : [
+      "export const MODULE_SERVER_REGISTRATIONS: readonly ModuleServerRegistration[] = [",
+      ...entryLines,
+      "];"
+    ],
+    ""
+  ].join("\n");
+}
 
 // ../../packages/lib/src/server/module-rail/composition-artifacts.ts
 var COMPOSITION_ARTIFACTS_GENERATED_BY = "module-rail";
@@ -4862,6 +4917,14 @@ function formatRouteMarker(owner, nextRelativePath) {
 function formatRegistryMarker() {
   return `// ${MODULE_STUB_MARKER} scope=registry`;
 }
+var OWNERLESS_MARKER_KINDS = [
+  "registry",
+  "contributions",
+  "datastores",
+  "i18n",
+  "init",
+  "server"
+];
 function parseCompositionArtifactMarker(source) {
   const firstLine = source.split(/\r?\n/, 1)[0]?.trim() ?? "";
   const match = firstLine.match(
@@ -4872,26 +4935,8 @@ function parseCompositionArtifactMarker(source) {
   if (!match) return null;
   const owner = match[1];
   const scope = match[2];
-  if (scope === "registry") {
-    if (owner) return null;
-    return { kind: "registry" };
-  }
-  if (scope === "contributions") {
-    if (owner) return null;
-    return { kind: "contributions" };
-  }
-  if (scope === "datastores") {
-    if (owner) return null;
-    return { kind: "datastores" };
-  }
-  if (scope === "i18n") {
-    if (owner) return null;
-    return { kind: "i18n" };
-  }
-  if (scope === "init") {
-    if (owner) return null;
-    return { kind: "init" };
-  }
+  const ownerless = OWNERLESS_MARKER_KINDS.find((kind) => kind === scope);
+  if (ownerless) return owner ? null : { kind: ownerless };
   if (!owner || !isValidModuleName(owner)) return null;
   if (scope === "route") {
     const nextRelativePath = match[3]?.trim();
@@ -5017,6 +5062,7 @@ function expectedMarkerKindForPath(path3) {
   if (path3 === MODULE_DATASTORES_GEN_PATH) return "datastores";
   if (path3 === MODULE_I18N_GEN_PATH) return "i18n";
   if (path3 === MODULE_INIT_SERVER_GEN_PATH) return "init";
+  if (path3 === MODULE_SERVER_GEN_PATH) return "server";
   if (path3.startsWith(API_ROUTE_DIR_PREFIX) && path3.endsWith("/route.ts")) return "endpoint";
   if (path3.startsWith(APP_DIR_PREFIX) && !path3.startsWith(API_ROUTE_DIR_PREFIX) && PAGE_FILE_SUFFIXES.some((suffix) => path3.endsWith(suffix))) {
     return "route";
@@ -5104,6 +5150,25 @@ function emitModulesGenTs(registry) {
     '  if (entry && entry.kind !== "feature") return true;',
     '  return raw.split(",").includes(name);',
     "}",
+    "",
+    "/** Headless mount keys come from the platform at build time: that page is off, its Module stays on. */",
+    "export function isMountHeadless(key: string): boolean {",
+    `  const raw = process.env.${HEADLESS_MOUNTS_ENV};`,
+    '  return raw ? raw.split(",").includes(key) : false;',
+    "}",
+    "",
+    "/** True when `href` is a headless mount's URL or below it. */",
+    "export function isHrefHeadless(href: unknown): boolean {",
+    '  if (typeof href !== "string") return false;',
+    "  const target = href.split(/[?#]/)[0];",
+    "  return generatedModuleRegistry.modules.some((mod) =>",
+    "    mod.mounts.some((mount) => {",
+    "      if (!isMountHeadless(`${mod.name}:${mount.group}/${mount.segment}`)) return false;",
+    "      const path = `/${mount.segment}`;",
+    "      return target === path || target.startsWith(`${path}/`);",
+    "    })",
+    "  );",
+    "}",
     ""
   ].join("\n");
 }
@@ -5111,6 +5176,22 @@ var STUB_PRINT_WIDTH = 100;
 function wrapAtPrintWidth(flat, broken) {
   return flat.length > STUB_PRINT_WIDTH ? broken : [flat];
 }
+function emitGuardLines(guards, body) {
+  const operands = guards.map((guard) => `${guard.call}(${emitTsString(guard.arg)})`);
+  const condition = `  if (${operands.join(" || ")})`;
+  const brokenOperands = guards.flatMap((guard, i) => {
+    const suffix = i < guards.length - 1 ? " ||" : "";
+    return wrapAtPrintWidth(`    ${operands[i]}${suffix}`, [
+      `    ${guard.call}(`,
+      `      ${emitTsString(guard.arg)}`,
+      `    )${suffix}`
+    ]);
+  });
+  return wrapAtPrintWidth(`${condition} ${body}`, [
+    ...wrapAtPrintWidth(condition, ["  if (", ...brokenOperands, "  )"]),
+    `    ${body}`
+  ]);
+}
 function buildEndpointStubContent(input) {
   const sorted = [...input.methods].sort(
     (a, b) => METHOD_ORDER[a.method] - METHOD_ORDER[b.method] || a.pairKey.localeCompare(b.pairKey)
@@ -5118,24 +5199,15 @@ function buildEndpointStubContent(input) {
   const exports2 = sorted.map((m) => {
     const pair = emitTsString(m.pairKey);
     const guards = [
-      `!isModuleEnabled(${emitTsString(input.owner)})`,
-      ...input.scope.kind === "enhancement" ? [`!isModuleEnabled(${emitTsString(input.scope.peer)})`] : []
+      { call: "!isModuleEnabled", arg: input.owner },
+      ...input.scope.kind === "enhancement" ? [{ call: "!isModuleEnabled", arg: input.scope.peer }] : []
     ];
-    const condition = `  if (${guards.join(" || ")})`;
-    const notFoundBody = "return new Response(null, { status: 404 });";
     const message = emitTsString(`Missing endpoint handler for ${m.pairKey}`);
     const importPath = emitTsString(input.importModule);
     return [
       `export async function ${m.method}(request: Request, context?: unknown): Promise<Response> {`,
       "  await initializeActiveEnhancements();",
-      ...wrapAtPrintWidth(`${condition} ${notFoundBody}`, [
-        ...wrapAtPrintWidth(condition, [
-          "  if (",
-          ...guards.map((guard, i) => `    ${guard}${i < guards.length - 1 ? " ||" : ""}`),
-          "  )"
-        ]),
-        `    ${notFoundBody}`
-      ]),
+      ...emitGuardLines(guards, "return new Response(null, { status: 404 });"),
       ...wrapAtPrintWidth(`  const { endpointHandlers } = await import(${importPath});`, [
         "  const { endpointHandlers } = await import(",
         `    ${importPath}`,
@@ -5165,12 +5237,16 @@ function buildEndpointStubContent(input) {
   ].join("\n");
 }
 function buildRouteStubContent(input) {
+  const guards = [
+    { call: "!isModuleEnabled", arg: input.owner },
+    { call: "isMountHeadless", arg: input.mountKey }
+  ];
   const lines = [
     formatRouteMarker(input.owner, input.nextRelativePath),
     'import { notFound } from "next/navigation";',
     // simple-import-sort puts packages and "@/" aliases in separate groups.
     "",
-    'import { isModuleEnabled } from "@/modules.gen";',
+    'import { isModuleEnabled, isMountHeadless } from "@/modules.gen";',
     `import Page from ${emitTsString(input.importModule)};`
   ];
   if (input.hasGenerateMetadata) {
@@ -5178,7 +5254,7 @@ function buildRouteStubContent(input) {
       `import { generateMetadata as sourceGenerateMetadata } from ${emitTsString(input.importModule)};`,
       "",
       "export async function generateMetadata(...args: Parameters<typeof sourceGenerateMetadata>) {",
-      `  if (!isModuleEnabled(${emitTsString(input.owner)})) return {};`,
+      ...emitGuardLines(guards, "return {};"),
       "  return sourceGenerateMetadata(...args);",
       "}"
     );
@@ -5189,7 +5265,7 @@ function buildRouteStubContent(input) {
     "  Parameters<typeof Page> extends [infer P, ...unknown[]] ? NonNullable<P> : Record<never, never>;",
     "",
     "export default function ModulePage(props: PageProps) {",
-    `  if (!isModuleEnabled(${emitTsString(input.owner)})) notFound();`,
+    ...emitGuardLines(guards, "notFound();"),
     "  return <Page {...props} />;",
     "}",
     ""
@@ -5391,7 +5467,6 @@ function planRouteStubs(input) {
     }
     for (const entry of entries) {
       const nextRelativePath = entry.nextRelativePath;
-      analyzeRouteEntryPath(nextRelativePath);
       const destination = normalizeAppRouterDestinationPattern(nextRelativePath);
       const path3 = routeEntryToAppPageFile(nextRelativePath);
       const existing = routeDestinationOwners.get(destination);
@@ -5406,6 +5481,8 @@ function planRouteStubs(input) {
         path: path3
       });
       const importModule = routeEntryImport(regMod.name, nextRelativePath);
+      const analyzed = analyzeRouteEntryPath(nextRelativePath);
+      const mount = mounts.find((claim) => routeEntryCoveredByMountClaim(analyzed, claim));
       routeStubs.push({
         path: path3,
         owner: regMod.name,
@@ -5415,6 +5492,7 @@ function planRouteStubs(input) {
           owner: regMod.name,
           nextRelativePath,
           importModule,
+          mountKey: mountKey(regMod.name, mount),
           hasGenerateMetadata: entry.hasGenerateMetadata
         })
       });
@@ -5584,6 +5662,7 @@ function planCompositionArtifacts(input) {
   let datastoresContent;
   let i18nContent;
   let initContent;
+  let serverContent;
   try {
     contributionsContent = emitModuleContributionsGenTs({
       registry: input.registry,
@@ -5608,6 +5687,10 @@ function planCompositionArtifacts(input) {
       registry: input.registry,
       facts: compositionEntryFacts
     });
+    serverContent = emitModuleServerGenTs({
+      registry: input.registry,
+      facts: compositionEntryFacts
+    });
   } catch (error) {
     return {
       ok: false,
@@ -5620,6 +5703,7 @@ function planCompositionArtifacts(input) {
   desired.set(MODULE_DATASTORES_GEN_PATH, datastoresContent);
   desired.set(MODULE_I18N_GEN_PATH, i18nContent);
   desired.set(MODULE_INIT_SERVER_GEN_PATH, initContent);
+  desired.set(MODULE_SERVER_GEN_PATH, serverContent);
   for (const stub of stubs.endpointStubs) desired.set(stub.path, stub.content);
   for (const stub of stubs.routeStubs) desired.set(stub.path, stub.content);
   const endpointStubByPath = new Map(stubs.endpointStubs.map((stub) => [stub.path, stub]));
@@ -6890,6 +6974,7 @@ function readFailurePath(error) {
   return typeof error === "object" && error !== null && "path" in error ? String(error.path) : "unknown";
 }
 var CONVENTIONAL_ENTRY_KIND_PROBE_TOKEN = "conventional-entry-kind";
+var SERVER_REGISTRATIONS_FILE = "server/registrations.ts";
 var COMPOSITION_ARTIFACT_KIND_PROBE_TOKEN = "composition-artifact-kind";
 async function classifyCompositionArtifactPathKind(context, path3) {
   return classifySandboxPathPresenceKind(context, path3, COMPOSITION_ARTIFACT_KIND_PROBE_TOKEN);
@@ -6927,6 +7012,10 @@ async function readConventionalEntryIfRealFile(path3, kind, presences, files) {
   }
   return source;
 }
+function hasRealServerRegistrations(modulePath, presences) {
+  const path3 = `${modulePath}/${SERVER_REGISTRATIONS_FILE}`;
+  return assertRealCompositionArtifactFilePresence(path3, presences.get(path3) ?? "unreadable") === "file";
+}
 async function readJsonObjectFile(path3, files) {
   const raw = files.get(path3);
   let parsed;
@@ -6950,6 +7039,9 @@ async function collectCompositionEntryFacts(context, registry) {
   const overridesDir = `${APP_PACKAGE_DIR}/src/lib/i18n/overrides`;
   const localeDirs = [substrateDir, overridesDir];
   const conventionalPaths = [];
+  const serverRegistrationPaths = registry.modules.map(
+    (mod) => `${MODULES_SANDBOX_DIR}/${mod.name}/${SERVER_REGISTRATIONS_FILE}`
+  );
   for (const mod of registry.modules) {
     const modulePath = `${MODULES_SANDBOX_DIR}/${mod.name}`;
     localeDirs.push(`${modulePath}/i18n`);
@@ -6978,7 +7070,7 @@ async function collectCompositionEntryFacts(context, registry) {
   const [conventionalPresences, localePresences] = await Promise.all([
     classifySandboxPathPresenceKindMany(
       context,
-      conventionalPaths,
+      [...conventionalPaths, ...serverRegistrationPaths],
       CONVENTIONAL_ENTRY_KIND_PROBE_TOKEN
     ),
     classifySandboxPathPresenceKindMany(context, localePaths, LOCALE_JSON_KIND_PROBE_TOKEN)
@@ -7040,6 +7132,7 @@ async function collectCompositionEntryFacts(context, registry) {
         );
       }
     }
+    const hasServerRegistrations = hasRealServerRegistrations(modulePath, conventionalPresences);
     const rootLocales = localesByDir.get(`${modulePath}/i18n`);
     if (rootLocales.length > 0 && !rootLocales.includes("en")) {
       throw new Error(
@@ -7079,6 +7172,7 @@ async function collectCompositionEntryFacts(context, registry) {
       moduleName: mod.name,
       hasRootContributions,
       hasRootSlots,
+      hasServerRegistrations,
       rootLocales,
       enhancements
     });
@@ -7282,6 +7376,7 @@ async function reconcileCompositionArtifacts(context, options = {}) {
     MODULE_DATASTORES_GEN_PATH,
     MODULE_I18N_GEN_PATH,
     MODULE_INIT_SERVER_GEN_PATH,
+    MODULE_SERVER_GEN_PATH,
     ...existingGeneratedPaths,
     ...Object.keys(existingAppPages),
     ...Object.keys(existingAppRoutes)

package/dist/index.mjs

@@ -4114,13 +4114,20 @@ function isModuleEnabledByList(raw, name, kindOf) {
 var APP_WEB_PREFIX = "apps/web/";
 var MODULE_STUB_MARKER = "@stardeck-module-rail-generated";
 var ENABLED_MODULES_ENV = "NEXT_PUBLIC_STARDECK_ENABLED_MODULES";
+var HEADLESS_MOUNTS_ENV = "NEXT_PUBLIC_STARDECK_HEADLESS_MOUNTS";
 var MODULE_CONTRIBUTIONS_GEN_PATH = `${APP_WEB_PREFIX}src/module-contributions.gen.ts`;
 var MODULE_DATASTORES_GEN_PATH = `${APP_WEB_PREFIX}src/module-datastores.gen.ts`;
 var MODULE_I18N_GEN_PATH = `${APP_WEB_PREFIX}src/module-i18n.gen.ts`;
 var MODULE_INIT_SERVER_GEN_PATH = `${APP_WEB_PREFIX}src/module-init.server.gen.ts`;
+var MODULE_SERVER_GEN_PATH = `${APP_WEB_PREFIX}src/module-server.gen.ts`;
 var MODULES_GEN_PATH = `${APP_WEB_PREFIX}src/modules.gen.ts`;
 var APP_EXTENSIONS_PATH = `${APP_WEB_PREFIX}src/lib/modules/app-extensions.ts`;
 
+// ../../packages/lib/src/shared/module-mount-key.ts
+function mountKey(moduleName, mount) {
+  return `${moduleName}:${mount.group}/${mount.segment}`;
+}
+
 // ../../packages/lib/src/server/module-rail/composition-artifacts.ts
 import ts4 from "typescript";
 
@@ -4129,7 +4136,8 @@ var COMPOSITION_RUNTIME_GEN_PATHS = [
   MODULE_CONTRIBUTIONS_GEN_PATH,
   MODULE_I18N_GEN_PATH,
   MODULE_INIT_SERVER_GEN_PATH,
-  MODULE_DATASTORES_GEN_PATH
+  MODULE_DATASTORES_GEN_PATH,
+  MODULE_SERVER_GEN_PATH
 ];
 function compareNames(a, b) {
   return a < b ? -1 : a > b ? 1 : 0;
@@ -4150,6 +4158,9 @@ function formatI18nMarker() {
 function formatInitMarker() {
   return `// ${MODULE_STUB_MARKER} scope=init`;
 }
+function formatServerMarker() {
+  return `// ${MODULE_STUB_MARKER} scope=server`;
+}
 function formatDatastoresMarker() {
   return `// ${MODULE_STUB_MARKER} scope=datastores`;
 }
@@ -4449,7 +4460,7 @@ function emitModuleContributionsGenTs(input) {
     "  type SurfaceSlotCatalog,",
     '} from "@/lib/modules/contributions";',
     'import { substrateSlotCatalogs } from "@/lib/modules/substrate-slots";',
-    'import { generatedModuleRegistry, isModuleEnabled } from "@/modules.gen";',
+    'import { generatedModuleRegistry, isHrefHeadless, isModuleEnabled } from "@/modules.gen";',
     ...[...moduleImportLines].sort((a, b) => {
       const pathA = a.match(/from ("[^"]+")/)?.[1] ?? a;
       const pathB = b.match(/from ("[^"]+")/)?.[1] ?? b;
@@ -4499,11 +4510,19 @@ function emitModuleContributionsGenTs(input) {
     "export function resolveModuleContributions(",
     "  registry: typeof generatedModuleRegistry = generatedModuleRegistry",
     "): ResolvedModuleContributions {",
-    "  return resolveContributions({",
+    "  const resolved = resolveContributions({",
     "    registry,",
     "    catalogs: moduleSlotCatalogs,",
     "    sources: moduleContributionSources,",
     "  });",
+    "  // A nav entry into a headless mount would link to a page that is switched off.",
+    '  const nav = resolved["admin.nav"];',
+    "  if (nav) {",
+    '    resolved["admin.nav"] = nav.filter(',
+    "      (entry) => !isHrefHeadless((entry as { href?: unknown }).href)",
+    "    );",
+    "  }",
+    "  return resolved;",
     "}",
     "",
     "export const resolvedModuleContributions: ResolvedModuleContributions =",
@@ -4785,6 +4804,42 @@ function emitModuleInitServerGenTs(input) {
     ""
   ].join("\n");
 }
+function emitModuleServerGenTs(input) {
+  const installed = new Set(input.registry.modules.map((m) => m.name));
+  const moduleNames = input.facts.filter((f) => f.hasServerRegistrations && installed.has(f.moduleName)).map((f) => f.moduleName).sort(compareNames);
+  for (const name of moduleNames) {
+    if (!isValidModuleName(name)) {
+      throw new Error(`[ModuleRail] composition artifacts: invalid module name "${name}"`);
+    }
+  }
+  const importLines = moduleNames.map(
+    (name, index) => [
+      `@/modules/${name}/server/registrations`,
+      `import * as serverRegistrations${index} from ${JSON.stringify(`@/modules/${name}/server/registrations`)};`
+    ]
+  ).sort((a, b) => compareImportSpecifiers(a[0], b[0])).map(([, line]) => line);
+  const entryLines = moduleNames.map(
+    (name, index) => `  { module: ${JSON.stringify(name)}, registrations: serverRegistrations${index} },`
+  );
+  return [
+    formatServerMarker(),
+    "/** DO NOT EDIT \u2014 owned by the module install rail. */",
+    "",
+    ...importLines,
+    ...importLines.length > 0 ? [""] : [],
+    "export type ModuleServerRegistration = {",
+    "  module: string;",
+    "  registrations: Readonly<Record<string, unknown>>;",
+    "};",
+    "",
+    ...entryLines.length === 0 ? ["export const MODULE_SERVER_REGISTRATIONS: readonly ModuleServerRegistration[] = [];"] : [
+      "export const MODULE_SERVER_REGISTRATIONS: readonly ModuleServerRegistration[] = [",
+      ...entryLines,
+      "];"
+    ],
+    ""
+  ].join("\n");
+}
 
 // ../../packages/lib/src/server/module-rail/composition-artifacts.ts
 var COMPOSITION_ARTIFACTS_GENERATED_BY = "module-rail";
@@ -4847,6 +4902,14 @@ function formatRouteMarker(owner, nextRelativePath) {
 function formatRegistryMarker() {
   return `// ${MODULE_STUB_MARKER} scope=registry`;
 }
+var OWNERLESS_MARKER_KINDS = [
+  "registry",
+  "contributions",
+  "datastores",
+  "i18n",
+  "init",
+  "server"
+];
 function parseCompositionArtifactMarker(source) {
   const firstLine = source.split(/\r?\n/, 1)[0]?.trim() ?? "";
   const match = firstLine.match(
@@ -4857,26 +4920,8 @@ function parseCompositionArtifactMarker(source) {
   if (!match) return null;
   const owner = match[1];
   const scope = match[2];
-  if (scope === "registry") {
-    if (owner) return null;
-    return { kind: "registry" };
-  }
-  if (scope === "contributions") {
-    if (owner) return null;
-    return { kind: "contributions" };
-  }
-  if (scope === "datastores") {
-    if (owner) return null;
-    return { kind: "datastores" };
-  }
-  if (scope === "i18n") {
-    if (owner) return null;
-    return { kind: "i18n" };
-  }
-  if (scope === "init") {
-    if (owner) return null;
-    return { kind: "init" };
-  }
+  const ownerless = OWNERLESS_MARKER_KINDS.find((kind) => kind === scope);
+  if (ownerless) return owner ? null : { kind: ownerless };
   if (!owner || !isValidModuleName(owner)) return null;
   if (scope === "route") {
     const nextRelativePath = match[3]?.trim();
@@ -5002,6 +5047,7 @@ function expectedMarkerKindForPath(path3) {
   if (path3 === MODULE_DATASTORES_GEN_PATH) return "datastores";
   if (path3 === MODULE_I18N_GEN_PATH) return "i18n";
   if (path3 === MODULE_INIT_SERVER_GEN_PATH) return "init";
+  if (path3 === MODULE_SERVER_GEN_PATH) return "server";
   if (path3.startsWith(API_ROUTE_DIR_PREFIX) && path3.endsWith("/route.ts")) return "endpoint";
   if (path3.startsWith(APP_DIR_PREFIX) && !path3.startsWith(API_ROUTE_DIR_PREFIX) && PAGE_FILE_SUFFIXES.some((suffix) => path3.endsWith(suffix))) {
     return "route";
@@ -5089,6 +5135,25 @@ function emitModulesGenTs(registry) {
     '  if (entry && entry.kind !== "feature") return true;',
     '  return raw.split(",").includes(name);',
     "}",
+    "",
+    "/** Headless mount keys come from the platform at build time: that page is off, its Module stays on. */",
+    "export function isMountHeadless(key: string): boolean {",
+    `  const raw = process.env.${HEADLESS_MOUNTS_ENV};`,
+    '  return raw ? raw.split(",").includes(key) : false;',
+    "}",
+    "",
+    "/** True when `href` is a headless mount's URL or below it. */",
+    "export function isHrefHeadless(href: unknown): boolean {",
+    '  if (typeof href !== "string") return false;',
+    "  const target = href.split(/[?#]/)[0];",
+    "  return generatedModuleRegistry.modules.some((mod) =>",
+    "    mod.mounts.some((mount) => {",
+    "      if (!isMountHeadless(`${mod.name}:${mount.group}/${mount.segment}`)) return false;",
+    "      const path = `/${mount.segment}`;",
+    "      return target === path || target.startsWith(`${path}/`);",
+    "    })",
+    "  );",
+    "}",
     ""
   ].join("\n");
 }
@@ -5096,6 +5161,22 @@ var STUB_PRINT_WIDTH = 100;
 function wrapAtPrintWidth(flat, broken) {
   return flat.length > STUB_PRINT_WIDTH ? broken : [flat];
 }
+function emitGuardLines(guards, body) {
+  const operands = guards.map((guard) => `${guard.call}(${emitTsString(guard.arg)})`);
+  const condition = `  if (${operands.join(" || ")})`;
+  const brokenOperands = guards.flatMap((guard, i) => {
+    const suffix = i < guards.length - 1 ? " ||" : "";
+    return wrapAtPrintWidth(`    ${operands[i]}${suffix}`, [
+      `    ${guard.call}(`,
+      `      ${emitTsString(guard.arg)}`,
+      `    )${suffix}`
+    ]);
+  });
+  return wrapAtPrintWidth(`${condition} ${body}`, [
+    ...wrapAtPrintWidth(condition, ["  if (", ...brokenOperands, "  )"]),
+    `    ${body}`
+  ]);
+}
 function buildEndpointStubContent(input) {
   const sorted = [...input.methods].sort(
     (a, b) => METHOD_ORDER[a.method] - METHOD_ORDER[b.method] || a.pairKey.localeCompare(b.pairKey)
@@ -5103,24 +5184,15 @@ function buildEndpointStubContent(input) {
   const exports = sorted.map((m) => {
     const pair = emitTsString(m.pairKey);
     const guards = [
-      `!isModuleEnabled(${emitTsString(input.owner)})`,
-      ...input.scope.kind === "enhancement" ? [`!isModuleEnabled(${emitTsString(input.scope.peer)})`] : []
+      { call: "!isModuleEnabled", arg: input.owner },
+      ...input.scope.kind === "enhancement" ? [{ call: "!isModuleEnabled", arg: input.scope.peer }] : []
     ];
-    const condition = `  if (${guards.join(" || ")})`;
-    const notFoundBody = "return new Response(null, { status: 404 });";
     const message = emitTsString(`Missing endpoint handler for ${m.pairKey}`);
     const importPath = emitTsString(input.importModule);
     return [
       `export async function ${m.method}(request: Request, context?: unknown): Promise<Response> {`,
       "  await initializeActiveEnhancements();",
-      ...wrapAtPrintWidth(`${condition} ${notFoundBody}`, [
-        ...wrapAtPrintWidth(condition, [
-          "  if (",
-          ...guards.map((guard, i) => `    ${guard}${i < guards.length - 1 ? " ||" : ""}`),
-          "  )"
-        ]),
-        `    ${notFoundBody}`
-      ]),
+      ...emitGuardLines(guards, "return new Response(null, { status: 404 });"),
       ...wrapAtPrintWidth(`  const { endpointHandlers } = await import(${importPath});`, [
         "  const { endpointHandlers } = await import(",
         `    ${importPath}`,
@@ -5150,12 +5222,16 @@ function buildEndpointStubContent(input) {
   ].join("\n");
 }
 function buildRouteStubContent(input) {
+  const guards = [
+    { call: "!isModuleEnabled", arg: input.owner },
+    { call: "isMountHeadless", arg: input.mountKey }
+  ];
   const lines = [
     formatRouteMarker(input.owner, input.nextRelativePath),
     'import { notFound } from "next/navigation";',
     // simple-import-sort puts packages and "@/" aliases in separate groups.
     "",
-    'import { isModuleEnabled } from "@/modules.gen";',
+    'import { isModuleEnabled, isMountHeadless } from "@/modules.gen";',
     `import Page from ${emitTsString(input.importModule)};`
   ];
   if (input.hasGenerateMetadata) {
@@ -5163,7 +5239,7 @@ function buildRouteStubContent(input) {
       `import { generateMetadata as sourceGenerateMetadata } from ${emitTsString(input.importModule)};`,
       "",
       "export async function generateMetadata(...args: Parameters<typeof sourceGenerateMetadata>) {",
-      `  if (!isModuleEnabled(${emitTsString(input.owner)})) return {};`,
+      ...emitGuardLines(guards, "return {};"),
       "  return sourceGenerateMetadata(...args);",
       "}"
     );
@@ -5174,7 +5250,7 @@ function buildRouteStubContent(input) {
     "  Parameters<typeof Page> extends [infer P, ...unknown[]] ? NonNullable<P> : Record<never, never>;",
     "",
     "export default function ModulePage(props: PageProps) {",
-    `  if (!isModuleEnabled(${emitTsString(input.owner)})) notFound();`,
+    ...emitGuardLines(guards, "notFound();"),
     "  return <Page {...props} />;",
     "}",
     ""
@@ -5376,7 +5452,6 @@ function planRouteStubs(input) {
     }
     for (const entry of entries) {
       const nextRelativePath = entry.nextRelativePath;
-      analyzeRouteEntryPath(nextRelativePath);
       const destination = normalizeAppRouterDestinationPattern(nextRelativePath);
       const path3 = routeEntryToAppPageFile(nextRelativePath);
       const existing = routeDestinationOwners.get(destination);
@@ -5391,6 +5466,8 @@ function planRouteStubs(input) {
         path: path3
       });
       const importModule = routeEntryImport(regMod.name, nextRelativePath);
+      const analyzed = analyzeRouteEntryPath(nextRelativePath);
+      const mount = mounts.find((claim) => routeEntryCoveredByMountClaim(analyzed, claim));
       routeStubs.push({
         path: path3,
         owner: regMod.name,
@@ -5400,6 +5477,7 @@ function planRouteStubs(input) {
           owner: regMod.name,
           nextRelativePath,
           importModule,
+          mountKey: mountKey(regMod.name, mount),
           hasGenerateMetadata: entry.hasGenerateMetadata
         })
       });
@@ -5569,6 +5647,7 @@ function planCompositionArtifacts(input) {
   let datastoresContent;
   let i18nContent;
   let initContent;
+  let serverContent;
   try {
     contributionsContent = emitModuleContributionsGenTs({
       registry: input.registry,
@@ -5593,6 +5672,10 @@ function planCompositionArtifacts(input) {
       registry: input.registry,
       facts: compositionEntryFacts
     });
+    serverContent = emitModuleServerGenTs({
+      registry: input.registry,
+      facts: compositionEntryFacts
+    });
   } catch (error) {
     return {
       ok: false,
@@ -5605,6 +5688,7 @@ function planCompositionArtifacts(input) {
   desired.set(MODULE_DATASTORES_GEN_PATH, datastoresContent);
   desired.set(MODULE_I18N_GEN_PATH, i18nContent);
   desired.set(MODULE_INIT_SERVER_GEN_PATH, initContent);
+  desired.set(MODULE_SERVER_GEN_PATH, serverContent);
   for (const stub of stubs.endpointStubs) desired.set(stub.path, stub.content);
   for (const stub of stubs.routeStubs) desired.set(stub.path, stub.content);
   const endpointStubByPath = new Map(stubs.endpointStubs.map((stub) => [stub.path, stub]));
@@ -6875,6 +6959,7 @@ function readFailurePath(error) {
   return typeof error === "object" && error !== null && "path" in error ? String(error.path) : "unknown";
 }
 var CONVENTIONAL_ENTRY_KIND_PROBE_TOKEN = "conventional-entry-kind";
+var SERVER_REGISTRATIONS_FILE = "server/registrations.ts";
 var COMPOSITION_ARTIFACT_KIND_PROBE_TOKEN = "composition-artifact-kind";
 async function classifyCompositionArtifactPathKind(context, path3) {
   return classifySandboxPathPresenceKind(context, path3, COMPOSITION_ARTIFACT_KIND_PROBE_TOKEN);
@@ -6912,6 +6997,10 @@ async function readConventionalEntryIfRealFile(path3, kind, presences, files) {
   }
   return source;
 }
+function hasRealServerRegistrations(modulePath, presences) {
+  const path3 = `${modulePath}/${SERVER_REGISTRATIONS_FILE}`;
+  return assertRealCompositionArtifactFilePresence(path3, presences.get(path3) ?? "unreadable") === "file";
+}
 async function readJsonObjectFile(path3, files) {
   const raw = files.get(path3);
   let parsed;
@@ -6935,6 +7024,9 @@ async function collectCompositionEntryFacts(context, registry) {
   const overridesDir = `${APP_PACKAGE_DIR}/src/lib/i18n/overrides`;
   const localeDirs = [substrateDir, overridesDir];
   const conventionalPaths = [];
+  const serverRegistrationPaths = registry.modules.map(
+    (mod) => `${MODULES_SANDBOX_DIR}/${mod.name}/${SERVER_REGISTRATIONS_FILE}`
+  );
   for (const mod of registry.modules) {
     const modulePath = `${MODULES_SANDBOX_DIR}/${mod.name}`;
     localeDirs.push(`${modulePath}/i18n`);
@@ -6963,7 +7055,7 @@ async function collectCompositionEntryFacts(context, registry) {
   const [conventionalPresences, localePresences] = await Promise.all([
     classifySandboxPathPresenceKindMany(
       context,
-      conventionalPaths,
+      [...conventionalPaths, ...serverRegistrationPaths],
       CONVENTIONAL_ENTRY_KIND_PROBE_TOKEN
     ),
     classifySandboxPathPresenceKindMany(context, localePaths, LOCALE_JSON_KIND_PROBE_TOKEN)
@@ -7025,6 +7117,7 @@ async function collectCompositionEntryFacts(context, registry) {
         );
       }
     }
+    const hasServerRegistrations = hasRealServerRegistrations(modulePath, conventionalPresences);
     const rootLocales = localesByDir.get(`${modulePath}/i18n`);
     if (rootLocales.length > 0 && !rootLocales.includes("en")) {
       throw new Error(
@@ -7064,6 +7157,7 @@ async function collectCompositionEntryFacts(context, registry) {
       moduleName: mod.name,
       hasRootContributions,
       hasRootSlots,
+      hasServerRegistrations,
       rootLocales,
       enhancements
     });
@@ -7267,6 +7361,7 @@ async function reconcileCompositionArtifacts(context, options = {}) {
     MODULE_DATASTORES_GEN_PATH,
     MODULE_I18N_GEN_PATH,
     MODULE_INIT_SERVER_GEN_PATH,
+    MODULE_SERVER_GEN_PATH,
     ...existingGeneratedPaths,
     ...Object.keys(existingAppPages),
     ...Object.keys(existingAppRoutes)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@stardeck-customer-apps/compose",
-  "version": "0.6.0",
-  "description": "Regenerates a Stardeck app's Module-rail artifacts — the five src/*.gen.ts registries and every route/endpoint stub — from src/modules/*/module.json",
+  "version": "0.8.0",
+  "description": "Regenerates a Stardeck app's Module-rail artifacts — the six src/*.gen.ts registries and every route/endpoint stub — from src/modules/*/module.json",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
   "types": "dist/index.d.ts",