@aethervtt/shard-text 0.0.1

package/dist/locale.js

@@ -0,0 +1,574 @@
+import {
+  AssetStore,
+  assetServer,
+  defineAssetSchema,
+  defineAssetType,
+  defineImporter
+} from "@aethervtt/shard-assets";
+import {
+  defineResource,
+  defineSchema,
+  defineSystem,
+  isPlainObject,
+  PostUpdate,
+  pointer,
+  ShardError,
+  t
+} from "@aethervtt/shard-core";
+import { LogResource } from "@aethervtt/shard-runtime";
+import { Localized, ScreenText, Text } from "./components.js";
+const PLURAL_CATEGORIES = ["zero", "one", "two", "few", "many", "other"];
+class StringTable {
+  locale;
+  strings;
+  version = 0;
+  constructor(locale, strings) {
+    this.locale = locale;
+    this.strings = strings;
+  }
+  copyFrom(other) {
+    this.locale = other.locale;
+    this.strings = other.strings;
+    this.version++;
+  }
+}
+const StringTables = defineResource(
+  "text/StringTables",
+  {
+    description: "Loaded string tables (locales/*.strings.json) by guid.",
+    init: () => new AssetStore("StringTable")
+  }
+);
+const StringTableAssetType = defineAssetType("StringTable", {
+  store: StringTables,
+  load: (artifact) => {
+    const json = artifact.json;
+    return new StringTable(json.locale, new Map(Object.entries(json.strings)));
+  },
+  update: (existing, next) => existing.copyFrom(next)
+});
+function localeOfPath(path) {
+  const name = path.slice(path.lastIndexOf("/") + 1).replace(/\.strings\.json$/i, "");
+  const tag = name.slice(name.lastIndexOf(".") + 1);
+  try {
+    return Intl.getCanonicalLocales(tag)[0];
+  } catch {
+    return void 0;
+  }
+}
+const PLACEHOLDER = /\{([A-Za-z_][\w-]*)\}/g;
+function placeholdersOf(entry) {
+  const names = /* @__PURE__ */ new Set();
+  const texts = typeof entry === "string" ? [entry] : Object.values(entry);
+  for (const text of texts) {
+    if (typeof text !== "string") continue;
+    for (const m of text.matchAll(PLACEHOLDER)) names.add(m[1]);
+  }
+  return [...names].sort();
+}
+function validateStringTable(json) {
+  const errors = [];
+  if (!isPlainObject(json)) {
+    return [
+      new ShardError("locale/invalid-table", "A string table must be a JSON object", {
+        path: "",
+        hint: 'Map keys to strings: { "hud.fuel": "Fuel: {amount}%" }.'
+      })
+    ];
+  }
+  for (const [key, value] of Object.entries(json)) {
+    if (key === "$schema") continue;
+    const at = pointer("", key);
+    if (typeof value === "string") continue;
+    if (!isPlainObject(value)) {
+      errors.push(
+        new ShardError("schema/type-mismatch", `"${key}" must be a string or plural forms`, {
+          path: at,
+          hint: 'Use "text", or { "one": "{n} item", "other": "{n} items" } for plurals.'
+        })
+      );
+      continue;
+    }
+    for (const [category, text] of Object.entries(value)) {
+      if (!PLURAL_CATEGORIES.includes(category)) {
+        errors.push(
+          new ShardError("locale/bad-plural", `"${category}" isn't a plural category in "${key}"`, {
+            path: pointer(at, category),
+            hint: `Plural forms are ${PLURAL_CATEGORIES.join(", ")} (Intl.PluralRules categories).`
+          })
+        );
+      } else if (typeof text !== "string") {
+        errors.push(
+          new ShardError("schema/type-mismatch", `"${key}".${category} must be a string`, {
+            path: pointer(at, category)
+          })
+        );
+      }
+    }
+    if (typeof value.other !== "string") {
+      errors.push(
+        new ShardError("locale/bad-plural", `Plural forms of "${key}" need "other"`, {
+          path: at,
+          hint: '"other" is the form every locale falls back to.'
+        })
+      );
+    }
+  }
+  return errors;
+}
+const NoSettings = defineSchema("text/StringTableSettings", {}, { description: "No settings." });
+const StringTableImporter = defineImporter({
+  name: "strings",
+  version: 1,
+  extensions: [".strings.json"],
+  settings: NoSettings,
+  async import(source) {
+    const locale = localeOfPath(source.path);
+    if (!locale) {
+      throw new ShardError("locale/bad-locale", `${source.path} doesn't name a locale`, {
+        path: "",
+        hint: "Name tables by BCP 47 tag: locales/en.strings.json, locales/pt-BR.strings.json (or hud.pt-BR.strings.json)."
+      });
+    }
+    let json;
+    try {
+      json = JSON.parse(source.text());
+    } catch (cause) {
+      throw new ShardError("assets/import-failed", `${source.path} isn't valid JSON`, {
+        path: "",
+        cause
+      });
+    }
+    const errors = validateStringTable(json);
+    if (errors.length > 0) {
+      throw new ShardError(errors[0].code, `${source.path}: ${errors[0].message}`, {
+        path: errors[0].path,
+        hint: errors[0].hint,
+        details: errors
+      });
+    }
+    const { $schema: _, ...strings } = json;
+    return {
+      assets: [
+        {
+          label: "",
+          type: "StringTable",
+          json: { locale, strings },
+          info: { locale, keys: Object.keys(strings).length }
+        }
+      ]
+    };
+  }
+});
+const stringTableSchema = defineAssetSchema("strings.schema.json", () => ({
+  $schema: "https://json-schema.org/draft/2020-12/schema",
+  title: "Shard string table",
+  description: "locales/<locale>.strings.json: key \u2192 string. {name} is a placeholder filled from params; an object picks a plural form by n (or count).",
+  type: "object",
+  properties: { $schema: { type: "string" } },
+  additionalProperties: {
+    oneOf: [
+      { type: "string" },
+      {
+        type: "object",
+        properties: Object.fromEntries(PLURAL_CATEGORIES.map((c) => [c, { type: "string" }])),
+        required: ["other"],
+        additionalProperties: false
+      }
+    ]
+  }
+}));
+const Locale = defineResource("text/Locale", {
+  description: 'The current locale (current, e.g. "pt-BR") and the last one tried (fallback, "en"). Set current to switch language: keyed text updates on the next frame.',
+  init: () => ({ current: "en", fallback: "en" })
+});
+function localeChain(current, fallback) {
+  const out = [];
+  const add = (tag) => {
+    if (tag !== "" && !out.includes(tag)) out.push(tag);
+  };
+  add(current);
+  const dash = current.indexOf("-");
+  if (dash > 0) add(current.slice(0, dash));
+  add(fallback);
+  return out;
+}
+class LocaleStore {
+  /** Bumped when a string table loads, changes, or goes away. */
+  revision = 0;
+  /** The chain tried for the current locale. */
+  chain = [];
+  /** Bumped when the chain changes (the locale was switched). */
+  chainRevision = 0;
+  chainFor = "\0";
+  merged;
+  plurals = /* @__PURE__ */ new Map();
+  numbers = /* @__PURE__ */ new Map();
+  /** Keys requested at runtime that no locale in the chain had, by locale. */
+  missing = /* @__PURE__ */ new Map();
+  /** Components whose `key` and `params` fields localize (UiText, Text, ScreenText). */
+  targets = [];
+  /** The resolved string's locale after `resolve` ('' if the key was missing). */
+  resolvedLocale = "";
+  /** Recomputes the chain if the locale changed. True if it did. */
+  sync(locale) {
+    const id = `${locale.current}|${locale.fallback}`;
+    if (id === this.chainFor) return false;
+    this.chainFor = id;
+    this.chain = localeChain(locale.current, locale.fallback);
+    this.chainRevision++;
+    return true;
+  }
+  /** Every loaded table's strings, merged per locale (rebuilt after a table changes). */
+  tables(world) {
+    if (this.merged) return this.merged;
+    const out = /* @__PURE__ */ new Map();
+    const server = assetServer(world);
+    const store = world.tryResource(StringTables);
+    for (const entry of server.all("StringTable")) {
+      const table = store?.byGuid(entry.guid);
+      if (!table) {
+        if (entry.state === "unloaded") {
+          server.pin(entry.guid, PIN);
+          void server.request(entry.guid);
+        }
+        continue;
+      }
+      let m = out.get(table.locale);
+      if (!m) {
+        m = { strings: /* @__PURE__ */ new Map(), source: /* @__PURE__ */ new Map() };
+        out.set(table.locale, m);
+      }
+      for (const [key, value] of table.strings) {
+        m.strings.set(key, value);
+        m.source.set(key, entry.path);
+      }
+    }
+    this.merged = out;
+    return out;
+  }
+  invalidate() {
+    this.merged = void 0;
+    this.revision++;
+  }
+  /**
+   * The string for `key` in the first locale of the chain that has it, formatted with `params`.
+   * Undefined if none has it (the miss is recorded and logged once).
+   */
+  resolve(world, key, params) {
+    const tables = this.tables(world);
+    for (let i = 0; i < this.chain.length; i++) {
+      const locale = this.chain[i];
+      const entry = tables.get(locale)?.strings.get(key);
+      if (entry === void 0) continue;
+      this.resolvedLocale = locale;
+      return this.format(entry, this.chain[0], params);
+    }
+    this.resolvedLocale = "";
+    const current = this.chain[0] ?? "";
+    let keys = this.missing.get(current);
+    if (!keys) {
+      keys = /* @__PURE__ */ new Set();
+      this.missing.set(current, keys);
+    }
+    if (!keys.has(key)) {
+      keys.add(key);
+      world.tryResource(LogResource)?.log("warn", `No string for "${key}" in ${this.chain.join(" \u2192 ")}`, {
+        code: "locale/missing-key",
+        hint: `Add "${key}" to locales/${current}.strings.json (or the fallback locale's table).`
+      });
+    }
+    return void 0;
+  }
+  /** Formats one entry: picks the plural form, then fills `{name}` placeholders. */
+  format(entry, locale, params) {
+    const values = isPlainObject(params) ? params : void 0;
+    let text;
+    if (typeof entry === "string") text = entry;
+    else {
+      const n = pluralCount(values);
+      const category = n === 0 && entry.zero !== void 0 ? "zero" : this.pluralRules(locale).select(n);
+      text = entry[category] ?? entry.other ?? "";
+    }
+    if (!values || text.indexOf("{") === -1) return text;
+    return text.replace(PLACEHOLDER, (whole, name) => {
+      const v = values[name];
+      if (typeof v === "number") return this.numberFormat(locale).format(v);
+      if (typeof v === "string" || typeof v === "boolean") return String(v);
+      return whole;
+    });
+  }
+  pluralRules(locale) {
+    let rules = this.plurals.get(locale);
+    if (!rules) {
+      rules = new Intl.PluralRules(locale);
+      this.plurals.set(locale, rules);
+    }
+    return rules;
+  }
+  numberFormat(locale) {
+    let format = this.numbers.get(locale);
+    if (!format) {
+      format = new Intl.NumberFormat(locale);
+      this.numbers.set(locale, format);
+    }
+    return format;
+  }
+}
+function pluralCount(params) {
+  if (!params) return 0;
+  if (typeof params.n === "number") return params.n;
+  if (typeof params.count === "number") return params.count;
+  for (const k in params) if (typeof params[k] === "number") return params[k];
+  return 0;
+}
+const LocaleState = defineResource("text/LocaleState", {
+  description: "Merged string tables, plural rules, and missing keys (localization internals)."
+});
+function tr(world, key, params) {
+  const store = world.tryResource(LocaleState);
+  if (!store) return key;
+  store.sync(world.resource(Locale));
+  return store.resolve(world, key, params) ?? key;
+}
+function setLocale(world, locale) {
+  let tag;
+  try {
+    tag = Intl.getCanonicalLocales(locale)[0];
+  } catch {
+    tag = void 0;
+  }
+  if (!tag) {
+    throw new ShardError("locale/bad-locale", `"${locale}" isn't a locale`, {
+      hint: 'Use a BCP 47 tag like "en", "pt-BR", or "ja".'
+    });
+  }
+  world.resource(Locale).current = tag;
+}
+function localizeComponent(world, def) {
+  const store = world.resource(LocaleState);
+  if (!store.targets.some((x) => x.def === def)) store.targets.push({ def, query: void 0 });
+}
+const localizeText = defineSystem({
+  name: "text/localize",
+  description: "Resolves UiText, Text, and ScreenText keys in the current locale.",
+  setup: () => ({ revision: -1, chain: -1 }),
+  run: (s, world, ctx) => {
+    const store = world.resource(LocaleState);
+    store.sync(world.resource(Locale));
+    const all = store.chainRevision !== s.chain || store.revision !== s.revision;
+    s.revision = store.revision;
+    s.chain = store.chainRevision;
+    const since = ctx.lastRunTick;
+    for (let t2 = 0; t2 < store.targets.length; t2++) {
+      const target = store.targets[t2];
+      target.query ??= world.query({ with: [target.def] });
+      const def = target.def;
+      const tables = target.query.tables;
+      for (let k = 0; k < tables.length; k++) {
+        const table = tables[k];
+        if (table.count === 0 || !all && table.lastChanged(def) <= since) continue;
+        const keys = table.column(def, "key");
+        const params = table.column(def, "params");
+        const ticks = table.changedTicks(def);
+        const has = table.has(Localized);
+        const values = has ? table.column(Localized, "value") : void 0;
+        const locales = has ? table.column(Localized, "locale") : void 0;
+        let wrote = false;
+        for (let i = 0; i < table.count; i++) {
+          if (!all && ticks[i] <= since) continue;
+          const entity = table.entities[i];
+          const key = keys[i];
+          if (key === "") {
+            if (has) ctx.commands.remove(entity, Localized);
+            continue;
+          }
+          const value = store.resolve(world, key, params[i]);
+          const locale = store.resolvedLocale;
+          if (value === void 0) {
+            if (has) ctx.commands.remove(entity, Localized);
+            continue;
+          }
+          if (!has) ctx.commands.add(entity, Localized, { value, locale });
+          else if (values[i] !== value || locales[i] !== locale) {
+            values[i] = value;
+            locales[i] = locale;
+            wrote = true;
+          }
+        }
+        if (wrote) table.markChanged(Localized);
+      }
+    }
+  }
+});
+const KEYED_COMPONENTS = ["ui/UiText", "text/Text", "text/ScreenText"];
+function localizationKeysIn(json) {
+  const out = [];
+  const walk = (value, at) => {
+    if (Array.isArray(value)) {
+      for (let i = 0; i < value.length; i++) walk(value[i], pointer(at, i));
+      return;
+    }
+    if (!isPlainObject(value)) return;
+    for (const [k, v] of Object.entries(value)) {
+      const here = pointer(at, k);
+      if (KEYED_COMPONENTS.includes(k) && isPlainObject(v)) {
+        if (typeof v.key === "string" && v.key !== "")
+          out.push({ key: v.key, path: pointer(here, "key") });
+      }
+      walk(v, here);
+    }
+  };
+  walk(json, "");
+  return out;
+}
+async function validateLocalization(world) {
+  const server = assetServer(world);
+  const entries = server.all("StringTable");
+  await Promise.all(entries.map((e) => server.load(e.guid).catch(() => void 0)));
+  const store = world.initResource(StringTables);
+  const byLocale = /* @__PURE__ */ new Map();
+  for (const entry of entries) {
+    const table = store.byGuid(entry.guid);
+    if (!table) continue;
+    const list = byLocale.get(table.locale) ?? [];
+    list.push({ path: entry.path, table });
+    byLocale.set(table.locale, list);
+  }
+  const keys = /* @__PURE__ */ new Set();
+  for (const list of byLocale.values())
+    for (const { table } of list) for (const key of table.strings.keys()) keys.add(key);
+  const locales = [...byLocale.keys()].sort();
+  const errors = [];
+  const firstDefinition = /* @__PURE__ */ new Map();
+  for (const locale of locales) {
+    const list = byLocale.get(locale);
+    const own = /* @__PURE__ */ new Map();
+    for (const { table } of list) for (const [k, v] of table.strings) own.set(k, v);
+    const source = list[0].path;
+    for (const key of [...keys].sort()) {
+      const entry = own.get(key);
+      if (entry === void 0) {
+        const others = locales.filter(
+          (l) => l !== locale && byLocale.get(l).some((x) => x.table.strings.has(key))
+        );
+        errors.push({
+          source,
+          error: new ShardError("locale/missing-key", `"${key}" is missing in ${locale}`, {
+            path: pointer("", key),
+            hint: `Defined in ${others.join(", ")}. Add it to ${source}.`
+          })
+        });
+        continue;
+      }
+      const params = placeholdersOf(entry).join(", ");
+      const first = firstDefinition.get(key);
+      if (!first) firstDefinition.set(key, { locale, params });
+      else if (first.params !== params) {
+        errors.push({
+          source,
+          error: new ShardError(
+            "locale/param-mismatch",
+            `"${key}" uses {${params}} in ${locale} but {${first.params}} in ${first.locale}`,
+            {
+              path: pointer("", key),
+              hint: "Every locale gets the same params: use the same {placeholders} in each."
+            }
+          )
+        });
+      }
+    }
+  }
+  return { locales, keys, errors };
+}
+const localeMethods = [
+  {
+    name: "locale.set",
+    description: 'Switches the locale (a BCP 47 tag like "pt-BR"): keyed UiText, Text, and ScreenText update on the next frame. Returns the fallback chain.',
+    params: defineSchema("protocol/LocaleSetParams", {
+      locale: t.string({ required: true, description: 'e.g. "en", "pt-BR".' })
+    }),
+    handler: ({ world }, params) => {
+      setLocale(world, params.locale);
+      const store = world.resource(LocaleState);
+      store.sync(world.resource(Locale));
+      return { current: world.resource(Locale).current, chain: store.chain };
+    }
+  },
+  {
+    name: "locale.missing",
+    description: "What doesn't translate: per locale, keys another locale's table defines but its own lacks, and keys requested at runtime that no locale in the chain had. Also the current locale, chain, and loaded locales.",
+    params: defineSchema("protocol/LocaleMissingParams", {}),
+    handler: ({ world }) => {
+      const store = world.resource(LocaleState);
+      store.sync(world.resource(Locale));
+      const tables = store.tables(world);
+      const all = /* @__PURE__ */ new Set();
+      for (const m of tables.values()) for (const k of m.strings.keys()) all.add(k);
+      const missing = {};
+      for (const [locale, m] of tables) {
+        const lacks = [...all].filter((k) => !m.strings.has(k)).sort();
+        if (lacks.length > 0) missing[locale] = lacks;
+      }
+      const requested = {};
+      for (const [locale, keys] of store.missing) requested[locale] = [...keys].sort();
+      return {
+        current: world.resource(Locale).current,
+        chain: store.chain,
+        locales: [...tables.keys()].sort(),
+        missing,
+        requested
+      };
+    }
+  }
+];
+const installed = /* @__PURE__ */ new WeakSet();
+function installLocalization(app) {
+  if (installed.has(app)) return;
+  installed.add(app);
+  const world = app.world;
+  world.initResource(Locale);
+  world.initResource(StringTables);
+  const store = new LocaleStore();
+  world.insertResource(LocaleState, store);
+  localizeComponent(world, Text);
+  localizeComponent(world, ScreenText);
+  assetServer(world).onEvent((e) => {
+    if (assetServer(world).entry(e.guid)?.type !== "StringTable" && e.kind !== "removed") return;
+    store.invalidate();
+  });
+  app.addSystems(PostUpdate, localizeText);
+  app.addMethod(...localeMethods);
+}
+async function loadStringTables(world) {
+  const server = assetServer(world);
+  const entries = server.all("StringTable");
+  for (const e of entries) server.pin(e.guid, PIN);
+  await Promise.all(entries.map((e) => server.load(e.guid)));
+}
+const PIN = "text/strings";
+export {
+  KEYED_COMPONENTS,
+  Locale,
+  LocaleState,
+  LocaleStore,
+  PLURAL_CATEGORIES,
+  StringTable,
+  StringTableAssetType,
+  StringTableImporter,
+  StringTables,
+  installLocalization,
+  loadStringTables,
+  localeChain,
+  localeMethods,
+  localeOfPath,
+  localizationKeysIn,
+  localizeComponent,
+  localizeText,
+  placeholdersOf,
+  setLocale,
+  stringTableSchema,
+  tr,
+  validateLocalization,
+  validateStringTable
+};

package/dist/msdf.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Multi-channel signed distance fields: a TypeScript port of msdfgen's core.
+ *
+ * - Per-channel perpendicular ("pseudo") distance with msdfgen's `MultiDistanceSelector`, per-edge
+ *   distance caches, and the `OverlappingContourCombiner` (correct fields for overlapping contours).
+ * - A scanline pass that fixes the sign of any texel whose median disagrees with the nonzero fill.
+ * - msdfgen's edge-priority error correction: protect corners and edges, find texels whose linear
+ *   or bilinear interpolation makes an artifact, and flatten those to their median.
+ *
+ * Everything per pixel runs on typed arrays that grow once and are reused across glyphs.
+ * Coordinates follow msdfgen: shape units, y up; bitmap row 0 is the bottom row.
+ */
+import { type Shape } from './shape.js';
+export interface MsdfOptions {
+    /** Pixels per shape unit. */
+    scale: number;
+    /** Distance range in pixels: the field spans ±range/2 around the outline. */
+    range: number;
+    /** Corner angle threshold for edge coloring, radians. Default 3. */
+    angleThreshold?: number;
+    /** Run the scanline sign pass (default true). */
+    scanline?: boolean;
+    /** Run edge-priority error correction (default true). */
+    errorCorrection?: boolean;
+}
+/** Where a glyph's bitmap sits relative to the shape (msdf-atlas-gen's box wrapping). */
+export interface MsdfBox {
+    width: number;
+    height: number;
+    /** Shape-space translation: pixel x = (shapeX + tx) * scale. */
+    tx: number;
+    ty: number;
+    /** Quad bounds in shape units (pixel center to pixel center): left, bottom, right, top. */
+    plane: [number, number, number, number];
+}
+/** The bitmap box for bounds: padded by half the range, centered, one spare pixel. */
+export declare function msdfBox(bounds: readonly [number, number, number, number], scale: number, range: number): MsdfBox;
+/**
+ * Prepares a shape for MSDF: splits single-edge contours, fixes the orientation so the outside is
+ * negative, and colors the edges. Mutates the shape.
+ */
+export declare function prepareShape(shape: Shape, angleThreshold?: number): void;
+/**
+ * Generates the MSDF of a prepared shape into a reused float buffer (3 channels, normalized so 0.5
+ * is the outline, row 0 at the bottom). Returns the buffer; valid until the next call.
+ */
+export declare function generateMsdf(shape: Shape, box: MsdfBox, options: MsdfOptions): Float32Array;
+/**
+ * Writes a generated field into an RGBA8 image with row 0 at the top (flipping msdfgen's rows),
+ * at (x, y). Alpha is 255.
+ */
+export declare function blitMsdf(sdf: Float32Array, w: number, h: number, out: Uint8Array, outWidth: number, x: number, y: number): void;