langsys-js-typescript 0.1.0 → 0.2.1

package/dist/index.mjs

@@ -1,3 +1,5 @@
+import { IntlMessageFormat } from 'intl-messageformat';
+
 // src/signal.ts
 function createSignal(initial) {
   let value = initial;
@@ -67,7 +69,11 @@ var LangsysAppAPIClass = class {
     };
     this.headers = {
       "Content-Type": "application/json; charset=utf-8",
-      "x-Authorization": this.config.key
+      "x-Authorization": this.config.key,
+      // Declare ICU MessageFormat rendering so the server sends raw ICU
+      // (plural/select) instead of flat-template downgrades. Pre-ICU
+      // builds omit this header and keep receiving flat strings.
+      "X-Langsys-Capabilities": "icu"
     };
   }
   setup(config2) {
@@ -85,7 +91,18 @@ var LangsysAppAPIClass = class {
     return await this.get("authorize-project/[projectid]");
   }
   async getTranslations(locale) {
-    return await this.get("projects/[projectid]/translations", { locale });
+    return await this.get("translations", { project_id: this.config.projectid, locale });
+  }
+  /**
+   * Register phrases and/or content blocks via the current unified endpoint.
+   * Each item carries `type: 'phrase' | 'content_block'`. Replaces the
+   * deprecated `projects/{id}/tokens` and `projects/{id}/content-blocks` routes.
+   */
+  async createTranslatableItems(items) {
+    return await this.post("translatable-items", {
+      project_id: this.config.projectid,
+      translatable_items: items
+    });
   }
   async post(path, data = {}) {
     return await this.send("POST", path, data);
@@ -209,7 +226,6 @@ var initialTranslations = {
 };
 var sTranslations = persist("translations", initialTranslations);
 var currentlyLoadedLocale = createSignal("");
-var contentBlocks = createSignal([]);
 var config = {
   projectid: "",
   key: "",
@@ -218,10 +234,22 @@ var config = {
   debug: false,
   key_type: "read"
 };
-
-// src/interpolate.ts
-function interpolate(template, params) {
-  return template.replace(/\{([^{}]+)\}/g, (match, rawKey) => {
+function isICU(template) {
+  return ICU_PATTERN.test(template);
+}
+var ICU_PATTERN = /\{[^{}]+,\s*(plural|select|selectordinal|number|date|time)\s*,/;
+function interpolate(template, params, locale) {
+  if (isICU(template)) {
+    try {
+      return new IntlMessageFormat(template, locale ?? "en").format(params);
+    } catch {
+      return simpleInterpolate(template, params);
+    }
+  }
+  return simpleInterpolate(template, params);
+}
+function simpleInterpolate(template, params) {
+  return template.replace(/\{([^{},]+)\}/g, (match, rawKey) => {
     const key = rawKey.trim();
     if (!(key in params)) return match;
     const value = params[key];
@@ -245,6 +273,11 @@ var Translations = class {
     this.timer = null;
     this.flushScheduled = false;
     this.isFirstClientRun = true;
+    this.readyResolve = () => {
+    };
+    this.readyPromise = new Promise((resolve) => {
+      this.readyResolve = resolve;
+    });
     this.config = config2;
     this.debug = new Logger(!!config2.debug);
     this.locale = config2.baseLocale || "";
@@ -253,6 +286,16 @@ var Translations = class {
     currentlyLoadedLocale.subscribe(() => this.tSignal.set(this.buildTFn()));
     if (config2.key && config2.projectid) this.setup(config2);
   }
+  /**
+   * Resolves once the first `getTranslations` call has completed (or
+   * immediately if no fetch is configured). Callers that need to read
+   * `sTranslations` before issuing a write — e.g. the `Translate` DOM
+   * class deciding whether to POST a content block — should await this
+   * to avoid acting on an empty cache during the cold-start race.
+   */
+  ready() {
+    return this.readyPromise;
+  }
   /** Current translation function. Reads fresh state on every call. */
   get t() {
     return this.tSignal.get();
@@ -275,8 +318,22 @@ var Translations = class {
     const value = contentData[token];
     return typeof value === "string" ? value : null;
   }
+  /**
+   * Raw stored translation for a phrase, without interpolation or
+   * missing-token registration. Returns null when no (non-empty) translation
+   * is cached. Used by the `Phrase` rich-text handler, which needs the
+   * un-interpolated template (it supplies its own markup-token values).
+   */
+  lookup(phrase, category) {
+    const cats = sTranslations.get();
+    const lookupCat = category || "__uncategorized__";
+    const value = cats[lookupCat]?.[phrase];
+    return typeof value === "string" && value.length > 0 ? value : null;
+  }
   buildTFn() {
-    return (category, phrase, ...args) => {
+    const fn = ((phrase, ...rest) => {
+      const category = typeof rest[0] === "string" ? rest[0] : "";
+      const params = typeof rest[0] === "object" ? rest[0] : rest[1];
       const cats = sTranslations.get();
       const lookupCat = category || "__uncategorized__";
       const value = cats[lookupCat]?.[phrase];
@@ -285,12 +342,12 @@ var Translations = class {
         this.debug.log("TRANSLATION FOUND", [lookupCat, phrase, value]);
         translated = value;
       } else {
-        this.missingToken(lookupCat, phrase);
+        this.missingToken(category, phrase);
         translated = phrase;
       }
-      const params = args[0];
-      return params ? interpolate(translated, params) : translated;
-    };
+      return params ? interpolate(translated, params, currentlyLoadedLocale.get()) : translated;
+    });
+    return fn;
   }
   missingToken(category, token) {
     if (token === void 0 || token === null) {
@@ -418,11 +475,12 @@ var Translations = class {
     const currentData = sTranslations.get();
     this.missingTokens = this.missingTokens.filter((tokenObj) => {
       tokenObj.projectid = this.config.projectid;
-      if (tokenObj.category in currentData && tokenObj.token in currentData[tokenObj.category]) {
+      const lookupCat = tokenObj.category || "__uncategorized__";
+      if (lookupCat in currentData && tokenObj.token in currentData[lookupCat]) {
         this.debug.log("Missing token already exists! Skipping:", {
           category: tokenObj.category,
           token: tokenObj.token,
-          existing: currentData[tokenObj.category][tokenObj.token]
+          existing: currentData[lookupCat][tokenObj.token]
         });
         return false;
       }
@@ -431,25 +489,34 @@ var Translations = class {
     if (!this.missingTokens.length) return false;
     this.debug.log("CREATE MISSING TOKENS", this.missingTokens);
     try {
-      const response = await LangsysAppAPI.post("projects/[projectid]/tokens", {
-        tokens: this.missingTokens
-      });
-      if (!response.status) {
-        if (response.errors) {
-          this.debug.log("TOKEN UPDATE FAIL", this.missingTokens);
-          this.debug.error("Error updating project tokens", response.errors);
+      const phraseItems = this.missingTokens.map((tokenObj) => ({
+        type: "phrase",
+        phrase: tokenObj.token,
+        category: tokenObj.category || null
+      }));
+      const BATCH_SIZE = 200;
+      for (let offset = 0; offset < phraseItems.length; offset += BATCH_SIZE) {
+        const response = await LangsysAppAPI.createTranslatableItems(
+          phraseItems.slice(offset, offset + BATCH_SIZE)
+        );
+        if (!response.status) {
+          if (response.errors) {
+            this.debug.log("TOKEN UPDATE FAIL", this.missingTokens);
+            this.debug.error("Error updating project tokens", response.errors);
+          }
+          return false;
         }
-        return false;
       }
       this.missingTokens.forEach((tokenObj) => {
-        if (!currentData[tokenObj.category]) {
-          currentData[tokenObj.category] = {
-            __category__: tokenObj.category,
-            __symbol__: tokenObj.category
+        const lookupCat = tokenObj.category || "__uncategorized__";
+        if (!currentData[lookupCat]) {
+          currentData[lookupCat] = {
+            __category__: lookupCat,
+            __symbol__: lookupCat
           };
         }
-        currentData[tokenObj.category][tokenObj.token] = tokenObj.token;
-        currentData[tokenObj.category]["__category__"] = tokenObj.category;
+        currentData[lookupCat][tokenObj.token] = tokenObj.token;
+        currentData[lookupCat]["__category__"] = lookupCat;
       });
       sTranslations.set({ ...currentData });
       this.missingTokens = [];
@@ -468,6 +535,7 @@ var Translations = class {
     this.debug.log("GET TRANSLATIONS API RESPONSE", response);
     if (response.errors) {
       this.debug.error("Error", response.errors[0]);
+      this.readyResolve();
       return;
     }
     const trans = response.data;
@@ -484,6 +552,7 @@ var Translations = class {
     sTranslations.set(trans);
     setTimeout(() => currentlyLoadedLocale.set(this.locale), 100);
     this.lastLoaded[this.locale] = (/* @__PURE__ */ new Date()).getTime() / 1e3;
+    this.readyResolve();
   }
 };
 
@@ -513,7 +582,8 @@ var LangsysAppClass = class {
   }
   /**
    * Initialize Langsys. Configuration must include at least `projectid`,
-   * `key`, and `UserLocaleStore` (any Signal<string>).
+   * `key`, and `UserLocaleStore` (anything satisfying `LocaleSource` — see
+   * its docstring for framework-specific adapters).
    */
   async init(initConfig) {
     const projectid = initConfig.projectid;
@@ -542,9 +612,9 @@ var LangsysAppClass = class {
       this.debug.error("LangsysApp.init missing API key in configuration object!");
       return { status: false, errors: ["Missing API key"] };
     }
-    if (!UserLocaleStore?.subscribe) {
+    if (!UserLocaleStore?.subscribe || typeof UserLocaleStore.get !== "function") {
       this.debug.error(
-        "LangsysApp.init missing UserLocaleStore \u2014 pass a Signal<string> (createSignal('en-us') works if you have nothing of your own)."
+        "LangsysApp.init missing UserLocaleStore \u2014 pass any object satisfying LocaleSource (get + subscribe). createSignal('en-us') works if you have nothing of your own."
       );
       return { status: false, errors: ["Missing UserLocaleStore"] };
     }
@@ -908,7 +978,7 @@ function md5(inputString) {
   return rh(a) + rh(b) + rh(c) + rh(d);
 }
 
-// src/translate.ts
+// src/content-block.ts
 var TRANSLATABLE_ATTRIBUTES = [
   "placeholder",
   "alt",
@@ -973,9 +1043,147 @@ var SEMANTIC_STYLE_PROPERTIES = [
   "list-style-type",
   "cursor"
 ];
+function generateCustomId(category, tokens) {
+  return md5(JSON.stringify([category, tokens]));
+}
+function isContentBlockKnown(category, customId) {
+  const cats = sTranslations.get();
+  const lookupCat = category || "__uncategorized__";
+  const cbData = cats[lookupCat]?.[customId];
+  return typeof cbData === "object" && cbData !== null;
+}
+async function registerContentBlock(contentBlock) {
+  if (config.key_type !== "write") {
+    if (config.debug) {
+      logger.log(`Skipping content block save (API key is ${config.key_type || "unknown"})`);
+    }
+    return { status: true };
+  }
+  try {
+    const response = await LangsysAppAPI.createTranslatableItems([
+      {
+        type: "content_block",
+        custom_id: contentBlock.custom_id,
+        category: contentBlock.category,
+        content: contentBlock.content,
+        label: contentBlock.label,
+        phrases: contentBlock.tokens.map((phrase) => ({ phrase }))
+      }
+    ]);
+    if (!response.status) {
+      logger.error("Could not save content block", response.errors);
+      return { status: false, errors: response.errors };
+    }
+    _writeKnownContentBlockToCache(contentBlock.category, contentBlock.custom_id);
+    return { status: true };
+  } catch (err) {
+    logger.error("Could not save content block", err);
+    return { status: false, errors: [err] };
+  }
+}
+function tokenizeElement(element) {
+  const tokens = [];
+  const clone = element.cloneNode(true);
+  _walkForTokens(element, Array.from(clone.childNodes), tokens, []);
+  return { tokens, content: clone.outerHTML };
+}
+function _writeKnownContentBlockToCache(category, customId) {
+  const lookupCat = category || "__uncategorized__";
+  sTranslations.update((current) => {
+    if (!current[lookupCat]) {
+      current[lookupCat] = {
+        __category__: lookupCat,
+        __symbol__: lookupCat
+      };
+    }
+    current[lookupCat][customId] = {};
+    return { ...current };
+  });
+}
+function _walkForTokens(liveRoot, cloneNodes, tokens, indices) {
+  cloneNodes.forEach((node, index) => {
+    if (node.nodeType === Node.ELEMENT_NODE) {
+      const el = node;
+      if (el.getAttribute("translate") === "no") return;
+      if (el.hasAttribute("data-ls-phrase")) return;
+    }
+    if (node.hasChildNodes()) {
+      _applyStylesToClone(liveRoot, node, [...indices, index]);
+    }
+    if (node.nodeType === Node.ELEMENT_NODE) {
+      _tokenizeAttributes(node, tokens);
+    }
+    const contentToken = node.nodeValue?.replace(/\s+/g, " ").trim();
+    if (node.nodeType === Node.TEXT_NODE && contentToken) {
+      tokens.push(contentToken);
+      return;
+    }
+    if (!node.hasChildNodes()) return;
+    _walkForTokens(liveRoot, Array.from(node.childNodes), tokens, [...indices, index]);
+  });
+}
+function _tokenizeAttributes(element, tokens) {
+  const tagName = element.tagName.toLowerCase();
+  if (tagName === "img") {
+    const img = element;
+    if (img.src) element.setAttribute("src", img.src);
+  }
+  for (const attr of TRANSLATABLE_ATTRIBUTES) {
+    const value = element.getAttribute(attr)?.trim();
+    if (value) tokens.push(value);
+  }
+  if (VALUE_TRANSLATABLE_ELEMENTS.includes(tagName)) {
+    const value = element.getAttribute("value")?.trim();
+    if (value) tokens.push(value);
+  }
+  if (tagName === "input") {
+    const inputType = element.getAttribute("type")?.toLowerCase();
+    if (inputType && VALUE_TRANSLATABLE_INPUT_TYPES.includes(inputType)) {
+      const value = element.getAttribute("value")?.trim();
+      if (value) tokens.push(value);
+    }
+  }
+  if (tagName === "select") {
+    const options = element.querySelectorAll("option");
+    options.forEach((option) => {
+      const optionText = option.textContent?.trim();
+      if (optionText) tokens.push(optionText);
+    });
+  }
+}
+function _applyStylesToClone(liveRoot, cloneNode, indices) {
+  if (typeof window === "undefined") return;
+  const domNode = _findNode(Array.from(liveRoot.childNodes), indices);
+  if (!domNode) return;
+  const tagName = domNode.tagName.toLowerCase();
+  const reference = document.createElement(tagName);
+  reference.style.visibility = "hidden";
+  reference.style.position = "absolute";
+  document.body.appendChild(reference);
+  const computed = window.getComputedStyle(domNode);
+  const defaults = window.getComputedStyle(reference);
+  for (const prop of SEMANTIC_STYLE_PROPERTIES) {
+    const value = computed.getPropertyValue(prop);
+    const defaultValue = defaults.getPropertyValue(prop);
+    if (value && value !== defaultValue) {
+      cloneNode.style.setProperty(prop, value);
+    }
+  }
+  document.body.removeChild(reference);
+  cloneNode.removeAttribute("class");
+}
+function _findNode(nodes, indices) {
+  let currentNode = nodes[indices[0]];
+  for (let i = 1; i < indices.length; i++) {
+    if (!currentNode || !currentNode.hasChildNodes()) return void 0;
+    currentNode = Array.from(currentNode.childNodes)[indices[i]];
+  }
+  return currentNode;
+}
+
+// src/translate.ts
 var Translate = class {
   constructor(element, options = {}) {
-    this.contentClone = null;
     this.tokens = [];
     this.parseComplete = false;
     this.isTokenizing = false;
@@ -1001,7 +1209,7 @@ var Translate = class {
     if (this.lastTranslatedLocale === currentLocale) return;
     const { category = "" } = this.options;
     if (this.tokens.length === 1) {
-      this.element.innerText = LangsysApp.Translations.t(category, this.tokens[0]);
+      this.element.innerText = LangsysApp.Translations.t(this.tokens[0], category);
     } else {
       this.translate(Array.from(this.element.childNodes));
       this.lastTranslatedLocale = currentLocale;
@@ -1015,18 +1223,17 @@ var Translate = class {
       return false;
     }
     this.isTokenizing = true;
-    this.contentClone = this.element.cloneNode(true);
-    const nodes = Array.from(this.contentClone.childNodes || []);
-    this.tokenize(nodes);
+    const { tokens, content } = tokenizeElement(this.element);
+    this.tokens = tokens;
     const { category = "" } = this.options;
     if (this.tokens.length === 1) {
-      this.element.innerText = LangsysApp.Translations.t(category, this.tokens[0]);
+      this.element.innerText = LangsysApp.Translations.t(this.tokens[0], category);
     } else {
       const contentBlock = {
         custom_id: "",
         category,
         label: this.options.label,
-        content: this.contentClone.outerHTML,
+        content,
         tokens: this.tokens
       };
       await this.handleContentBlock(contentBlock);
@@ -1036,85 +1243,23 @@ var Translate = class {
     return true;
   }
   async handleContentBlock(contentBlock) {
-    if (isEmpty(this.custom_id)) this.custom_id = this.generateCustomId(contentBlock);
+    if (isEmpty(this.custom_id)) {
+      this.custom_id = generateCustomId(contentBlock.category, contentBlock.tokens);
+    }
     contentBlock.custom_id = this.custom_id;
-    const current = contentBlocks.get();
-    const existing = current.find((b) => b.custom_id === this.custom_id);
-    if (!existing) {
-      if (config.key_type === "write") {
-        LangsysAppAPI.post("projects/[projectid]/content-blocks", contentBlock).then((response) => {
-          if (!response.status) {
-            logger.error("Could not save content block", response.errors);
-          } else {
-            contentBlocks.update((blocks) => [...blocks, contentBlock]);
-          }
-        }).catch((err) => logger.error("Could not save content block", err));
-      } else if (config.debug) {
-        logger.log(`Skipping content block save (API key is ${config.key_type || "unknown"})`);
-      }
+    await LangsysApp.Translations.ready();
+    if (isContentBlockKnown(contentBlock.category, this.custom_id)) {
       if (this.tokens.length > 1 && this.element) {
         this.translate(Array.from(this.element.childNodes));
         this.lastTranslatedLocale = currentlyLoadedLocale.get();
       }
+      return;
     }
-  }
-  tokenize(nodes, indices = []) {
-    nodes.forEach((node, index) => {
-      if (node?.nodeType === Node.ELEMENT_NODE) {
-        const element = node;
-        if (element.getAttribute("translate") === "no") return;
-      }
-      if (node?.hasChildNodes()) {
-        this.applyStylesToNode(node, [...indices, index]);
-      }
-      if (node?.nodeType === Node.ELEMENT_NODE) {
-        this.tokenizeAttributes(node);
-      }
-      const contentToken = node.nodeValue?.replace(/\s+/g, " ").trim();
-      if (node?.nodeType === Node.TEXT_NODE && contentToken) {
-        this.tokens.push(contentToken);
-        return;
-      }
-      if (!node?.hasChildNodes()) return;
-      this.tokenize(Array.from(node.childNodes), [...indices, index]);
-    });
-  }
-  tokenizeAttributes(element) {
-    const tagName = element.tagName.toLowerCase();
-    if (tagName === "img") {
-      const img = element;
-      if (img.src) element.setAttribute("src", img.src);
-    }
-    for (const attr of TRANSLATABLE_ATTRIBUTES) {
-      const value = element.getAttribute(attr)?.trim();
-      if (value) this.tokens.push(value);
-    }
-    if (VALUE_TRANSLATABLE_ELEMENTS.includes(tagName)) {
-      const value = element.getAttribute("value")?.trim();
-      if (value) this.tokens.push(value);
-    }
-    if (tagName === "input") {
-      const inputType = element.getAttribute("type")?.toLowerCase();
-      if (inputType && VALUE_TRANSLATABLE_INPUT_TYPES.includes(inputType)) {
-        const value = element.getAttribute("value")?.trim();
-        if (value) this.tokens.push(value);
-      }
-    }
-    if (tagName === "select") {
-      const options = element.querySelectorAll("option");
-      options.forEach((option) => {
-        const optionText = option.textContent?.trim();
-        if (optionText) this.tokens.push(optionText);
-      });
-    }
-  }
-  findNode(nodes, indices) {
-    let currentNode = nodes[indices[0]];
-    for (let i = 1; i < indices.length; i++) {
-      if (!currentNode || !currentNode.hasChildNodes()) return void 0;
-      currentNode = Array.from(currentNode.childNodes)[indices[i]];
+    void registerContentBlock(contentBlock);
+    if (this.tokens.length > 1 && this.element) {
+      this.translate(Array.from(this.element.childNodes));
+      this.lastTranslatedLocale = currentlyLoadedLocale.get();
     }
-    return currentNode;
   }
   translate(nodes) {
     const currentLocale = currentlyLoadedLocale.get();
@@ -1125,6 +1270,7 @@ var Translate = class {
       if (node?.nodeType === Node.ELEMENT_NODE) {
         const element = node;
         if (element.getAttribute("translate") === "no") return;
+        if (element.hasAttribute("data-ls-phrase")) return;
         this.translateAttributes(node);
       }
       if (node?.nodeType !== Node.TEXT_NODE) {
@@ -1194,38 +1340,136 @@ var Translate = class {
     if (translation) element.setAttribute(attr, translation);
     else element.setAttribute(attr, element.originalAttributes[attr]);
   }
-  generateCustomId(contentBlock) {
-    return md5(`${contentBlock.category}-${contentBlock.tokens.join("-")}`);
-  }
-  applyStylesToNode(node, indices) {
-    if (!this.element || typeof window === "undefined") return;
-    const domNode = this.findNode(Array.from(this.element.childNodes), indices);
-    if (!domNode) return;
-    const tagName = domNode.tagName.toLowerCase();
-    const reference = document.createElement(tagName);
-    reference.style.visibility = "hidden";
-    reference.style.position = "absolute";
-    document.body.appendChild(reference);
-    const computed = window.getComputedStyle(domNode);
-    const defaults = window.getComputedStyle(reference);
-    for (const prop of SEMANTIC_STYLE_PROPERTIES) {
-      const value = computed.getPropertyValue(prop);
-      const defaultValue = defaults.getPropertyValue(prop);
-      if (value && value !== defaultValue) {
-        node.style.setProperty(prop, value);
+};
+
+// src/richtext.ts
+var SENT_OPEN_START = String.fromCharCode(57344);
+var SENT_OPEN_END = String.fromCharCode(57345);
+var SENT_CLOSE_START = String.fromCharCode(57346);
+var SENT_CLOSE_END = String.fromCharCode(57347);
+var SENT_SCAN = /\uE000(\d+)\uE001|\uE002(\d+)\uE003/g;
+function encodeRichText(root) {
+  const slots = [];
+  const phrase = _encodeNodes(Array.from(root.childNodes), slots);
+  return { phrase: phrase.replace(/\s+/g, " ").trim(), slots };
+}
+function _encodeNodes(nodes, slots) {
+  let out = "";
+  for (const node of nodes) {
+    if (node.nodeType === Node.TEXT_NODE) {
+      out += node.nodeValue ?? "";
+      continue;
+    }
+    if (node.nodeType !== Node.ELEMENT_NODE) continue;
+    const element = node;
+    const index = slots.length;
+    slots.push({ template: element.cloneNode(false) });
+    out += `{m${index}o}` + _encodeNodes(Array.from(element.childNodes), slots) + `{m${index}c}`;
+  }
+  return out;
+}
+function markupTokenValues(slotCount) {
+  const values = {};
+  for (let i = 0; i < slotCount; i++) {
+    values[`m${i}o`] = `${SENT_OPEN_START}${i}${SENT_OPEN_END}`;
+    values[`m${i}c`] = `${SENT_CLOSE_START}${i}${SENT_CLOSE_END}`;
+  }
+  return values;
+}
+function reconstitute(resolved, slots, doc = document) {
+  const root = doc.createDocumentFragment();
+  const stack = [root];
+  const top = () => stack[stack.length - 1];
+  let lastIndex = 0;
+  let match;
+  SENT_SCAN.lastIndex = 0;
+  try {
+    while ((match = SENT_SCAN.exec(resolved)) !== null) {
+      const text = resolved.slice(lastIndex, match.index);
+      if (text) top().appendChild(doc.createTextNode(text));
+      lastIndex = SENT_SCAN.lastIndex;
+      const isOpen = match[1] !== void 0;
+      const slotIndex = Number(isOpen ? match[1] : match[2]);
+      if (isOpen) {
+        const slot = slots[slotIndex];
+        if (!slot) throw new Error("unknown markup slot");
+        const el = slot.template.cloneNode(false);
+        top().appendChild(el);
+        stack.push(el);
+      } else {
+        if (stack.length <= 1) throw new Error("unbalanced close");
+        stack.pop();
       }
     }
-    document.body.removeChild(reference);
-    node.removeAttribute("class");
+    const tail = resolved.slice(lastIndex);
+    if (tail) top().appendChild(doc.createTextNode(tail));
+    if (stack.length !== 1) throw new Error("unbalanced open");
+  } catch {
+    return [doc.createTextNode(stripSentinels(resolved))];
+  }
+  return Array.from(root.childNodes);
+}
+function stripSentinels(value) {
+  return value.replace(SENT_SCAN, "");
+}
+
+// src/phrase.ts
+var PHRASE_MARKER_ATTR = "data-ls-phrase";
+var Phrase = class {
+  constructor(host, options = {}) {
+    this.phrase = "";
+    this.slots = [];
+    this.unsubscribers = [];
+    this.ready = false;
+    this.host = host;
+    this.category = options.category ?? "";
+    this.params = options.params ?? {};
+    void this._init();
+    const rerender = () => {
+      if (this.ready) this._render();
+    };
+    this.unsubscribers.push(currentlyLoadedLocale.subscribe(rerender));
+    this.unsubscribers.push(sTranslations.subscribe(rerender));
+  }
+  /** Update interpolation params (e.g. a changed count) and re-render. */
+  setParams(params) {
+    this.params = params ?? {};
+    if (this.ready) this._render();
+  }
+  /** Stop reacting to locale/translation changes. Safe to call multiple times. */
+  destroy() {
+    this.unsubscribers.forEach((unsub) => unsub());
+    this.unsubscribers = [];
+  }
+  async _init() {
+    if (!this.host || !this.host.childNodes.length) {
+      this.ready = true;
+      return;
+    }
+    const { phrase, slots } = encodeRichText(this.host);
+    this.phrase = phrase;
+    this.slots = slots;
+    await LangsysApp.Translations.ready();
+    LangsysApp.Translations.t(this.phrase, this.category);
+    this.ready = true;
+    this._render();
+  }
+  _render() {
+    if (!this.phrase) return;
+    const raw = LangsysApp.Translations.lookup(this.phrase, this.category) ?? this.phrase;
+    const params = { ...this.params, ...markupTokenValues(this.slots.length) };
+    const resolved = interpolate(raw, params, currentlyLoadedLocale.get());
+    const nodes = reconstitute(resolved, this.slots, this.host.ownerDocument ?? document);
+    this.host.replaceChildren(...nodes);
   }
 };
 
 // src/index.ts
-var t = ((category, phrase, ...args) => {
-  return LangsysApp.Translations.t(category, phrase, ...args);
+var t = ((phrase, ...rest) => {
+  return LangsysApp.Translations.t(phrase, ...rest);
 });
 var tSignal = LangsysApp.Translations.tSignal;
 
-export { LangsysApp, LangsysAppAPI, Logger, Translate, Translations, contentBlocks, createSignal, currentlyLoadedLocale, getValue, interpolate, isEmpty, logger, md5, persist, sTranslations, t, tSignal };
+export { LangsysApp, LangsysAppAPI, Logger, PHRASE_MARKER_ATTR, Phrase, Translate, Translations, createSignal, currentlyLoadedLocale, encodeRichText, generateCustomId, getValue, interpolate, isContentBlockKnown, isEmpty, isICU, logger, markupTokenValues, md5, persist, reconstitute, registerContentBlock, sTranslations, stripSentinels, t, tSignal, tokenizeElement };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map