@stardeck-customer-apps/compose 0.5.0 → 0.6.0

package/SKILL.md

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

package/dist/cli.js

@@ -4267,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();
@@ -4318,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;
 }
@@ -4497,6 +4541,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 +4562,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 +4627,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 +4694,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));
@@ -5494,7 +5592,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 +6938,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 +6990,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 +7122,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 +7264,7 @@ async function reconcileCompositionArtifacts(context, options = {}) {
   const {
     facts: compositionEntryFacts,
     substrateLocales,
+    overrideLocales,
     moduleLocaleLayers
   } = await collectCompositionEntryFacts(context, registry);
   const candidatePaths = /* @__PURE__ */ new Set([
@@ -7180,6 +7287,7 @@ async function reconcileCompositionArtifacts(context, options = {}) {
     existingAppRoutes,
     compositionEntryFacts,
     substrateLocales,
+    overrideLocales,
     moduleLocaleLayers,
     moduleDataStoreBindings
   });
@@ -7248,6 +7356,7 @@ async function reconcileCompositionArtifacts(context, options = {}) {
     existingAppRoutes,
     compositionEntryFacts,
     substrateLocales,
+    overrideLocales,
     moduleLocaleLayers,
     moduleDataStoreBindings
   });

package/dist/index.js

@@ -4276,6 +4276,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 +4361,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;
 }
@@ -4506,6 +4550,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 +4571,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 +4636,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 +4703,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));
@@ -5503,7 +5601,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 +6947,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 +6999,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 +7131,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 +7273,7 @@ async function reconcileCompositionArtifacts(context, options = {}) {
   const {
     facts: compositionEntryFacts,
     substrateLocales,
+    overrideLocales,
     moduleLocaleLayers
   } = await collectCompositionEntryFacts(context, registry);
   const candidatePaths = /* @__PURE__ */ new Set([
@@ -7189,6 +7296,7 @@ async function reconcileCompositionArtifacts(context, options = {}) {
     existingAppRoutes,
     compositionEntryFacts,
     substrateLocales,
+    overrideLocales,
     moduleLocaleLayers,
     moduleDataStoreBindings
   });
@@ -7257,6 +7365,7 @@ async function reconcileCompositionArtifacts(context, options = {}) {
     existingAppRoutes,
     compositionEntryFacts,
     substrateLocales,
+    overrideLocales,
     moduleLocaleLayers,
     moduleDataStoreBindings
   });

package/dist/index.mjs

@@ -4261,6 +4261,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 +4346,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;
 }
@@ -4491,6 +4535,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 +4556,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 +4621,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 +4688,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));
@@ -5488,7 +5586,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 +6932,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 +6984,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 +7116,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 +7258,7 @@ async function reconcileCompositionArtifacts(context, options = {}) {
   const {
     facts: compositionEntryFacts,
     substrateLocales,
+    overrideLocales,
     moduleLocaleLayers
   } = await collectCompositionEntryFacts(context, registry);
   const candidatePaths = /* @__PURE__ */ new Set([
@@ -7174,6 +7281,7 @@ async function reconcileCompositionArtifacts(context, options = {}) {
     existingAppRoutes,
     compositionEntryFacts,
     substrateLocales,
+    overrideLocales,
     moduleLocaleLayers,
     moduleDataStoreBindings
   });
@@ -7242,6 +7350,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.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",
   "main": "dist/index.js",
   "module": "dist/index.mjs",