lsr-text-catalog 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tomáš Vojík
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,184 @@
+# Text Catalog for Vue and Vite
+
+`lsr-text-catalog` supplies typed Vue/gettext helpers and a Vite plugin for NEON source-copy catalogs compiled by the independently versioned [PHP package](https://packagist.org/packages/lsr/text-catalog).
+
+## Installation
+
+Install from [npm](https://www.npmjs.com/package/lsr-text-catalog) together with its Vue/gettext peers:
+
+```sh
+npm install lsr-text-catalog vue vue3-gettext
+```
+
+For Vite integration, also install the host build tools:
+
+```sh
+npm install --save-dev vite @vitejs/plugin-vue typescript
+```
+
+Use the PHP compiler to generate or update catalog artifacts:
+
+```sh
+composer require lsr/text-catalog:^0.1.2
+```
+
+PHP compiler `0.1.2` introduces the unscoped TypeScript imports. Regenerate existing frontend artifacts when upgrading; do not hand-edit generated import paths.
+
+Prebuilt frontend catalogs do not require PHP at runtime. Applications supply their own HTML sanitizer; no sanitizer package is installed automatically.
+
+## Requirements and exports
+
+Node `^20.19.0 || >=22.12.0`; ESM only. Host peers: Vue `^3.5.42` and vue3-gettext `^4.0.1`. `/vite` additionally needs Vite `^8.2.2` (an optional peer so prebuilt runtime consumers do not need Vite).
+
+| Export | Responsibility |
+| --- | --- |
+| `lsr-text-catalog/runtime` | `createRuntimeCatalog`: typed dynamic source lookup, contextual/plural translation and guarded HTML rendering. |
+| `lsr-text-catalog/compiled` | `createCompiledCatalog`: lookup-free contextual/plural/HTML adapters for transformed calls. |
+| `lsr-text-catalog/types` | Reusable catalog, translation, interpolation and instance types. Consumer-specific key unions are generated locally. |
+| `lsr-text-catalog/vite` | `textCatalog`: Node-only compiler orchestration, versioned artifact validation and literal transformation. |
+
+Babel, Vue compilers, MagicString and TypeScript are direct dependencies because the shipped Node plugin executes them. Browser entry points do not import the Node plugin or its filesystem/compiler modules. PHP is needed only when the consumer's compiler callback invokes it, not to use prebuilt frontend data.
+
+For local package development, build before linking a checkout with pnpm `link:`. Consumer applications should normally install a released npm version instead of a local link.
+
+## Generate consumer-owned artifacts
+
+Configure `Lsr\TextCatalog\TextCatalogCompiler` with explicit source/language directories, source-reference root, domain, locales, source locale, cache file, and frontend directory. Run it before standalone `tsc`/`vue-tsc` checks; Vite generation cannot supply types to a command that ran earlier.
+
+The frontend directory contains `catalog.ts`, `catalog.compiled.ts`, and `catalog.build.json`. Generated files import this package's `/types` export, not application aliases. Keep these files in the consumer's normal TypeScript resolution graph.
+
+## Runtime facade
+
+Create a real consumer module such as `src/copy.ts`:
+
+```ts
+import * as generated from '../generated/catalog.js';
+import { createRuntimeCatalog } from 'lsr-text-catalog/runtime';
+import { sanitizeCopyHtml } from './sanitizeCopyHtml.js';
+
+export const {
+  text, langText, langTextPlural, langHtmlText, createCatalog, installCatalog,
+} = createRuntimeCatalog({ ...generated, sanitizeHtml: sanitizeCopyHtml });
+export type { TextKey, HtmlTextKey } from '../generated/catalog.js';
+```
+
+`sanitizeCopyHtml` is an application implementation, not a package export. Omit `sanitizeHtml` for plain-text-only consumers; HTML calls then throw rather than return raw markup.
+
+Create and install a new instance for **each Vue app and SSR request**:
+
+```ts
+import { createSSRApp } from 'vue';
+import App from './App.vue';
+import { createCatalog, installCatalog } from './copy.js';
+
+const app = createSSRApp(App);
+const copy = createCatalog({ locale: 'cs_CZ' });
+installCatalog(app, copy);
+```
+
+Use the same initial locale and sanitizer output policy during SSR and hydration. The instance exposes `gettext`; changing `copy.gettext.current` updates that instance. Each instance owns cloned nested translation/plural data. Consumer facades have distinct Vue injection keys. Helpers select the current app at invocation time; outside an injection context they use a private, fixed source-language fallback. For ordinary non-Vue code needing a selected locale, call the explicit instance's helpers instead of relying on ambient state.
+
+```vue
+<script setup lang="ts">
+import { computed, ref } from 'vue';
+import { langText, langTextPlural, langHtmlText } from './copy.js';
+
+const count = ref(3);
+const label = computed(() => langText('example.title', { name: 'Ada' }));
+</script>
+
+<template>
+  <h1>{{ label }}</h1>
+  <p>{{ langTextPlural('example.count.one', 'example.count.plural', count, { count }) }}</p>
+  <div v-html="langHtmlText('example.rich', { name: 'Ada' })" />
+</template>
+```
+
+`text(key)` returns canonical source text without translating/interpolating. Runtime mode accepts typed dynamic keys. Plural helpers require sibling `.one`/`.plural` entries and use their parent as gettext context. Plain text uses ordinary escaped Vue rendering. `langHtmlText` validates HTML membership at runtime, translates/interpolates, and then sanitizes. A generated `HtmlTextKey` union is available to type stricter application wrappers.
+
+## Vite configuration
+
+```ts
+import { execFileSync } from 'node:child_process';
+import vue from '@vitejs/plugin-vue';
+import { defineConfig } from 'vite';
+import { textCatalog } from 'lsr-text-catalog/vite';
+
+export default defineConfig({
+  plugins: [
+    textCatalog({
+      mode: 'runtime', // default; 'compiled' is explicit opt-in
+      sourceDirectory: 'copy',
+      languageDirectory: 'languages',
+      frontendDirectory: 'generated',
+      facade: 'src/copy.ts',
+      compiledFacade: 'src/copy.compiled.ts',
+      domain: 'example',
+      sourceLocale: 'en_US',
+      locales: ['en_US', 'cs_CZ'],
+      compile(root) {
+        execFileSync('php', ['compile.php'], { cwd: root, stdio: 'inherit' });
+      },
+    }),
+    vue(),
+  ],
+});
+```
+
+Paths are relative to the configured Vite root (or explicit `root`) unless absolute. The callback may return a promise; the consumer owns its command, environment and bootstrap. Plugin and PHP identity/output configuration must agree. No application-specific command, domain, locale, alias or environment defaults are injected.
+
+The plugin validates **artifact format 1**: identity, source/HTML/plural references, exact artifact-byte SHA-256 digests and the canonical generation digest. Missing/unknown formats, tampering and mixed generations fail before output is used. A successful compiler callback alone is not sufficient. Client, SSR and custom environments use the same validated generation, and stale in-flight generations are not published.
+
+Development watches source and editable PO inputs, updates unchanged callers and evaluated SSR, and preserves ordinary Vue HMR. Build-watch mode handles nested input creation/deletion and recovery, including cleaned generated-output directories. Compilation failure blocks reads/builds until repaired; it does not silently serve the last good generation. Generated PO/output writes do not cause perpetual watch loops.
+
+## Compiled mode
+
+Add `src/copy.compiled.ts`:
+
+```ts
+import * as generated from '../generated/catalog.compiled.js';
+import { createCompiledCatalog } from 'lsr-text-catalog/compiled';
+import { sanitizeCopyHtml } from './sanitizeCopyHtml.js';
+
+export const {
+  pgettext, npgettext, htmlPgettext, createCatalog, installCatalog,
+} = createCompiledCatalog({ ...generated, sanitizeHtml: sanitizeCopyHtml });
+```
+
+Keep authored imports pointed at `src/copy.ts`; set `mode: 'compiled'`. The plugin resolves the configured facade canonically through Vite, including aliases and symlinks, and redirects bootstrap/adapter imports to its compiled companion. It expands literal-key calls before Vue, without a runtime lookup-map fallback.
+
+Compiled mode is deliberately stricter: dynamic keys, first-class helper escapes, unsupported import/SFC/macro forms, mismatched plurals and ineligible HTML calls are errors. Unrelated lexical bindings are not rewritten. Non-key argument evaluation order, source maps, contextual translation and interpolation are preserved. Generated compiled `text` is declaration-only and must not escape the transform into JavaScript execution.
+
+Application sanitizers remain responsible for final-output safety in both modes, including SSR DOM lifetimes. This package does not import DOMPurify, jsdom or Inertia and supplies no application-specific HTML policy.
+
+## Development
+
+```sh
+pnpm install
+pnpm run build
+pnpm run typecheck
+pnpm test
+pnpm run format:check
+pnpm run format
+npm pack --dry-run --ignore-scripts --json
+```
+
+The build emits ESM and declarations into `dist`; package exports point only at these files. `prepack` rebuilds them. The npm tarball also includes `src` so JavaScript and declaration source maps resolve to the original TypeScript. Tests cover runtime/request isolation, source-map and macro boundaries, manifest validation, real Vite client/SSR/custom-environment lifecycle and native build-watch behavior with synthetic inputs. Consumer verification should additionally exercise the actual PHP compiler and browser hydration in each supported mode.
+
+During verification, Vite emitted an upstream browser-externalization warning for `fs` from `pofile 1.1.4`, a dependency of `vue3-gettext 4.0.1`. Both production modes and SSR hydration passed without browser console errors. The package's browser entries do not import its Node plugin; recheck the upstream warning when choosing release peer versions rather than suppressing it globally.
+
+## Agent skill
+
+Use the [lsr-text-catalog skill](https://github.com/Heroyt/lsr-skills/tree/master/skills/lsr-text-catalog) for generated artifacts, runtime/compiled mode selection, per-app/SSR catalog instances and application-owned sanitization.
+
+```sh
+npx skills add Heroyt/lsr-skills --skill lsr-text-catalog
+```
+
+The skill is guidance, not a runtime dependency; installing it does not install or publish either package.
+
+## License and maintenance
+
+[MIT](LICENSE), copyright (c) 2026 Tomáš Vojík. Source and issue tracking: [Heroyt/lsr-text-catalog-js](https://github.com/Heroyt/lsr-text-catalog-js). npm releases are independent of PHP/Packagist releases and artifact format versions.
+
+The manifest targets public publication on `https://registry.npmjs.org/`. Build and inspect the tarball with `npm pack` before a release; packing or creating a Git tag does not publish it. Publishing credentials and release authorization are maintainer prerequisites.

package/dist/compiled/index.d.ts

@@ -0,0 +1,12 @@
+import { type App } from "vue";
+import type { CatalogInstanceOptions, CatalogLanguageOptions, CompiledCatalog, InterpolationParameters } from "../types.js";
+export type { CatalogInstanceOptions, CatalogLanguageOptions, CompiledCatalog, } from "../types.js";
+/** Lookup-free companion facade for the compiled Vite mode. */
+export declare function createCompiledCatalog(options: CatalogLanguageOptions): {
+    pgettext: (context: string, source: string, parameters?: InterpolationParameters) => string;
+    npgettext: (context: string, singular: string, plural: string, count: number, parameters?: InterpolationParameters) => string;
+    htmlPgettext: (context: string, source: string, parameters?: InterpolationParameters) => string;
+    createCatalog: (instance?: CatalogInstanceOptions) => CompiledCatalog;
+    installCatalog: (app: App, catalog: CompiledCatalog) => void;
+};
+//# sourceMappingURL=index.d.ts.map

package/dist/compiled/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/compiled/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAA+B,KAAK,GAAG,EAAqB,MAAM,KAAK,CAAC;AAE/E,OAAO,KAAK,EACV,sBAAsB,EACtB,sBAAsB,EACtB,eAAe,EACf,uBAAuB,EACxB,MAAM,aAAa,CAAC;AAErB,YAAY,EACV,sBAAsB,EACtB,sBAAsB,EACtB,eAAe,GAChB,MAAM,aAAa,CAAC;AAErB,+DAA+D;AAC/D,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,sBAAsB;wBAmCxD,MAAM,UACP,MAAM,eACD,uBAAuB,KACnC,MAAM;yBAIE,MAAM,YACL,MAAM,UACR,MAAM,SACP,MAAM,eACA,uBAAuB,KACnC,MAAM;4BAUE,MAAM,UACP,MAAM,eACD,uBAAuB,KACnC,MAAM;+BAtDG,sBAAsB,KAC/B,eAAe;0BAsBW,GAAG,WAAW,eAAe,KAAG,IAAI;EAmClE"}

package/dist/compiled/index.js

@@ -0,0 +1,39 @@
+import { hasInjectionContext, inject } from "vue";
+import { languageFactory } from "../language.js";
+/** Lookup-free companion facade for the compiled Vite mode. */
+export function createCompiledCatalog(options) {
+    const createLanguage = languageFactory(options);
+    const sanitizeHtml = options.sanitizeHtml;
+    const key = Symbol("TextCatalog");
+    function createCatalog(instance = {}) {
+        const gettext = createLanguage(instance.locale);
+        const sanitize = instance.sanitizeHtml ?? sanitizeHtml;
+        function htmlPgettext(context, source, parameters) {
+            if (!sanitize)
+                throw new Error("Catalog HTML requires an injected sanitizeHtml function.");
+            return sanitize(gettext.$pgettext(context, source, parameters));
+        }
+        return { gettext, htmlPgettext };
+    }
+    // Private and never installed: every facade has its own fixed source-language fallback.
+    const source = createCatalog();
+    function current() {
+        return hasInjectionContext() ? inject(key, source) : source;
+    }
+    function installCatalog(app, catalog) {
+        app.provide(key, catalog);
+        app.config.globalProperties.$htmlPgettext = catalog.htmlPgettext;
+        app.use(catalog.gettext);
+    }
+    function pgettext(context, source, parameters) {
+        return current().gettext.$pgettext(context, source, parameters);
+    }
+    function npgettext(context, singular, plural, count, parameters) {
+        return current().gettext.$npgettext(context, singular, plural, count, parameters);
+    }
+    function htmlPgettext(context, source, parameters) {
+        return current().htmlPgettext(context, source, parameters);
+    }
+    return { pgettext, npgettext, htmlPgettext, createCatalog, installCatalog };
+}
+//# sourceMappingURL=index.js.map

package/dist/compiled/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/compiled/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,EAA+B,MAAM,KAAK,CAAC;AAC/E,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAcjD,+DAA+D;AAC/D,MAAM,UAAU,qBAAqB,CAAC,OAA+B;IACnE,MAAM,cAAc,GAAG,eAAe,CAAC,OAAO,CAAC,CAAC;IAChD,MAAM,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC;IAC1C,MAAM,GAAG,GAAkC,MAAM,CAAC,aAAa,CAAC,CAAC;IAEjE,SAAS,aAAa,CACpB,WAAmC,EAAE;QAErC,MAAM,OAAO,GAAG,cAAc,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;QAChD,MAAM,QAAQ,GAAG,QAAQ,CAAC,YAAY,IAAI,YAAY,CAAC;QACvD,SAAS,YAAY,CACnB,OAAe,EACf,MAAc,EACd,UAAoC;YAEpC,IAAI,CAAC,QAAQ;gBACX,MAAM,IAAI,KAAK,CACb,0DAA0D,CAC3D,CAAC;YACJ,OAAO,QAAQ,CAAC,OAAO,CAAC,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,CAAC,CAAC,CAAC;QAClE,CAAC;QACD,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,CAAC;IACnC,CAAC;IAED,wFAAwF;IACxF,MAAM,MAAM,GAAG,aAAa,EAAE,CAAC;IAC/B,SAAS,OAAO;QACd,OAAO,mBAAmB,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;IAC9D,CAAC;IACD,SAAS,cAAc,CAAC,GAAQ,EAAE,OAAwB;QACxD,GAAG,CAAC,OAAO,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;QAC1B,GAAG,CAAC,MAAM,CAAC,gBAAgB,CAAC,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC;QACjE,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IAC3B,CAAC;IACD,SAAS,QAAQ,CACf,OAAe,EACf,MAAc,EACd,UAAoC;QAEpC,OAAO,OAAO,EAAE,CAAC,OAAO,CAAC,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,CAAC,CAAC;IAClE,CAAC;IACD,SAAS,SAAS,CAChB,OAAe,EACf,QAAgB,EAChB,MAAc,EACd,KAAa,EACb,UAAoC;QAEpC,OAAO,OAAO,EAAE,CAAC,OAAO,CAAC,UAAU,CACjC,OAAO,EACP,QAAQ,EACR,MAAM,EACN,KAAK,EACL,UAAU,CACX,CAAC;IACJ,CAAC;IACD,SAAS,YAAY,CACnB,OAAe,EACf,MAAc,EACd,UAAoC;QAEpC,OAAO,OAAO,EAAE,CAAC,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,CAAC,CAAC;IAC7D,CAAC;IACD,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,YAAY,EAAE,aAAa,EAAE,cAAc,EAAE,CAAC;AAC9E,CAAC"}

package/dist/language.d.ts

@@ -0,0 +1,4 @@
+import type { CatalogLanguageOptions, Language } from "./types.js";
+/** Capture facade identity once; never borrow an application's mutable locale. */
+export declare function languageFactory(options: CatalogLanguageOptions): (locale?: string) => Language;
+//# sourceMappingURL=language.d.ts.map

package/dist/language.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"language.d.ts","sourceRoot":"","sources":["../src/language.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,sBAAsB,EACtB,QAAQ,EAET,MAAM,YAAY,CAAC;AAwBpB,kFAAkF;AAClF,wBAAgB,eAAe,CAC7B,OAAO,EAAE,sBAAsB,GAC9B,CAAC,MAAM,CAAC,EAAE,MAAM,KAAK,QAAQ,CA6B/B"}

package/dist/language.js

@@ -0,0 +1,50 @@
+import { createGettext } from "vue3-gettext";
+/** Gettext normalizes only its outer catalog; clone every mutable nested plural array. */
+function cloneTranslations(source) {
+    const translations = {};
+    for (const [locale, sourceMessages] of Object.entries(source)) {
+        const messages = { ...sourceMessages };
+        for (const [key, message] of Object.entries(messages)) {
+            if (typeof message === "string")
+                continue;
+            if (Array.isArray(message)) {
+                messages[key] = message.slice();
+                continue;
+            }
+            const contexts = { ...message };
+            for (const [context, translation] of Object.entries(contexts)) {
+                if (Array.isArray(translation))
+                    contexts[context] = translation.slice();
+            }
+            messages[key] = contexts;
+        }
+        translations[locale] = messages;
+    }
+    return translations;
+}
+/** Capture facade identity once; never borrow an application's mutable locale. */
+export function languageFactory(options) {
+    const sourceLocale = options.sourceLocale;
+    const locales = [...options.locales];
+    if (!sourceLocale ||
+        !locales.includes(sourceLocale) ||
+        new Set(locales).size !== locales.length) {
+        throw new Error("Catalog locales must be unique and include the source locale.");
+    }
+    const availableLanguages = Object.fromEntries(locales.map((locale) => [
+        locale,
+        options.languageNames?.[locale] ?? locale,
+    ]));
+    const translations = options.catalogTranslations;
+    return (locale = sourceLocale) => {
+        if (!locales.includes(locale))
+            throw new Error(`Unknown catalog locale "${locale}".`);
+        return createGettext({
+            availableLanguages: { ...availableLanguages },
+            defaultLanguage: locale,
+            sourceCodeLanguage: sourceLocale,
+            translations: cloneTranslations(translations),
+        });
+    };
+}
+//# sourceMappingURL=language.js.map

package/dist/language.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"language.js","sourceRoot":"","sources":["../src/language.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAO7C,0FAA0F;AAC1F,SAAS,iBAAiB,CAAC,MAAoB;IAC7C,MAAM,YAAY,GAAiB,EAAE,CAAC;IACtC,KAAK,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QAC9D,MAAM,QAAQ,GAAG,EAAE,GAAG,cAAc,EAAE,CAAC;QACvC,KAAK,MAAM,CAAC,GAAG,EAAE,OAAO,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC;YACtD,IAAI,OAAO,OAAO,KAAK,QAAQ;gBAAE,SAAS;YAC1C,IAAI,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;gBAC3B,QAAQ,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC,KAAK,EAAE,CAAC;gBAChC,SAAS;YACX,CAAC;YACD,MAAM,QAAQ,GAAG,EAAE,GAAG,OAAO,EAAE,CAAC;YAChC,KAAK,MAAM,CAAC,OAAO,EAAE,WAAW,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC;gBAC9D,IAAI,KAAK,CAAC,OAAO,CAAC,WAAW,CAAC;oBAAE,QAAQ,CAAC,OAAO,CAAC,GAAG,WAAW,CAAC,KAAK,EAAE,CAAC;YAC1E,CAAC;YACD,QAAQ,CAAC,GAAG,CAAC,GAAG,QAAQ,CAAC;QAC3B,CAAC;QACD,YAAY,CAAC,MAAM,CAAC,GAAG,QAAQ,CAAC;IAClC,CAAC;IACD,OAAO,YAAY,CAAC;AACtB,CAAC;AAED,kFAAkF;AAClF,MAAM,UAAU,eAAe,CAC7B,OAA+B;IAE/B,MAAM,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC;IAC1C,MAAM,OAAO,GAAG,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACrC,IACE,CAAC,YAAY;QACb,CAAC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC;QAC/B,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC,IAAI,KAAK,OAAO,CAAC,MAAM,EACxC,CAAC;QACD,MAAM,IAAI,KAAK,CACb,+DAA+D,CAChE,CAAC;IACJ,CAAC;IACD,MAAM,kBAAkB,GAAG,MAAM,CAAC,WAAW,CAC3C,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC;QACtB,MAAM;QACN,OAAO,CAAC,aAAa,EAAE,CAAC,MAAM,CAAC,IAAI,MAAM;KAC1C,CAAC,CACH,CAAC;IACF,MAAM,YAAY,GAAG,OAAO,CAAC,mBAAmB,CAAC;IACjD,OAAO,CAAC,MAAM,GAAG,YAAY,EAAE,EAAE;QAC/B,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC;YAC3B,MAAM,IAAI,KAAK,CAAC,2BAA2B,MAAM,IAAI,CAAC,CAAC;QACzD,OAAO,aAAa,CAAC;YACnB,kBAAkB,EAAE,EAAE,GAAG,kBAAkB,EAAE;YAC7C,eAAe,EAAE,MAAM;YACvB,kBAAkB,EAAE,YAAY;YAChC,YAAY,EAAE,iBAAiB,CAAC,YAAY,CAAC;SAC9C,CAAC,CAAC;IACL,CAAC,CAAC;AACJ,CAAC"}

package/dist/runtime/index.d.ts

@@ -0,0 +1,17 @@
+import { type App } from "vue";
+import type { CatalogInstanceOptions, CatalogLanguageOptions, InterpolationParameters, RuntimeCatalog } from "../types.js";
+export type { CatalogHelpers, CatalogInstanceOptions, CatalogLanguageOptions, RuntimeCatalog, } from "../types.js";
+export interface RuntimeCatalogOptions<Key extends string> extends CatalogLanguageOptions {
+    readonly catalog: Readonly<Record<Key, string>>;
+    readonly htmlTextKeys: readonly NoInfer<Key>[];
+}
+/** One consumer-local authoring facade; each createCatalog call creates independent app/request state. */
+export declare function createRuntimeCatalog<Key extends string>(options: RuntimeCatalogOptions<Key>): {
+    text: (key: Key) => string;
+    langText: (key: Key, parameters?: InterpolationParameters) => string;
+    langTextPlural: (singularKey: Extract<Key, `${string}.one`>, pluralKey: Extract<Key, `${string}.plural`>, count: number, parameters?: InterpolationParameters) => string;
+    langHtmlText: (key: Key, parameters?: InterpolationParameters) => string;
+    createCatalog: (instance?: CatalogInstanceOptions) => RuntimeCatalog<Key>;
+    installCatalog: (app: App, catalog: RuntimeCatalog<Key>) => void;
+};
+//# sourceMappingURL=index.d.ts.map

package/dist/runtime/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/runtime/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAA+B,KAAK,GAAG,EAAqB,MAAM,KAAK,CAAC;AAE/E,OAAO,KAAK,EAEV,sBAAsB,EACtB,sBAAsB,EACtB,uBAAuB,EACvB,cAAc,EACf,MAAM,aAAa,CAAC;AAErB,YAAY,EACV,cAAc,EACd,sBAAsB,EACtB,sBAAsB,EACtB,cAAc,GACf,MAAM,aAAa,CAAC;AAErB,MAAM,WAAW,qBAAqB,CACpC,GAAG,SAAS,MAAM,CAClB,SAAQ,sBAAsB;IAC9B,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC,CAAC;IAChD,QAAQ,CAAC,YAAY,EAAE,SAAS,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;CAChD;AAED,0GAA0G;AAC1G,wBAAgB,oBAAoB,CAAC,GAAG,SAAS,MAAM,EACrD,OAAO,EAAE,qBAAqB,CAAC,GAAG,CAAC;gBAQhB,GAAG,KAAG,MAAM;;;;+BAOnB,sBAAsB,KAC/B,cAAc,CAAC,GAAG,CAAC;0BAuDO,GAAG,WAAW,cAAc,CAAC,GAAG,CAAC,KAAG,IAAI;EAyBtE"}

package/dist/runtime/index.js

@@ -0,0 +1,68 @@
+import { hasInjectionContext, inject } from "vue";
+import { languageFactory } from "../language.js";
+/** One consumer-local authoring facade; each createCatalog call creates independent app/request state. */
+export function createRuntimeCatalog(options) {
+    const createLanguage = languageFactory(options);
+    const sanitizeHtml = options.sanitizeHtml;
+    const catalog = options.catalog;
+    const htmlKeys = new Set(options.htmlTextKeys);
+    const key = Symbol("TextCatalog");
+    function text(key) {
+        if (!Object.hasOwn(catalog, key))
+            throw new Error(`Unknown catalog key "${key}".`);
+        return catalog[key];
+    }
+    function createCatalog(instance = {}) {
+        const gettext = createLanguage(instance.locale);
+        const sanitize = instance.sanitizeHtml ?? sanitizeHtml;
+        function langText(key, parameters) {
+            return gettext.$pgettext(key, text(key), parameters);
+        }
+        function langTextPlural(singularKey, pluralKey, count, parameters) {
+            const context = singularKey.slice(0, -".one".length);
+            if (!singularKey.endsWith(".one") || pluralKey !== `${context}.plural`) {
+                throw new Error('Catalog plural keys must be sibling ".one" and ".plural" entries.');
+            }
+            return gettext.$npgettext(context, text(singularKey), text(pluralKey), count, parameters);
+        }
+        function langHtmlText(key, parameters) {
+            if (!htmlKeys.has(key))
+                throw new Error(`Catalog key "${key}" is not declared as HTML.`);
+            if (!sanitize)
+                throw new Error("Catalog HTML requires an injected sanitizeHtml function.");
+            return sanitize(langText(key, parameters));
+        }
+        return { gettext, langText, langTextPlural, langHtmlText };
+    }
+    // Do not expose or install the source translator: its locale must remain fixed.
+    const { langText: sourceText, langTextPlural: sourcePlural, langHtmlText: sourceHtml, } = createCatalog();
+    const source = Object.freeze({
+        langText: sourceText,
+        langTextPlural: sourcePlural,
+        langHtmlText: sourceHtml,
+    });
+    function current() {
+        return hasInjectionContext() ? inject(key, source) : source;
+    }
+    function installCatalog(app, catalog) {
+        app.provide(key, catalog);
+        app.config.globalProperties.$langText = catalog.langText;
+        app.config.globalProperties.$langTextPlural = catalog.langTextPlural;
+        app.config.globalProperties.$langHtmlText = catalog.langHtmlText;
+        app.use(catalog.gettext);
+    }
+    const langText = (key, parameters) => current().langText(key, parameters);
+    const langTextPlural = (one, plural, count, parameters) => current().langTextPlural(one, plural, count, parameters);
+    const langHtmlText = (key, parameters) => current().langHtmlText(key, parameters);
+    return {
+        text,
+        langText,
+        langTextPlural,
+        langHtmlText,
+        createCatalog,
+        installCatalog,
+    };
+}
+// Consumer facades can augment these with their catalog-specific key types instead.
+// The package does not install a global catalog or globally claim one app's key union.
+//# sourceMappingURL=index.js.map

package/dist/runtime/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/runtime/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,EAA+B,MAAM,KAAK,CAAC;AAC/E,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAuBjD,0GAA0G;AAC1G,MAAM,UAAU,oBAAoB,CAClC,OAAmC;IAEnC,MAAM,cAAc,GAAG,eAAe,CAAC,OAAO,CAAC,CAAC;IAChD,MAAM,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC;IAC1C,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IAChC,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC;IAC/C,MAAM,GAAG,GAAsC,MAAM,CAAC,aAAa,CAAC,CAAC;IAErE,SAAS,IAAI,CAAC,GAAQ;QACpB,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,GAAG,CAAC;YAC9B,MAAM,IAAI,KAAK,CAAC,wBAAwB,GAAG,IAAI,CAAC,CAAC;QACnD,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC;IACtB,CAAC;IAED,SAAS,aAAa,CACpB,WAAmC,EAAE;QAErC,MAAM,OAAO,GAAG,cAAc,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;QAChD,MAAM,QAAQ,GAAG,QAAQ,CAAC,YAAY,IAAI,YAAY,CAAC;QACvD,SAAS,QAAQ,CAAC,GAAQ,EAAE,UAAoC;YAC9D,OAAO,OAAO,CAAC,SAAS,CAAC,GAAG,EAAE,IAAI,CAAC,GAAG,CAAC,EAAE,UAAU,CAAC,CAAC;QACvD,CAAC;QACD,SAAS,cAAc,CACrB,WAA0C,EAC1C,SAA2C,EAC3C,KAAa,EACb,UAAoC;YAEpC,MAAM,OAAO,GAAG,WAAW,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;YACrD,IAAI,CAAC,WAAW,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,SAAS,KAAK,GAAG,OAAO,SAAS,EAAE,CAAC;gBACvE,MAAM,IAAI,KAAK,CACb,mEAAmE,CACpE,CAAC;YACJ,CAAC;YACD,OAAO,OAAO,CAAC,UAAU,CACvB,OAAO,EACP,IAAI,CAAC,WAAW,CAAC,EACjB,IAAI,CAAC,SAAS,CAAC,EACf,KAAK,EACL,UAAU,CACX,CAAC;QACJ,CAAC;QACD,SAAS,YAAY,CACnB,GAAQ,EACR,UAAoC;YAEpC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC;gBACpB,MAAM,IAAI,KAAK,CAAC,gBAAgB,GAAG,4BAA4B,CAAC,CAAC;YACnE,IAAI,CAAC,QAAQ;gBACX,MAAM,IAAI,KAAK,CACb,0DAA0D,CAC3D,CAAC;YACJ,OAAO,QAAQ,CAAC,QAAQ,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC,CAAC;QAC7C,CAAC;QACD,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAE,YAAY,EAAE,CAAC;IAC7D,CAAC;IAED,gFAAgF;IAChF,MAAM,EACJ,QAAQ,EAAE,UAAU,EACpB,cAAc,EAAE,YAAY,EAC5B,YAAY,EAAE,UAAU,GACzB,GAAG,aAAa,EAAE,CAAC;IACpB,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC;QAC3B,QAAQ,EAAE,UAAU;QACpB,cAAc,EAAE,YAAY;QAC5B,YAAY,EAAE,UAAU;KACzB,CAAC,CAAC;IACH,SAAS,OAAO;QACd,OAAO,mBAAmB,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;IAC9D,CAAC;IACD,SAAS,cAAc,CAAC,GAAQ,EAAE,OAA4B;QAC5D,GAAG,CAAC,OAAO,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;QAC1B,GAAG,CAAC,MAAM,CAAC,gBAAgB,CAAC,SAAS,GAAG,OAAO,CAAC,QAAQ,CAAC;QACzD,GAAG,CAAC,MAAM,CAAC,gBAAgB,CAAC,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC;QACrE,GAAG,CAAC,MAAM,CAAC,gBAAgB,CAAC,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC;QACjE,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IAC3B,CAAC;IACD,MAAM,QAAQ,GAAoC,CAAC,GAAG,EAAE,UAAU,EAAE,EAAE,CACpE,OAAO,EAAE,CAAC,QAAQ,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC;IACtC,MAAM,cAAc,GAA0C,CAC5D,GAAG,EACH,MAAM,EACN,KAAK,EACL,UAAU,EACV,EAAE,CAAC,OAAO,EAAE,CAAC,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,CAAC,CAAC;IAC9D,MAAM,YAAY,GAAwC,CAAC,GAAG,EAAE,UAAU,EAAE,EAAE,CAC5E,OAAO,EAAE,CAAC,YAAY,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC;IAC1C,OAAO;QACL,IAAI;QACJ,QAAQ;QACR,cAAc;QACd,YAAY;QACZ,aAAa;QACb,cAAc;KACf,CAAC;AACJ,CAAC;AAED,oFAAoF;AACpF,uFAAuF"}

package/dist/types.d.ts

@@ -0,0 +1,37 @@
+import type { Language, Translations } from "vue3-gettext";
+export type { Language, Translations } from "vue3-gettext";
+export type InterpolationParameters = Record<string, string | number>;
+export type HtmlSanitizer = (html: string) => string;
+export interface CatalogLanguageOptions {
+    readonly catalogTranslations: Translations;
+    readonly sourceLocale: string;
+    readonly locales: readonly string[];
+    /** Optional display names; locale identifiers are used by default. */
+    readonly languageNames?: Readonly<Record<string, string>>;
+    /** Required whenever HTML is rendered, including outside an installed app. */
+    readonly sanitizeHtml?: HtmlSanitizer;
+}
+export interface CatalogInstanceOptions {
+    readonly locale?: string;
+    /** Override the facade's sanitizer for this app/request only. */
+    readonly sanitizeHtml?: HtmlSanitizer;
+}
+export interface CatalogHelpers<Key extends string> {
+    langText(key: Key, parameters?: InterpolationParameters): string;
+    langTextPlural(singularKey: Extract<Key, `${string}.one`>, pluralKey: Extract<Key, `${string}.plural`>, count: number, parameters?: InterpolationParameters): string;
+    langHtmlText(key: Key, parameters?: InterpolationParameters): string;
+}
+/** Extend Vue's ComponentCustomProperties in the consumer facade to type its template globals. */
+export interface CatalogComponentProperties<Key extends string> {
+    $langText: CatalogHelpers<Key>["langText"];
+    $langTextPlural: CatalogHelpers<Key>["langTextPlural"];
+    $langHtmlText: CatalogHelpers<Key>["langHtmlText"];
+}
+export interface RuntimeCatalog<Key extends string> extends CatalogHelpers<Key> {
+    gettext: Language;
+}
+export interface CompiledCatalog {
+    gettext: Language;
+    htmlPgettext(context: string, source: string, parameters?: InterpolationParameters): string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAE3D,YAAY,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAE3D,MAAM,MAAM,uBAAuB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,CAAC;AACtE,MAAM,MAAM,aAAa,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;AAErD,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,mBAAmB,EAAE,YAAY,CAAC;IAC3C,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,sEAAsE;IACtE,QAAQ,CAAC,aAAa,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAC1D,8EAA8E;IAC9E,QAAQ,CAAC,YAAY,CAAC,EAAE,aAAa,CAAC;CACvC;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,iEAAiE;IACjE,QAAQ,CAAC,YAAY,CAAC,EAAE,aAAa,CAAC;CACvC;AAED,MAAM,WAAW,cAAc,CAAC,GAAG,SAAS,MAAM;IAChD,QAAQ,CAAC,GAAG,EAAE,GAAG,EAAE,UAAU,CAAC,EAAE,uBAAuB,GAAG,MAAM,CAAC;IACjE,cAAc,CACZ,WAAW,EAAE,OAAO,CAAC,GAAG,EAAE,GAAG,MAAM,MAAM,CAAC,EAC1C,SAAS,EAAE,OAAO,CAAC,GAAG,EAAE,GAAG,MAAM,SAAS,CAAC,EAC3C,KAAK,EAAE,MAAM,EACb,UAAU,CAAC,EAAE,uBAAuB,GACnC,MAAM,CAAC;IACV,YAAY,CAAC,GAAG,EAAE,GAAG,EAAE,UAAU,CAAC,EAAE,uBAAuB,GAAG,MAAM,CAAC;CACtE;AAED,kGAAkG;AAClG,MAAM,WAAW,0BAA0B,CAAC,GAAG,SAAS,MAAM;IAC5D,SAAS,EAAE,cAAc,CAAC,GAAG,CAAC,CAAC,UAAU,CAAC,CAAC;IAC3C,eAAe,EAAE,cAAc,CAAC,GAAG,CAAC,CAAC,gBAAgB,CAAC,CAAC;IACvD,aAAa,EAAE,cAAc,CAAC,GAAG,CAAC,CAAC,cAAc,CAAC,CAAC;CACpD;AAED,MAAM,WAAW,cAAc,CAC7B,GAAG,SAAS,MAAM,CAClB,SAAQ,cAAc,CAAC,GAAG,CAAC;IAC3B,OAAO,EAAE,QAAQ,CAAC;CACnB;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,QAAQ,CAAC;IAClB,YAAY,CACV,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,UAAU,CAAC,EAAE,uBAAuB,GACnC,MAAM,CAAC;CACX"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/dist/vite/index.d.ts

@@ -0,0 +1,21 @@
+import { type Plugin } from "vite";
+import type { CatalogIdentity } from "./types.js";
+export type TextCatalogMode = "runtime" | "compiled";
+export interface TextCatalogOptions extends CatalogIdentity {
+    /** Preserve dynamic runtime lookups by default; opt into literal expansion explicitly. */
+    mode?: TextCatalogMode;
+    root?: string;
+    /** Input/output paths are relative to root, or absolute. No app-specific defaults. */
+    sourceDirectory: string;
+    languageDirectory: string;
+    frontendDirectory: string;
+    /** Real consumer-local authoring facade, also resolved by standalone TypeScript. */
+    facade: string;
+    /** Required in compiled mode; exports createCatalog/installCatalog and gettext adapters. */
+    compiledFacade?: string;
+    /** Compile and publish all format-v1 artifacts. The host owns process/env/bootstrap choices. */
+    compile: (root: string) => void | Promise<void>;
+}
+/** Generate Text catalog, optionally expanding literals before Vue, with one coherent snapshot across environments. */
+export declare function textCatalog(options: TextCatalogOptions): Plugin;
+//# sourceMappingURL=index.d.ts.map

package/dist/vite/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/vite/index.ts"],"names":[],"mappings":"AAYA,OAAO,EAGL,KAAK,MAAM,EAEZ,MAAM,MAAM,CAAC;AAGd,OAAO,KAAK,EACV,eAAe,EAGhB,MAAM,YAAY,CAAC;AAGpB,MAAM,MAAM,eAAe,GAAG,SAAS,GAAG,UAAU,CAAC;AAErD,MAAM,WAAW,kBAAmB,SAAQ,eAAe;IACzD,0FAA0F;IAC1F,IAAI,CAAC,EAAE,eAAe,CAAC;IACvB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,sFAAsF;IACtF,eAAe,EAAE,MAAM,CAAC;IACxB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,oFAAoF;IACpF,MAAM,EAAE,MAAM,CAAC;IACf,4FAA4F;IAC5F,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,gGAAgG;IAChG,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACjD;AAkBD,uHAAuH;AACvH,wBAAgB,WAAW,CAAC,OAAO,EAAE,kBAAkB,GAAG,MAAM,CAmkB/D"}