@xtyle/core 0.5.0

package/dist/host/index.d.ts

@@ -0,0 +1,29 @@
+import type { Algorithm } from "../types.js";
+export interface LoadAlgorithmOptions {
+    /** Wall-clock execution rail (ms). Defaults to the host manifest's declared limit;
+     *  raise it for work that must not be gated on how long a derivation takes. */
+    timeoutMs?: number;
+}
+export interface LoadAuthoredOptions extends LoadAlgorithmOptions {
+    /** The facade id for the authored algorithm. Defaults to `"authored"`. */
+    name?: string;
+}
+/**
+ * Load an algorithm from author-written source — the in-browser authoring path. The source is
+ * import-free: it calls `defineAlgorithm` / `defineXtyleAlgorithm` (Tier-2 or Tier-1) directly,
+ * and the pre-bundled {@link authoringPrelude} prepended here supplies those helpers on the
+ * sandbox global scope, so no bundler runs in the browser. The result is a real sandboxed
+ * `Algorithm` — the same isolation a third-party pack gets — so this, not the baked path, is
+ * where self-authored *code* (a `derive` body) must run.
+ */
+export declare function loadAuthoredAlgorithm(source: string, options?: LoadAuthoredOptions): Promise<Algorithm>;
+/**
+ * Loads a xtyle algorithm packaged as a script-format xript mod and returns a
+ * facade structurally identical to {@link Algorithm}. `initXript` is amortized
+ * across every call; each algorithm gets its own runtime (the export map is flat,
+ * so two mods would collide on `graph`). `loadMod` and `invokeExport` are
+ * synchronous for an already-loaded script mod, so every facade method below runs
+ * synchronously over a single cached runtime.
+ */
+export declare function loadAlgorithm(modManifest: unknown, source: string, options?: LoadAlgorithmOptions): Promise<Algorithm>;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/host/index.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EACX,SAAS,EAYT,MAAM,aAAa,CAAC;AAqCrB,MAAM,WAAW,oBAAoB;IACpC;mFAC+E;IAC/E,SAAS,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,mBAAoB,SAAQ,oBAAoB;IAChE,0EAA0E;IAC1E,IAAI,CAAC,EAAE,MAAM,CAAC;CACd;AAuBD;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACpC,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,mBAAwB,GAC/B,OAAO,CAAC,SAAS,CAAC,CAGpB;AAeD;;;;;;;GAOG;AACH,wBAAsB,aAAa,CAClC,WAAW,EAAE,OAAO,EACpB,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,oBAAyB,GAChC,OAAO,CAAC,SAAS,CAAC,CAiFpB"}

package/dist/host/index.js

@@ -0,0 +1,148 @@
+import { initXript } from "@xriptjs/runtime";
+import hostManifest from "../../manifest.json" with { type: "json" };
+import { authoringPrelude } from "./authoring-prelude.generated.js";
+import { createCuti } from "../cuti.js";
+import { resolveGraph } from "../graph.js";
+/**
+ * The stub `run` for a host facade's `passes`. Pass closures cannot cross the sandbox
+ * boundary, so a hosted algorithm exposes pass names for labeling but not runnable
+ * stages — `deriveTraced` returns the snapshots a caller actually needs for layers.
+ */
+function hostPassRunUnsupported() {
+    throw new Error("xtyle: host passes are name-only; pass closures do not cross the sandbox — use deriveTraced for layer snapshots");
+}
+/**
+ * The sandbox safety rails. `timeout_ms` is a wall-clock rail against a runaway mod (an
+ * infinite loop), not a performance budget. The runtime's effective rail is the smaller
+ * of the host manifest's declared `limits.timeout_ms` and the runtime hard cap, so both
+ * are raised together below. The interpreted (hosted) derivation is far slower than the
+ * native baked path — the hardest anchor sets (extreme, AAA contrast) can take ~1s+ — so
+ * the rail must clear that, and correctness work (byte-identity tests) raises it
+ * generously so it never depends on how long an interpreted derivation happens to take.
+ */
+const HOST_LIMITS = hostManifest.limits ?? {};
+const DEFAULT_TIMEOUT_MS = HOST_LIMITS.timeout_ms ?? 5000;
+/** The synthesized manifest an authored Tier-2 source loads under — the four exports the
+ *  authoring helpers register, gated by the same `color-math` capability the blessed mods use. */
+function authoredManifest(name) {
+    return {
+        xript: "0.7",
+        name,
+        version: "0.0.0",
+        capabilities: ["color-math"],
+        entry: {
+            script: "src/mod.js",
+            format: "script",
+            exports: {
+                graph: { returns: { array: "TokenNode" } },
+                traced: { returns: { array: "TraceSnapshot" } },
+                manifest: { returns: "AlgorithmManifest" },
+                invariants: { returns: { array: "InvariantResult" } },
+            },
+        },
+    };
+}
+/**
+ * Load an algorithm from author-written source — the in-browser authoring path. The source is
+ * import-free: it calls `defineAlgorithm` / `defineXtyleAlgorithm` (Tier-2 or Tier-1) directly,
+ * and the pre-bundled {@link authoringPrelude} prepended here supplies those helpers on the
+ * sandbox global scope, so no bundler runs in the browser. The result is a real sandboxed
+ * `Algorithm` — the same isolation a third-party pack gets — so this, not the baked path, is
+ * where self-authored *code* (a `derive` body) must run.
+ */
+export function loadAuthoredAlgorithm(source, options = {}) {
+    const { name = "authored", ...rest } = options;
+    return loadAlgorithm(authoredManifest(name), `${authoringPrelude}\n${source}`, rest);
+}
+let factoryPromise;
+function factory() {
+    if (!factoryPromise)
+        factoryPromise = initXript();
+    return factoryPromise;
+}
+function entryScriptKey(modManifest) {
+    const entry = modManifest.entry;
+    if (typeof entry === "string")
+        return entry;
+    return entry?.script ?? "src/mod.js";
+}
+/**
+ * Loads a xtyle algorithm packaged as a script-format xript mod and returns a
+ * facade structurally identical to {@link Algorithm}. `initXript` is amortized
+ * across every call; each algorithm gets its own runtime (the export map is flat,
+ * so two mods would collide on `graph`). `loadMod` and `invokeExport` are
+ * synchronous for an already-loaded script mod, so every facade method below runs
+ * synchronously over a single cached runtime.
+ */
+export async function loadAlgorithm(modManifest, source, options = {}) {
+    const xript = await factory();
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    // the runtime's effective rail is min(manifest limit, hard cap), so raise both in lockstep.
+    const runtimeManifest = options.timeoutMs === undefined
+        ? hostManifest
+        : { ...hostManifest, limits: { ...HOST_LIMITS, timeout_ms: timeoutMs } };
+    const rt = xript.createRuntime(runtimeManifest, {
+        hostBindings: { log: () => undefined, cuti: createCuti() },
+        capabilities: ["color-math"],
+        console,
+        hardLimits: { timeout_ms: timeoutMs, memory_mb: HOST_LIMITS.memory_mb ?? 16, max_stack_depth: HOST_LIMITS.max_stack_depth ?? 128 },
+    });
+    rt.loadMod(modManifest, {
+        fragmentSources: { [entryScriptKey(modManifest)]: source },
+    });
+    const manifest = rt.invokeExport("manifest", []);
+    const graphCache = new Map();
+    const graph = (opts) => {
+        const key = JSON.stringify(opts ?? {});
+        const cached = graphCache.get(key);
+        if (cached)
+            return cached;
+        const nodes = rt.invokeExport("graph", [opts]);
+        graphCache.set(key, nodes);
+        return nodes;
+    };
+    const invariantCache = new WeakMap();
+    const runInvariants = (ctx) => {
+        let results = invariantCache.get(ctx);
+        if (!results) {
+            results = rt.invokeExport("invariants", [ctx]);
+            invariantCache.set(ctx, results);
+        }
+        return results;
+    };
+    const invariants = Array.from({ length: manifest.invariantCount }, (_, index) => (ctx) => runInvariants(ctx)[index]);
+    const tracedCache = new Map();
+    const traced = (opts) => {
+        const key = JSON.stringify(opts ?? {});
+        const cached = tracedCache.get(key);
+        if (cached)
+            return cached;
+        let snapshots;
+        try {
+            snapshots = rt.invokeExport("traced", [opts]);
+        }
+        catch {
+            snapshots = [{ name: "derive", register: resolveGraph(graph(opts)) }];
+        }
+        tracedCache.set(key, snapshots);
+        return snapshots;
+    };
+    const passNames = manifest.passNames ?? ["settle"];
+    const passes = passNames.map((name) => ({ name, run: hostPassRunUnsupported }));
+    return {
+        id: modManifest.name ?? manifest.produces[0] ?? "unknown",
+        produces: manifest.produces,
+        knobs: manifest.knobs,
+        categories: manifest.categories,
+        derive: (opts = {}) => resolveGraph(graph(opts)),
+        lineage: (opts = {}) => graph(opts).map(({ name, value, refs }) => refs && refs.length ? { name, value, refs } : { name, value }),
+        invariants,
+        passes,
+        deriveTraced: (opts = {}) => {
+            const trace = traced(opts);
+            const last = trace[trace.length - 1];
+            return { register: last ? last.register : resolveGraph(graph(opts)), trace };
+        },
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/host/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/host/index.ts"],"names":[],"mappings":"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"}

package/dist/host/registry.d.ts

@@ -0,0 +1,24 @@
+import type { Algorithm } from "../types.js";
+/** The ids of the bundled mods the host can resolve. */
+export declare function availableAlgorithms(): string[];
+/**
+ * Resolves an algorithm by id to its host facade: loads the algorithm's xript mod
+ * from `algorithms/<id>/`, runs it through the zero-authority sandbox, and returns
+ * an `Algorithm`. Cached per id. This is the canonical resolution path — the whole
+ * CLI (`derive` / `coverage` / `gauntlet`) and the site's SSR derive through it, so
+ * the gauntlet proves the sandboxed mod that ships, not a baked copy. The baked
+ * `getAlgorithm` registry from `@xtyle/core/algorithms` remains as the byte-identical
+ * test oracle and as the synchronous first-paint fallback in the browser, where the
+ * async mod load may not have completed yet.
+ */
+export declare function resolveAlgorithm(id: string): Promise<Algorithm>;
+/**
+ * Synchronous accessor for an already-resolved mod: returns the cached `Algorithm`
+ * once `resolveAlgorithm(id)` has settled, else `null`. The hosted resolution is
+ * async (the sandbox load), but a synchronous caller — a framework reactive
+ * computation, a first-paint path — can warm the cache with `resolveAlgorithm`,
+ * then read the canonical mod here without awaiting, falling back only for the
+ * window before the load lands.
+ */
+export declare function snapshotAlgorithm(id: string): Algorithm | null;
+//# sourceMappingURL=registry.d.ts.map

package/dist/host/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/host/registry.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAW7C,wDAAwD;AACxD,wBAAgB,mBAAmB,IAAI,MAAM,EAAE,CAE9C;AAgCD;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,CAqB/D;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAE9D"}

package/dist/host/registry.js

@@ -0,0 +1,83 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, parse } from "node:path";
+import { fileURLToPath } from "node:url";
+import { loadAlgorithm } from "./index.js";
+const MOD_DIRS = {
+    "xtyle-default": "xtyle-default",
+    "xtyle-hc": "xtyle-hc",
+    "xtyle-quiet": "xtyle-quiet",
+    "xtyle-loud": "xtyle-loud",
+    "nxi-nite": "nxi-nite",
+};
+/** The ids of the bundled mods the host can resolve. */
+export function availableAlgorithms() {
+    return Object.keys(MOD_DIRS);
+}
+/**
+ * Walks up from this module toward the filesystem root looking for the sibling
+ * `algorithms/` directory that holds the mods. A fixed relative offset breaks the
+ * moment a consumer bundles this file to a different depth (the site's SSR build
+ * does exactly that), so the directory is discovered by marker instead.
+ */
+function findAlgorithmsRoot() {
+    let dir = dirname(fileURLToPath(import.meta.url));
+    const { root } = parse(dir);
+    while (true) {
+        const candidate = join(dir, "algorithms");
+        if (existsSync(join(candidate, "xtyle-default", "mod-manifest.json"))) {
+            return candidate;
+        }
+        if (dir === root)
+            break;
+        dir = dirname(dir);
+    }
+    throw new Error("xtyle: could not locate the algorithms/ directory");
+}
+let algorithmsRoot;
+function algorithmsDir() {
+    if (!algorithmsRoot)
+        algorithmsRoot = findAlgorithmsRoot();
+    return algorithmsRoot;
+}
+const cache = new Map();
+const resolved = new Map();
+/**
+ * Resolves an algorithm by id to its host facade: loads the algorithm's xript mod
+ * from `algorithms/<id>/`, runs it through the zero-authority sandbox, and returns
+ * an `Algorithm`. Cached per id. This is the canonical resolution path — the whole
+ * CLI (`derive` / `coverage` / `gauntlet`) and the site's SSR derive through it, so
+ * the gauntlet proves the sandboxed mod that ships, not a baked copy. The baked
+ * `getAlgorithm` registry from `@xtyle/core/algorithms` remains as the byte-identical
+ * test oracle and as the synchronous first-paint fallback in the browser, where the
+ * async mod load may not have completed yet.
+ */
+export function resolveAlgorithm(id) {
+    const cached = cache.get(id);
+    if (cached)
+        return cached;
+    const dir = MOD_DIRS[id];
+    if (!dir) {
+        return Promise.reject(new Error(`xtyle: no hosted mod for algorithm "${id}" (have: ${Object.keys(MOD_DIRS).join(", ")})`));
+    }
+    const modDir = join(algorithmsDir(), dir);
+    const modManifest = JSON.parse(readFileSync(join(modDir, "mod-manifest.json"), "utf8"));
+    const source = readFileSync(join(modDir, "src/mod.js"), "utf8");
+    const loaded = loadAlgorithm(modManifest, source).then((algorithm) => {
+        resolved.set(id, algorithm);
+        return algorithm;
+    });
+    cache.set(id, loaded);
+    return loaded;
+}
+/**
+ * Synchronous accessor for an already-resolved mod: returns the cached `Algorithm`
+ * once `resolveAlgorithm(id)` has settled, else `null`. The hosted resolution is
+ * async (the sandbox load), but a synchronous caller — a framework reactive
+ * computation, a first-paint path — can warm the cache with `resolveAlgorithm`,
+ * then read the canonical mod here without awaiting, falling back only for the
+ * window before the load lands.
+ */
+export function snapshotAlgorithm(id) {
+    return resolved.get(id) ?? null;
+}
+//# sourceMappingURL=registry.js.map

package/dist/host/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/host/registry.ts"],"names":[],"mappings":"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"}

package/dist/icon-builder.d.ts

@@ -0,0 +1,155 @@
+/**
+ * The icon builder: a terse name grammar, a tokenizer that parses a name into a
+ * layered composition, and a `composeIcon` renderer that assembles the SVG from
+ * named primitives, the same way an algorithm assembles a token register from
+ * anchors. The composition is the cheap, materialized artifact; the primitive
+ * library, the grammar, and the compose engine are the durable, reusable asset.
+ *
+ * A composition is a back-to-front list of layers. Each layer places a primitive
+ * (a shape, a frame, a band, or a symbol) at a grid position, sized and rotated,
+ * painted in a color or subtracted from the art beneath it. Colors resolve three
+ * ways: a literal, a theme token (`--accent`), or a series slot (`series:2`) off a
+ * scheme. With a derived register the token and series colors bake to concrete
+ * values (a static export); without one they emit `var(--…)` so the mark
+ * re-colors live with the theme.
+ *
+ * The full name grammar is documented in `docs/icon-name-grammar.md`.
+ */
+import { type SeriesScheme } from "./series.js";
+import type { TokenRegister } from "./types.js";
+/** A primitive: inner SVG markup on the 24×24 grid, authored centered so a layer's scale, rotation, and position transform it uniformly. */
+export interface IconPrimitive {
+    body: string;
+    /** The version this primitive first shipped in; drives a "new" marker in authoring surfaces (the Bench palette). */
+    since?: string;
+    /** Plain-language taxonomy for search / filter / organize — descriptive terms, not the internal key. */
+    tags?: string[];
+}
+/** A layer's outline: a stroke size step (1 thin, 2 medium, 3 thick) and its color. */
+export interface IconOutline {
+    size: number;
+    color: string;
+}
+/** One placement in a composition: a primitive, a color, a transform, and optional outline / flip / knockout. */
+export interface IconLayer {
+    /** The primitive name, a key into `ICON_PRIMITIVES` (or a short keyword resolved through `PRIMITIVE_KEYWORDS`). */
+    primitive: string;
+    /** A literal color, `currentColor`, `transparent`, a token (`--accent`), or a series slot (`series:2`). Omit to inherit `currentColor`. */
+    fill?: string;
+    /** Uniform scale about the center (default 1). The grammar's `s{%}` maps here as a fraction of the full grid. */
+    scale?: number;
+    /** Rotation in degrees about the object's own center. */
+    rotate?: number;
+    /** Translate on the grid (24-unit space); the grammar folds the grid position and any fine offset into this. */
+    x?: number;
+    y?: number;
+    /** Layer opacity (0–1). */
+    opacity?: number;
+    /** A stroke around the shape. */
+    outline?: IconOutline;
+    /** Mirror horizontally about the center. */
+    flipH?: boolean;
+    /** Mirror vertically about the center. */
+    flipV?: boolean;
+    /** Subtract this shape from the art beneath it (a hole to the page); a later layer paints over the hole. */
+    knockout?: boolean;
+    /** Invert the shape's coverage region — the layer covers everything *except* the shape. Paired with
+     * `knockout` (`-i-ko`) it clips the accumulated art to the shape's silhouette (a `circle` → circular
+     * clip, a `heart` → heart clip); painted alone (`-i`) it fills the complement, a field with a shape-hole. */
+    invert?: boolean;
+}
+/** A whole-icon drop shadow (a `---` finish): a colored, offset, blurred copy cast behind the mark. */
+export interface IconDropShadow {
+    /** Shadow color spec (resolved through `resolveColor`, so a ladder slot / token / literal all work). */
+    color: string;
+    /** Offset from the mark, in 24-grid units. */
+    dx: number;
+    dy: number;
+    /** Gaussian blur radius, in 24-grid units. */
+    blur: number;
+}
+/** A layered icon composition, back to front. */
+export interface IconComposition {
+    layers: IconLayer[];
+    /** An accessible name; when set the SVG is `role="img"`, otherwise it is decorative. */
+    label?: string;
+    /** A whole-icon drop shadow declared in the `---` finish (`d{color}p{dir}s{size}t{soft}`). */
+    dropShadow?: IconDropShadow;
+}
+export interface ComposeIconOptions {
+    /** A derived register: when present, token and series colors bake to concrete values; without it they emit `var(--…)`. */
+    register?: TokenRegister;
+    /** The scheme a `series:N` slot draws from (default `accents`). */
+    scheme?: SeriesScheme | string[];
+    /** A class on the root `<svg>`, so a host can size / spin / tone the mark like a functional glyph. */
+    className?: string;
+    /** A `part` on the root `<svg>`, for `::part()` styling from a consumer. */
+    part?: string;
+}
+/** The seed primitive library: shapes, frames, bars, symbols, and the functional glyphs. Each carries
+ * plain-language `tags` for search and filter; the keys are internal identifiers, not a taxonomy. */
+export declare const ICON_PRIMITIVES: Record<string, IconPrimitive>;
+/** Short grammar keywords → primitive-library names. A keyword the map doesn't cover is used as-is (so `shape-shield` also works verbatim). */
+export declare const PRIMITIVE_KEYWORDS: Record<string, string>;
+/** Resolve a grammar keyword (`star`) or a bare library name (`symbol-star`) to its library name. */
+export declare function resolvePrimitiveName(nameOrKeyword: string): string;
+/** The version a primitive first shipped in, addressed by keyword or library name (undefined if unknown). */
+export declare function primitiveSince(nameOrKeyword: string): string | undefined;
+/** A primitive's plain-language tags, addressed by keyword or library name (empty when unknown). */
+export declare function primitiveTags(nameOrKeyword: string): string[];
+/** True when `name` resolves to a primitive in the library. */
+export declare function hasPrimitive(name: string): boolean;
+/** Every primitive name in the library. */
+export declare const ICON_PRIMITIVE_NAMES: string[];
+/** The number of series slots the grammar exposes (`s1`..`s5` → `series:0`..`series:4`); a scheme
+ * always resolves to this many evenly-spread colors so a slot is a stable pick across schemes. */
+export declare const ICON_SERIES_COUNT = 5;
+/** Maps a grammar color slot to a fill spec: 0 transparent, 1 `--fg-0`, 2 `--bg-0`, N≥3 the (N−3)th series color. */
+export declare function colorSlot(slot: number): string;
+/** The `xtyle-icon` root class for a glyph or mark, shared by the element and the Astro binding so
+ * the size / tone / spin chrome stays in one place. (The fragment sandbox keeps its own copy: that
+ * module must stay import-free to bundle whole.) */
+export declare function iconClass(opts: {
+    size?: string;
+    tone?: string | null;
+    spin?: boolean;
+    extra?: string;
+}): string;
+/**
+ * Composes a layered icon into an SVG string. Layers paint back to front; a
+ * `knockout` layer punches its shape through everything beneath it (a later layer
+ * paints over the hole). An unknown primitive renders a visible placeholder box
+ * rather than nothing, so a typo shows on screen.
+ */
+export declare function composeIcon(composition: IconComposition, opts?: ComposeIconOptions): string;
+/**
+ * Composes an icon for a live surface: series slots resolve against `opts.register`
+ * (the live cascade) while token fills stay `var(--…)`, so a mark bakes only what a
+ * plain CSS variable can't carry and re-colors with the theme for everything else.
+ */
+export declare function composeIconThemed(composition: IconComposition, opts?: ComposeIconOptions): string;
+/** A parsed icon name: its accessible label (humanized) and the composition its spec describes. */
+export interface ParsedIconName {
+    label: string | null;
+    composition: IconComposition;
+}
+/**
+ * Parses an icon name into a composition. A name is a spec when it contains `--`
+ * (a label, then `--`-separated objects, then an optional `---` finish). A bare
+ * name with no `--` is a lookup, not a spec, and returns `null` so the caller can
+ * fall back to the functional set or a baked artifact.
+ */
+export declare function parseIconName(name: string): ParsedIconName | null;
+/** A name→mark generator: a pure function from a name to a composition, or null when the name isn't its shape. */
+export type IconGenerator = (name: string) => ParsedIconName | null;
+/**
+ * Registers an alternative name→mark generator (a hashed-identicon mode, a domain-specific mark
+ * set). Generators are tried in registration order after the blessed default grammar, so an
+ * alternative claims only the names the default declines. This is the seam that keeps the mark
+ * generator swappable the way a token algorithm is: the engine owns `composeIcon` + the primitive
+ * library, an author owns how a string becomes a composition.
+ */
+export declare function registerIconGenerator(generator: IconGenerator): void;
+/** Resolves a name to a mark through the registered generators (the default grammar first), or null when none claims it. */
+export declare function resolveIconMark(name: string): ParsedIconName | null;
+//# sourceMappingURL=icon-builder.d.ts.map

package/dist/icon-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"icon-builder.d.ts","sourceRoot":"","sources":["../src/icon-builder.ts"],"names":[],"mappings":"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"}