@uniweb/core 0.11.1 → 0.11.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/core",
-  "version": "0.11.1",
+  "version": "0.11.3",
   "description": "Core classes for the Uniweb platform - Uniweb, Website, Page, Block",
   "type": "module",
   "exports": {

package/src/locale-config.js

@@ -41,6 +41,72 @@ function codeOf(entry) {
  * @param {*} value - The authored `languages` value.
  * @returns {boolean}
  */
+/**
+ * Human-readable display names for the locales a site is likely to declare.
+ *
+ * This lives in core, not kit, because core is what BUILDS the locale objects a
+ * foundation reads (`website.getLocales()`, `website.langs`). It used to live
+ * only in kit, so core could not resolve a label and left the field absent for
+ * a plain-string `languages:` entry — which meant the very form this module
+ * tells authors to migrate TO produced worse labels than the legacy object form
+ * it warns about. Measured 2026-08-23 on a site with 11 locales: dropping the
+ * `label:` keys silently turned "Français" into "fr" in the switcher, because
+ * the common foundation idiom is `locale.label || locale.code`.
+ *
+ * Kit re-exports this so `@uniweb/kit`'s `LOCALE_DISPLAY_NAMES` keeps working.
+ */
+export const LOCALE_DISPLAY_NAMES = {
+  en: 'English',
+  es: 'Español',
+  fr: 'Français',
+  de: 'Deutsch',
+  it: 'Italiano',
+  pt: 'Português',
+  nl: 'Nederlands',
+  pl: 'Polski',
+  ru: 'Русский',
+  ja: '日本語',
+  ko: '한국어',
+  zh: '中文',
+  'zh-CN': '简体中文',
+  'zh-TW': '繁體中文',
+  ar: 'العربية',
+  he: 'עברית',
+  hi: 'हिन्दी',
+  th: 'ไทย',
+  vi: 'Tiếng Việt',
+  tr: 'Türkçe',
+  uk: 'Українська',
+  cs: 'Čeština',
+  el: 'Ελληνικά',
+  hu: 'Magyar',
+  ro: 'Română',
+  sv: 'Svenska',
+  da: 'Dansk',
+  fi: 'Suomi',
+  no: 'Norsk',
+  id: 'Bahasa Indonesia',
+  ms: 'Bahasa Melayu'
+}
+
+/**
+ * Resolve a locale's display label.
+ *
+ * Priority: an explicitly configured `label` -> the display-name table -> the
+ * code uppercased. Accepts either a bare code string or a `{ code, label? }`
+ * object, so callers do not have to branch on which form the config used.
+ *
+ * @param {string|{code: string, label?: string}} entry
+ * @returns {string} Display label, or '' when the entry carries no code.
+ */
+export function localeLabel(entry) {
+  if (typeof entry === 'string') {
+    return LOCALE_DISPLAY_NAMES[entry] || entry.toUpperCase()
+  }
+  if (!entry || typeof entry.code !== 'string' || !entry.code) return ''
+  return entry.label || LOCALE_DISPLAY_NAMES[entry.code] || entry.code.toUpperCase()
+}
+
 export function isWildcardLanguages(value) {
   return value === '*' || (Array.isArray(value) && value.includes('*'))
 }

package/src/tracker.js

@@ -414,15 +414,64 @@ export default class Tracker {
    * Report a page view. Framework-owned: it carries the acquisition context and
    * dedupes consecutive reports of the same path.
    *
+   * ⭐ **`first_of_load` marks the one view that opened this document**, and it
+   * is computed here rather than living in `acquisition` — precisely because
+   * everything in `acquisition` is *replayed* onto every view, and this must
+   * not be. Exactly one emission per `Tracker` can carry it: `currentPath` is
+   * `null` only before the first report and is never reset.
+   *
+   * ⛔ **Why it exists at all, since a consumer holding the events can derive
+   * it from `visit`.** Not every consumer holds the events. A counter store
+   * that keeps no per-event rows cannot ask *"was this the first `page_view`
+   * with this `visit`?"* without remembering which `visit` values it has seen —
+   * which is retaining `visit`, arrived at by the back door. This bit makes the
+   * document-scoped question answerable with **no collector state at all**, and
+   * a store that deliberately retains nothing is a supported consumer, not an
+   * unusual one.
+   *
+   * ⛔ **The name carries the unit on purpose.** Bare `first` reads as *the
+   * visitor's first ever view*, which is a claim this file refuses to make and
+   * could not make — nothing here survives the document. The unit is **one
+   * document load**, so a panel built on it counts loads, never people and
+   * never sessions. *(`lane-chain.md` §4a: when a misread name is paid by
+   * another lane, put the constraint in the name.)*
+   *
+   * ⛔ **IT MUST NEVER SHIP IN A RELEASE THAT LACKS `continues`, and that is a
+   * standing contract rather than an accident of ordering.** A consumer uses
+   * its *presence* as proof that this emitter is new enough to have sent
+   * `continues` had the referrer been same-origin — which is what lets an
+   * entry-page metric drop the "runtime too old to say" case entirely instead
+   * of caveating it. Backport `first_of_load` to a line without `continues`
+   * and every such consumer starts counting continuations as arrivals, with
+   * nothing anywhere reporting an error. *(The dependency is one-way:
+   * `continues` without `first_of_load` is fine and shipped that way.)*
+   *
+   * ⚖️ **It states a FACT, not a metric** — the same discipline as `continues`.
+   * Whether a first-of-load view is an "entry page" also depends on
+   * `continues`, and that combination is the consumer's to make; a field named
+   * `entry` would age badly the moment a second metric wanted this bit.
+   *
    * @param {string} path
    */
   trackPageView(path) {
     if (!this.arms('page_view') || !path) return
     if (path === this.currentPath) return
+    const firstOfLoad = this.currentPath === null
     this.currentPath = path
     // Promptly, rather than waiting out the batch window: a page view is the
     // event most likely to be the only one of a short visit.
-    this.enqueue({ event: 'page_view', path, ...(this.acquisition || {}) }, true)
+    //
+    // Emitted only when true, like `continues` — absent is the negative, and it
+    // keeps every later view the size it already was.
+    this.enqueue(
+      {
+        event: 'page_view',
+        path,
+        ...(this.acquisition || {}),
+        ...(firstOfLoad ? { first_of_load: true } : {})
+      },
+      true
+    )
   }
 
   /**

package/src/website.js

@@ -10,7 +10,7 @@ import EntityStore from './entity-store.js'
 import FetcherDispatcher from './fetcher-dispatcher.js'
 import ObservableState from './observable-state.js'
 import { normalizeSeo } from './seo.js'
-import { resolveDefaultLocale } from './locale-config.js'
+import { resolveDefaultLocale, localeLabel } from './locale-config.js'
 import { matchDynamicRoute, decodeRouteValue } from './route-match.js'
 
 /**
@@ -226,8 +226,12 @@ export default class Website {
   /**
    * Build locales list from config
    * Supports both string codes and objects: ['es', 'fr'] or [{code: 'es', label: 'Español'}]
-   * Labels are passed through if provided; otherwise only code is returned.
-   * Use kit's getLocaleLabel() for display names.
+   * Every returned locale carries a resolved `label`: an explicitly configured
+   * one wins, otherwise it comes from LOCALE_DISPLAY_NAMES, otherwise the code
+   * uppercased. It used to be passed through only when configured, which made
+   * the common foundation idiom `locale.label || locale.code` render "fr"
+   * instead of "Français" for a plain-string `languages:` entry — i.e. the form
+   * locale-config tells authors to migrate to was the one that read worse.
    * @private
    */
   buildLocalesList(config) {
@@ -262,6 +266,7 @@ export default class Website {
     // Build final array with isDefault flag
     return Array.from(localeMap.values()).map(locale => ({
       ...locale,
+      label: localeLabel(locale),
       isDefault: locale.code === defaultLocale
     }))
   }
@@ -857,9 +862,16 @@ export default class Website {
   // ─────────────────────────────────────────────────────────────────
 
   /**
-   * Get all available locales
-   * Label is optional - use kit's getLocaleLabel() for display names if not provided.
-   * @returns {Array<{code: string, label?: string, isDefault: boolean}>}
+   * Get all available locales.
+   *
+   * `label` is always present and always displayable: an explicitly configured
+   * label wins, otherwise it is resolved from LOCALE_DISPLAY_NAMES, otherwise it
+   * is the code uppercased. So `locale.label` needs no fallback at the call site
+   * — the idiom `locale.label || locale.code` is now redundant rather than
+   * load-bearing, and kit's `getLocaleLabel()` is only needed for a code that
+   * did not come from here.
+   *
+   * @returns {Array<{code: string, label: string, isDefault: boolean}>}
    */
   getLocales() {
     return this.locales