@stardeck-customer-apps/compose 0.6.0 → 0.7.0

package/SKILL.md

@@ -9,7 +9,7 @@ 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`
@@ -89,6 +89,18 @@ 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.
 - `@stardeck-customer-apps/compose/runtime` exports `isModuleEnabledByList`,
   the single enablement rule, and imports nothing — it is safe in client
   components.

package/dist/cli.js

@@ -3891,6 +3891,7 @@ 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`;
@@ -4127,6 +4128,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);
 
@@ -4455,7 +4461,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 +4511,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 =",
@@ -5095,6 +5109,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 +5135,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 +5158,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 +5196,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 +5213,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 +5224,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 +5426,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 +5440,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 +5451,7 @@ function planRouteStubs(input) {
           owner: regMod.name,
           nextRelativePath,
           importModule,
+          mountKey: mountKey(regMod.name, mount),
           hasGenerateMetadata: entry.hasGenerateMetadata
         })
       });

package/dist/index.js

@@ -4129,6 +4129,7 @@ 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`;
@@ -4136,6 +4137,11 @@ var MODULE_INIT_SERVER_GEN_PATH = `${APP_WEB_PREFIX}src/module-init.server.gen.t
 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);
 
@@ -4464,7 +4470,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 +4520,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 =",
@@ -5104,6 +5118,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 +5144,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 +5167,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 +5205,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 +5222,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 +5233,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 +5435,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 +5449,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 +5460,7 @@ function planRouteStubs(input) {
           owner: regMod.name,
           nextRelativePath,
           importModule,
+          mountKey: mountKey(regMod.name, mount),
           hasGenerateMetadata: entry.hasGenerateMetadata
         })
       });

package/dist/index.mjs

@@ -4114,6 +4114,7 @@ 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`;
@@ -4121,6 +4122,11 @@ var MODULE_INIT_SERVER_GEN_PATH = `${APP_WEB_PREFIX}src/module-init.server.gen.t
 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";
 
@@ -4449,7 +4455,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 +4505,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 =",
@@ -5089,6 +5103,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 +5129,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 +5152,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 +5190,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 +5207,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 +5218,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 +5420,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 +5434,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 +5445,7 @@ function planRouteStubs(input) {
           owner: regMod.name,
           nextRelativePath,
           importModule,
+          mountKey: mountKey(regMod.name, mount),
           hasGenerateMetadata: entry.hasGenerateMetadata
         })
       });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stardeck-customer-apps/compose",
-  "version": "0.6.0",
+  "version": "0.7.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",
   "main": "dist/index.js",
   "module": "dist/index.mjs",