@aethervtt/shard-text 0.0.1

package/dist/font.js

@@ -0,0 +1,377 @@
+import { SkylinePacker, Texture } from "@aethervtt/shard-texture";
+import { FontSource, rasterizeGlyph } from "./source.js";
+class FontPage {
+  font;
+  index;
+  width;
+  height;
+  /** The page's texture asset (`font.ttf#Atlas`), for imported fonts. */
+  ref;
+  /**
+   * The page's pixels, for runtime pages and fonts built in code. Its `version` bumps when glyphs
+   * are added, so the renderer re-uploads it.
+   */
+  texture;
+  /** Made at runtime for glyphs outside the imported set. */
+  runtime;
+  /** @internal Free space, for runtime pages. */
+  packer;
+  constructor(font, index, init) {
+    this.font = font;
+    this.index = index;
+    this.width = init.width;
+    this.height = init.height;
+    this.ref = init.ref;
+    this.texture = init.texture;
+    this.runtime = init.runtime ?? false;
+    this.packer = void 0;
+  }
+}
+class Glyph {
+  codepoint;
+  /** The font whose atlas holds the glyph (a fallback's, for fallback glyphs). */
+  font;
+  advance;
+  left;
+  bottom;
+  right;
+  top;
+  /** Index into `font.pages`. */
+  page;
+  /** Atlas box in pixels. */
+  x;
+  y;
+  w;
+  h;
+  /** Texture coordinates of the quad: (u0, v0) is its top-left. */
+  u0;
+  v0;
+  u1;
+  v1;
+  /** Generated at runtime rather than imported. */
+  runtime;
+  /** Whether it draws anything (spaces don't). */
+  visible;
+  /** @internal Range of this glyph's kerning pairs (as the left glyph) in its font's tables. */
+  kernStart = 0;
+  kernCount = 0;
+  constructor(font, json, runtime) {
+    this.font = font;
+    this.codepoint = json.u;
+    this.advance = json.a;
+    this.runtime = runtime;
+    const b = json.b;
+    const r = json.r;
+    this.page = json.p ?? 0;
+    if (b && r) {
+      this.left = b[0];
+      this.bottom = b[1];
+      this.right = b[2];
+      this.top = b[3];
+      this.x = r[0];
+      this.y = r[1];
+      this.w = r[2];
+      this.h = r[3];
+      const page = font.pages[this.page];
+      const pw = page?.width ?? 1;
+      const ph = page?.height ?? 1;
+      this.u0 = (r[0] + 0.5) / pw;
+      this.v0 = (r[1] + 0.5) / ph;
+      this.u1 = (r[0] + r[2] - 0.5) / pw;
+      this.v1 = (r[1] + r[3] - 0.5) / ph;
+      this.visible = true;
+    } else {
+      this.left = this.bottom = this.right = this.top = 0;
+      this.x = this.y = this.w = this.h = 0;
+      this.u0 = this.v0 = this.u1 = this.v1 = 0;
+      this.visible = false;
+    }
+  }
+}
+const round6 = (v) => Math.round(v * 1e6) / 1e6;
+const RUNTIME_PAGE_SIZE = 512;
+const GLYPH_PADDING = 1;
+class Font {
+  name;
+  size;
+  range;
+  unitsPerEm;
+  ascent;
+  descent;
+  lineGap;
+  charset;
+  pages = [];
+  /** Glyphs this font holds (imported and generated), by codepoint. */
+  glyphs = /* @__PURE__ */ new Map();
+  notdef;
+  /** Bumps when glyphs or pages are added (on-demand glyphs), or on hot reload. */
+  version = 0;
+  /** Glyphs generated at runtime so far. */
+  runtimeGlyphs = 0;
+  /** Codepoints nothing could draw (they show the missing-glyph box). */
+  missing = /* @__PURE__ */ new Set();
+  /** Fallback fonts from the import settings, before the `Fonts` store links them. */
+  fallbackRefs = [];
+  /** The metrics' fallback paths (project paths). */
+  fallbackPaths = [];
+  /** @internal The store that links this font's fallbacks (set by `FontStore`). */
+  linker;
+  /** @internal Kerning tables: right codepoints and em adjustments, grouped by left glyph. */
+  kernRight = new Int32Array(0);
+  kernValue = new Float32Array(0);
+  _fallbacks = [];
+  resolved = /* @__PURE__ */ new Map();
+  sourceBytes;
+  _source;
+  json;
+  constructor(json) {
+    this.json = json;
+    this.name = json.name;
+    this.size = json.size;
+    this.range = json.range;
+    this.unitsPerEm = json.unitsPerEm;
+    this.ascent = json.ascent;
+    this.descent = json.descent;
+    this.lineGap = json.lineGap;
+    this.charset = json.charset ?? "custom";
+  }
+  /** Builds a font from its metrics JSON and its atlas pages (pixels or texture refs). */
+  static fromMetrics(json, options = {}) {
+    const font = new Font(json);
+    font.pages = json.pages.map((p, i) => {
+      const pixels = options.pixels?.[i];
+      return new FontPage(font, i, {
+        width: p.width,
+        height: p.height,
+        ref: options.pageRefs?.[i],
+        texture: pixels ? Texture.create({
+          width: p.width,
+          height: p.height,
+          mips: [pixels],
+          usage: "data",
+          cpu: true
+        }) : void 0
+      });
+    });
+    for (const g of json.glyphs) font.glyphs.set(g.u, new Glyph(font, g, false));
+    font.notdef = new Glyph(font, json.notdef, false);
+    font.setKerning(json.kerning);
+    if (options.source instanceof FontSource) font._source = options.source;
+    else font.sourceBytes = options.source;
+    font.fallbackRefs = [...options.fallbackRefs ?? []];
+    font.fallbackPaths = [...json.fallback ?? []];
+    font.resolved = new Map(font.glyphs);
+    return font;
+  }
+  /** The metrics this font was loaded from. */
+  get metrics() {
+    return this.json;
+  }
+  /** Line height in em: ascent - descent + line gap. */
+  get lineHeight() {
+    return this.ascent - this.descent + this.lineGap;
+  }
+  get fallbacks() {
+    return this._fallbacks;
+  }
+  /** Sets the fallback fonts, tried in order. Clears the resolved-glyph cache. */
+  set fallbacks(fonts) {
+    this._fallbacks = [...fonts];
+    this.invalidate();
+  }
+  /** Forgets resolved fallback and missing glyphs (after fallbacks change). */
+  invalidate() {
+    this.resolved = new Map(this.glyphs);
+    this.missing.clear();
+    this.version++;
+  }
+  /** Whether on-demand glyphs can be generated (the font's outlines are available). */
+  get hasOutlines() {
+    return this._source !== void 0 || this.sourceBytes !== void 0;
+  }
+  /** The parsed font file, parsed on first use; undefined without outlines. */
+  get source() {
+    if (!this._source && this.sourceBytes)
+      this._source = new FontSource(this.sourceBytes, this.name);
+    return this._source;
+  }
+  /** This font's own glyph for a codepoint (imported or already generated), no fallbacks. */
+  glyph(codepoint) {
+    return this.glyphs.get(codepoint);
+  }
+  /** A glyph for any codepoint; never undefined (the missing-glyph box at worst). */
+  resolve(codepoint) {
+    const g = this.resolved.get(codepoint);
+    return g !== void 0 ? g : this.resolveSlow(codepoint);
+  }
+  /** Whether a codepoint resolves to a real glyph (here, on demand, or in a fallback). */
+  has(codepoint) {
+    return this.resolve(codepoint) !== this.notdef;
+  }
+  /** Kerning between two glyphs, in em (0 across fonts). */
+  kerning(left, right) {
+    if (left.font !== right.font || left.kernCount === 0) return 0;
+    const f = left.font;
+    const target = right.codepoint;
+    let lo = left.kernStart;
+    let hi = lo + left.kernCount - 1;
+    const keys = f.kernRight;
+    while (lo <= hi) {
+      const mid = lo + hi >> 1;
+      const k = keys[mid];
+      if (k === target) return f.kernValue[mid];
+      if (k < target) lo = mid + 1;
+      else hi = mid - 1;
+    }
+    return 0;
+  }
+  resolveSlow(codepoint) {
+    let g = this.find(codepoint, 0);
+    if (!g) {
+      g = this.notdef;
+      this.missing.add(codepoint);
+    }
+    this.resolved.set(codepoint, g);
+    return g;
+  }
+  find(codepoint, depth) {
+    const own = this.glyphs.get(codepoint);
+    if (own) return own;
+    const made = this.generate(codepoint);
+    if (made) return made;
+    if (depth < 4) {
+      for (const fb of this._fallbacks) {
+        if (fb === this) continue;
+        const g = fb.find(codepoint, depth + 1);
+        if (g) return g;
+      }
+    }
+    return void 0;
+  }
+  /**
+   * Generates a glyph from this font's outlines into a runtime atlas page, if the font has the
+   * codepoint. Bumps `version` and the page texture's version.
+   */
+  generate(codepoint) {
+    const source = this.source;
+    if (!source) return void 0;
+    const index = source.glyphIndex(codepoint);
+    if (index === 0) return void 0;
+    const bitmap = rasterizeGlyph(source.shape(index), source.unitsPerEm, this);
+    const json = { u: codepoint, a: round6(source.advance(index) / source.unitsPerEm) };
+    if (bitmap.plane) {
+      const spot = this.allocate(bitmap.width, bitmap.height);
+      const page = this.pages[spot.page];
+      const data = page.texture.levels[0];
+      for (let row = 0; row < bitmap.height; row++) {
+        data.set(
+          bitmap.pixels.subarray(row * bitmap.width * 4, (row + 1) * bitmap.width * 4),
+          ((spot.y + row) * page.width + spot.x) * 4
+        );
+      }
+      page.texture.version++;
+      json.b = bitmap.plane.map(round6);
+      json.r = [spot.x, spot.y, bitmap.width, bitmap.height];
+      json.p = spot.page;
+    }
+    const glyph = new Glyph(this, json, true);
+    this.glyphs.set(codepoint, glyph);
+    this.resolved.set(codepoint, glyph);
+    this.runtimeGlyphs++;
+    this.version++;
+    return glyph;
+  }
+  /** Finds room for a w×h box on a runtime page, adding a page when the last one is full. */
+  allocate(w, h) {
+    const pad = GLYPH_PADDING;
+    const last = this.pages[this.pages.length - 1];
+    if (last?.runtime && last.packer) {
+      const spot2 = last.packer.insert(w + pad * 2, h + pad * 2);
+      if (spot2) return { page: last.index, x: spot2.x + pad, y: spot2.y + pad };
+    }
+    let side = RUNTIME_PAGE_SIZE;
+    while (side < Math.max(w, h) + pad * 2) side *= 2;
+    const pixels = new Uint8Array(side * side * 4);
+    for (let i = 3; i < pixels.length; i += 4) pixels[i] = 255;
+    const page = new FontPage(this, this.pages.length, {
+      width: side,
+      height: side,
+      runtime: true,
+      texture: Texture.create({
+        width: side,
+        height: side,
+        mips: [pixels],
+        usage: "data",
+        cpu: true
+      })
+    });
+    page.packer = new SkylinePacker(side, side);
+    this.pages.push(page);
+    const spot = page.packer.insert(w + pad * 2, h + pad * 2);
+    return { page: page.index, x: spot.x + pad, y: spot.y + pad };
+  }
+  setKerning(triples) {
+    const n = Math.floor(triples.length / 3);
+    const order = new Int32Array(n);
+    for (let i2 = 0; i2 < n; i2++) order[i2] = i2;
+    order.sort(
+      (a, b) => triples[a * 3] - triples[b * 3] || triples[a * 3 + 1] - triples[b * 3 + 1]
+    );
+    this.kernRight = new Int32Array(n);
+    this.kernValue = new Float32Array(n);
+    const inv = 1 / this.unitsPerEm;
+    let i = 0;
+    while (i < n) {
+      const left = triples[order[i] * 3];
+      const start = i;
+      while (i < n && triples[order[i] * 3] === left) {
+        this.kernRight[i] = triples[order[i] * 3 + 1];
+        this.kernValue[i] = triples[order[i] * 3 + 2] * inv;
+        i++;
+      }
+      const g = this.glyphs.get(left);
+      if (g) {
+        g.kernStart = start;
+        g.kernCount = i - start;
+      }
+    }
+  }
+  /** Hot reload: takes over another font's data, keeping this object (and its fallbacks). */
+  copyFrom(next) {
+    this.json = next.json;
+    this.name = next.name;
+    this.size = next.size;
+    this.range = next.range;
+    this.unitsPerEm = next.unitsPerEm;
+    this.ascent = next.ascent;
+    this.descent = next.descent;
+    this.lineGap = next.lineGap;
+    this.charset = next.charset;
+    this.fallbackRefs = next.fallbackRefs;
+    this.fallbackPaths = next.fallbackPaths;
+    this.sourceBytes = next.sourceBytes;
+    this._source = next._source;
+    this.runtimeGlyphs = 0;
+    this.pages = next.pages.map(
+      (p) => new FontPage(this, p.index, {
+        width: p.width,
+        height: p.height,
+        ref: p.ref,
+        texture: p.texture,
+        runtime: p.runtime
+      })
+    );
+    this.glyphs = /* @__PURE__ */ new Map();
+    for (const g of next.json.glyphs) this.glyphs.set(g.u, new Glyph(this, g, false));
+    this.notdef = new Glyph(this, next.json.notdef, false);
+    this.setKerning(next.json.kerning);
+    this.invalidate();
+  }
+}
+export {
+  Font,
+  FontPage,
+  GLYPH_PADDING,
+  Glyph,
+  RUNTIME_PAGE_SIZE
+};

package/dist/importer.d.ts

@@ -0,0 +1,40 @@
+import { AssetStore } from '@aethervtt/shard-assets';
+import { type AssetRef } from '@aethervtt/shard-core';
+import { Font } from './font.js';
+export declare const FontImportSettings: import("@aethervtt/shard-core").ComponentDef<{
+    readonly charset: import("@aethervtt/shard-core").FieldType<"custom" | "latin" | "latin-extended", "u8">;
+    readonly customCharset: import("@aethervtt/shard-core").FieldType<string, "object">;
+    readonly size: import("@aethervtt/shard-core").FieldType<number, "u32">;
+    readonly range: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    readonly fallback: import("@aethervtt/shard-core").FieldType<string[], "object">;
+    readonly kerning: import("@aethervtt/shard-core").FieldType<boolean, "u8">;
+    readonly outlines: import("@aethervtt/shard-core").FieldType<boolean, "u8">;
+}>;
+export interface FontImportSettingsValue {
+    charset: 'latin' | 'latin-extended' | 'custom';
+    customCharset: string;
+    size: number;
+    range: number;
+    fallback: string[];
+    kerning: boolean;
+    outlines: boolean;
+}
+/** Label of an atlas page's texture sub-asset: `Atlas`, then `Atlas/1`, `Atlas/2`, … */
+export declare function atlasLabel(page: number): string;
+export declare const FontImporter: import("@aethervtt/shard-assets").ImporterDef;
+/**
+ * Loaded fonts by guid. Setting a font links fallback refs (from its import settings) to the
+ * fonts already loaded: the asset server loads fallbacks first, as dependencies.
+ */
+export declare class FontStore extends AssetStore<Font, 'Font'> {
+    private readonly fonts;
+    constructor();
+    add(item: Font, name?: string): AssetRef<'Font'>;
+    set(guid: string, item: Font): void;
+    delete(guid: string): boolean;
+    /** Points every font's `fallbacks` at its loaded fallback fonts. */
+    link(): void;
+}
+export declare const Fonts: import("@aethervtt/shard-core").ResourceDef<FontStore>;
+/** Fonts load from their metrics JSON; atlas pages are `#Atlas` texture sub-assets. */
+export declare const FontAssetType: import("@aethervtt/shard-assets").AssetTypeDef<Font>;

package/dist/importer.js

@@ -0,0 +1,193 @@
+import {
+  AssetStore,
+  defineAssetType,
+  defineImporter
+} from "@aethervtt/shard-assets";
+import {
+  defineResource,
+  defineSchema,
+  ShardError,
+  t
+} from "@aethervtt/shard-core";
+import { writeKtx2 } from "@aethervtt/shard-texture";
+import { buildFont } from "./build.js";
+import { Font } from "./font.js";
+import { FontSource } from "./source.js";
+const FontImportSettings = defineSchema(
+  "text/FontImportSettings",
+  {
+    charset: t.enum(["latin", "latin-extended", "custom"], {
+      description: "Glyphs to put in the atlas. latin: ASCII, Latin-1, and typographic punctuation. latin-extended: plus Latin Extended-A. custom: the characters of customCharset."
+    }),
+    customCharset: t.string({ description: "The characters to include when charset is custom." }),
+    size: t.u32({ default: 48, min: 8, max: 512, description: "Atlas pixels per em." }),
+    range: t.f32({
+      default: 4,
+      min: 1,
+      max: 32,
+      description: "Distance range in atlas pixels. Larger allows wider outlines and glows, at the cost of atlas space."
+    }),
+    fallback: t.list(t.string, {
+      description: "Fonts (paths) tried in order for characters this font lacks."
+    }),
+    kerning: t.bool({ default: true, description: "Import kerning pairs." }),
+    outlines: t.bool({
+      default: true,
+      description: "Keep the font file in the artifact, so characters outside the charset are generated at runtime."
+    })
+  },
+  { description: "Import settings for fonts (.ttf, .otf): an MSDF atlas and metrics." }
+);
+function atlasLabel(page) {
+  return page === 0 ? "Atlas" : `Atlas/${page}`;
+}
+const FontImporter = defineImporter({
+  name: "font",
+  version: 1,
+  extensions: [".ttf", ".otf"],
+  settings: FontImportSettings,
+  async import(source, ctx) {
+    const s = ctx.settings;
+    let charset = s.charset;
+    if (s.charset === "custom") {
+      if (!s.customCharset) {
+        ctx.warn('charset is "custom" but customCharset is empty; importing the latin charset.');
+        charset = "latin";
+      } else charset = s.customCharset;
+    }
+    const fallback = (s.fallback ?? []).map((p) => ctx.resolve(p));
+    let build;
+    try {
+      build = buildFont(new FontSource(source.bytes, source.path), {
+        charset,
+        size: s.size,
+        range: s.range,
+        kerning: s.kerning,
+        fallback
+      });
+    } catch (err) {
+      if (err instanceof ShardError) throw err;
+      throw new ShardError("text/import-failed", `${source.path}: ${err.message}`, {
+        path: source.path,
+        cause: err
+      });
+    }
+    if (build.missing.length > 0) {
+      const list = build.missing.slice(0, 12).map((c) => `U+${c.toString(16).toUpperCase().padStart(4, "0")}`).join(", ");
+      ctx.warn(
+        `The font lacks ${build.missing.length} charset characters (${list}${build.missing.length > 12 ? ", \u2026" : ""}); they use fallbacks or the missing-glyph box.`
+      );
+    }
+    const metrics = build.metrics;
+    const labels = build.pages.map((_, i) => atlasLabel(i));
+    const info = {
+      name: metrics.name,
+      glyphs: metrics.glyphs.length,
+      pages: build.pages.length,
+      atlas: build.pages.map((p) => `${p.width}x${p.height}`).join(", "),
+      kerningPairs: metrics.kerning.length / 3,
+      size: metrics.size,
+      range: metrics.range,
+      charset: metrics.charset ?? "custom",
+      missing: build.missing.length,
+      outlines: s.outlines !== false
+    };
+    const main = {
+      label: "",
+      type: "Font",
+      json: metrics,
+      dependencies: [...labels.map((l) => `#${l}`), ...fallback],
+      info
+    };
+    if (s.outlines !== false) main.bytes = source.bytes;
+    const assets = [main];
+    build.pages.forEach((page, i) => {
+      assets.push({
+        label: labels[i],
+        type: "Texture",
+        bytes: writeKtx2({ width: page.width, height: page.height, levels: [page.pixels] }, "data"),
+        info: {
+          width: page.width,
+          height: page.height,
+          usage: "data",
+          mips: 1,
+          font: metrics.name
+        }
+      });
+    });
+    return { assets };
+  }
+});
+class FontStore extends AssetStore {
+  fonts = /* @__PURE__ */ new Map();
+  constructor() {
+    super("Font");
+  }
+  add(item, name) {
+    const ref = super.add(item, name);
+    this.fonts.set(ref.guid, item);
+    item.linker = this;
+    this.link();
+    return ref;
+  }
+  set(guid, item) {
+    super.set(guid, item);
+    this.fonts.set(guid, item);
+    item.linker = this;
+    this.link();
+  }
+  delete(guid) {
+    this.fonts.delete(guid);
+    return super.delete(guid);
+  }
+  /** Points every font's `fallbacks` at its loaded fallback fonts. */
+  link() {
+    for (const font of this.fonts.values()) {
+      if (font.fallbackRefs.length === 0) continue;
+      const next = [];
+      for (const ref of font.fallbackRefs) {
+        const fb = ref.guid ? this.fonts.get(ref.guid) : void 0;
+        if (fb && fb !== font) next.push(fb);
+      }
+      const current = font.fallbacks;
+      if (next.length !== current.length || next.some((f, i) => f !== current[i])) {
+        font.fallbacks = next;
+      }
+    }
+  }
+}
+const Fonts = defineResource("text/Fonts", {
+  description: "Loaded fonts by guid.",
+  init: () => new FontStore()
+});
+const FontAssetType = defineAssetType("Font", {
+  store: Fonts,
+  load: (artifact, ctx) => {
+    const json = artifact.json;
+    if (json?.version !== 1 || !Array.isArray(json.glyphs)) {
+      throw new ShardError("text/invalid-metrics", `${ctx.path}: not font metrics`, {
+        path: ctx.path,
+        hint: "Re-import the font (`shard import`)."
+      });
+    }
+    const pageRefs = json.pages.map((_, i) => ctx.resolve(`#${atlasLabel(i)}`));
+    const fallbackRefs = [];
+    for (const p of json.fallback ?? []) {
+      const ref = ctx.resolve(p);
+      if (ref) fallbackRefs.push(ref);
+    }
+    return Font.fromMetrics(json, { pageRefs, source: artifact.bytes, fallbackRefs });
+  },
+  update: (existing, next) => {
+    existing.copyFrom(next);
+    existing.linker?.link();
+  }
+});
+export {
+  FontAssetType,
+  FontImportSettings,
+  FontImporter,
+  FontStore,
+  Fonts,
+  atlasLabel
+};

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+export { type PackItem, type PackResult, packRects, SkylinePacker } from '@aethervtt/shard-texture';
+export { buildFont, type FontBuild, type FontBuildOptions, fontFromBytes } from './build.js';
+export { type CharsetName, charsetCodepoints } from './charset.js';
+export { Localized, SCREEN_CORNERS, ScreenText, TEXT_ALIGNS, Text } from './components.js';
+export { Font, type FontLoadOptions, type FontMetricsJson, FontPage, GLYPH_PADDING, Glyph, type GlyphJson, RUNTIME_PAGE_SIZE, } from './font.js';
+export { atlasLabel, FontAssetType, FontImporter, FontImportSettings, type FontImportSettingsValue, FontStore, Fonts, } from './importer.js';
+export { hasGposKerning, readGposKerning } from './kerning.js';
+export { isCjk, layoutText, measureText, type TextAlign, TextLayout, type TextLayoutOptions, type TextLine, type TextMetrics, } from './layout.js';
+export { installLocalization, KEYED_COMPONENTS, Locale, LocaleState, LocaleStore, type LocaleValue, type LocalizationReport, loadStringTables, localeChain, localeMethods, localeOfPath, localizationKeysIn, localizeComponent, localizeText, PLURAL_CATEGORIES, type PluralCategory, placeholdersOf, type StringEntry, StringTable, StringTableAssetType, StringTableImporter, StringTables, setLocale, tr, validateLocalization, validateStringTable, } from './locale.js';
+export { blitMsdf, generateMsdf, type MsdfBox, type MsdfOptions, msdfBox, prepareShape, } from './msdf.js';
+export { textPlugin } from './plugin.js';
+export { describeText, prepareTexts, TextRenderer, TextStore } from './render.js';
+export { TEXT_SHADERS } from './shaders.js';
+export { type Contour, colorEdgesSimple, type Edge, EdgeColor, type EdgeKind, type OutlineCommand, type Shape, shapeBounds, shapeFromCommands, } from './shape.js';
+export { FontSource, type GlyphBitmap, type GlyphRaster, rasterizeGlyph, TOFU_ADVANCE, tofuShape, } from './source.js';