@graphics-i18n/core

Platform-agnostic pipeline for LPKG localized graphics packages: container reading (zip via fflate, plus *.lpkg.json debug bundles), manifest validation, locale negotiation, patch/locale application, deterministic text fitting, effective-scene building, caching and migration. No React, DOM or native dependency — runs in Node, browsers, workers and SSR.

Installation

pnpm add @graphics-i18n/core

If you are rendering with @graphics-i18n/react or @graphics-i18n/react-native, core is already included as a dependency — install it directly only for server pipelines, tooling or custom renderers.

Core API

import {
  loadLocalizedGraphic,
  validateLocalizedGraphicPackage,
} from '@graphics-i18n/core';

const { manifest, effectiveScene, container } = await loadLocalizedGraphic(
  source,
  'fr',
);

effectiveScene is the backend-agnostic draw list (EffectiveNode[] with resolved text, bounds, matrices and z-order) that renderers consume.

Text fitting runs against a TextMeasurer; the built-in approxTextMeasurer is deterministic and font-agnostic, and renderers can pass a platform-accurate measurer via LoadOptions.createMeasurer.

Authoring tools (Node only)

import {
  packLpkgFromFiles,
  packLpkgDir,
  validateLpkg,
} from '@graphics-i18n/core/tools';

The same operations are available on the command line:

lpkg pack ./my-banner -o banner.lpkg   # zips a spec §3.2 directory, adds chunk hashes
lpkg validate banner.lpkg

@graphics-i18n/core/testing exports the shared example-package fixtures used by the lib test suites.

Behavior notes

  • String fallback: requested pack → fallback pack → node fallbackText → empty string, each miss recorded as a STRING_MISSING diagnostic in effectiveScene.meta.diagnostics.
  • Badge text is literal unless prefixed with @ ("@promo.discount").
  • Override precedence for text nodes: scene patch → node localeOverrides[locale] → locale pack nodeOverrides (last wins).
  • RTL: direction comes from the locale pack (or locale heuristic); text nodes mirror alignment unless rtlAware: false.

v1 limitations

  • fit.mode: 'scroll' renders as clip; resize-box only grows height.
  • Group layout.justify and align: 'stretch' are ignored; clipPath and blendMode are not yet applied.
  • Path bounds are approximate (coordinate scan, curves overestimate).