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

package/dist/marks/svg.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Marks as data. A mark master is SVG, but the scene engine never passes through SVG it did not
+ * write (docs/spikes/render.md, rule 1). So a mark is read into a small, fixed subset (shapes,
+ * groups, solid fills and strokes), then written back out by the kit, recolored as each version
+ * needs. Anything outside the subset is listed, so the studio can say what to fix.
+ */
+export type MarkElement = {
+    tag: "g" | "path" | "circle" | "ellipse" | "rect" | "line" | "polyline" | "polygon";
+    attrs: Record<string, string>;
+    children: MarkElement[];
+};
+export type ParsedMark = {
+    viewBox: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    };
+    /** The root's own paint (Lucide-style fill="none" stroke="currentColor"), kept as a group. */
+    root: MarkElement;
+    /** Every hex color used, lowercase. */
+    colors: string[];
+    /** The thinnest stroke, in viewBox units (Infinity when nothing is stroked). */
+    thinnestStroke: number;
+    /** What was left out, in plain words. Empty for a clean mark. */
+    unsupported: string[];
+};
+/** Read a mark master into the kit's subset. Throws only when there is no usable <svg> root. */
+export declare function parseMark(svg: string): ParsedMark;
+export type MarkPaint = {
+    /** Map each hex the mark uses to the hex to draw. Default: as it is. */
+    color?: (hex: string) => string;
+    /** What currentColor and an unset fill mean here. Default: #000000, as in SVG. */
+    current?: string;
+};
+/** Write the mark's elements back out (no <svg> wrapper), recolored. */
+export declare function markBody(mark: ParsedMark, paint?: MarkPaint): string;
+/** A standalone SVG of the mark (recolored), with its own viewBox. */
+export declare function markSvg(mark: ParsedMark, paint?: MarkPaint): string;
+/**
+ * A mark master as the kit would draw it, written by the kit: only the subset parseMark reads, so
+ * no script, event handler, link or foreign content survives. currentColor stays. Running it on
+ * its own output gives the same bytes, so saving a clean mark again changes nothing. Throws like
+ * parseMark when there is no usable <svg> root.
+ */
+export declare function cleanMarkSvg(svg: string): string;

package/dist/marks/svg.js

@@ -0,0 +1,341 @@
+/**
+ * Marks as data. A mark master is SVG, but the scene engine never passes through SVG it did not
+ * write (docs/spikes/render.md, rule 1). So a mark is read into a small, fixed subset (shapes,
+ * groups, solid fills and strokes), then written back out by the kit, recolored as each version
+ * needs. Anything outside the subset is listed, so the studio can say what to fix.
+ */
+const SHAPES = new Set(["path", "circle", "ellipse", "rect", "line", "polyline", "polygon"]);
+const SKIPPED = new Set(["title", "desc", "metadata"]);
+const PAINT = new Set([
+    "fill",
+    "fill-rule",
+    "fill-opacity",
+    "stroke",
+    "stroke-width",
+    "stroke-linecap",
+    "stroke-linejoin",
+    "stroke-miterlimit",
+    "stroke-opacity",
+    "stroke-dasharray",
+    "opacity",
+    "clip-rule",
+]);
+const GEOMETRY = {
+    g: ["transform"],
+    path: ["d", "transform"],
+    circle: ["cx", "cy", "r", "transform"],
+    ellipse: ["cx", "cy", "rx", "ry", "transform"],
+    rect: ["x", "y", "width", "height", "rx", "ry", "transform"],
+    line: ["x1", "y1", "x2", "y2", "transform"],
+    polyline: ["points", "transform"],
+    polygon: ["points", "transform"],
+};
+// Attributes that carry no drawing and are dropped without a word.
+const IGNORED = /^(id|class|version|xml:space|xmlns(:.*)?|data-.*|aria-.*|role|focusable|style|width|height|viewBox|preserveAspectRatio|x|y|key)$/;
+// The names svgo writes when a name is shorter than the hex (convertColors), plus the basics.
+const NAMED = {
+    black: "#000000",
+    white: "#ffffff",
+    red: "#ff0000",
+    tan: "#d2b48c",
+    aqua: "#00ffff",
+    blue: "#0000ff",
+    cyan: "#00ffff",
+    gold: "#ffd700",
+    gray: "#808080",
+    grey: "#808080",
+    lime: "#00ff00",
+    navy: "#000080",
+    peru: "#cd853f",
+    pink: "#ffc0cb",
+    plum: "#dda0dd",
+    snow: "#fffafa",
+    teal: "#008080",
+    azure: "#f0ffff",
+    beige: "#f5f5dc",
+    brown: "#a52a2a",
+    coral: "#ff7f50",
+    green: "#008000",
+    ivory: "#fffff0",
+    khaki: "#f0e68c",
+    linen: "#faf0e6",
+    olive: "#808000",
+    wheat: "#f5deb3",
+    bisque: "#ffe4c4",
+    indigo: "#4b0082",
+    maroon: "#800000",
+    orange: "#ffa500",
+    orchid: "#da70d6",
+    purple: "#800080",
+    salmon: "#fa8072",
+    sienna: "#a0522d",
+    silver: "#c0c0c0",
+    tomato: "#ff6347",
+    violet: "#ee82ee",
+    yellow: "#ffff00",
+    crimson: "#dc143c",
+    fuchsia: "#ff00ff",
+    magenta: "#ff00ff",
+};
+const NUMBER = /^-?(\d+\.?\d*|\.\d+)(e-?\d+)?$/i;
+const TRANSFORM = /^(\s*(matrix|translate|scale|rotate|skewX|skewY)\s*\([-\d.,\se]*\)\s*)+$/i;
+/** A paint value as the kit stores it: lowercase hex, "none" or "currentColor". */
+function normalizePaint(value) {
+    const trimmed = value.trim().toLowerCase();
+    if (trimmed === "none" || trimmed === "transparent")
+        return "none";
+    if (trimmed === "currentcolor")
+        return "currentColor";
+    const short = /^#([0-9a-f])([0-9a-f])([0-9a-f])$/.exec(trimmed);
+    if (short)
+        return `#${short[1]}${short[1]}${short[2]}${short[2]}${short[3]}${short[3]}`;
+    if (/^#[0-9a-f]{6}$/.test(trimmed))
+        return trimmed;
+    const rgb = /^rgb\(\s*(\d+)[\s,]+(\d+)[\s,]+(\d+)\s*\)$/.exec(trimmed);
+    if (rgb) {
+        return `#${[rgb[1], rgb[2], rgb[3]].map((part) => Math.min(255, Number(part)).toString(16).padStart(2, "0")).join("")}`;
+    }
+    return NAMED[trimmed];
+}
+function readAttributes(source) {
+    const attrs = {};
+    for (const match of source.matchAll(/([A-Za-z_:][\w:.-]*)\s*=\s*(?:"([^"]*)"|'([^']*)')/g)) {
+        attrs[match[1] ?? ""] = match[2] ?? match[3] ?? "";
+    }
+    return attrs;
+}
+function decode(value) {
+    return value
+        .replaceAll(""", '"')
+        .replaceAll("'", "'")
+        .replaceAll("&lt;", "<")
+        .replaceAll("&gt;", ">")
+        .replaceAll("&amp;", "&");
+}
+/** Read a mark master into the kit's subset. Throws only when there is no usable <svg> root. */
+export function parseMark(svg) {
+    const unsupported = new Set();
+    const colors = new Set();
+    let thinnestStroke = Number.POSITIVE_INFINITY;
+    const source = svg
+        .replace(/<!--[\s\S]*?-->/g, "")
+        .replace(/<\?[\s\S]*?\?>/g, "")
+        .replace(/<!DOCTYPE[^>]*>/gi, "");
+    const stack = [];
+    let root;
+    let viewBox;
+    let skipDepth = 0;
+    let rootPaint = {};
+    const clean = (tag, raw) => {
+        const attrs = {};
+        const style = {};
+        for (const part of (raw.style ?? "").split(";")) {
+            const [name, ...rest] = part.split(":");
+            if (name?.trim() && rest.length)
+                style[name.trim()] = rest.join(":").trim();
+        }
+        const all = { ...raw, ...style };
+        for (const [name, rawValue] of Object.entries(all)) {
+            const value = decode(rawValue).trim();
+            if (PAINT.has(name)) {
+                if (name === "fill" || name === "stroke") {
+                    const paint = normalizePaint(value);
+                    if (!paint) {
+                        unsupported.add(`the color "${value}" (use a hex color)`);
+                        continue;
+                    }
+                    if (paint.startsWith("#"))
+                        colors.add(paint);
+                    attrs[name] = paint;
+                }
+                else if (name === "fill-rule" || name === "clip-rule") {
+                    if (value === "evenodd" || value === "nonzero")
+                        attrs[name] = value;
+                }
+                else if (name === "stroke-linecap") {
+                    if (["butt", "round", "square"].includes(value))
+                        attrs[name] = value;
+                }
+                else if (name === "stroke-linejoin") {
+                    if (["miter", "round", "bevel"].includes(value))
+                        attrs[name] = value;
+                }
+                else if (name === "stroke-dasharray") {
+                    if (/^[\d.\s,]+$/.test(value) || value === "none")
+                        attrs[name] = value;
+                }
+                else if (NUMBER.test(value.replace(/px$/, ""))) {
+                    attrs[name] = value.replace(/px$/, "");
+                }
+                continue;
+            }
+            if (GEOMETRY[tag]?.includes(name)) {
+                if (name === "transform" && !TRANSFORM.test(value)) {
+                    unsupported.add("a transform the kit cannot read");
+                    continue;
+                }
+                if (name === "d" && /[^MmLlHhVvCcSsQqTtAaZz\d\s,.eE+-]/.test(value)) {
+                    unsupported.add("path data with unknown commands");
+                    continue;
+                }
+                if (name === "points" && !/^[\d\s,.eE+-]*$/.test(value)) {
+                    unsupported.add("points that are not numbers");
+                    continue;
+                }
+                const isList = name === "d" || name === "points" || name === "transform";
+                const number = value.replace(/px$/, "");
+                if (!isList && !NUMBER.test(number)) {
+                    unsupported.add(`a ${name} that is not a number`);
+                    continue;
+                }
+                attrs[name] = isList ? value : number;
+                continue;
+            }
+            if (!IGNORED.test(name) && !(name in style))
+                unsupported.add(`the ${name} attribute`);
+            else if (name in style && !IGNORED.test(name))
+                unsupported.add(`the ${name} style`);
+        }
+        return attrs;
+    };
+    for (const match of source.matchAll(/<(\/?)([A-Za-z][\w:-]*)([^>]*?)(\/?)>/g)) {
+        const [, closing, tagName = "", rawAttrs = "", selfClosing] = match;
+        const tag = tagName.toLowerCase();
+        if (skipDepth > 0) {
+            if (!selfClosing)
+                skipDepth += closing ? -1 : 1;
+            continue;
+        }
+        if (closing) {
+            if (tag === "g" || tag === "svg")
+                stack.pop();
+            continue;
+        }
+        if (tag === "svg") {
+            const attrs = readAttributes(rawAttrs);
+            if (root) {
+                unsupported.add("a nested <svg>");
+                if (!selfClosing)
+                    skipDepth = 1;
+                continue;
+            }
+            const box = (attrs.viewBox ?? attrs.viewbox ?? "")
+                .trim()
+                .split(/[\s,]+/)
+                .map(Number);
+            if (box.length === 4 &&
+                box.every(Number.isFinite) &&
+                (box[2] ?? 0) > 0 &&
+                (box[3] ?? 0) > 0) {
+                viewBox = { x: box[0] ?? 0, y: box[1] ?? 0, w: box[2] ?? 1, h: box[3] ?? 1 };
+            }
+            else {
+                const w = Number.parseFloat(attrs.width ?? "");
+                const h = Number.parseFloat(attrs.height ?? "");
+                if (w > 0 && h > 0)
+                    viewBox = { x: 0, y: 0, w, h };
+            }
+            rootPaint = clean("g", attrs);
+            delete rootPaint.transform;
+            root = { tag: "g", attrs: rootPaint, children: [] };
+            stack.push(root);
+            continue;
+        }
+        const parent = stack[stack.length - 1];
+        if (!parent)
+            continue;
+        if (SKIPPED.has(tag)) {
+            if (!selfClosing)
+                skipDepth = 1;
+            continue;
+        }
+        if (tag !== "g" && !SHAPES.has(tag)) {
+            unsupported.add(`the <${tag}> element`);
+            if (!selfClosing)
+                skipDepth = 1;
+            continue;
+        }
+        const element = {
+            tag: tag,
+            attrs: clean(tag, readAttributes(rawAttrs)),
+            children: [],
+        };
+        parent.children.push(element);
+        if (tag === "g" && !selfClosing)
+            stack.push(element);
+    }
+    if (!root || !viewBox)
+        throw new TypeError("The mark has no <svg> root with a viewBox or a size.");
+    // Stroke widths, inherited down the tree: the legibility check needs the thinnest one.
+    const walk = (element, stroke, width) => {
+        const nextStroke = element.attrs.stroke ?? stroke;
+        const nextWidth = element.attrs["stroke-width"]
+            ? Number(element.attrs["stroke-width"])
+            : width;
+        if (element.tag !== "g" && nextStroke && nextStroke !== "none") {
+            thinnestStroke = Math.min(thinnestStroke, nextWidth);
+        }
+        for (const child of element.children)
+            walk(child, nextStroke, nextWidth);
+    };
+    walk(root, undefined, 1);
+    return {
+        viewBox,
+        root,
+        colors: [...colors].sort(),
+        thinnestStroke,
+        unsupported: [...unsupported],
+    };
+}
+function escapeAttr(value) {
+    return value.replaceAll("&", "&amp;").replaceAll('"', "&quot;").replaceAll("<", "&lt;");
+}
+/** Write the mark's elements back out (no <svg> wrapper), recolored. */
+export function markBody(mark, paint = {}) {
+    const current = paint.current ?? "#000000";
+    const color = paint.color ?? ((hex) => hex);
+    const write = (element, isRoot) => {
+        const attrs = { ...element.attrs };
+        // SVG paints an unset root fill black; say it, so recoloring reaches it too.
+        if (isRoot && attrs.fill === undefined)
+            attrs.fill = "currentColor";
+        const parts = Object.entries(attrs).map(([name, value]) => {
+            let out = value;
+            if (name === "fill" || name === "stroke") {
+                out =
+                    value === "currentColor"
+                        ? color(current)
+                        : value === "none"
+                            ? "none"
+                            : color(value);
+            }
+            return ` ${name}="${escapeAttr(out)}"`;
+        });
+        const inner = element.children.map((child) => write(child, false)).join("");
+        return element.tag === "g" || inner
+            ? `<${element.tag}${parts.join("")}>${inner}</${element.tag}>`
+            : `<${element.tag}${parts.join("")}/>`;
+    };
+    return write(mark.root, true);
+}
+/** A standalone SVG of the mark (recolored), with its own viewBox. */
+export function markSvg(mark, paint = {}) {
+    const { x, y, w, h } = mark.viewBox;
+    return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="${x} ${y} ${w} ${h}">${markBody(mark, paint)}</svg>`;
+}
+/**
+ * A mark master as the kit would draw it, written by the kit: only the subset parseMark reads, so
+ * no script, event handler, link or foreign content survives. currentColor stays. Running it on
+ * its own output gives the same bytes, so saving a clean mark again changes nothing. Throws like
+ * parseMark when there is no usable <svg> root.
+ */
+export function cleanMarkSvg(svg) {
+    const mark = parseMark(svg);
+    // markSvg writes the root's paint on a <g>, which reads back as a bare root around one group.
+    // Lifting that group back up keeps a second pass from nesting another one.
+    const [only, ...rest] = mark.root.children;
+    const root = Object.keys(mark.root.attrs).length === 0 && only?.tag === "g" && rest.length === 0
+        ? only
+        : mark.root;
+    return markSvg({ ...mark, root }, { current: "currentColor" });
+}

package/dist/node/index.d.ts

@@ -0,0 +1,13 @@
+import { type FontResolver } from "../text/fonts.ts";
+/** Where fonts are kept by default: ~/.cache/ideare/fonts (XDG_CACHE_HOME when set). */
+export declare function defaultFontCacheDir(): string;
+/**
+ * Downloads static TTFs (or WOFF2) from Fontsource once and keeps them on disk, keyed by the
+ * Fontsource version, so a pinned family never changes under you. Catalog families are pinned
+ * to the catalog's version; any other id follows "latest".
+ */
+export declare function diskFontResolver(options?: {
+    dir?: string;
+    fetch?: typeof fetch;
+    versions?: Record<string, string>;
+}): FontResolver;

package/dist/node/index.js

@@ -0,0 +1,41 @@
+/**
+ * The Node and Bun side of the kit: a font resolver with a disk cache. The core never touches a
+ * file system, so this lives behind its own entry, `@ideare/kit/node`.
+ */
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { catalogVersions } from "../fonts/pick.js";
+import { fetchFontResolver, fontFileName } from "../text/fonts.js";
+/** Where fonts are kept by default: ~/.cache/ideare/fonts (XDG_CACHE_HOME when set). */
+export function defaultFontCacheDir() {
+    const base = process.env.XDG_CACHE_HOME || join(homedir(), ".cache");
+    return join(base, "ideare", "fonts");
+}
+/**
+ * Downloads static TTFs (or WOFF2) from Fontsource once and keeps them on disk, keyed by the
+ * Fontsource version, so a pinned family never changes under you. Catalog families are pinned
+ * to the catalog's version; any other id follows "latest".
+ */
+export function diskFontResolver(options = {}) {
+    const dir = options.dir ?? defaultFontCacheDir();
+    const versions = { ...catalogVersions(), ...options.versions };
+    const remote = fetchFontResolver({ fetch: options.fetch, versions });
+    return {
+        async load(font) {
+            const file = join(dir, `${versions[font.id] ?? "latest"}`, fontFileName(font));
+            try {
+                return new Uint8Array(await readFile(file));
+            }
+            catch {
+                const bytes = await remote.load(font);
+                await mkdir(join(file, ".."), { recursive: true });
+                // Write then rename, so a crash never leaves half a font in the cache.
+                const partial = `${file}.${process.pid}.partial`;
+                await writeFile(partial, bytes);
+                await rename(partial, file);
+                return bytes;
+            }
+        },
+    };
+}

package/dist/posts/pix.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The Pix "copia e cola" code: what a static Pix QR code holds (BR Code, the EMV QR merchant
+ * format as Banco Central do Brasil's Pix manual sets it). A bank app reads the key, the name,
+ * the city and an optional amount from it, then asks the payer to confirm.
+ */
+export type PixDetails = {
+    /** The Pix key: a phone number with +55, an email, a CPF or CNPJ, or a random key. */
+    key: string;
+    /** Who receives, as the bank shows it. Accents are dropped; 25 characters at most. */
+    name: string;
+    /** The receiver's city. Accents are dropped; 15 characters at most. */
+    city: string;
+    /** A fixed amount in reais, like 25.5. Left out, the payer types it. */
+    amount?: number;
+    /** A reference for the payment, up to 25 letters and digits. Default `***`, for none. */
+    txid?: string;
+};
+/** The code for a static Pix QR code. Throws when the key is empty or too long to fit. */
+export declare function pixCode(details: PixDetails): string;

package/dist/posts/pix.js

@@ -0,0 +1,49 @@
+/**
+ * The Pix "copia e cola" code: what a static Pix QR code holds (BR Code, the EMV QR merchant
+ * format as Banco Central do Brasil's Pix manual sets it). A bank app reads the key, the name,
+ * the city and an optional amount from it, then asks the payer to confirm.
+ */
+function field(id, value) {
+    return `${id}${String(value.length).padStart(2, "0")}${value}`;
+}
+/** Plain ASCII, as the BR Code's name and city fields take them. */
+function plain(text, max) {
+    return text
+        .normalize("NFD")
+        .replace(/[\u0300-\u036f]/g, "")
+        .replace(/[^\x20-\x7e]/g, "")
+        .trim()
+        .slice(0, max)
+        .trimEnd();
+}
+/** CRC-16/CCITT-FALSE (polynomial 0x1021, start 0xFFFF), as four uppercase hex digits. */
+function crc16(text) {
+    let crc = 0xffff;
+    for (const byte of new TextEncoder().encode(text)) {
+        crc ^= byte << 8;
+        for (let bit = 0; bit < 8; bit++)
+            crc = crc & 0x8000 ? ((crc << 1) ^ 0x1021) & 0xffff : (crc << 1) & 0xffff;
+    }
+    return crc.toString(16).toUpperCase().padStart(4, "0");
+}
+/** The code for a static Pix QR code. Throws when the key is empty or too long to fit. */
+export function pixCode(details) {
+    const key = details.key.trim();
+    if (!key || key.length > 77)
+        throw new RangeError("A Pix key has 1 to 77 characters.");
+    const txid = (details.txid ?? "***").replace(/[^A-Za-z0-9*]/g, "").slice(0, 25) || "***";
+    const amount = details.amount !== undefined && details.amount > 0
+        ? field("54", details.amount.toFixed(2))
+        : "";
+    const body = field("00", "01") +
+        field("26", field("00", "br.gov.bcb.pix") + field("01", key)) +
+        field("52", "0000") +
+        field("53", "986") +
+        amount +
+        field("58", "BR") +
+        field("59", plain(details.name, 25) || "Pix") +
+        field("60", plain(details.city, 15) || "BRASIL") +
+        field("62", field("05", txid)) +
+        "6304";
+    return body + crc16(body);
+}

package/dist/posts/templates.d.ts

@@ -0,0 +1,45 @@
+import type { Brand, Locale } from "../brand/schema.ts";
+import { type Scene } from "../scene/schema.ts";
+/**
+ * The launch templates: a starting design for each job an owner posts for, in every size they
+ * post at. Each is plain scene data the editor opens and the API draws. Paints are brand tokens
+ * only, in the pairs every brand's palette keeps readable (ink and muted on ground and surface,
+ * onPrimary on primary, primary as large type on ground), and type uses the brand's two font
+ * roles, so a template looks like the brand it is made for. Photo spots are art layers named
+ * `photo`, which the editor fills with an upload or AI art; text the owner changes is a slot,
+ * and slots marked live can be filled by a live image link (`t.<slot>`).
+ */
+export declare const POST_TEMPLATES: readonly ["promotion", "hours", "menu", "pix", "new-product", "status-offer", "carousel"];
+export type PostTemplateId = (typeof POST_TEMPLATES)[number];
+export declare const POST_FORMATS: readonly ["ig-post", "ig-square", "ig-story", "wa-status", "share-card"];
+export type PostFormat = (typeof POST_FORMATS)[number];
+export type PostTemplateOptions = {
+    /** The size. Default: the template's own (`wa-status` for the status offer, else `ig-post`). */
+    format?: PostFormat;
+    /** The language of the words. Default: the brand's. */
+    locale?: Locale;
+    /** For the Pix card: the key its QR code pays. The name comes from the brand. */
+    pix?: {
+        key: string;
+        city?: string;
+        amount?: number;
+    };
+};
+type Info = {
+    name: string;
+    description: string;
+};
+/** What the template picker shows, and the size each template starts at. */
+export declare const POST_TEMPLATE_INFO: Record<PostTemplateId, {
+    format: PostFormat;
+    text: Record<Locale, Info>;
+}>;
+/**
+ * A starting design for one of the owner's jobs, in one size and language, for one brand.
+ *
+ * ```ts
+ * const scene = postTemplate("promotion", brand); // an Instagram post, in the brand's language
+ * ```
+ */
+export declare function postTemplate(id: PostTemplateId, brand: Brand, options?: PostTemplateOptions): Scene;
+export {};