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

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gustavo Salomé
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,149 @@
-# Temporary Holding Version
+# @ideare/kit
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The engine behind ideare: it reads a brand (`brand.json`) and makes every file the brand needs.
+Icons, logos, share cards, social sizes, tokens, a business card and plain-words guidelines all
+come from one scene engine, so the studio, the CLI and the server draw the same pixels.
+
+```ts
+import { parseBrand } from "@ideare/kit";
+
+const result = parseBrand(JSON.parse(text));
+if (!result.ok) console.log(result.issues); // [{ path: "colors.light.ink", message: "Use a 6-digit hex color, like #1A2B3C." }]
+```
+
+## Make the files
+
+```ts
+import { generate } from "@ideare/kit";
+import { diskFontResolver } from "@ideare/kit/node";
+import { resvgRasterizer } from "@ideare/kit/resvg";
+
+const files = await generate(brand, { fonts: diskFontResolver(), rasterize: resvgRasterizer() });
+// Map { "web/favicon.ico" => { bytes, mime, sha256, width, height }, "og/og.png" => ..., ... }
+```
+
+`generate()` writes nothing to disk; you decide where the bytes go. Pick groups with
+`targets: ["web", "tokens"]`. The groups are `web`, `logo`, `og`, `social`, `tokens`,
+`registry`, `docs`, `email` and `print`. When text would not fit or a letter is missing from a
+font, it refuses with a `GenerateRefusal` instead of making a cut file.
+
+## Check a brand
+
+```ts
+import { check } from "@ideare/kit";
+
+const results = await check(brand, { fonts: diskFontResolver() });
+// [{ id: "contrast.light.muted.surface", level: "error", title: "Quiet text on cards: hard to read. Fix it",
+//    fix: { kind: "set", label: "Use #6b5e55", changes: [...] }, details: { ratio: "3.12:1", needed: "4.5:1" } }, ...]
+```
+
+Contrast (WCAG 2), the logo on its icon, 16 px legibility, glyph coverage, text fit in every
+language, safe zones, the copy check (no em dash, no machine-sounding words, sentence case, no
+exclamation marks, lengths) and upload limits.
+
+## Draw a scene
+
+```ts
+import { renderScene } from "@ideare/kit";
+
+const { svg, boxes, checks, revision } = await renderScene(scene, brand, { fonts });
+```
+
+Text is shaped with HarfBuzz into glyph paths, so the browser and resvg show the same lines.
+Each layer sits in its own `<g transform="translate(x y) rotate(r w/2 h/2)">`, and a group's
+layers are placed in the group's own space. An editor passes one cache per stage, so a drag frame
+redraws only what changed:
+
+```ts
+import { createRenderCache } from "@ideare/kit";
+
+const cache = createRenderCache();
+const { svg } = await renderScene(scene, brand, { fonts, cache }); // the moved layer's transform, the rest from the cache
+```
+
+## Make a post from a template
+
+```ts
+import { postTemplate } from "@ideare/kit";
+
+const scene = postTemplate("promotion", brand); // an Instagram post, in the brand's language
+```
+
+There are 7 templates (`POST_TEMPLATES`): `promotion`, `hours`, `menu`, `pix`, `new-product`,
+`status-offer` and `carousel` (5 pages). Each comes in 5 sizes (`POST_FORMATS`): `ig-post`
+1080x1350, `ig-square` 1080x1080, `ig-story` and `wa-status` 1080x1920, and `share-card`
+1200x630. Pass `{ format: "ig-story", locale: "es" }` for another size or language. They use only
+the brand's colors and its two fonts. The words the owner changes are slots (`scene.slots`), and
+the photo spot is an art layer called `photo`.
+
+The Pix card needs the owner's Pix key, or its QR code shows a sample key that pays no one:
+
+```ts
+postTemplate("pix", brand, { pix: { key: "+5541999990000", city: "Curitiba" } });
+```
+
+`pixCode({ key, name, city, amount })` gives the "copia e cola" code itself.
+
+## Edit a scene
+
+Every edit is a plain function from a scene to a new scene, with no DOM, so an editor, an agent
+and a test edit the same way. Layers are found by id on a page (page 0 here), and positions are in
+the page's own pixels, even for a layer inside a turned group.
+
+```ts
+import { moveLayers } from "@ideare/kit";
+
+const moved = moveLayers(scene, 0, ["title"], 40, 0); // 40 px to the right
+```
+
+The others: `addLayer`, `removeLayers`, `duplicateLayers`, `resizeLayers` (any corner or side,
+the opposite one held still), `rotateLayers`, `groupLayers`, `ungroupLayers`, `reorderLayers`,
+`alignLayers`, `distributeLayers`, `lockLayers`, `setTextHeight`, and `addPage`, `duplicatePage`,
+`removePage` and `movePage` for carousels. For a drag, compute each frame from the scene at the
+press, never from the last frame. `snapTargets` and `snapBox` snap within 12 screen pixels at the
+stage's scale, and `turnAngle` lands a turn on 45 degrees, or in 15 degree steps.
+
+Undo keeps 50 steps, and a typing session is one step when its edits share a group:
+
+```ts
+import { emptyHistory, recordEdit, undoEdit } from "@ideare/kit";
+
+let history = recordEdit(emptyHistory(), before, after, "typing:title");
+const back = undoEdit(history, after); // { history, scene }
+```
+
+When a save comes back with someone else's change, `mergeScenes(mine, base, theirs)` brings it in
+and lists the fields you both changed, and `rebaseHistory` keeps Undo for everything they didn't.
+
+## Start from a name
+
+```ts
+import { draftBrand, newDraftSeed } from "@ideare/kit";
+
+const brand = await draftBrand(
+  { name: "Padaria Fermento", idea: "Pão de fermentação natural", locale: "pt-BR",
+    seed: newDraftSeed(), picks: { colors: 0, fonts: 0, logo: 0 } },
+  { fonts },
+);
+```
+
+A whole draft brand from a name and one line, drawn by code: colors, a font pair, a logo (an icon
+or a monogram) and the copy. The same input always draws the same brand, so `draftParams(input)`
+puts it in a link and `readDraftParams(params)` reads it back anywhere. Each `picks` count is one
+"Try another" press. The font pairs are a short list (`draftFontFiles()` names every file), so a
+page can serve them itself.
+
+## Where it runs
+
+- The core (`@ideare/kit`) runs in browsers, Node 20.3+, Bun and Workers. It loads the HarfBuzz
+  wasm only when it first draws text. A bundler must keep `harfbuzz.wasm` next to `harfbuzz.js`,
+  and a page's CSP needs `'wasm-unsafe-eval'`.
+- `@ideare/kit/node`: a font cache on disk (`~/.cache/ideare/fonts`).
+- `@ideare/kit/resvg`: the rasterizer, on `@resvg/resvg-js` 2.6.2 (an optional peer).
+- `@ideare/kit/wasm`: the same rasterizer built to wasm, on `@resvg/resvg-wasm` 2.6.2 (an
+  optional peer), for browsers and for tools that must install nothing native. Pass it the
+  wasm: `wasmRasterizer({ wasm: readFile(require.resolve("@resvg/resvg-wasm/index_bg.wasm")) })`
+  in Node, or a URL in the browser. It draws the same pixels as `@ideare/kit/resvg`.
+- Under Bun, the `bun` export condition loads the TypeScript source, with no build step.
+
+MIT. Lucide icons (ISC) and a QR encoder port (MIT) are inside; see `THIRD_PARTY.md`.

package/THIRD_PARTY.md

@@ -0,0 +1,52 @@
+# Third-party code and data in @ideare/kit
+
+## Lucide icons (`src/marks/icons.data.ts`)
+
+The kit carries the markup of a curated set of Lucide icons (lucide-static 1.68.0), drawn as
+icon marks and on highlight covers.
+
+ISC License
+
+Copyright (c) 2026 Lucide Icons and Contributors
+
+Permission to use, copy, modify, and/or distribute this software for any purpose with or without
+fee is hereby granted, provided that the above copyright notice and this permission notice appear
+in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS
+SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE
+AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
+NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE
+OF THIS SOFTWARE.
+
+Some Lucide icons are derived from Feather (MIT License, Copyright (c) 2013-present Cole Bemis).
+
+## QR Code generator (`src/scene/qr.ts`)
+
+Ported from Project Nayuki's QR Code generator library.
+
+MIT License
+
+Copyright (c) Project Nayuki. (MIT License) https://www.nayuki.io/page/qr-code-generator-library
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and
+associated documentation files (the "Software"), to deal in the Software without restriction,
+including without limitation the rights to use, copy, modify, merge, publish, distribute,
+sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+- The above copyright notice and this permission notice shall be included in all copies or
+  substantial portions of the Software.
+- The Software is provided "as is", without warranty of any kind, express or implied, including
+  but not limited to the warranties of merchantability, fitness for a particular purpose and
+  noninfringement. In no event shall the authors or copyright holders be liable for any claim,
+  damages or other liability, whether in an action of contract, tort or otherwise, arising from,
+  out of or in connection with the Software or the use or other dealings in the Software.
+
+## Fonts
+
+The kit ships no font. It downloads static files from Fontsource at run time, and every font in
+its catalog is under the SIL Open Font License 1.1, whose text the kit writes next to the font
+files it hands out (`OFL.txt`). The two fonts in `test/fonts` are used by the tests only; their
+notices are in `test/fonts/OFL.txt`.

package/dist/brand/schema.d.ts

@@ -0,0 +1,265 @@
+import { z } from "zod";
+/**
+ * brand.json v1, the masters. Everything else (icons, cards, tokens, brand.md) is derived from
+ * this file by `generate()`, so a field belongs here only when a person chooses it. The kit
+ * outlines the wordmark and draws every file; neither is stored.
+ */
+export declare const BRAND_SCHEMA_VERSION = 1;
+export declare const BRAND_SCHEMA_URL = "https://ideare.app/schema/brand.v1.json";
+/** The languages a brand can write its copy in. Widening this list is not a breaking change. */
+export declare const LOCALES: readonly ["pt-BR", "en", "es"];
+export type Locale = (typeof LOCALES)[number];
+/** Every color role, in the order tokens and brand.md list them. */
+export declare const COLOR_ROLES: readonly ["ground", "surface", "ink", "muted", "line", "primary", "onPrimary", "accent", "onAccent", "focus", "danger", "success", "warning"];
+export type ColorRole = (typeof COLOR_ROLES)[number];
+export declare const FONT_ROLES: readonly ["display", "text"];
+export type FontRole = (typeof FONT_ROLES)[number];
+/** The links a brand can list. `site` is a URL, the socials are handles, whatsapp is E.164. */
+export declare const LINK_KINDS: readonly ["site", "instagram", "facebook", "x", "linkedin", "youtube", "tiktok", "whatsapp", "email", "phone"];
+export type LinkKind = (typeof LINK_KINDS)[number];
+/** The links that reach a person. ideare publishes them only when the owner shares contacts. */
+export declare const CONTACT_LINK_KINDS: ["whatsapp", "email", "phone"];
+declare const copySchema: z.ZodObject<{
+    tagline: z.ZodString;
+    description: z.ZodString;
+    card: z.ZodObject<{
+        title: z.ZodString;
+        subtitle: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export declare const brandSchema: z.ZodObject<{
+    $schema: z.ZodDefault<z.ZodLiteral<"https://ideare.app/schema/brand.v1.json">>;
+    schemaVersion: z.ZodLiteral<1>;
+    slug: z.ZodOptional<z.ZodString>;
+    version: z.ZodOptional<z.ZodNumber>;
+    name: z.ZodString;
+    shortName: z.ZodString;
+    domain: z.ZodOptional<z.ZodString>;
+    locales: z.ZodArray<z.ZodEnum<{
+        "pt-BR": "pt-BR";
+        en: "en";
+        es: "es";
+    }>>;
+    defaultLocale: z.ZodEnum<{
+        "pt-BR": "pt-BR";
+        en: "en";
+        es: "es";
+    }>;
+    copy: z.ZodRecord<z.ZodEnum<{
+        "pt-BR": "pt-BR";
+        en: "en";
+        es: "es";
+    }> & z.core.$partial, z.ZodObject<{
+        tagline: z.ZodString;
+        description: z.ZodString;
+        card: z.ZodObject<{
+            title: z.ZodString;
+            subtitle: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>;
+    }, z.core.$strip>>;
+    voice: z.ZodPrefault<z.ZodObject<{
+        tone: z.ZodArray<z.ZodString>;
+        notes: z.ZodOptional<z.ZodString>;
+        notesPublic: z.ZodDefault<z.ZodBoolean>;
+        neverSay: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        examples: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            context: z.ZodString;
+            text: z.ZodString;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>;
+    mark: z.ZodObject<{
+        svg: z.ZodString;
+        small: z.ZodOptional<z.ZodString>;
+        dark: z.ZodOptional<z.ZodString>;
+        lockups: z.ZodOptional<z.ZodObject<{
+            horizontal: z.ZodOptional<z.ZodString>;
+            stacked: z.ZodOptional<z.ZodString>;
+            wordmark: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        tile: z.ZodPrefault<z.ZodObject<{
+            fill: z.ZodDefault<z.ZodEnum<{
+                ground: "ground";
+                surface: "surface";
+                ink: "ink";
+                muted: "muted";
+                line: "line";
+                primary: "primary";
+                onPrimary: "onPrimary";
+                accent: "accent";
+                onAccent: "onAccent";
+                focus: "focus";
+                danger: "danger";
+                success: "success";
+                warning: "warning";
+            }>>;
+            shape: z.ZodDefault<z.ZodEnum<{
+                square: "square";
+                rounded: "rounded";
+                circle: "circle";
+            }>>;
+            radius: z.ZodDefault<z.ZodNumber>;
+            padding: z.ZodDefault<z.ZodNumber>;
+        }, z.core.$strip>>;
+        source: z.ZodOptional<z.ZodObject<{
+            kind: z.ZodEnum<{
+                monogram: "monogram";
+                icon: "icon";
+                ai: "ai";
+                upload: "upload";
+            }>;
+            ref: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+    wordmark: z.ZodObject<{
+        text: z.ZodString;
+        font: z.ZodDefault<z.ZodEnum<{
+            display: "display";
+            text: "text";
+        }>>;
+        weight: z.ZodDefault<z.ZodNumber>;
+        tracking: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>;
+    colors: z.ZodObject<{
+        light: z.ZodObject<{
+            ground: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+            surface: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+            ink: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+            muted: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+            line: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+            primary: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+            onPrimary: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+            accent: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+            onAccent: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+            focus: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+            danger: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+            success: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+            warning: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+        }, z.core.$strip>;
+        dark: z.ZodObject<{
+            ground: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+            surface: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+            ink: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+            muted: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+            line: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+            primary: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+            onPrimary: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+            accent: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+            onAccent: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+            focus: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+            danger: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+            success: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+            warning: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+        }, z.core.$strip>;
+    }, z.core.$strip>;
+    paints: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>>;
+    fonts: z.ZodObject<{
+        display: z.ZodObject<{
+            family: z.ZodString;
+            id: z.ZodString;
+            weights: z.ZodArray<z.ZodNumber>;
+            license: z.ZodEnum<{
+                "OFL-1.1": "OFL-1.1";
+                "Apache-2.0": "Apache-2.0";
+            }>;
+            files: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+        }, z.core.$strip>;
+        text: z.ZodObject<{
+            family: z.ZodString;
+            id: z.ZodString;
+            weights: z.ZodArray<z.ZodNumber>;
+            license: z.ZodEnum<{
+                "OFL-1.1": "OFL-1.1";
+                "Apache-2.0": "Apache-2.0";
+            }>;
+            files: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+        }, z.core.$strip>;
+    }, z.core.$strip>;
+    radii: z.ZodPrefault<z.ZodObject<{
+        control: z.ZodDefault<z.ZodNumber>;
+        card: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>;
+    art: z.ZodPrefault<z.ZodObject<{
+        prompt: z.ZodDefault<z.ZodString>;
+        references: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            sha256: z.ZodString;
+            mime: z.ZodEnum<{
+                "image/png": "image/png";
+                "image/jpeg": "image/jpeg";
+                "image/webp": "image/webp";
+            }>;
+            width: z.ZodNumber;
+            height: z.ZodNumber;
+        }, z.core.$strip>>>;
+        referencesPublic: z.ZodDefault<z.ZodBoolean>;
+        avoid: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+    links: z.ZodDefault<z.ZodObject<{
+        site: z.ZodOptional<z.ZodObject<{
+            value: z.ZodString;
+            public: z.ZodDefault<z.ZodBoolean>;
+        }, z.core.$strip>>;
+        instagram: z.ZodOptional<z.ZodObject<{
+            value: z.ZodString;
+            public: z.ZodDefault<z.ZodBoolean>;
+        }, z.core.$strip>>;
+        facebook: z.ZodOptional<z.ZodObject<{
+            value: z.ZodString;
+            public: z.ZodDefault<z.ZodBoolean>;
+        }, z.core.$strip>>;
+        x: z.ZodOptional<z.ZodObject<{
+            value: z.ZodString;
+            public: z.ZodDefault<z.ZodBoolean>;
+        }, z.core.$strip>>;
+        linkedin: z.ZodOptional<z.ZodObject<{
+            value: z.ZodString;
+            public: z.ZodDefault<z.ZodBoolean>;
+        }, z.core.$strip>>;
+        youtube: z.ZodOptional<z.ZodObject<{
+            value: z.ZodString;
+            public: z.ZodDefault<z.ZodBoolean>;
+        }, z.core.$strip>>;
+        tiktok: z.ZodOptional<z.ZodObject<{
+            value: z.ZodString;
+            public: z.ZodDefault<z.ZodBoolean>;
+        }, z.core.$strip>>;
+        whatsapp: z.ZodOptional<z.ZodObject<{
+            value: z.ZodString;
+            public: z.ZodDefault<z.ZodBoolean>;
+        }, z.core.$strip>>;
+        email: z.ZodOptional<z.ZodObject<{
+            value: z.ZodString;
+            public: z.ZodDefault<z.ZodBoolean>;
+        }, z.core.$strip>>;
+        phone: z.ZodOptional<z.ZodObject<{
+            value: z.ZodString;
+            public: z.ZodDefault<z.ZodBoolean>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/** A parsed brand, with every default filled in. */
+export type Brand = z.output<typeof brandSchema>;
+/** What a person may write in brand.json: defaults may be left out. */
+export type BrandInput = z.input<typeof brandSchema>;
+export type Palette = Brand["colors"]["light"];
+export type BrandFont = Brand["fonts"]["display"];
+export type BrandCopy = z.output<typeof copySchema>;
+export type BrandIssue = {
+    path: string;
+    message: string;
+};
+export type ParseBrandResult = {
+    ok: true;
+    brand: Brand;
+} | {
+    ok: false;
+    reason: "newer" | "invalid";
+    issues: BrandIssue[];
+};
+/**
+ * Read a brand.json. A file from a newer kit is refused with "Update ideare" instead of being
+ * half-read, so a CLI never writes files from a format it does not know.
+ */
+export declare function parseBrand(input: unknown): ParseBrandResult;
+/** The JSON Schema for editors and outside tools, generated from the zod schema. */
+export declare function brandJsonSchema(): Record<string, unknown>;
+export {};