@lionrapid/core 0.5.0 → 0.6.1

package/dist/browser/lionrapid.auto.dev.js

@@ -1,5 +1,5 @@
 "use strict";
-var LionRapid = (() => {
+var __lionrapidAutoExports = (() => {
   var __defProp = Object.defineProperty;
   var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
   var __getOwnPropNames = Object.getOwnPropertyNames;
@@ -336,6 +336,49 @@ var LionRapid = (() => {
     packageEmoji: "\u{1F981}"
   });
 
+  // src/utils/locale.ts
+  var LOCALE_TAG_REGEX = /^[a-z]{2,3}(?:-[a-z0-9]{2,4})*$/i;
+  var RTL_LANGUAGES = /* @__PURE__ */ new Set(["ar", "fa", "he", "ur", "yi"]);
+  function primarySubtag(tag) {
+    return tag.split("-")[0].toLowerCase();
+  }
+  function normalizeLocale(tag) {
+    const trimmed = tag.trim();
+    if (!trimmed) return trimmed;
+    const [lang, ...rest] = trimmed.split("-");
+    const out = [lang.toLowerCase()];
+    for (const sub of rest) {
+      if (sub.length === 4) {
+        out.push(sub[0].toUpperCase() + sub.slice(1).toLowerCase());
+      } else if (sub.length === 2) {
+        out.push(sub.toUpperCase());
+      } else {
+        out.push(sub.toLowerCase());
+      }
+    }
+    return out.join("-");
+  }
+  function matchLocale(requested, available, fallback) {
+    if (available.length === 0) return fallback;
+    const avail = available.map((raw) => ({
+      raw,
+      lower: normalizeLocale(raw).toLowerCase()
+    }));
+    for (const req of requested) {
+      if (!req) continue;
+      const reqLower = normalizeLocale(req).toLowerCase();
+      const exact = avail.find((a) => a.lower === reqLower);
+      if (exact) return exact.raw;
+      const primary = primarySubtag(req);
+      const byPrimary = avail.find((a) => a.lower === primary);
+      if (byPrimary) return byPrimary.raw;
+    }
+    return fallback;
+  }
+  function localeDir(tag) {
+    return RTL_LANGUAGES.has(primarySubtag(tag)) ? "rtl" : "ltr";
+  }
+
   // src/base/event-emitter.ts
   var EventEmitter = class {
     constructor() {
@@ -624,7 +667,7 @@ var LionRapid = (() => {
         complete: () => {
           this.emit("language:change:success", {
             context: this.createContext(requestId, [...baseTrace, "complete"]),
-            payload: { oldLocale, newLocale }
+            payload: { oldLocale, newLocale, dir: localeDir(newLocale) }
           });
         },
         error: (error) => {
@@ -1034,12 +1077,11 @@ var LionRapid = (() => {
   }
 
   // src/utils/context-utils.ts
-  function createTranslationContext(parsedKey, currentLocale, defaultNamespace, fallbackLocale) {
+  function createTranslationContext(parsedKey, currentLocale, defaultNamespace) {
     const effectiveNamespace = parsedKey.hasExplicitNamespace ? parsedKey.namespace : defaultNamespace;
     return {
       locale: currentLocale,
-      namespace: effectiveNamespace,
-      fallbackLocale: fallbackLocale || currentLocale
+      namespace: effectiveNamespace
     };
   }
 
@@ -1156,7 +1198,7 @@ var LionRapid = (() => {
   }
 
   // src/utils/translation-flow.ts
-  function prepareTranslationRequest(key, currentLocale, defaultValueOrParams, paramsOrDefaultValue, defaultNamespace, fallbackLocale) {
+  function prepareTranslationRequest(key, currentLocale, defaultValueOrParams, paramsOrDefaultValue, defaultNamespace) {
     const startTime = performance.now();
     const { defaultValue, params } = parseTranslationParams(
       defaultValueOrParams,
@@ -1166,8 +1208,7 @@ var LionRapid = (() => {
     const context = createTranslationContext(
       parsedKey,
       currentLocale,
-      defaultNamespace,
-      fallbackLocale
+      defaultNamespace
     );
     const individualCacheKey = createIndividualCacheKey(
       context.locale,
@@ -1189,7 +1230,6 @@ var LionRapid = (() => {
       locale: currentLocale,
       namespace: context.namespace,
       // ✅ Use effective namespace (explicit or default)
-      fallbackLocale,
       individualCacheKey,
       // ✅ Ready-to-use cache key
       namespaceCacheKey,
@@ -2299,6 +2339,157 @@ var LionRapid = (() => {
     }
   };
 
+  // src/content/sanitizer/HTMLSanitizer.ts
+  var SAFE_TAGS = /* @__PURE__ */ new Set([
+    "a",
+    "abbr",
+    "b",
+    "bdi",
+    "bdo",
+    "br",
+    "cite",
+    "code",
+    "del",
+    "dfn",
+    "em",
+    "i",
+    "img",
+    "ins",
+    "kbd",
+    "mark",
+    "q",
+    "s",
+    "samp",
+    "small",
+    "span",
+    "strong",
+    "sub",
+    "sup",
+    "time",
+    "u",
+    "var",
+    "wbr"
+  ]);
+  var SAFE_ATTRS = /* @__PURE__ */ new Set([
+    "alt",
+    "cite",
+    "class",
+    "datetime",
+    "dir",
+    "height",
+    "href",
+    "id",
+    "lang",
+    "loading",
+    "rel",
+    "role",
+    "src",
+    "target",
+    "title",
+    "width"
+  ]);
+  var URL_ATTRS = /* @__PURE__ */ new Set(["href", "src", "cite"]);
+  var SAFE_STYLE_PROPS = /* @__PURE__ */ new Set([
+    "color",
+    "background-color",
+    "font-family",
+    "font-size",
+    "font-style",
+    "font-weight",
+    "letter-spacing",
+    "line-height",
+    "text-decoration",
+    "text-decoration-color",
+    "text-decoration-line",
+    "text-decoration-style",
+    "text-transform",
+    "vertical-align",
+    "white-space",
+    "word-spacing"
+  ]);
+  var DANGEROUS_CSS_VALUE = /url\s*\(|expression\s*\(|image-set\s*\(|element\s*\(|paint\s*\(|javascript:|\\|[<>{}@]/i;
+  var SAFE_SCHEMES = /* @__PURE__ */ new Set(["http", "https", "mailto", "tel"]);
+  var NAMED_ENTITIES = {
+    amp: "&",
+    lt: "<",
+    gt: ">",
+    quot: '"',
+    apos: "'",
+    nbsp: "\xA0",
+    colon: ":",
+    semi: ";",
+    sol: "/",
+    bsol: "\\",
+    Tab: "	",
+    NewLine: "\n"
+  };
+  function decodeEntities2(value) {
+    return value.replace(
+      /&(?:#[xX]([0-9a-fA-F]+);?|#(\d+);?|([a-zA-Z]+);)/g,
+      (full, hex, dec, name) => {
+        if (hex) return String.fromCodePoint(parseInt(hex, 16));
+        if (dec) return String.fromCodePoint(parseInt(dec, 10));
+        return NAMED_ENTITIES[name] ?? full;
+      }
+    );
+  }
+  function escapeHtml(text) {
+    return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
+  }
+  function sanitizeUrl(value) {
+    const decoded = decodeEntities2(value);
+    const probe = decoded.replace(/[\u0000-\u0020\u007f]/g, "").toLowerCase();
+    const scheme = /^([a-z][a-z0-9+.-]*):/.exec(probe);
+    if (!scheme) return value;
+    return SAFE_SCHEMES.has(scheme[1]) ? value : null;
+  }
+  function sanitizeStyle(value) {
+    return filterCssDeclarations(value, true);
+  }
+  function filterCssDeclarations(value, requirePropAllowlist) {
+    const decoded = decodeEntities2(value);
+    const kept = [];
+    for (const declaration of decoded.split(";")) {
+      const colon = declaration.indexOf(":");
+      if (colon === -1) continue;
+      const prop = declaration.slice(0, colon).trim().toLowerCase();
+      const val = declaration.slice(colon + 1).trim();
+      if (!/^[a-z-]+$/.test(prop)) continue;
+      if (requirePropAllowlist && !SAFE_STYLE_PROPS.has(prop)) continue;
+      if (val === "" || DANGEROUS_CSS_VALUE.test(val)) continue;
+      kept.push(`${prop}: ${val}`);
+    }
+    return kept.length > 0 ? kept.join("; ") : null;
+  }
+  var ATTR_PATTERN = /([^\s=/>"']+)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s>]*)))?/g;
+  function sanitizeOpeningTag(rawOpen) {
+    if (!rawOpen.startsWith("<")) return null;
+    const tagName = extractTagName(rawOpen);
+    if (!/^[a-z][a-z0-9-]*$/.test(tagName) || !SAFE_TAGS.has(tagName)) {
+      return null;
+    }
+    const end = rawOpen.endsWith("/>") ? rawOpen.length - 2 : rawOpen.endsWith(">") ? rawOpen.length - 1 : rawOpen.length;
+    const attrSource = rawOpen.slice(1 + tagName.length, end);
+    const attrs = {};
+    for (const match of attrSource.matchAll(ATTR_PATTERN)) {
+      const name = match[1].toLowerCase();
+      const value = match[2] ?? match[3] ?? match[4] ?? "";
+      if (name in attrs) continue;
+      if (name === "style") {
+        const cleanStyle = sanitizeStyle(value);
+        if (cleanStyle !== null) attrs[name] = cleanStyle;
+        continue;
+      }
+      const allowed = SAFE_ATTRS.has(name) || /^data-[a-z0-9-]*$/.test(name) || /^aria-[a-z0-9-]*$/.test(name);
+      if (!allowed) continue;
+      if (URL_ATTRS.has(name)) {
+        if (sanitizeUrl(value) === null) continue;
+      }
+      attrs[name] = value;
+    }
+    return serializeOpeningTag(tagName, attrs);
+  }
+
   // src/content/serializer/HTMLSerializer.ts
   var HTMLSerializer = class {
     serialize(unit) {
@@ -2308,24 +2499,25 @@ var LionRapid = (() => {
       let lastIndex = 0;
       let match;
       while ((match = tagPattern.exec(text)) !== null) {
-        result += text.slice(lastIndex, match.index);
+        result += escapeHtml(text.slice(lastIndex, match.index));
         const [fullMatch, closingSlash, indexStr] = match;
         const styleList = styles[indexStr] ?? [];
         const rawOpen = readRawStyle(styleList);
-        if (rawOpen) {
+        const safeOpen = rawOpen === null ? null : sanitizeOpeningTag(rawOpen);
+        if (rawOpen && safeOpen !== null) {
           const tagName = extractTagName(rawOpen);
           const isVoid = VOID_TAGS.has(tagName);
           if (closingSlash) {
             if (!isVoid) result += `</${tagName}>`;
           } else {
-            result += rawOpen;
+            result += safeOpen;
           }
         } else {
           result += fullMatch;
         }
         lastIndex = match.index + fullMatch.length;
       }
-      result += text.slice(lastIndex);
+      result += escapeHtml(text.slice(lastIndex));
       return result;
     }
   };
@@ -2564,10 +2756,9 @@ var LionRapid = (() => {
   var INDEXED_TAG_REGEX = /<\/?[0-9]+\/?>/;
   var HTML_TAG_REGEX = /<[a-z][a-z0-9]*(?:\s+[^>]*)?\/?>/i;
   var LionRapidCore = class {
-    constructor(eventEmitter, handlerChain, defaultLocale = "en", fallbackLocale = "en", defaultNamespace) {
+    constructor(eventEmitter, handlerChain, defaultLocale = "en", defaultNamespace) {
       __publicField(this, "handlerChain");
       __publicField(this, "currentLocale");
-      __publicField(this, "fallbackLocale");
       __publicField(this, "defaultNamespace");
       __publicField(this, "pendingTranslations", /* @__PURE__ */ new Map());
       __publicField(this, "bus");
@@ -2575,6 +2766,7 @@ var LionRapid = (() => {
       // 🔥 EMBEDDED: Core integration maps
       __publicField(this, "formatters", /* @__PURE__ */ new Map());
       __publicField(this, "processors", /* @__PURE__ */ new Map());
+      __publicField(this, "warnedNoInterpolate", false);
       // 📡 EVENT-DRIVEN: Just track for cleanup
       __publicField(this, "eventPlugins", /* @__PURE__ */ new Set());
       // 📦 CONTENT: Parser and serializer for ContentUnit processing
@@ -2585,7 +2777,6 @@ var LionRapid = (() => {
       this.bus = eventEmitter;
       this.handlerChain = handlerChain;
       this.currentLocale = defaultLocale;
-      this.fallbackLocale = fallbackLocale;
       this.defaultNamespace = defaultNamespace;
       this.cache = new CacheManager(
         this.handlerChain,
@@ -2650,8 +2841,7 @@ var LionRapid = (() => {
         this.currentLocale,
         firstArg,
         secondArg,
-        this.defaultNamespace,
-        this.fallbackLocale
+        this.defaultNamespace
       );
       logger.debug(`Translation requested: ${request.cleanKey}`);
       const translateBus = this.bus.translation(request);
@@ -2701,8 +2891,7 @@ var LionRapid = (() => {
         this.currentLocale,
         firstArg,
         secondArg,
-        this.defaultNamespace,
-        this.fallbackLocale
+        this.defaultNamespace
       );
       logger.debug(`HTML translation requested: ${request.cleanKey}`);
       const translateBus = this.bus.translation(request);
@@ -2870,6 +3059,11 @@ var LionRapid = (() => {
             resolvedLocale,
             resolvedKey
           );
+        } else if (!this.warnedNoInterpolate && params && Object.keys(params).length > 0 && processedValue.includes("{")) {
+          this.warnedNoInterpolate = true;
+          console.warn(
+            "[LionRapid] Translation params were passed but no interpolate formatter is registered \u2014 {placeholders} render literally. Install @lionrapid/formatters and add .use(coreFormattersPlugin) to the builder."
+          );
         }
         if (this.processors.size > 0) {
           for (const [name, processor] of this.processors.entries()) {
@@ -2910,8 +3104,7 @@ var LionRapid = (() => {
         this.currentLocale,
         params,
         defaultValue,
-        this.defaultNamespace,
-        this.fallbackLocale
+        this.defaultNamespace
       );
       const syncResult = this.handlerChain.handleSync(request);
       const rawValue = syncResult && syncResult.status === 200 ? syncResult.value : request.parsedDefaultValue || request.cleanKey;
@@ -3032,8 +3225,7 @@ var LionRapid = (() => {
         this.currentLocale,
         void 0,
         void 0,
-        this.defaultNamespace,
-        this.fallbackLocale
+        this.defaultNamespace
       );
       return this.handlerChain.isCached(request);
     }
@@ -3454,6 +3646,9 @@ var LionRapid = (() => {
   };
 
   // src/builder.ts
+  function isLoudPreloadFailure(error) {
+    return !(error instanceof TranslationNotFoundError || error instanceof TranslationLockedError);
+  }
   var LionRapidBuilder = class _LionRapidBuilder {
     constructor(config) {
       __publicField(this, "config");
@@ -3464,7 +3659,6 @@ var LionRapid = (() => {
       __publicField(this, "syncQueue", null);
       this.config = {
         defaultLocale: config.defaultLocale || "en",
-        fallbackLocale: config.fallbackLocale || "en",
         namespace: config.namespace || "app"
       };
     }
@@ -3565,7 +3759,6 @@ var LionRapid = (() => {
         eventEmitter,
         handlerChain,
         this.config.defaultLocale,
-        this.config.fallbackLocale,
         this.config.namespace
       );
       for (const plugin of this.plugins) {
@@ -3596,7 +3789,17 @@ var LionRapid = (() => {
       logger.debug("Preload targets", {
         namespaces: eagerPreloads.map((c) => `${c.locale}:${c.namespace}`)
       });
+      let warnedLoudly = false;
+      const warnLoudlyOnce = (namespaceKey, error) => {
+        if (!isLoudPreloadFailure(error) || warnedLoudly) return;
+        warnedLoudly = true;
+        console.warn(
+          `[LionRapid] Could not load translations for ${namespaceKey} \u2014 the page stays untranslated until the server is reachable.`,
+          error
+        );
+      };
       const promises = eagerPreloads.map(async (preloadConfig) => {
+        const namespaceKey = `${preloadConfig.locale}:${preloadConfig.namespace}`;
         try {
           const result = await networkHandler.loadNamespace(
             preloadConfig.locale,
@@ -3605,19 +3808,19 @@ var LionRapid = (() => {
           if (result && result.data && result.status === 200) {
             const context = {
               locale: preloadConfig.locale,
-              namespace: preloadConfig.namespace,
-              fallbackLocale: this.config.fallbackLocale
+              namespace: preloadConfig.namespace
             };
             await handlerChain.saveNamespaceToHandlers(result.data, context);
-            logger.debug(
-              `Preloaded: ${preloadConfig.locale}:${preloadConfig.namespace}`
-            );
+            logger.debug(`Preloaded: ${namespaceKey}`);
+            return;
+          }
+          if (result?.error) {
+            warnLoudlyOnce(namespaceKey, result.error);
+            logger.warn(`Preload failed: ${namespaceKey}`, result.error);
           }
         } catch (error) {
-          logger.warn(
-            `Preload failed: ${preloadConfig.locale}:${preloadConfig.namespace}`,
-            error
-          );
+          warnLoudlyOnce(namespaceKey, error);
+          logger.warn(`Preload failed: ${namespaceKey}`, error);
         }
       });
       await Promise.allSettled(promises);
@@ -3631,8 +3834,16 @@ var LionRapid = (() => {
       __publicField(this, "name", "NetworkRepository");
       __publicField(this, "type", "network");
       __publicField(this, "config", {});
-      /** Cached version (opaque string from server) per namespace key "locale:namespace" */
-      __publicField(this, "namespaceVersions", /* @__PURE__ */ new Map());
+      /**
+       * Namespace snapshot per key "locale:namespace": the server version TOGETHER
+       * with the payload it describes, persisted as ONE localStorage entry.
+       *
+       * Canonical 304 contract (same as edge KV bundle + WP transient cache):
+       * never claim freshness you can't back. If-None-Match is only sent when the
+       * snapshot is in hand; a 304 answers with that snapshot's payload; version
+       * and payload can never desync because they live and die together.
+       */
+      __publicField(this, "namespaceSnapshots", /* @__PURE__ */ new Map());
       /**
        * Default endpoint templates with placeholder support
        * Placeholders: :key, :locale, :namespace
@@ -3745,36 +3956,50 @@ var LionRapid = (() => {
         logger.debug("API base URL is not set");
         throw new NetworkError("API base URL is not set");
       }
+      try {
+        return await this.fetchNamespaceRaw(locale, namespace);
+      } catch (error) {
+        this.handleCaughtError(error);
+      }
+    }
+    /**
+     * Shared namespace fetch with the canonical 304 contract:
+     * - If-None-Match is sent ONLY when a snapshot (version + payload) is in hand.
+     * - 304 answers with that snapshot's payload — never with "nothing".
+     * - A 304 with no snapshot (server/proxy surprise) refetches unconditionally.
+     * - A 200 stores version + payload atomically before either is trusted.
+     */
+    async fetchNamespaceRaw(locale, namespace, allowConditional = true) {
       const url = this.buildUrl("getNamespace", { locale, namespace });
       logger.debug(`API GET Namespace: ${url}`);
       const namespaceKey = `${locale}:${namespace}`;
-      try {
-        const extraHeaders = {};
-        const cachedVersion = this.getVersion(namespaceKey);
-        if (cachedVersion) {
-          extraHeaders["If-None-Match"] = `W/"${cachedVersion}"`;
-        }
-        const response = await this.makeRequest(url, "GET", void 0, extraHeaders);
-        if (response.status === 304) {
-          logger.debug(`Namespace ${namespaceKey}: 304 Not Modified`);
-          return null;
-        }
-        if (!response.ok) {
-          this.handleHttpError(response, namespaceKey);
-        }
-        const data = await response.json();
-        logger.debug("API response data:", data);
-        if (!data.translations) {
-          throw new TranslationNotFoundError(namespaceKey);
-        }
-        const version = data.meta?.version != null ? String(data.meta.version) : null;
-        if (version) {
-          this.setVersion(namespaceKey, version);
+      const snapshot = allowConditional ? this.getSnapshot(namespaceKey) : void 0;
+      const extraHeaders = {};
+      if (snapshot) {
+        extraHeaders["If-None-Match"] = `W/"${snapshot.version}"`;
+      }
+      const response = await this.makeRequest(url, "GET", void 0, extraHeaders);
+      if (response.status === 304) {
+        if (snapshot) {
+          logger.debug(`Namespace ${namespaceKey}: 304 Not Modified (snapshot served)`);
+          return snapshot.translations;
         }
-        return data.translations;
-      } catch (error) {
-        this.handleCaughtError(error);
+        logger.debug(`Namespace ${namespaceKey}: unexpected 304 with no snapshot \u2014 refetching`);
+        return this.fetchNamespaceRaw(locale, namespace, false);
+      }
+      if (!response.ok) {
+        this.handleHttpError(response, namespaceKey);
+      }
+      const data = await response.json();
+      logger.debug("API response data:", data);
+      if (!data.translations) {
+        throw new TranslationNotFoundError(namespaceKey);
+      }
+      const version = data.meta?.version != null ? String(data.meta.version) : null;
+      if (version) {
+        this.setSnapshot(namespaceKey, { version, translations: data.translations });
       }
+      return data.translations;
     }
     /**
      * Save translation to API (if supported)
@@ -3859,33 +4084,8 @@ var LionRapid = (() => {
         logger.debug("API base URL is not set");
         throw new NetworkError("API base URL is not set");
       }
-      const url = this.buildUrl("getNamespace", { locale, namespace });
-      logger.debug(`API GET Namespace ContentUnits: ${url}`);
-      const namespaceKey = `${locale}:${namespace}`;
       try {
-        const extraHeaders = {};
-        const cachedVersion = this.getVersion(namespaceKey);
-        if (cachedVersion) {
-          extraHeaders["If-None-Match"] = `W/"${cachedVersion}"`;
-        }
-        const response = await this.makeRequest(url, "GET", void 0, extraHeaders);
-        if (response.status === 304) {
-          logger.debug(`Namespace ContentUnits ${namespaceKey}: 304 Not Modified`);
-          return null;
-        }
-        if (!response.ok) {
-          this.handleHttpError(response, namespaceKey);
-        }
-        const data = await response.json();
-        logger.debug("API response data:", data);
-        if (!data.translations) {
-          throw new TranslationNotFoundError(namespaceKey);
-        }
-        const version = data.meta?.version != null ? String(data.meta.version) : null;
-        if (version) {
-          this.setVersion(namespaceKey, version);
-        }
-        return data.translations;
+        return await this.fetchNamespaceRaw(locale, namespace);
       } catch (error) {
         this.handleCaughtError(error);
       }
@@ -3995,25 +4195,37 @@ var LionRapid = (() => {
     getConfig() {
       return this.config;
     }
-    /** Read persisted version from localStorage, falling back to in-memory map */
-    getVersion(namespaceKey) {
-      const mem = this.namespaceVersions.get(namespaceKey);
+    /** Read a persisted snapshot (version + payload), falling back to memory.
+     *  Legacy bare-version entries and corrupt snapshots are deleted on sight —
+     *  a version without its payload must never drive a conditional request. */
+    getSnapshot(namespaceKey) {
+      const mem = this.namespaceSnapshots.get(namespaceKey);
       if (mem) return mem;
       try {
-        const stored = localStorage.getItem(_NetworkRepository.VERSION_PREFIX + namespaceKey);
-        if (stored) {
-          this.namespaceVersions.set(namespaceKey, stored);
-          return stored;
+        localStorage.removeItem(_NetworkRepository.LEGACY_VERSION_PREFIX + namespaceKey);
+        const raw = localStorage.getItem(_NetworkRepository.SNAPSHOT_PREFIX + namespaceKey);
+        if (raw) {
+          const parsed = JSON.parse(raw);
+          if (parsed && typeof parsed.version === "string" && parsed.version.length > 0 && parsed.translations && typeof parsed.translations === "object") {
+            this.namespaceSnapshots.set(namespaceKey, parsed);
+            return parsed;
+          }
+          localStorage.removeItem(_NetworkRepository.SNAPSHOT_PREFIX + namespaceKey);
         }
       } catch {
       }
       return void 0;
     }
-    /** Persist version to both in-memory map and localStorage */
-    setVersion(namespaceKey, version) {
-      this.namespaceVersions.set(namespaceKey, version);
+    /** Persist version + payload as ONE entry (memory + localStorage). On quota
+     *  failure the previous stored snapshot stays — still a consistent pair. */
+    setSnapshot(namespaceKey, snapshot) {
+      this.namespaceSnapshots.set(namespaceKey, snapshot);
       try {
-        localStorage.setItem(_NetworkRepository.VERSION_PREFIX + namespaceKey, version);
+        localStorage.setItem(
+          _NetworkRepository.SNAPSHOT_PREFIX + namespaceKey,
+          JSON.stringify(snapshot)
+        );
+        localStorage.removeItem(_NetworkRepository.LEGACY_VERSION_PREFIX + namespaceKey);
       } catch {
       }
     }
@@ -4102,8 +4314,11 @@ var LionRapid = (() => {
       }
     }
   };
-  /** localStorage key prefix for persisted versions */
-  __publicField(_NetworkRepository, "VERSION_PREFIX", "lionrapid:v:");
+  /** localStorage key prefix for persisted snapshots (version + payload) */
+  __publicField(_NetworkRepository, "SNAPSHOT_PREFIX", "lionrapid:ns:");
+  /** Legacy bare-version prefix — a version WITHOUT its payload is exactly the
+   *  desync the snapshot store exists to prevent; entries are deleted on sight. */
+  __publicField(_NetworkRepository, "LEGACY_VERSION_PREFIX", "lionrapid:v:");
   var NetworkRepository = _NetworkRepository;
 
   // src/browser/exclude-filter.ts
@@ -4496,7 +4711,7 @@ var LionRapid = (() => {
     isInsideSkipTag(element) {
       let current = element.parentElement;
       while (current) {
-        if (SKIP_TAGS.has(current.tagName)) {
+        if (SKIP_TAGS.has(current.tagName.toUpperCase())) {
           return true;
         }
         current = current.parentElement;
@@ -4610,7 +4825,7 @@ var LionRapid = (() => {
     isInsideSkipTag(element) {
       let current = element.parentElement;
       while (current) {
-        if (SKIP_TAGS2.has(current.tagName)) return true;
+        if (SKIP_TAGS2.has(current.tagName.toUpperCase())) return true;
         current = current.parentElement;
       }
       return false;
@@ -5723,6 +5938,50 @@ var LionRapid = (() => {
   };
 
   // src/browser/auto-init.ts
+  function resolveWritePolicy(apiKey) {
+    const isPublishable = apiKey.startsWith("pk_");
+    return {
+      syncMissing: { enabled: isPublishable },
+      warnReadOnly: !isPublishable
+    };
+  }
+  function configForWindow(config) {
+    return { ...config, apiKey: "" };
+  }
+  function createDeferredLocaleHandler(effects) {
+    let applyLocale = null;
+    let pendingLocale = null;
+    return {
+      onChange: async (locale) => {
+        effects.setCookie(locale);
+        if (effects.navigate) {
+          effects.navigate(locale);
+          return;
+        }
+        if (applyLocale) {
+          await applyLocale(locale);
+          return;
+        }
+        pendingLocale = locale;
+      },
+      attach: (apply) => {
+        applyLocale = apply;
+        if (pendingLocale !== null) {
+          const replay = pendingLocale;
+          pendingLocale = null;
+          void apply(replay).catch(() => {
+          });
+        }
+      }
+    };
+  }
+  function onDomReady(fn) {
+    if (document.readyState === "loading") {
+      document.addEventListener("DOMContentLoaded", fn, { once: true });
+    } else {
+      fn();
+    }
+  }
   function parseConfig(script) {
     const apiKey = script.dataset.apiKey || "";
     const baseUrl = script.dataset.baseUrl || "https://api.lionrapid.com";
@@ -5759,50 +6018,86 @@ var LionRapid = (() => {
   }
   function readLocaleCookie(availableLanguages) {
     if (typeof document === "undefined") return null;
-    const match = document.cookie.match(/lionrapid_locale=([a-z]{2})/);
+    const match = document.cookie.match(
+      /(?:^|;\s*)lionrapid_locale=([a-z]{2,3}(?:-[a-z0-9]{2,4})*)/i
+    );
     if (!match) return null;
-    return availableLanguages.includes(match[1]) ? match[1] : null;
+    return matchLocale([match[1]], availableLanguages, "") || null;
   }
   function detectBrowserLanguage(availableLanguages, defaultLocale) {
     if (typeof navigator === "undefined") return defaultLocale;
-    const browserLang = navigator.language || navigator.userLanguage || "";
-    const primaryLang = browserLang.split("-")[0].toLowerCase();
-    if (availableLanguages.includes(primaryLang)) {
-      return primaryLang;
-    }
-    return defaultLocale;
+    const requested = navigator.languages && navigator.languages.length > 0 ? [...navigator.languages] : [
+      navigator.language || navigator.userLanguage || ""
+    ];
+    return matchLocale(requested, availableLanguages, defaultLocale);
   }
-  function navigateToLocale(locale, defaultLocale) {
-    const path = window.location.pathname.replace(/^\/([a-z]{2})(\/|$)/, "/");
+  function buildLocaleUrl(pathname, search, locale, defaultLocale, availableLanguages) {
+    const segments = pathname.split("/");
+    const first = segments[1] ?? "";
+    const hasLocalePrefix = LOCALE_TAG_REGEX.test(first) && matchLocale([first], availableLanguages, "") !== "";
+    const path = hasLocalePrefix ? "/" + segments.slice(2).join("/") : pathname;
     const prefix = locale === defaultLocale ? "" : "/" + locale;
-    window.location.href = prefix + (path || "/") + window.location.search;
+    return prefix + (path || "/") + search;
   }
-  async function autoInit() {
+  function navigateToLocale(locale, defaultLocale, availableLanguages) {
+    window.location.href = buildLocaleUrl(
+      window.location.pathname,
+      window.location.search,
+      locale,
+      defaultLocale,
+      availableLanguages
+    );
+  }
+  function resolveInitialLocale(config) {
+    if (config.mode === "dynamic-only") {
+      const htmlLang = typeof document !== "undefined" ? document.documentElement.lang : "";
+      return htmlLang ? normalizeLocale(htmlLang) : config.defaultLocale;
+    }
+    const cookieLocale = readLocaleCookie(config.languages);
+    if (cookieLocale) return cookieLocale;
+    if (config.autoDetect) {
+      return detectBrowserLanguage(config.languages, config.defaultLocale);
+    }
+    return config.defaultLocale;
+  }
+  function applyLocaleDir(locale) {
+    if (typeof document !== "undefined") {
+      document.documentElement.dir = localeDir(locale);
+    }
+  }
+  function findConfigScript() {
+    const current = document.currentScript;
+    if (current instanceof HTMLScriptElement && current.dataset.apiKey) {
+      return current;
+    }
     const scripts = document.querySelectorAll("script[data-api-key]");
-    const script = scripts[scripts.length - 1];
+    if (scripts.length > 1) {
+      console.warn(
+        `[LionRapid] ${scripts.length} script tags with data-api-key found; using the last one`
+      );
+    }
+    return scripts[scripts.length - 1];
+  }
+  async function autoInit() {
+    const script = findConfigScript();
     if (!script) {
       console.warn("[LionRapid] No script tag with data-api-key found");
       return;
     }
     const config = parseConfig(script);
-    window.__lionrapidConfig = config;
+    window.__lionrapidConfig = configForWindow(config);
     if (!config.apiKey) {
       console.warn("[LionRapid] Missing data-api-key attribute");
       return;
     }
-    let initialLocale = config.defaultLocale;
-    if (config.mode === "dynamic-only") {
-      const htmlLang = document.documentElement.lang?.split("-")[0]?.toLowerCase();
-      initialLocale = htmlLang || config.defaultLocale;
-    } else {
-      const cookieLocale = readLocaleCookie(config.languages);
-      if (cookieLocale) {
-        initialLocale = cookieLocale;
-      } else if (config.autoDetect) {
-        initialLocale = detectBrowserLanguage(config.languages, config.defaultLocale);
-      }
+    const writePolicy = resolveWritePolicy(config.apiKey);
+    if (writePolicy.warnReadOnly) {
+      console.error(
+        "[LionRapid] data-api-key must be a publishable pk_ key; running read-only"
+      );
     }
-    const syncMode = config.apiKey.startsWith("pk_") ? "report-only" : "sync";
+    const initialLocale = resolveInitialLocale(config);
+    applyLocaleDir(initialLocale);
     const languageSwitcher = new LanguageSwitcher();
     languageSwitcher.setLanguages(config.languages);
     languageSwitcher.setInitialLocale(initialLocale);
@@ -5828,11 +6123,14 @@ var LionRapid = (() => {
       }
       languageSwitcher.initAll();
     };
-    if (document.readyState === "loading") {
-      document.addEventListener("DOMContentLoaded", renderSwitcher);
-    } else {
-      renderSwitcher();
-    }
+    onDomReady(renderSwitcher);
+    const localeHandler = createDeferredLocaleHandler({
+      setCookie: (locale) => {
+        document.cookie = `lionrapid_locale=${locale}; path=/; max-age=31536000; SameSite=Lax`;
+      },
+      navigate: config.mode === "dynamic-only" ? (locale) => navigateToLocale(locale, config.defaultLocale, config.languages) : null
+    });
+    languageSwitcher.setOnLanguageChange(localeHandler.onChange);
     try {
       const builder = LionRapidBuilder.init({
         defaultLocale: initialLocale,
@@ -5855,11 +6153,9 @@ var LionRapid = (() => {
           options: {
             baseUrl: config.baseUrl,
             apiKey: config.apiKey,
-            syncMissing: {
-              enabled: syncMode === "sync",
-              debounceMs: 500,
-              batchSize: 50
-            },
+            // pk_ keys sync missing source strings (discovery); anything else
+            // runs read-only — see resolveWritePolicy.
+            syncMissing: writePolicy.syncMissing,
             preloadNamespaces: [
               {
                 locale: initialLocale,
@@ -5880,15 +6176,11 @@ var LionRapid = (() => {
         sourceLocale: config.defaultLocale
       });
       languageSwitcher.setCore(core);
-      languageSwitcher.setOnLanguageChange(async (locale) => {
-        document.cookie = `lionrapid_locale=${locale}; path=/; max-age=31536000; SameSite=Lax`;
-        if (config.mode === "dynamic-only") {
-          navigateToLocale(locale, config.defaultLocale);
-          return;
-        }
+      localeHandler.attach(async (locale) => {
         await core.changeLanguage(locale, {
           preloadNamespaces: [config.namespace]
         });
+        applyLocaleDir(locale);
         autoTranslator.updateLocale(locale);
         autoTranslator.retranslate();
       });
@@ -5935,6 +6227,7 @@ var LionRapid = (() => {
           await core.changeLanguage(locale, {
             preloadNamespaces: [config.namespace]
           });
+          applyLocaleDir(locale);
           autoTranslator.updateLocale(locale);
           autoTranslator.retranslate();
           languageSwitcher.initAll();
@@ -5957,10 +6250,12 @@ var LionRapid = (() => {
         editorScript.async = true;
         document.body.appendChild(editorScript);
       }
-      if (config.mode !== "dynamic-only") {
-        autoTranslator.translatePage();
-      }
-      autoTranslator.observe();
+      onDomReady(() => {
+        if (config.mode !== "dynamic-only") {
+          autoTranslator.translatePage();
+        }
+        autoTranslator.observe();
+      });
     } catch (error) {
       console.error("[LionRapid] Initialization failed:", error);
     }