@ultimat3/core 22.2.1 → 22.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/core",
-  "version": "22.2.1",
+  "version": "22.3.0",
   "description": "Ultimate's foundation: errors, context, env, config, clock, ids, logging, telemetry, lifecycle",
   "license": "MIT",
   "type": "module",
@@ -40,6 +40,6 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/schema": "22.2.1"
+    "@ultimat3/schema": "22.3.0"
   }
 }

package/src/config-site.ts

@@ -0,0 +1,87 @@
+// Single responsibility: the `site` and `seo` blocks of `app.config.ts` — the public origin every
+// absolute URL a document carries is built from, and the paths `robots.txt` keeps crawlers out of.
+// Split from `config.ts` for `config-pwa.ts`' reason: that file sits at its 500-line ceiling.
+
+import { type Input, layered } from './config-merge';
+
+export interface SiteConfig {
+  /**
+   * `https://www.example.com` — canonical, `og:url`, hreflang and the sitemap are absolute against
+   * it. `null` falls back to `APP_URL`, then to the request's own origin; a production build with
+   * neither warns, because a relative canonical is one a search engine may resolve against a CDN
+   * host or a preview domain.
+   */
+  readonly origin: string | null;
+}
+
+export interface SeoRobotsConfig {
+  /** Paths `robots.txt` disallows in production, e.g. `['/panel', '/api']`. Each starts with `/`. */
+  readonly disallow: readonly string[];
+}
+
+export interface SeoConfig {
+  readonly robots: SeoRobotsConfig;
+}
+
+/** `robots` is NESTED for `AiConfigInput`'s reason: `section` applies a patch one level deep. */
+export interface SeoConfigInput {
+  readonly robots?: Input<SeoRobotsConfig> | undefined;
+}
+
+export interface SiteSections {
+  readonly site: SiteConfig;
+  readonly seo: SeoConfig;
+}
+
+export interface SiteSectionsInput {
+  readonly site?: Input<SiteConfig> | undefined;
+  readonly seo?: SeoConfigInput | undefined;
+}
+
+/** Both sections, every layer applied key by key over the defaults. */
+export function mergeSite(layers: readonly SiteSectionsInput[]): SiteSections {
+  return {
+    site: layered<SiteConfig>(
+      { origin: null },
+      layers.map((layer) => layer.site),
+    ),
+    seo: {
+      robots: layered<SeoRobotsConfig>(
+        { disallow: [] },
+        layers.map((layer) => layer.seo?.robots),
+      ),
+    },
+  };
+}
+
+/**
+ * An origin is scheme + host (+ port) and nothing else: a path would be doubled into every URL built
+ * against it, and a scheme other than http(s) is not a page a crawler can fetch.
+ */
+function originIssue(origin: string): string | undefined {
+  let url: URL;
+  try {
+    url = new URL(origin);
+  } catch {
+    return `site.origin "${origin}" is not an absolute URL`;
+  }
+  if (url.protocol !== 'https:' && url.protocol !== 'http:') {
+    return `site.origin "${origin}" must be http:// or https://`;
+  }
+  if (url.pathname !== '/' || url.search !== '' || url.hash !== '') {
+    return `site.origin "${origin}" must be an origin only — no path, query or fragment`;
+  }
+  return undefined;
+}
+
+/** Appends every refusal the two sections earn to `issues`, `config.ts`' one list. */
+export function siteIssues(config: SiteSections, issues: string[]): void {
+  const origin = config.site.origin;
+  if (origin !== null) {
+    const issue = originIssue(origin);
+    if (issue !== undefined) issues.push(issue);
+  }
+  for (const path of config.seo.robots.disallow) {
+    if (!path.startsWith('/')) issues.push(`seo.robots.disallow entry "${path}" must start with /`);
+  }
+}

package/src/config.ts

@@ -12,6 +12,8 @@ import { BASE_FIX, CACHE_TIER_FIX, TIMEZONE_FIX } from './config-fixes';
 import { type Input, lastSaid, layered } from './config-merge';
 import type { PwaConfig, PwaOfflineConfig } from './config-pwa';
 import { PWA_FIX, pwaIssues } from './config-pwa';
+import type { SeoConfig, SiteConfig, SiteSectionsInput } from './config-site';
+import { mergeSite, siteIssues } from './config-site';
 import { describeValue } from './error-render';
 import { ConfigInvalidError } from './errors';
 import { defaultReadinessGraceMs, readinessGraceIssue } from './lifecycle-grace';
@@ -212,6 +214,8 @@ export interface AppConfig {
   readonly notify: NotifyConfig;
   readonly ai: AiConfig;
   readonly drain: DrainConfig;
+  readonly site: SiteConfig;
+  readonly seo: SeoConfig;
 }
 
 /** `mcp` is the only member, and it is NESTED — `Input<AiConfig>` would make it all-or-nothing. */
@@ -230,7 +234,7 @@ export interface PwaConfigInput extends Omit<Input<PwaConfig>, 'offline'> {
   readonly offline?: Input<PwaOfflineConfig> | undefined;
 }
 
-export interface AppConfigInput {
+export interface AppConfigInput extends SiteSectionsInput {
   readonly name: string;
   readonly locales?: readonly string[] | undefined;
   readonly defaultLocale?: string | undefined;
@@ -271,7 +275,7 @@ function isLocale(value: string): boolean {
   }
 }
 
-function defaults(name: string): Omit<AppConfig, 'name'> {
+function defaults(name: string): Omit<AppConfig, 'name' | 'site' | 'seo'> {
   return {
     locales: ['en'],
     defaultLocale: 'en',
@@ -380,6 +384,7 @@ function validate(config: AppConfig): void {
   // remedy, because `pwa.enabled` turning four other requirements on is a question about that block
   // and nothing else here.
   if (pwaIssues(config.pwa, issues)) pwaFix.push(PWA_FIX);
+  siteIssues(config, issues);
 
   // A rung the ladder cannot build is the defect this key had: `sortTiers` places a name by its
   // index in `CACHE_TIERS`, and a name missing from it sorts to `-1` — AHEAD of the request memo.
@@ -487,6 +492,7 @@ export function defineConfig(
       base.drain,
       layers.map((layer) => layer.drain),
     ),
+    ...mergeSite(layers),
   };
 
   validate(config);

package/src/index.ts

@@ -111,6 +111,14 @@ export type {
 export { defineConfig, INBOX_RETENTION_KEYS } from './config';
 export type { PwaColors, PwaConfig, PwaOfflineConfig, PwaSchemeColors } from './config-pwa';
 export { PWA_COLOR_KEYS, PWA_SCHEMES } from './config-pwa';
+export type {
+  SeoConfig,
+  SeoConfigInput,
+  SeoRobotsConfig,
+  SiteConfig,
+  SiteSections,
+  SiteSectionsInput,
+} from './config-site';
 export type { ConflictPolicy, ResolveConflictOptions, Row } from './conflict-policy';
 export { resolveConflict } from './conflict-policy';
 export type { Ctx, CtxFacts, CtxInit, CtxPatch, CtxServices, ServiceBag } from './context';
@@ -536,6 +544,8 @@ export { installSignalHandlers } from './lifecycle-signals';
 export { isSelfOrigin, listeningOrigins, markListening, resetListeners } from './listeners';
 export type { Direction } from './locale-direction';
 export { directionOf, isRtl } from './locale-direction';
+export type { LocalePathSplit } from './locale-path';
+export { localeSegment, localizePath, splitLocalePath } from './locale-path';
 export { isMcpExposed, type McpExposureDeclaration } from './mcp-exposure';
 export type { MeasurementActorFactory } from './measurement-actor';
 export {

package/src/locale-path.ts

@@ -0,0 +1,65 @@
+// A locale in a URL, as pure path arithmetic over an explicit locale list: the default locale is
+// the UNPREFIXED path, every other one is `/<locale>/…`. Tier 0 for `locale-direction.ts`' reason:
+// `@ultimat3/ui`'s `LocaleSwitcher` spells its links with it, and reaching the i18n barrel for one
+// function puts the whole framework catalog into every browser chunk (issue #490). i18n wraps these
+// with the app's configured locales (`localizedPath`, `splitLocalePrefix`), so apps call those.
+
+/** The segment a locale is written as in a URL: lowercase, so `pt-BR` is `/pt-br/`. */
+export function localeSegment(locale: string): string {
+  return locale.toLowerCase();
+}
+
+export interface LocalePathSplit {
+  /** The spelling the locale list carries. */
+  readonly locale: string;
+  /** The pathname with the segment removed — `/` for `/en` and `/en/`. */
+  readonly path: string;
+  /** The segment named the default locale: a duplicate URL, answered with a redirect. */
+  readonly isDefault: boolean;
+}
+
+/**
+ * `/en/precios` → `{ locale: 'en', path: '/precios' }`; `undefined` when the first segment names no
+ * listed locale. Exact lowercase match only: `/EN/x` is not a second spelling of `/en/x`, because
+ * two URLs for one document is the duplicate-content bug the default's redirect exists to prevent.
+ */
+export function splitLocalePath(
+  pathname: string,
+  locales: readonly string[],
+  defaultLocale: string,
+): LocalePathSplit | undefined {
+  if (!pathname.startsWith('/')) return undefined;
+  const end = pathname.indexOf('/', 1);
+  const segment = end === -1 ? pathname.slice(1) : pathname.slice(1, end);
+  if (segment === '') return undefined;
+  const locale = locales.find((candidate) => localeSegment(candidate) === segment);
+  if (locale === undefined) return undefined;
+  const rest = end === -1 ? '' : pathname.slice(end);
+  return {
+    locale,
+    path: rest === '' ? '/' : rest,
+    isDefault: localeSegment(locale) === localeSegment(defaultLocale),
+  };
+}
+
+/**
+ * `path` as `locale` spells it: `/precios` + `en` → `/en/precios`, the default locale → `/precios`,
+ * and the root → `/en/` (the directory a static host serves `en/index.html` from without a
+ * redirect). A path already carrying a listed prefix is re-spelled, never doubled, so a language
+ * switcher can hand in the page it is on. A query or fragment is kept as written.
+ */
+export function localizePath(
+  path: string,
+  locale: string,
+  locales: readonly string[],
+  defaultLocale: string,
+): string {
+  const cut = path.search(/[?#]/);
+  const pathname = cut === -1 ? path : path.slice(0, cut);
+  const suffix = cut === -1 ? '' : path.slice(cut);
+  const bare = splitLocalePath(pathname, locales, defaultLocale)?.path ?? pathname;
+  const rooted = bare.startsWith('/') ? bare : `/${bare}`;
+  if (localeSegment(locale) === localeSegment(defaultLocale)) return `${rooted}${suffix}`;
+  const prefix = `/${localeSegment(locale)}`;
+  return `${rooted === '/' ? `${prefix}/` : `${prefix}${rooted}`}${suffix}`;
+}