@ideare/kit 0.0.0-stage → 0.1.0-next.0

package/dist/text/engine.d.ts

@@ -0,0 +1,128 @@
+import type { FontKey, FontResolver } from "./fonts.ts";
+/**
+ * The text engine: HarfBuzz shapes text into glyph paths, so line breaks, fit and pixels come
+ * from one computation in the browser and on the server (docs/spikes/text.md: byte-identical
+ * SVG in Bun and Chrome). resvg never sees a <text> element.
+ */
+type Harfbuzz = typeof import("harfbuzzjs");
+type HbFont = InstanceType<Harfbuzz["Font"]>;
+/** harfbuzzjs loads 444 kB of wasm at import, so it is imported on first use only. */
+export declare function loadHarfbuzz(): Promise<Harfbuzz>;
+type PathCommand = {
+    type: string;
+    values: number[];
+};
+/** A font ready to shape: the HarfBuzz objects plus the numbers layout needs. */
+export type LoadedFont = {
+    key: FontKey;
+    upem: number;
+    ascender: number;
+    descender: number;
+    /** The code points the file has glyphs for. */
+    coverage: Set<number>;
+    /** The copyright and license strings from the name table (ids 0 and 13). */
+    copyright: string;
+    license: string;
+    /** The file itself, for hashing and for fonts.css. */
+    bytes: Uint8Array;
+    hb: HbFont;
+    paths: Map<number, PathCommand[]>;
+};
+type ShapedGlyph = {
+    gid: number;
+    x: number;
+    dx: number;
+    dy: number;
+    cluster: number;
+};
+/** One shaped run at a size: glyph positions in px from the run's start, and its width. */
+export type Run = {
+    glyphs: ShapedGlyph[];
+    width: number;
+    missing: string[];
+};
+export type TextAlign = "start" | "center" | "end";
+export type TextVAlign = "top" | "middle" | "bottom";
+export type TextBlock = {
+    text: string;
+    font: LoadedFont;
+    /** px */
+    size: number;
+    /** Line height as a multiple of the size. */
+    lineHeight: number;
+    /** Letter spacing in em. */
+    tracking?: number;
+    align?: TextAlign;
+    valign?: TextVAlign;
+    /** The box the text must stay inside, in px. */
+    box: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    };
+    maxLines?: number;
+    /** shrink: the largest size from `min` to `size` that fits. none: `size` or an overflow. */
+    fit?: {
+        mode: "none" | "shrink";
+        min: number;
+    };
+    locale?: string;
+    uppercase?: boolean;
+};
+export type TextOverflow = {
+    /** width: a word is wider than the box. lines: more lines than allowed. height: too tall. */
+    reason: "width" | "lines" | "height";
+    /** The size the text was laid out at, after shrinking. */
+    size: number;
+    /** What would be needed: the widest word's width, the line count or the block height. */
+    needed: number;
+    /** What the box allows. */
+    allowed: number;
+};
+export type TextLayout = {
+    /** One `d` for the whole block, in the scene's px. Empty when there is no visible glyph. */
+    d: string;
+    size: number;
+    lines: {
+        text: string;
+        width: number;
+        x: number;
+        baseline: number;
+    }[];
+    /** The block's box: the lines' extent, not the frame. */
+    bounds: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    };
+    overflow?: TextOverflow;
+    /** Characters the font has no glyph for. They are never drawn as a box. */
+    missing: string[];
+};
+/** Round for output: 2 decimals keeps paths small and identical on every platform. */
+export declare function fmt(value: number): string;
+export declare class TextEngine {
+    private readonly fonts;
+    private buffer;
+    private readonly runs;
+    private readonly hb;
+    private readonly resolver;
+    private constructor();
+    static create(resolver: FontResolver): Promise<TextEngine>;
+    /** Load (once) and prepare a font. */
+    font(key: FontKey): Promise<LoadedFont>;
+    /** Wrap bytes you already hold, for tests and for fonts outside any resolver. */
+    fromBytes(key: FontKey, bytes: Uint8Array): LoadedFont;
+    private prepare;
+    /** Shape one line of text at a size. Cached, since line breaking measures the same runs. */
+    shape(font: LoadedFont, text: string, size: number, tracking?: number): Run;
+    /** The outline of a shaped run as one path, starting at (x, baseline). */
+    runPath(font: LoadedFont, run: Run, size: number, x: number, baseline: number): string;
+    /** Break, fit and outline a block of text. Overflow is reported, never cut or ellipsized. */
+    layout(block: TextBlock): TextLayout;
+    private breakLines;
+    private place;
+}
+export {};

package/dist/text/engine.js

@@ -0,0 +1,245 @@
+let harfbuzz;
+/** harfbuzzjs loads 444 kB of wasm at import, so it is imported on first use only. */
+export function loadHarfbuzz() {
+    harfbuzz ??= import("harfbuzzjs");
+    return harfbuzz;
+}
+/** Round for output: 2 decimals keeps paths small and identical on every platform. */
+export function fmt(value) {
+    const rounded = Math.round(value * 100) / 100;
+    return Object.is(rounded, -0) ? "0" : String(rounded);
+}
+export class TextEngine {
+    fonts = new Map();
+    buffer;
+    runs = new Map();
+    hb;
+    resolver;
+    constructor(hb, resolver) {
+        this.hb = hb;
+        this.resolver = resolver;
+    }
+    static async create(resolver) {
+        return new TextEngine(await loadHarfbuzz(), resolver);
+    }
+    /** Load (once) and prepare a font. */
+    font(key) {
+        const id = `${key.id}:${key.weight}:${key.style ?? "normal"}`;
+        let pending = this.fonts.get(id);
+        if (!pending) {
+            pending = this.resolver
+                .load({ ...key, format: "ttf" })
+                .then((bytes) => this.prepare(key, bytes));
+            pending.catch(() => this.fonts.delete(id));
+            this.fonts.set(id, pending);
+        }
+        return pending;
+    }
+    /** Wrap bytes you already hold, for tests and for fonts outside any resolver. */
+    fromBytes(key, bytes) {
+        return this.prepare(key, bytes);
+    }
+    prepare(key, bytes) {
+        const { hb } = this;
+        const face = new hb.Face(new hb.Blob(bytes), 0);
+        const font = new hb.Font(face);
+        const extents = font.hExtents();
+        const name = (id) => {
+            try {
+                return face.getName(id, "en") ?? "";
+            }
+            catch {
+                return "";
+            }
+        };
+        return {
+            key,
+            upem: face.upem,
+            ascender: extents.ascender,
+            descender: extents.descender,
+            coverage: new Set(face.collectUnicodes()),
+            copyright: name(0),
+            license: name(13),
+            bytes,
+            hb: font,
+            paths: new Map(),
+        };
+    }
+    /** Shape one line of text at a size. Cached, since line breaking measures the same runs. */
+    shape(font, text, size, tracking = 0) {
+        const cacheKey = `${font.key.id}:${font.key.weight}:${size}:${tracking}:${text}`;
+        const cached = this.runs.get(cacheKey);
+        if (cached)
+            return cached;
+        const { hb } = this;
+        this.buffer ??= new hb.Buffer();
+        const buffer = this.buffer;
+        buffer.reset();
+        buffer.addText(text);
+        buffer.guessSegmentProperties();
+        hb.shape(font.hb, buffer);
+        const scale = size / font.upem;
+        const extra = tracking * size;
+        const glyphs = [];
+        const missing = new Set();
+        let x = 0;
+        const infos = buffer.getGlyphInfosAndPositions();
+        infos.forEach((info, index) => {
+            if (info.codepoint === 0) {
+                const char = String.fromCodePoint(text.codePointAt(info.cluster) ?? 0xfffd);
+                if (char.trim())
+                    missing.add(char);
+            }
+            glyphs.push({
+                gid: info.codepoint,
+                x,
+                dx: (info.xOffset ?? 0) * scale,
+                dy: (info.yOffset ?? 0) * scale,
+                cluster: info.cluster,
+            });
+            x += (info.xAdvance ?? 0) * scale + (index < infos.length - 1 ? extra : 0);
+        });
+        const run = { glyphs, width: x, missing: [...missing] };
+        if (this.runs.size > 5000)
+            this.runs.clear();
+        this.runs.set(cacheKey, run);
+        return run;
+    }
+    /** The outline of a shaped run as one path, starting at (x, baseline). */
+    runPath(font, run, size, x, baseline) {
+        const scale = size / font.upem;
+        const parts = [];
+        for (const glyph of run.glyphs) {
+            if (glyph.gid === 0)
+                continue;
+            let commands = font.paths.get(glyph.gid);
+            if (!commands) {
+                commands = font.hb.glyphToJson(glyph.gid);
+                font.paths.set(glyph.gid, commands);
+            }
+            const ox = x + glyph.x + glyph.dx;
+            const oy = baseline - glyph.dy;
+            for (const command of commands) {
+                const values = command.values;
+                const points = [];
+                for (let i = 0; i + 1 < values.length; i += 2) {
+                    points.push(`${fmt(ox + (values[i] ?? 0) * scale)} ${fmt(oy - (values[i + 1] ?? 0) * scale)}`);
+                }
+                parts.push(`${command.type}${points.join(" ")}`);
+            }
+        }
+        return parts.join("");
+    }
+    /** Break, fit and outline a block of text. Overflow is reported, never cut or ellipsized. */
+    layout(block) {
+        const text = block.uppercase ? block.text.toLocaleUpperCase(block.locale) : block.text;
+        const at = (size) => this.breakLines(block, text, size);
+        let size = block.size;
+        let attempt = at(size);
+        if (attempt.overflow && block.fit?.mode === "shrink") {
+            // The largest size on a half-pixel grid from `min` up that fits. When even `min`
+            // overflows, lay out at `min` and report it.
+            const min = Math.min(block.fit.min, block.size);
+            const steps = Math.floor((block.size - min) / 0.5);
+            const sizeOf = (step) => min + step * 0.5;
+            const smallest = at(min);
+            size = min;
+            attempt = smallest;
+            if (!smallest.overflow) {
+                let low = 0;
+                let high = steps;
+                while (low < high) {
+                    const mid = Math.ceil((low + high) / 2);
+                    if (at(sizeOf(mid)).overflow)
+                        high = mid - 1;
+                    else
+                        low = mid;
+                }
+                size = sizeOf(low);
+                attempt = at(size);
+            }
+        }
+        return this.place(block, attempt.lines, size, attempt.overflow, attempt.missing);
+    }
+    breakLines(block, text, size) {
+        const tracking = block.tracking ?? 0;
+        const width = (line) => this.shape(block.font, line, size, tracking).width;
+        const maxWidth = block.box.w;
+        const lines = [];
+        let overflow;
+        const missing = new Set();
+        for (const paragraph of text.split("\n")) {
+            const words = paragraph.split(/[ \t]+/).filter(Boolean);
+            if (words.length === 0) {
+                lines.push({ text: "", width: 0 });
+                continue;
+            }
+            let current = "";
+            for (const word of words) {
+                const candidate = current ? `${current} ${word}` : word;
+                const candidateWidth = width(candidate);
+                if (!current || candidateWidth <= maxWidth) {
+                    current = candidate;
+                    continue;
+                }
+                lines.push({ text: current, width: width(current) });
+                current = word;
+            }
+            lines.push({ text: current, width: width(current) });
+        }
+        for (const line of lines) {
+            for (const char of this.shape(block.font, line.text, size, tracking).missing)
+                missing.add(char);
+            if (!overflow && line.width > maxWidth + 0.01) {
+                overflow = { reason: "width", size, needed: line.width, allowed: maxWidth };
+            }
+        }
+        const height = lines.length * size * block.lineHeight;
+        if (!overflow && block.maxLines !== undefined && lines.length > block.maxLines) {
+            overflow = { reason: "lines", size, needed: lines.length, allowed: block.maxLines };
+        }
+        if (!overflow && height > block.box.h + 0.01) {
+            overflow = { reason: "height", size, needed: height, allowed: block.box.h };
+        }
+        return { lines, overflow, missing: [...missing] };
+    }
+    place(block, lines, size, overflow, missing) {
+        const { font, box } = block;
+        const tracking = block.tracking ?? 0;
+        const scale = size / font.upem;
+        const gap = size * block.lineHeight;
+        const height = lines.length * gap;
+        const valign = block.valign ?? "top";
+        const top = valign === "top"
+            ? box.y
+            : valign === "middle"
+                ? box.y + (box.h - height) / 2
+                : box.y + box.h - height;
+        // Center the font's ascent-to-descent span inside each line's gap.
+        const glyphSpan = (font.ascender - font.descender) * scale;
+        const firstBaseline = top + (gap - glyphSpan) / 2 + font.ascender * scale;
+        const align = block.align ?? "start";
+        const placed = [];
+        const parts = [];
+        let minX = Number.POSITIVE_INFINITY;
+        let maxX = Number.NEGATIVE_INFINITY;
+        lines.forEach((line, index) => {
+            const x = align === "start"
+                ? box.x
+                : align === "center"
+                    ? box.x + (box.w - line.width) / 2
+                    : box.x + box.w - line.width;
+            const baseline = firstBaseline + index * gap;
+            placed.push({ text: line.text, width: line.width, x, baseline });
+            if (line.text) {
+                parts.push(this.runPath(font, this.shape(font, line.text, size, tracking), size, x, baseline));
+                minX = Math.min(minX, x);
+                maxX = Math.max(maxX, x + line.width);
+            }
+        });
+        const bounds = minX <= maxX
+            ? { x: minX, y: top, w: maxX - minX, h: height }
+            : { x: box.x, y: top, w: 0, h: height };
+        return { d: parts.join(""), size, lines: placed, bounds, overflow, missing };
+    }
+}

package/dist/text/fonts.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Where font bytes come from. The kit never bundles a font: a resolver hands it the static TTF
+ * (one file per weight) for a Fontsource id. The default reads Fontsource's CDN with fetch and
+ * keeps the bytes in memory; `@ideare/kit/node` adds a disk cache, and the server can point a
+ * resolver at its R2 mirror (`fonts/<sha256>.ttf`).
+ */
+export type FontStyle = "normal" | "italic";
+export type FontFormat = "ttf" | "woff2";
+export type FontKey = {
+    id: string;
+    weight: number;
+    style?: FontStyle;
+};
+export interface FontResolver {
+    load(font: FontKey & {
+        format?: FontFormat;
+    }): Promise<Uint8Array>;
+}
+/** Fontsource's CDN. Every family there ships per-weight static files for each subset. */
+export declare const FONTSOURCE_CDN = "https://cdn.jsdelivr.net/fontsource/fonts";
+/**
+ * The CDN address of one static file. The latin subset covers pt-BR and es (Latin-1 plus the
+ * euro sign and typographic quotes). `version` pins the bytes; "latest" follows Fontsource.
+ */
+export declare function fontsourceUrl(font: FontKey & {
+    format?: FontFormat;
+}, version?: string, subset?: string): string;
+/** The cache key for one file, shared by every resolver. */
+export declare function fontFileName(font: FontKey & {
+    format?: FontFormat;
+}): string;
+export declare class FontLoadError extends Error {
+    readonly font: FontKey;
+    readonly status: number | undefined;
+    constructor(font: FontKey, status: number | undefined, message: string);
+}
+/**
+ * Fetch from Fontsource, keeping each file in memory once loaded. `versions` pins a family to a
+ * Fontsource release (the curated catalog does this), so the same brand always draws with the
+ * same bytes.
+ */
+export declare function fetchFontResolver(options?: {
+    fetch?: typeof fetch;
+    versions?: Record<string, string>;
+    /**
+     * Where to fetch each file, when not from Fontsource: a page whose CSP allows only its
+     * own origin and cdn.ideare.app points this at its own copies.
+     */
+    url?: (font: FontKey & {
+        format?: FontFormat;
+    }) => string;
+}): FontResolver;
+/** ideare's API serves the catalog's TTFs at this path, for pages whose CSP allows no CDN. */
+export declare function ideareFontUrl(apiOrigin: string, font: FontKey & {
+    format?: FontFormat;
+}, version: string): string;

package/dist/text/fonts.js

@@ -0,0 +1,65 @@
+/**
+ * Where font bytes come from. The kit never bundles a font: a resolver hands it the static TTF
+ * (one file per weight) for a Fontsource id. The default reads Fontsource's CDN with fetch and
+ * keeps the bytes in memory; `@ideare/kit/node` adds a disk cache, and the server can point a
+ * resolver at its R2 mirror (`fonts/<sha256>.ttf`).
+ */
+/** Fontsource's CDN. Every family there ships per-weight static files for each subset. */
+export const FONTSOURCE_CDN = "https://cdn.jsdelivr.net/fontsource/fonts";
+/**
+ * The CDN address of one static file. The latin subset covers pt-BR and es (Latin-1 plus the
+ * euro sign and typographic quotes). `version` pins the bytes; "latest" follows Fontsource.
+ */
+export function fontsourceUrl(font, version = "latest", subset = "latin") {
+    const style = font.style ?? "normal";
+    return `${FONTSOURCE_CDN}/${font.id}@${version}/${subset}-${font.weight}-${style}.${font.format ?? "ttf"}`;
+}
+/** The cache key for one file, shared by every resolver. */
+export function fontFileName(font) {
+    return `${font.id}-${font.weight}-${font.style ?? "normal"}.${font.format ?? "ttf"}`;
+}
+export class FontLoadError extends Error {
+    font;
+    status;
+    constructor(font, status, message) {
+        super(message);
+        this.name = "FontLoadError";
+        this.font = font;
+        this.status = status;
+    }
+}
+/**
+ * Fetch from Fontsource, keeping each file in memory once loaded. `versions` pins a family to a
+ * Fontsource release (the curated catalog does this), so the same brand always draws with the
+ * same bytes.
+ */
+export function fetchFontResolver(options = {}) {
+    const cache = new Map();
+    const doFetch = options.fetch ?? fetch;
+    return {
+        load(font) {
+            const key = fontFileName(font);
+            let pending = cache.get(key);
+            if (!pending) {
+                pending = (async () => {
+                    const url = options.url?.(font) ??
+                        fontsourceUrl(font, options.versions?.[font.id] ?? "latest");
+                    const response = await doFetch(url);
+                    if (!response.ok) {
+                        throw new FontLoadError(font, response.status, `Could not download ${font.id} ${font.weight} (${response.status} from ${url}). Check the font id and weight, then try again.`);
+                    }
+                    return new Uint8Array(await response.arrayBuffer());
+                })();
+                // A failed download is not remembered, so the next call can retry.
+                pending.catch(() => cache.delete(key));
+                cache.set(key, pending);
+            }
+            return pending;
+        },
+    };
+}
+/** ideare's API serves the catalog's TTFs at this path, for pages whose CSP allows no CDN. */
+export function ideareFontUrl(apiOrigin, font, version) {
+    const style = font.style && font.style !== "normal" ? `-${font.style}` : "";
+    return `${apiOrigin.replace(/\/$/, "")}/public/fonts/${font.id}/${version}/${font.weight}${style}.${font.format ?? "ttf"}`;
+}

package/dist/version.d.ts

@@ -0,0 +1,2 @@
+/** The kit's version, kept equal to package.json's (src/brand/schema.test.ts checks it). */
+export declare const VERSION = "0.1.0-next.0";

package/dist/version.js

@@ -0,0 +1,2 @@
+/** The kit's version, kept equal to package.json's (src/brand/schema.test.ts checks it). */
+export const VERSION = "0.1.0-next.0";

package/dist/wasm/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The rasterizer for browsers and for the CLI: @resvg/resvg-wasm 2.6.2, the same resvg 0.34 as
+ * `@ideare/kit/resvg`, built to wasm, so `npx ideare` installs nothing native. The kit only ever
+ * hands it glyph paths, so it never needs a font.
+ *
+ * The caller says where the wasm comes from, because only the caller knows: a browser passes a
+ * URL its bundler made (`import wasm from "@resvg/resvg-wasm/index_bg.wasm?url"` in Vite), and
+ * Node passes the file's bytes.
+ */
+import { type InitInput } from "@resvg/resvg-wasm";
+import type { Rasterizer } from "../files/raster.ts";
+export type WasmSource = InitInput | Promise<InitInput>;
+export declare function wasmRasterizer(options: {
+    wasm: WasmSource;
+}): Rasterizer;

package/dist/wasm/index.js

@@ -0,0 +1,46 @@
+/**
+ * The rasterizer for browsers and for the CLI: @resvg/resvg-wasm 2.6.2, the same resvg 0.34 as
+ * `@ideare/kit/resvg`, built to wasm, so `npx ideare` installs nothing native. The kit only ever
+ * hands it glyph paths, so it never needs a font.
+ *
+ * The caller says where the wasm comes from, because only the caller knows: a browser passes a
+ * URL its bundler made (`import wasm from "@resvg/resvg-wasm/index_bg.wasm?url"` in Vite), and
+ * Node passes the file's bytes.
+ */
+import { Resvg, initWasm } from "@resvg/resvg-wasm";
+// resvg-wasm may be initialized once per page or process, so every rasterizer shares this.
+let ready;
+function init(wasm) {
+    ready ??= initWasm(wasm).catch((error) => {
+        ready = undefined; // a failed download may work next time
+        throw error;
+    });
+    return ready;
+}
+export function wasmRasterizer(options) {
+    return async (svg, { width }) => {
+        await init(options.wasm);
+        const resvg = new Resvg(svg, {
+            fitTo: { mode: "width", value: Math.round(width) },
+            font: { loadSystemFonts: false },
+        });
+        // Each object holds wasm memory that JavaScript's collector never frees.
+        try {
+            const image = resvg.render();
+            try {
+                return {
+                    png: image.asPng(),
+                    pixels: image.pixels,
+                    width: image.width,
+                    height: image.height,
+                };
+            }
+            finally {
+                image.free();
+            }
+        }
+        finally {
+            resvg.free();
+        }
+    };
+}

package/package.json

@@ -1,6 +1,79 @@
 {
-  "name": "@ideare/kit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+    "name": "@ideare/kit",
+    "version": "0.1.0-next.0",
+    "description": "The brand kit engine behind ideare: brand.json, file generation, checks and the scene renderer.",
+    "license": "MIT",
+    "homepage": "https://ideare.app",
+    "type": "module",
+    "exports": {
+        ".": {
+            "bun": "./src/index.ts",
+            "types": "./dist/index.d.ts",
+            "default": "./dist/index.js"
+        },
+        "./resvg": {
+            "bun": "./src/resvg/index.ts",
+            "types": "./dist/resvg/index.d.ts",
+            "default": "./dist/resvg/index.js"
+        },
+        "./wasm": {
+            "bun": "./src/wasm/index.ts",
+            "types": "./dist/wasm/index.d.ts",
+            "default": "./dist/wasm/index.js"
+        },
+        "./node": {
+            "bun": "./src/node/index.ts",
+            "types": "./dist/node/index.d.ts",
+            "default": "./dist/node/index.js"
+        },
+        "./schema/brand.v1.json": "./schema/brand.v1.json",
+        "./package.json": "./package.json"
+    },
+    "files": [
+        "dist",
+        "schema",
+        "LICENSE",
+        "README.md",
+        "THIRD_PARTY.md"
+    ],
+    "sideEffects": false,
+    "publishConfig": {
+        "access": "public"
+    },
+    "engines": {
+        "node": ">=20.3"
+    },
+    "scripts": {
+        "build": "rm -rf dist && tsc -p tsconfig.build.json",
+        "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.node.json",
+        "lint": "eslint .",
+        "test": "vitest --run --passWithNoTests",
+        "schema": "bun run scripts/write-json-schema.ts"
+    },
+    "dependencies": {
+        "culori": "4.0.2",
+        "fflate": "^0.8.3",
+        "harfbuzzjs": "1.6.4",
+        "zod": "^4.4.3"
+    },
+    "peerDependencies": {
+        "@resvg/resvg-js": "2.6.2",
+        "@resvg/resvg-wasm": "2.6.2"
+    },
+    "peerDependenciesMeta": {
+        "@resvg/resvg-js": {
+            "optional": true
+        },
+        "@resvg/resvg-wasm": {
+            "optional": true
+        }
+    },
+    "devDependencies": {
+        "@resvg/resvg-js": "2.6.2",
+        "@resvg/resvg-wasm": "2.6.2",
+        "@types/bun": "^1.3.14",
+        "@types/culori": "^4.0.1",
+        "typescript": "^5.9.3",
+        "vitest": "^4.1.2"
+    }
+}