@stardeck-customer-apps/compose 0.5.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`
@@ -81,6 +81,26 @@ a silent fallback. It holds deployment facts: gitignore it (`apps/web/.gitignore
   missing or wrong makes compose refuse rather than clobber your edit.
 - Change `module.json` (or the Module's own source under `routes/`,
   `contributions.ts`, `i18n/`, …) and re-run compose.
+- To reword a Module string, don't edit the Module: put the same key in
+  `apps/web/src/lib/i18n/overrides/<locale>.json` (app-owned, composed last).
+  It may only replace keys a Module or `lib/i18n/substrate/` defines; an
+  override of a missing key fails compose and names the key. An override file
+  for a locale the Modules don't ship (e.g. `ja`) translates their keys for that
+  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);
 
@@ -4267,6 +4273,40 @@ function cloneTree(value) {
   }
   return clone;
 }
+function collectLeafPaths(value, path3, out) {
+  if (typeof value === "string") {
+    out.push(path3);
+    return;
+  }
+  assertMessageTree(value, path3);
+  for (const [key, child] of Object.entries(value)) collectLeafPaths(child, `${path3}.${key}`, out);
+}
+function overrideInto(target, source, owner, path3, missing) {
+  for (const [key, value] of Object.entries(source)) {
+    const nextPath = path3 ? `${path3}.${key}` : key;
+    if (!Object.prototype.hasOwnProperty.call(target, key)) {
+      collectLeafPaths(value, nextPath, missing);
+      continue;
+    }
+    const existing = target[key];
+    if (typeof value === "string") {
+      if (typeof existing !== "string") {
+        throw new Error(
+          `[ModuleRail] composition artifacts: i18n merge conflict at ${nextPath}: ${owner} has string leaf but another owner has an object`
+        );
+      }
+      target[key] = value;
+      continue;
+    }
+    assertMessageTree(value, nextPath);
+    if (typeof existing === "string") {
+      throw new Error(
+        `[ModuleRail] composition artifacts: i18n merge conflict at ${nextPath}: ${owner} has object but another owner has a string leaf`
+      );
+    }
+    overrideInto(existing, value, owner, nextPath, missing);
+  }
+}
 function composeLocaleMessagesForPlan(layers) {
   const result = createMessageTree();
   const leafOwners = /* @__PURE__ */ new Map();
@@ -4318,7 +4358,17 @@ function composeLocaleMessagesForPlan(layers) {
   }
   for (const layer of layers) {
     assertMessageTree(layer.messages, layer.owner);
-    mergeInto(result, cloneTree(layer.messages), layer.owner, "");
+    if (!layer.override) {
+      mergeInto(result, cloneTree(layer.messages), layer.owner, "");
+      continue;
+    }
+    const missing = [];
+    overrideInto(result, cloneTree(layer.messages), layer.owner, "", missing);
+    if (missing.length > 0) {
+      throw new Error(
+        `[ModuleRail] composition artifacts: i18n override in ${layer.owner} replaces keys that no Module or substrate defines: ${missing.join(", ")}`
+      );
+    }
   }
   return result;
 }
@@ -4411,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;
@@ -4461,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 =",
@@ -4497,6 +4555,7 @@ function emitModuleI18nGenTs(input) {
     );
   }
   const targetLocales = substrate.map((l) => l.locale);
+  const overrideByLocale = indexOverrideLocales(input.overrideLocales ?? [], targetLocales);
   const installed = new Set(input.registry.modules.map((m) => m.name));
   const allLayers = input.moduleLayers ? [...input.moduleLayers] : deriveModuleLocaleLayers(input.registry, input.facts);
   const layers = allLayers.filter((layer) => installed.has(layer.owner.split("/")[0]));
@@ -4517,19 +4576,38 @@ function emitModuleI18nGenTs(input) {
       const messages = layer.localeMessages[locale] ?? (locale === "en" ? layer.enMessages : layer.enMessages);
       composeLayers.push({ owner: layer.sourceLabel, messages });
     }
+    const override = overrideByLocale.get(locale);
+    if (override) {
+      composeLayers.push({
+        owner: overrideOwner(locale),
+        messages: override.messages,
+        override: true
+      });
+    }
     composeLocaleMessagesForPlan(composeLayers);
   }
   const composeImport = 'import { composeLocaleMessages } from "@/lib/i18n/compose-messages";';
   const moduleJsonImports = [];
   const relativeSubstrateImports = [];
   const substrateIdentByLocale = {};
+  const overrideIdentByLocale = {};
   targetLocales.forEach((locale, localeIdx) => {
     const ident = `i18nSubstrateLoc${localeIdx}`;
     relativeSubstrateImports.push(
       `import ${ident} from ${JSON.stringify(`./lib/i18n/substrate/${locale}.json`)};`
     );
     substrateIdentByLocale[locale] = ident;
+    if (overrideByLocale.has(locale)) {
+      const overrideIdent = `i18nOverrideLoc${localeIdx}`;
+      relativeSubstrateImports.push(
+        `import ${overrideIdent} from ${JSON.stringify(`./${overrideOwner(locale)}`)};`
+      );
+      overrideIdentByLocale[locale] = overrideIdent;
+    }
   });
+  relativeSubstrateImports.sort(
+    (a, b) => compareImportSpecifiers(a.match(/ from (.+);$/)[1], b.match(/ from (.+);$/)[1])
+  );
   const layerIdents = [];
   layers.forEach((layer, layerIdx) => {
     const localeIdents = {};
@@ -4563,15 +4641,29 @@ function emitModuleI18nGenTs(input) {
         (layer) => `    { owner: ${JSON.stringify(layer.owner)}, messages: ${layer.localeIdents[locale]} },`
       )
     ];
+    const overrideIdent = overrideIdentByLocale[locale];
+    const messageLines = overrideIdent ? [
+      "    messages: composeLocaleMessages([",
+      "    ...[",
+      ...layerLines,
+      "    ].map((layer) => ({",
+      "      ...layer,",
+      '      disabled: layer.owner !== "substrate" && !layer.owner.split("/").every(enabled),',
+      "    })),",
+      `    { owner: ${JSON.stringify(overrideOwner(locale))}, messages: ${overrideIdent}, override: true },`,
+      "    ]),"
+    ] : [
+      "    messages: composeLocaleMessages([",
+      ...layerLines,
+      "    ].filter((layer) =>",
+      '      layer.owner === "substrate" || layer.owner.split("/").every(enabled)',
+      "    )),"
+    ];
     bundleBlocks.push(
       [
         `  ${JSON.stringify(locale)}: {`,
         `    locale: ${JSON.stringify(locale)},`,
-        "    messages: composeLocaleMessages([",
-        ...layerLines,
-        "    ].filter((layer) =>",
-        '      layer.owner === "substrate" || layer.owner.split("/").every(enabled)',
-        "    )),",
+        ...messageLines,
         "  }"
       ].join("\n")
     );
@@ -4616,6 +4708,26 @@ function emitModuleI18nGenTs(input) {
     ""
   ].join("\n");
 }
+function indexOverrideLocales(overrideLocales, targetLocales) {
+  const byLocale = /* @__PURE__ */ new Map();
+  for (const layer of overrideLocales) {
+    if (!isValidLocaleBasename(layer.locale)) {
+      throw new Error(
+        `[ModuleRail] composition artifacts: unsafe override locale basename "${layer.locale}"`
+      );
+    }
+    if (!targetLocales.includes(layer.locale)) {
+      throw new Error(
+        `[ModuleRail] composition artifacts: ${overrideOwner(layer.locale)} has no matching lib/i18n/substrate/${layer.locale}.json; add that substrate file to make ${layer.locale} an app locale`
+      );
+    }
+    byLocale.set(layer.locale, layer);
+  }
+  return byLocale;
+}
+function overrideOwner(locale) {
+  return `lib/i18n/overrides/${locale}.json`;
+}
 function deriveModuleLocaleLayers(registry, facts) {
   const layers = [];
   const installed = new Set(registry.modules.map((m) => m.name));
@@ -4997,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");
 }
@@ -5004,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)
@@ -5011,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}`,
@@ -5058,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) {
@@ -5071,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);",
       "}"
     );
@@ -5082,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} />;",
     "}",
     ""
@@ -5284,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);
@@ -5299,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,
@@ -5308,6 +5451,7 @@ function planRouteStubs(input) {
           owner: regMod.name,
           nextRelativePath,
           importModule,
+          mountKey: mountKey(regMod.name, mount),
           hasGenerateMetadata: entry.hasGenerateMetadata
         })
       });
@@ -5494,7 +5638,8 @@ function planCompositionArtifacts(input) {
       registry: input.registry,
       facts: compositionEntryFacts,
       substrateLocales,
-      moduleLayers: input.moduleLocaleLayers
+      moduleLayers: input.moduleLocaleLayers,
+      overrideLocales: input.overrideLocales
     });
     initContent = emitModuleInitServerGenTs({
       registry: input.registry,
@@ -6839,7 +6984,8 @@ async function collectCompositionEntryFacts(context, registry) {
     `[ModuleRail] runId=${context.runId} collecting composition entry facts modules=${registry.modules.length}`
   );
   const substrateDir = `${APP_PACKAGE_DIR}/src/lib/i18n/substrate`;
-  const localeDirs = [substrateDir];
+  const overridesDir = `${APP_PACKAGE_DIR}/src/lib/i18n/overrides`;
+  const localeDirs = [substrateDir, overridesDir];
   const conventionalPaths = [];
   for (const mod of registry.modules) {
     const modulePath = `${MODULES_SANDBOX_DIR}/${mod.name}`;
@@ -6890,6 +7036,12 @@ async function collectCompositionEntryFacts(context, registry) {
       messages: await readJsonObjectFile(localePath, files)
     });
   }
+  const overrideLocales = [];
+  for (const locale of localesByDir.get(overridesDir) ?? []) {
+    const localePath = `${overridesDir}/${locale}.json`;
+    assertRealLocaleJsonFilePresence(localePath, localePresences.get(localePath) ?? "unreadable");
+    overrideLocales.push({ locale, messages: await readJsonObjectFile(localePath, files) });
+  }
   const facts = [];
   const moduleLocaleLayers = [];
   for (const mod of registry.modules) {
@@ -7016,9 +7168,9 @@ async function collectCompositionEntryFacts(context, registry) {
   facts.sort((a, b) => a.moduleName.localeCompare(b.moduleName));
   moduleLocaleLayers.sort((a, b) => a.sourceLabel.localeCompare(b.sourceLabel));
   console.log(
-    `[ModuleRail] runId=${context.runId} composition entry facts modules=${facts.length} substrateLocales=${substrateLocales.length} moduleLocaleLayers=${moduleLocaleLayers.length}`
+    `[ModuleRail] runId=${context.runId} composition entry facts modules=${facts.length} substrateLocales=${substrateLocales.length} overrideLocales=${overrideLocales.map((layer) => layer.locale).join(",") || "none"} moduleLocaleLayers=${moduleLocaleLayers.length}`
   );
-  return { facts, substrateLocales, moduleLocaleLayers };
+  return { facts, substrateLocales, overrideLocales, moduleLocaleLayers };
 }
 function selectComposedModules(presentNames, manifestsByName, enabledRaw) {
   if (enabledRaw) {
@@ -7158,6 +7310,7 @@ async function reconcileCompositionArtifacts(context, options = {}) {
   const {
     facts: compositionEntryFacts,
     substrateLocales,
+    overrideLocales,
     moduleLocaleLayers
   } = await collectCompositionEntryFacts(context, registry);
   const candidatePaths = /* @__PURE__ */ new Set([
@@ -7180,6 +7333,7 @@ async function reconcileCompositionArtifacts(context, options = {}) {
     existingAppRoutes,
     compositionEntryFacts,
     substrateLocales,
+    overrideLocales,
     moduleLocaleLayers,
     moduleDataStoreBindings
   });
@@ -7248,6 +7402,7 @@ async function reconcileCompositionArtifacts(context, options = {}) {
     existingAppRoutes,
     compositionEntryFacts,
     substrateLocales,
+    overrideLocales,
     moduleLocaleLayers,
     moduleDataStoreBindings
   });

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);
 
@@ -4276,6 +4282,40 @@ function cloneTree(value) {
   }
   return clone;
 }
+function collectLeafPaths(value, path3, out) {
+  if (typeof value === "string") {
+    out.push(path3);
+    return;
+  }
+  assertMessageTree(value, path3);
+  for (const [key, child] of Object.entries(value)) collectLeafPaths(child, `${path3}.${key}`, out);
+}
+function overrideInto(target, source, owner, path3, missing) {
+  for (const [key, value] of Object.entries(source)) {
+    const nextPath = path3 ? `${path3}.${key}` : key;
+    if (!Object.prototype.hasOwnProperty.call(target, key)) {
+      collectLeafPaths(value, nextPath, missing);
+      continue;
+    }
+    const existing = target[key];
+    if (typeof value === "string") {
+      if (typeof existing !== "string") {
+        throw new Error(
+          `[ModuleRail] composition artifacts: i18n merge conflict at ${nextPath}: ${owner} has string leaf but another owner has an object`
+        );
+      }
+      target[key] = value;
+      continue;
+    }
+    assertMessageTree(value, nextPath);
+    if (typeof existing === "string") {
+      throw new Error(
+        `[ModuleRail] composition artifacts: i18n merge conflict at ${nextPath}: ${owner} has object but another owner has a string leaf`
+      );
+    }
+    overrideInto(existing, value, owner, nextPath, missing);
+  }
+}
 function composeLocaleMessagesForPlan(layers) {
   const result = createMessageTree();
   const leafOwners = /* @__PURE__ */ new Map();
@@ -4327,7 +4367,17 @@ function composeLocaleMessagesForPlan(layers) {
   }
   for (const layer of layers) {
     assertMessageTree(layer.messages, layer.owner);
-    mergeInto(result, cloneTree(layer.messages), layer.owner, "");
+    if (!layer.override) {
+      mergeInto(result, cloneTree(layer.messages), layer.owner, "");
+      continue;
+    }
+    const missing = [];
+    overrideInto(result, cloneTree(layer.messages), layer.owner, "", missing);
+    if (missing.length > 0) {
+      throw new Error(
+        `[ModuleRail] composition artifacts: i18n override in ${layer.owner} replaces keys that no Module or substrate defines: ${missing.join(", ")}`
+      );
+    }
   }
   return result;
 }
@@ -4420,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;
@@ -4470,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 =",
@@ -4506,6 +4564,7 @@ function emitModuleI18nGenTs(input) {
     );
   }
   const targetLocales = substrate.map((l) => l.locale);
+  const overrideByLocale = indexOverrideLocales(input.overrideLocales ?? [], targetLocales);
   const installed = new Set(input.registry.modules.map((m) => m.name));
   const allLayers = input.moduleLayers ? [...input.moduleLayers] : deriveModuleLocaleLayers(input.registry, input.facts);
   const layers = allLayers.filter((layer) => installed.has(layer.owner.split("/")[0]));
@@ -4526,19 +4585,38 @@ function emitModuleI18nGenTs(input) {
       const messages = layer.localeMessages[locale] ?? (locale === "en" ? layer.enMessages : layer.enMessages);
       composeLayers.push({ owner: layer.sourceLabel, messages });
     }
+    const override = overrideByLocale.get(locale);
+    if (override) {
+      composeLayers.push({
+        owner: overrideOwner(locale),
+        messages: override.messages,
+        override: true
+      });
+    }
     composeLocaleMessagesForPlan(composeLayers);
   }
   const composeImport = 'import { composeLocaleMessages } from "@/lib/i18n/compose-messages";';
   const moduleJsonImports = [];
   const relativeSubstrateImports = [];
   const substrateIdentByLocale = {};
+  const overrideIdentByLocale = {};
   targetLocales.forEach((locale, localeIdx) => {
     const ident = `i18nSubstrateLoc${localeIdx}`;
     relativeSubstrateImports.push(
       `import ${ident} from ${JSON.stringify(`./lib/i18n/substrate/${locale}.json`)};`
     );
     substrateIdentByLocale[locale] = ident;
+    if (overrideByLocale.has(locale)) {
+      const overrideIdent = `i18nOverrideLoc${localeIdx}`;
+      relativeSubstrateImports.push(
+        `import ${overrideIdent} from ${JSON.stringify(`./${overrideOwner(locale)}`)};`
+      );
+      overrideIdentByLocale[locale] = overrideIdent;
+    }
   });
+  relativeSubstrateImports.sort(
+    (a, b) => compareImportSpecifiers(a.match(/ from (.+);$/)[1], b.match(/ from (.+);$/)[1])
+  );
   const layerIdents = [];
   layers.forEach((layer, layerIdx) => {
     const localeIdents = {};
@@ -4572,15 +4650,29 @@ function emitModuleI18nGenTs(input) {
         (layer) => `    { owner: ${JSON.stringify(layer.owner)}, messages: ${layer.localeIdents[locale]} },`
       )
     ];
+    const overrideIdent = overrideIdentByLocale[locale];
+    const messageLines = overrideIdent ? [
+      "    messages: composeLocaleMessages([",
+      "    ...[",
+      ...layerLines,
+      "    ].map((layer) => ({",
+      "      ...layer,",
+      '      disabled: layer.owner !== "substrate" && !layer.owner.split("/").every(enabled),',
+      "    })),",
+      `    { owner: ${JSON.stringify(overrideOwner(locale))}, messages: ${overrideIdent}, override: true },`,
+      "    ]),"
+    ] : [
+      "    messages: composeLocaleMessages([",
+      ...layerLines,
+      "    ].filter((layer) =>",
+      '      layer.owner === "substrate" || layer.owner.split("/").every(enabled)',
+      "    )),"
+    ];
     bundleBlocks.push(
       [
         `  ${JSON.stringify(locale)}: {`,
         `    locale: ${JSON.stringify(locale)},`,
-        "    messages: composeLocaleMessages([",
-        ...layerLines,
-        "    ].filter((layer) =>",
-        '      layer.owner === "substrate" || layer.owner.split("/").every(enabled)',
-        "    )),",
+        ...messageLines,
         "  }"
       ].join("\n")
     );
@@ -4625,6 +4717,26 @@ function emitModuleI18nGenTs(input) {
     ""
   ].join("\n");
 }
+function indexOverrideLocales(overrideLocales, targetLocales) {
+  const byLocale = /* @__PURE__ */ new Map();
+  for (const layer of overrideLocales) {
+    if (!isValidLocaleBasename(layer.locale)) {
+      throw new Error(
+        `[ModuleRail] composition artifacts: unsafe override locale basename "${layer.locale}"`
+      );
+    }
+    if (!targetLocales.includes(layer.locale)) {
+      throw new Error(
+        `[ModuleRail] composition artifacts: ${overrideOwner(layer.locale)} has no matching lib/i18n/substrate/${layer.locale}.json; add that substrate file to make ${layer.locale} an app locale`
+      );
+    }
+    byLocale.set(layer.locale, layer);
+  }
+  return byLocale;
+}
+function overrideOwner(locale) {
+  return `lib/i18n/overrides/${locale}.json`;
+}
 function deriveModuleLocaleLayers(registry, facts) {
   const layers = [];
   const installed = new Set(registry.modules.map((m) => m.name));
@@ -5006,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");
 }
@@ -5013,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)
@@ -5020,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}`,
@@ -5067,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) {
@@ -5080,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);",
       "}"
     );
@@ -5091,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} />;",
     "}",
     ""
@@ -5293,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);
@@ -5308,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,
@@ -5317,6 +5460,7 @@ function planRouteStubs(input) {
           owner: regMod.name,
           nextRelativePath,
           importModule,
+          mountKey: mountKey(regMod.name, mount),
           hasGenerateMetadata: entry.hasGenerateMetadata
         })
       });
@@ -5503,7 +5647,8 @@ function planCompositionArtifacts(input) {
       registry: input.registry,
       facts: compositionEntryFacts,
       substrateLocales,
-      moduleLayers: input.moduleLocaleLayers
+      moduleLayers: input.moduleLocaleLayers,
+      overrideLocales: input.overrideLocales
     });
     initContent = emitModuleInitServerGenTs({
       registry: input.registry,
@@ -6848,7 +6993,8 @@ async function collectCompositionEntryFacts(context, registry) {
     `[ModuleRail] runId=${context.runId} collecting composition entry facts modules=${registry.modules.length}`
   );
   const substrateDir = `${APP_PACKAGE_DIR}/src/lib/i18n/substrate`;
-  const localeDirs = [substrateDir];
+  const overridesDir = `${APP_PACKAGE_DIR}/src/lib/i18n/overrides`;
+  const localeDirs = [substrateDir, overridesDir];
   const conventionalPaths = [];
   for (const mod of registry.modules) {
     const modulePath = `${MODULES_SANDBOX_DIR}/${mod.name}`;
@@ -6899,6 +7045,12 @@ async function collectCompositionEntryFacts(context, registry) {
       messages: await readJsonObjectFile(localePath, files)
     });
   }
+  const overrideLocales = [];
+  for (const locale of localesByDir.get(overridesDir) ?? []) {
+    const localePath = `${overridesDir}/${locale}.json`;
+    assertRealLocaleJsonFilePresence(localePath, localePresences.get(localePath) ?? "unreadable");
+    overrideLocales.push({ locale, messages: await readJsonObjectFile(localePath, files) });
+  }
   const facts = [];
   const moduleLocaleLayers = [];
   for (const mod of registry.modules) {
@@ -7025,9 +7177,9 @@ async function collectCompositionEntryFacts(context, registry) {
   facts.sort((a, b) => a.moduleName.localeCompare(b.moduleName));
   moduleLocaleLayers.sort((a, b) => a.sourceLabel.localeCompare(b.sourceLabel));
   console.log(
-    `[ModuleRail] runId=${context.runId} composition entry facts modules=${facts.length} substrateLocales=${substrateLocales.length} moduleLocaleLayers=${moduleLocaleLayers.length}`
+    `[ModuleRail] runId=${context.runId} composition entry facts modules=${facts.length} substrateLocales=${substrateLocales.length} overrideLocales=${overrideLocales.map((layer) => layer.locale).join(",") || "none"} moduleLocaleLayers=${moduleLocaleLayers.length}`
   );
-  return { facts, substrateLocales, moduleLocaleLayers };
+  return { facts, substrateLocales, overrideLocales, moduleLocaleLayers };
 }
 function selectComposedModules(presentNames, manifestsByName, enabledRaw) {
   if (enabledRaw) {
@@ -7167,6 +7319,7 @@ async function reconcileCompositionArtifacts(context, options = {}) {
   const {
     facts: compositionEntryFacts,
     substrateLocales,
+    overrideLocales,
     moduleLocaleLayers
   } = await collectCompositionEntryFacts(context, registry);
   const candidatePaths = /* @__PURE__ */ new Set([
@@ -7189,6 +7342,7 @@ async function reconcileCompositionArtifacts(context, options = {}) {
     existingAppRoutes,
     compositionEntryFacts,
     substrateLocales,
+    overrideLocales,
     moduleLocaleLayers,
     moduleDataStoreBindings
   });
@@ -7257,6 +7411,7 @@ async function reconcileCompositionArtifacts(context, options = {}) {
     existingAppRoutes,
     compositionEntryFacts,
     substrateLocales,
+    overrideLocales,
     moduleLocaleLayers,
     moduleDataStoreBindings
   });

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";
 
@@ -4261,6 +4267,40 @@ function cloneTree(value) {
   }
   return clone;
 }
+function collectLeafPaths(value, path3, out) {
+  if (typeof value === "string") {
+    out.push(path3);
+    return;
+  }
+  assertMessageTree(value, path3);
+  for (const [key, child] of Object.entries(value)) collectLeafPaths(child, `${path3}.${key}`, out);
+}
+function overrideInto(target, source, owner, path3, missing) {
+  for (const [key, value] of Object.entries(source)) {
+    const nextPath = path3 ? `${path3}.${key}` : key;
+    if (!Object.prototype.hasOwnProperty.call(target, key)) {
+      collectLeafPaths(value, nextPath, missing);
+      continue;
+    }
+    const existing = target[key];
+    if (typeof value === "string") {
+      if (typeof existing !== "string") {
+        throw new Error(
+          `[ModuleRail] composition artifacts: i18n merge conflict at ${nextPath}: ${owner} has string leaf but another owner has an object`
+        );
+      }
+      target[key] = value;
+      continue;
+    }
+    assertMessageTree(value, nextPath);
+    if (typeof existing === "string") {
+      throw new Error(
+        `[ModuleRail] composition artifacts: i18n merge conflict at ${nextPath}: ${owner} has object but another owner has a string leaf`
+      );
+    }
+    overrideInto(existing, value, owner, nextPath, missing);
+  }
+}
 function composeLocaleMessagesForPlan(layers) {
   const result = createMessageTree();
   const leafOwners = /* @__PURE__ */ new Map();
@@ -4312,7 +4352,17 @@ function composeLocaleMessagesForPlan(layers) {
   }
   for (const layer of layers) {
     assertMessageTree(layer.messages, layer.owner);
-    mergeInto(result, cloneTree(layer.messages), layer.owner, "");
+    if (!layer.override) {
+      mergeInto(result, cloneTree(layer.messages), layer.owner, "");
+      continue;
+    }
+    const missing = [];
+    overrideInto(result, cloneTree(layer.messages), layer.owner, "", missing);
+    if (missing.length > 0) {
+      throw new Error(
+        `[ModuleRail] composition artifacts: i18n override in ${layer.owner} replaces keys that no Module or substrate defines: ${missing.join(", ")}`
+      );
+    }
   }
   return result;
 }
@@ -4405,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;
@@ -4455,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 =",
@@ -4491,6 +4549,7 @@ function emitModuleI18nGenTs(input) {
     );
   }
   const targetLocales = substrate.map((l) => l.locale);
+  const overrideByLocale = indexOverrideLocales(input.overrideLocales ?? [], targetLocales);
   const installed = new Set(input.registry.modules.map((m) => m.name));
   const allLayers = input.moduleLayers ? [...input.moduleLayers] : deriveModuleLocaleLayers(input.registry, input.facts);
   const layers = allLayers.filter((layer) => installed.has(layer.owner.split("/")[0]));
@@ -4511,19 +4570,38 @@ function emitModuleI18nGenTs(input) {
       const messages = layer.localeMessages[locale] ?? (locale === "en" ? layer.enMessages : layer.enMessages);
       composeLayers.push({ owner: layer.sourceLabel, messages });
     }
+    const override = overrideByLocale.get(locale);
+    if (override) {
+      composeLayers.push({
+        owner: overrideOwner(locale),
+        messages: override.messages,
+        override: true
+      });
+    }
     composeLocaleMessagesForPlan(composeLayers);
   }
   const composeImport = 'import { composeLocaleMessages } from "@/lib/i18n/compose-messages";';
   const moduleJsonImports = [];
   const relativeSubstrateImports = [];
   const substrateIdentByLocale = {};
+  const overrideIdentByLocale = {};
   targetLocales.forEach((locale, localeIdx) => {
     const ident = `i18nSubstrateLoc${localeIdx}`;
     relativeSubstrateImports.push(
       `import ${ident} from ${JSON.stringify(`./lib/i18n/substrate/${locale}.json`)};`
     );
     substrateIdentByLocale[locale] = ident;
+    if (overrideByLocale.has(locale)) {
+      const overrideIdent = `i18nOverrideLoc${localeIdx}`;
+      relativeSubstrateImports.push(
+        `import ${overrideIdent} from ${JSON.stringify(`./${overrideOwner(locale)}`)};`
+      );
+      overrideIdentByLocale[locale] = overrideIdent;
+    }
   });
+  relativeSubstrateImports.sort(
+    (a, b) => compareImportSpecifiers(a.match(/ from (.+);$/)[1], b.match(/ from (.+);$/)[1])
+  );
   const layerIdents = [];
   layers.forEach((layer, layerIdx) => {
     const localeIdents = {};
@@ -4557,15 +4635,29 @@ function emitModuleI18nGenTs(input) {
         (layer) => `    { owner: ${JSON.stringify(layer.owner)}, messages: ${layer.localeIdents[locale]} },`
       )
     ];
+    const overrideIdent = overrideIdentByLocale[locale];
+    const messageLines = overrideIdent ? [
+      "    messages: composeLocaleMessages([",
+      "    ...[",
+      ...layerLines,
+      "    ].map((layer) => ({",
+      "      ...layer,",
+      '      disabled: layer.owner !== "substrate" && !layer.owner.split("/").every(enabled),',
+      "    })),",
+      `    { owner: ${JSON.stringify(overrideOwner(locale))}, messages: ${overrideIdent}, override: true },`,
+      "    ]),"
+    ] : [
+      "    messages: composeLocaleMessages([",
+      ...layerLines,
+      "    ].filter((layer) =>",
+      '      layer.owner === "substrate" || layer.owner.split("/").every(enabled)',
+      "    )),"
+    ];
     bundleBlocks.push(
       [
         `  ${JSON.stringify(locale)}: {`,
         `    locale: ${JSON.stringify(locale)},`,
-        "    messages: composeLocaleMessages([",
-        ...layerLines,
-        "    ].filter((layer) =>",
-        '      layer.owner === "substrate" || layer.owner.split("/").every(enabled)',
-        "    )),",
+        ...messageLines,
         "  }"
       ].join("\n")
     );
@@ -4610,6 +4702,26 @@ function emitModuleI18nGenTs(input) {
     ""
   ].join("\n");
 }
+function indexOverrideLocales(overrideLocales, targetLocales) {
+  const byLocale = /* @__PURE__ */ new Map();
+  for (const layer of overrideLocales) {
+    if (!isValidLocaleBasename(layer.locale)) {
+      throw new Error(
+        `[ModuleRail] composition artifacts: unsafe override locale basename "${layer.locale}"`
+      );
+    }
+    if (!targetLocales.includes(layer.locale)) {
+      throw new Error(
+        `[ModuleRail] composition artifacts: ${overrideOwner(layer.locale)} has no matching lib/i18n/substrate/${layer.locale}.json; add that substrate file to make ${layer.locale} an app locale`
+      );
+    }
+    byLocale.set(layer.locale, layer);
+  }
+  return byLocale;
+}
+function overrideOwner(locale) {
+  return `lib/i18n/overrides/${locale}.json`;
+}
 function deriveModuleLocaleLayers(registry, facts) {
   const layers = [];
   const installed = new Set(registry.modules.map((m) => m.name));
@@ -4991,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");
 }
@@ -4998,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)
@@ -5005,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}`,
@@ -5052,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) {
@@ -5065,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);",
       "}"
     );
@@ -5076,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} />;",
     "}",
     ""
@@ -5278,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);
@@ -5293,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,
@@ -5302,6 +5445,7 @@ function planRouteStubs(input) {
           owner: regMod.name,
           nextRelativePath,
           importModule,
+          mountKey: mountKey(regMod.name, mount),
           hasGenerateMetadata: entry.hasGenerateMetadata
         })
       });
@@ -5488,7 +5632,8 @@ function planCompositionArtifacts(input) {
       registry: input.registry,
       facts: compositionEntryFacts,
       substrateLocales,
-      moduleLayers: input.moduleLocaleLayers
+      moduleLayers: input.moduleLocaleLayers,
+      overrideLocales: input.overrideLocales
     });
     initContent = emitModuleInitServerGenTs({
       registry: input.registry,
@@ -6833,7 +6978,8 @@ async function collectCompositionEntryFacts(context, registry) {
     `[ModuleRail] runId=${context.runId} collecting composition entry facts modules=${registry.modules.length}`
   );
   const substrateDir = `${APP_PACKAGE_DIR}/src/lib/i18n/substrate`;
-  const localeDirs = [substrateDir];
+  const overridesDir = `${APP_PACKAGE_DIR}/src/lib/i18n/overrides`;
+  const localeDirs = [substrateDir, overridesDir];
   const conventionalPaths = [];
   for (const mod of registry.modules) {
     const modulePath = `${MODULES_SANDBOX_DIR}/${mod.name}`;
@@ -6884,6 +7030,12 @@ async function collectCompositionEntryFacts(context, registry) {
       messages: await readJsonObjectFile(localePath, files)
     });
   }
+  const overrideLocales = [];
+  for (const locale of localesByDir.get(overridesDir) ?? []) {
+    const localePath = `${overridesDir}/${locale}.json`;
+    assertRealLocaleJsonFilePresence(localePath, localePresences.get(localePath) ?? "unreadable");
+    overrideLocales.push({ locale, messages: await readJsonObjectFile(localePath, files) });
+  }
   const facts = [];
   const moduleLocaleLayers = [];
   for (const mod of registry.modules) {
@@ -7010,9 +7162,9 @@ async function collectCompositionEntryFacts(context, registry) {
   facts.sort((a, b) => a.moduleName.localeCompare(b.moduleName));
   moduleLocaleLayers.sort((a, b) => a.sourceLabel.localeCompare(b.sourceLabel));
   console.log(
-    `[ModuleRail] runId=${context.runId} composition entry facts modules=${facts.length} substrateLocales=${substrateLocales.length} moduleLocaleLayers=${moduleLocaleLayers.length}`
+    `[ModuleRail] runId=${context.runId} composition entry facts modules=${facts.length} substrateLocales=${substrateLocales.length} overrideLocales=${overrideLocales.map((layer) => layer.locale).join(",") || "none"} moduleLocaleLayers=${moduleLocaleLayers.length}`
   );
-  return { facts, substrateLocales, moduleLocaleLayers };
+  return { facts, substrateLocales, overrideLocales, moduleLocaleLayers };
 }
 function selectComposedModules(presentNames, manifestsByName, enabledRaw) {
   if (enabledRaw) {
@@ -7152,6 +7304,7 @@ async function reconcileCompositionArtifacts(context, options = {}) {
   const {
     facts: compositionEntryFacts,
     substrateLocales,
+    overrideLocales,
     moduleLocaleLayers
   } = await collectCompositionEntryFacts(context, registry);
   const candidatePaths = /* @__PURE__ */ new Set([
@@ -7174,6 +7327,7 @@ async function reconcileCompositionArtifacts(context, options = {}) {
     existingAppRoutes,
     compositionEntryFacts,
     substrateLocales,
+    overrideLocales,
     moduleLocaleLayers,
     moduleDataStoreBindings
   });
@@ -7242,6 +7396,7 @@ async function reconcileCompositionArtifacts(context, options = {}) {
     existingAppRoutes,
     compositionEntryFacts,
     substrateLocales,
+    overrideLocales,
     moduleLocaleLayers,
     moduleDataStoreBindings
   });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stardeck-customer-apps/compose",
-  "version": "0.5.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",