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

package/dist/scene/schema.d.ts

@@ -0,0 +1,271 @@
+import { z } from "zod";
+import { type ColorRole } from "../brand/schema.ts";
+/**
+ * The scene, v1: what every derived file, every editor design and every live image is drawn
+ * from. The shape stays close to Polotno's (pages of absolutely placed layers), so importing and
+ * exporting stays cheap. Coordinates are px in the page's own space; print sizes are converted to
+ * px at their dpi by the template that makes them. A group's layers sit in the group's own space:
+ * (0, 0) is the group frame's top-left corner, and they move and turn with it. A frame's `rotate`
+ * is in degrees, clockwise, about the frame's center.
+ *
+ * Page ids are unique in a scene and layer ids are unique on their page, groups included: the
+ * editor, its history and the render's boxes all find a layer by its id.
+ */
+export declare const SCENE_VERSION = 1;
+export type SolidPaint = {
+    token: ColorRole;
+    alpha?: number;
+} | {
+    hex: string;
+    alpha?: number;
+};
+export type GradientStop = {
+    at: number;
+    paint: SolidPaint;
+};
+export type Paint = SolidPaint | {
+    linear: {
+        angle: number;
+        stops: GradientStop[];
+    };
+}
+/** cx, cy and r are fractions of the layer's box (r of its larger side). */
+ | {
+    radial: {
+        cx: number;
+        cy: number;
+        r: number;
+        stops: GradientStop[];
+    };
+};
+export type FontRef = {
+    role: "display" | "text";
+    weight?: number;
+} | {
+    id: string;
+    weight: number;
+};
+export type Frame = {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    rotate?: number;
+};
+export type Lock = {
+    move?: boolean;
+    resize?: boolean;
+    edit?: boolean;
+    style?: boolean;
+    delete?: boolean;
+};
+export type AssetRef = {
+    sha256: string;
+    width: number;
+    height: number;
+    mime: string;
+};
+export type Blend = "normal" | "multiply" | "screen" | "overlay";
+type Base = {
+    id: string;
+    name?: string;
+    frame: Frame;
+    opacity?: number;
+    blend?: Blend;
+    hidden?: boolean;
+    lock?: Lock;
+    /** "Use any color" and any font: hex paints and font ids outside the brand are allowed. */
+    free?: boolean;
+};
+export type TextLayer = Base & {
+    type: "text";
+    text: string;
+    /** A slot the template or a live image URL can fill (`t.<slot>`). */
+    slot?: string;
+    style: {
+        font: FontRef;
+        size: number;
+        lineHeight: number;
+        tracking?: number;
+        align?: "start" | "center" | "end";
+        valign?: "top" | "middle" | "bottom";
+        uppercase?: boolean;
+        fill: SolidPaint;
+    };
+    fit?: {
+        mode: "none" | "shrink";
+        min: number;
+        maxLines?: number;
+    };
+};
+export type ImageLayer = Base & {
+    type: "image";
+    slot?: string;
+    asset: AssetRef;
+    fit: "cover" | "contain";
+    /** Where the crop centers, 0..1 on each axis. */
+    focus?: {
+        x: number;
+        y: number;
+    };
+    radius?: number;
+    mask?: "rect" | "circle";
+};
+export type LogoLayer = Base & {
+    type: "logo";
+    variant: "mark" | "small" | "wordmark" | "horizontal" | "stacked";
+    /** color: as drawn, adapted to the ground. ink or white: one color. auto: the same as color. */
+    tone: "color" | "ink" | "white" | "auto";
+    /** Where the logo sits across its frame when the frame is wider. Default center. */
+    align?: "start" | "center" | "end";
+};
+export type ShapeLayer = Base & {
+    type: "shape";
+    shape: "rect" | "ellipse" | "line" | "path";
+    /** Path data in the frame's own space (0,0 is the frame's corner). */
+    d?: string;
+    radius?: number;
+    fill?: Paint;
+    stroke?: {
+        paint: SolidPaint;
+        width: number;
+        dash?: number[];
+    };
+    shadow?: {
+        x: number;
+        y: number;
+        blur: number;
+        paint: SolidPaint;
+    };
+};
+export type IconLayer = Base & {
+    type: "icon";
+    /** A name from the kit's icon set, like "scissors" or "lucide:scissors". */
+    icon: string;
+    stroke: SolidPaint;
+    strokeWidth?: number;
+};
+export type ArtLayer = Base & {
+    type: "art";
+    /** A photo slot the editor and the template name (`photo`), filled by an upload or AI art. */
+    slot?: string;
+    asset?: AssetRef;
+    /** The brief for an AI picture in the brand's style; drawn by a job, never in the scene. */
+    prompt?: string;
+    focus?: {
+        x: number;
+        y: number;
+    };
+    radius?: number;
+};
+export type QrLayer = Base & {
+    type: "qr";
+    value: string;
+    fill: SolidPaint;
+    background?: SolidPaint;
+    ecc?: "L" | "M" | "Q" | "H";
+};
+export type GroupLayer = Base & {
+    type: "group";
+    layers: Layer[];
+};
+export type Layer = TextLayer | ImageLayer | LogoLayer | ShapeLayer | IconLayer | ArtLayer | QrLayer | GroupLayer;
+export type Background = Paint | {
+    image: AssetRef;
+    fit: "cover" | "contain";
+    focus?: {
+        x: number;
+        y: number;
+    };
+};
+export type Page = {
+    id: string;
+    name?: string;
+    background: Background;
+    /** A tiled grain over the page, 0..1 opacity (a PNG tile, never feTurbulence). */
+    grain?: number;
+    layers: Layer[];
+};
+export type Slot = {
+    kind: "text" | "image";
+    label: string;
+    maxChars?: number;
+    required?: boolean;
+    live?: boolean;
+};
+export type Scene = {
+    v: 1;
+    id?: string;
+    /** A preset from FORMATS, like "ig-post". */
+    format?: string;
+    size: {
+        w: number;
+        h: number;
+    };
+    theme: "light" | "dark";
+    locale?: string;
+    pages: Page[];
+    slots?: Record<string, Slot>;
+    meta?: {
+        name?: string;
+        template?: string;
+        source?: "ai" | "user" | "template";
+    };
+};
+export declare const layerSchema: z.ZodType<Layer>;
+export declare const sceneSchema: z.ZodType<Scene>;
+export declare function parseScene(input: unknown): {
+    ok: true;
+    scene: Scene;
+} | {
+    ok: false;
+    issues: {
+        path: string;
+        message: string;
+    }[];
+};
+/** The sizes the studio offers and the derived files use, in px. */
+export declare const FORMATS: {
+    readonly "ig-post": {
+        readonly w: 1080;
+        readonly h: 1350;
+        readonly label: "Instagram post";
+    };
+    readonly "ig-square": {
+        readonly w: 1080;
+        readonly h: 1080;
+        readonly label: "Square post";
+    };
+    readonly "ig-story": {
+        readonly w: 1080;
+        readonly h: 1920;
+        readonly label: "Story";
+    };
+    readonly "wa-status": {
+        readonly w: 1080;
+        readonly h: 1920;
+        readonly label: "WhatsApp status";
+    };
+    readonly "share-card": {
+        readonly w: 1200;
+        readonly h: 630;
+        readonly label: "Share card";
+    };
+    readonly "x-header": {
+        readonly w: 1500;
+        readonly h: 500;
+        readonly label: "X header";
+    };
+    readonly "linkedin-banner": {
+        readonly w: 1584;
+        readonly h: 396;
+        readonly label: "LinkedIn banner";
+    };
+    readonly avatar: {
+        readonly w: 1080;
+        readonly h: 1080;
+        readonly label: "Profile picture";
+    };
+};
+export type FormatId = keyof typeof FORMATS;
+export {};

package/dist/scene/schema.js

@@ -0,0 +1,257 @@
+import { z } from "zod";
+import { COLOR_ROLES } from "../brand/schema.js";
+/**
+ * The scene, v1: what every derived file, every editor design and every live image is drawn
+ * from. The shape stays close to Polotno's (pages of absolutely placed layers), so importing and
+ * exporting stays cheap. Coordinates are px in the page's own space; print sizes are converted to
+ * px at their dpi by the template that makes them. A group's layers sit in the group's own space:
+ * (0, 0) is the group frame's top-left corner, and they move and turn with it. A frame's `rotate`
+ * is in degrees, clockwise, about the frame's center.
+ *
+ * Page ids are unique in a scene and layer ids are unique on their page, groups included: the
+ * editor, its history and the render's boxes all find a layer by its id.
+ */
+export const SCENE_VERSION = 1;
+const unit = z.number().min(0).max(1);
+const hex = z.string().regex(/^#[0-9a-fA-F]{6}$/);
+const solid = z.union([
+    z.object({ token: z.enum(COLOR_ROLES), alpha: unit.optional() }).strict(),
+    z.object({ hex, alpha: unit.optional() }).strict(),
+]);
+const stops = z
+    .array(z.object({ at: unit, paint: solid }))
+    .min(2)
+    .max(8);
+const paint = z.union([
+    solid,
+    z.object({ linear: z.object({ angle: z.number(), stops }) }).strict(),
+    z
+        .object({
+        radial: z.object({ cx: z.number(), cy: z.number(), r: z.number().positive(), stops }),
+    })
+        .strict(),
+]);
+const focus = z.object({ x: unit, y: unit });
+/** An upload's own size, as the scene claims it. The renderer draws by it, so it is capped. */
+const assetSide = z.number().int().positive().max(65_535);
+const asset = z.object({
+    sha256: z.string().regex(/^[0-9a-f]{64}$/),
+    width: assetSide,
+    height: assetSide,
+    mime: z.enum(["image/png", "image/jpeg"]),
+});
+const frame = z.object({
+    x: z.number(),
+    y: z.number(),
+    w: z.number().nonnegative(),
+    h: z.number().nonnegative(),
+    rotate: z.number().optional(),
+});
+const base = {
+    id: z.string().min(1).max(64),
+    name: z.string().max(80).optional(),
+    frame,
+    opacity: unit.optional(),
+    blend: z.enum(["normal", "multiply", "screen", "overlay"]).optional(),
+    hidden: z.boolean().optional(),
+    lock: z
+        .object({
+        move: z.boolean().optional(),
+        resize: z.boolean().optional(),
+        edit: z.boolean().optional(),
+        style: z.boolean().optional(),
+        delete: z.boolean().optional(),
+    })
+        .optional(),
+    free: z.boolean().optional(),
+};
+const fontRef = z.union([
+    z.object({
+        role: z.enum(["display", "text"]),
+        weight: z.number().int().min(100).max(900).optional(),
+    }),
+    z.object({ id: z.string().regex(/^[a-z0-9-]+$/), weight: z.number().int().min(100).max(900) }),
+]);
+export const layerSchema = z.lazy(() => z.discriminatedUnion("type", [
+    z.object({
+        ...base,
+        type: z.literal("text"),
+        text: z.string().max(2000),
+        slot: z.string().max(40).optional(),
+        style: z.object({
+            font: fontRef,
+            size: z.number().positive().max(2000),
+            lineHeight: z.number().positive().max(4),
+            tracking: z.number().min(-0.5).max(1).optional(),
+            align: z.enum(["start", "center", "end"]).optional(),
+            valign: z.enum(["top", "middle", "bottom"]).optional(),
+            uppercase: z.boolean().optional(),
+            fill: solid,
+        }),
+        fit: z
+            .object({
+            mode: z.enum(["none", "shrink"]),
+            min: z.number().positive(),
+            maxLines: z.number().int().positive().optional(),
+        })
+            .optional(),
+    }),
+    z.object({
+        ...base,
+        type: z.literal("image"),
+        slot: z.string().max(40).optional(),
+        asset,
+        fit: z.enum(["cover", "contain"]),
+        focus: focus.optional(),
+        radius: z.number().nonnegative().optional(),
+        mask: z.enum(["rect", "circle"]).optional(),
+    }),
+    z.object({
+        ...base,
+        type: z.literal("logo"),
+        variant: z.enum(["mark", "small", "wordmark", "horizontal", "stacked"]),
+        tone: z.enum(["color", "ink", "white", "auto"]),
+        align: z.enum(["start", "center", "end"]).optional(),
+    }),
+    z.object({
+        ...base,
+        type: z.literal("shape"),
+        shape: z.enum(["rect", "ellipse", "line", "path"]),
+        d: z
+            .string()
+            .regex(/^[MmLlHhVvCcSsQqTtAaZz\d\s,.eE+-]*$/)
+            .optional(),
+        radius: z.number().nonnegative().optional(),
+        fill: paint.optional(),
+        stroke: z
+            .object({
+            paint: solid,
+            width: z.number().positive(),
+            dash: z.array(z.number().nonnegative()).max(8).optional(),
+        })
+            .optional(),
+        shadow: z
+            .object({
+            x: z.number(),
+            y: z.number(),
+            blur: z.number().nonnegative().max(200),
+            paint: solid,
+        })
+            .optional(),
+    }),
+    z.object({
+        ...base,
+        type: z.literal("icon"),
+        icon: z.string().max(60),
+        stroke: solid,
+        strokeWidth: z.number().positive().max(6).optional(),
+    }),
+    z.object({
+        ...base,
+        type: z.literal("art"),
+        slot: z.string().max(40).optional(),
+        asset: asset.optional(),
+        prompt: z.string().max(2000).optional(),
+        focus: focus.optional(),
+        radius: z.number().nonnegative().optional(),
+    }),
+    z.object({
+        ...base,
+        type: z.literal("qr"),
+        value: z.string().min(1).max(2000),
+        fill: solid,
+        background: solid.optional(),
+        ecc: z.enum(["L", "M", "Q", "H"]).optional(),
+    }),
+    z.object({ ...base, type: z.literal("group"), layers: z.array(layerSchema).max(200) }),
+]));
+const background = z.union([
+    paint,
+    z.object({ image: asset, fit: z.enum(["cover", "contain"]), focus: focus.optional() }).strict(),
+]);
+export const sceneSchema = z
+    .object({
+    v: z.literal(SCENE_VERSION),
+    id: z.string().max(64).optional(),
+    format: z.string().max(40).optional(),
+    size: z.object({
+        w: z.number().int().positive().max(8192),
+        h: z.number().int().positive().max(8192),
+    }),
+    theme: z.enum(["light", "dark"]),
+    locale: z.string().max(10).optional(),
+    pages: z
+        .array(z.object({
+        id: z.string().min(1).max(64),
+        name: z.string().max(80).optional(),
+        background,
+        grain: unit.optional(),
+        layers: z.array(layerSchema).max(200),
+    }))
+        .min(1)
+        .max(20),
+    slots: z
+        .record(z.string(), z.object({
+        kind: z.enum(["text", "image"]),
+        label: z.string().max(60),
+        maxChars: z.number().int().positive().optional(),
+        required: z.boolean().optional(),
+        live: z.boolean().optional(),
+    }))
+        .optional(),
+    meta: z
+        .object({
+        name: z.string().max(80).optional(),
+        template: z.string().max(80).optional(),
+        source: z.enum(["ai", "user", "template"]).optional(),
+    })
+        .optional(),
+})
+    .superRefine((scene, ctx) => {
+    const pageIds = new Set();
+    scene.pages.forEach((page, pageIndex) => {
+        if (pageIds.has(page.id))
+            ctx.addIssue({
+                code: "custom",
+                path: ["pages", pageIndex, "id"],
+                message: "Give each page its own id.",
+            });
+        pageIds.add(page.id);
+        const layerIds = new Set();
+        const walk = (layers, path) => layers.forEach((layer, index) => {
+            if (layerIds.has(layer.id))
+                ctx.addIssue({
+                    code: "custom",
+                    path: [...path, index, "id"],
+                    message: "Give each layer on a page its own id.",
+                });
+            layerIds.add(layer.id);
+            if (layer.type === "group")
+                walk(layer.layers, [...path, index, "layers"]);
+        });
+        walk(page.layers, ["pages", pageIndex, "layers"]);
+    });
+});
+export function parseScene(input) {
+    const result = sceneSchema.safeParse(input);
+    if (result.success)
+        return { ok: true, scene: result.data };
+    return {
+        ok: false,
+        issues: result.error.issues.map((issue) => ({
+            path: issue.path.map(String).join(".") || "(root)",
+            message: issue.message,
+        })),
+    };
+}
+/** The sizes the studio offers and the derived files use, in px. */
+export const FORMATS = {
+    "ig-post": { w: 1080, h: 1350, label: "Instagram post" },
+    "ig-square": { w: 1080, h: 1080, label: "Square post" },
+    "ig-story": { w: 1080, h: 1920, label: "Story" },
+    "wa-status": { w: 1080, h: 1920, label: "WhatsApp status" },
+    "share-card": { w: 1200, h: 630, label: "Share card" },
+    "x-header": { w: 1500, h: 500, label: "X header" },
+    "linkedin-banner": { w: 1584, h: 396, label: "LinkedIn banner" },
+    avatar: { w: 1080, h: 1080, label: "Profile picture" },
+};

package/dist/sign.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Purpose-keyed HMAC signing on Web Crypto, so the API, the worker, the SDK and a browser share
+ * one implementation (Node 20, Bun, Workers and browsers all have crypto.subtle). Copied from
+ * @gusnips/server's token.ts (MIT, same author) so the kit does not depend on a server package.
+ *
+ * **The purpose is in the key.** The signing key is HMAC(secret, purpose), so the secret never
+ * signs anything itself, and a signature made for one purpose never verifies for another.
+ */
+/** Equal in a time that does not depend on where they first differ. False when either is empty. */
+export declare function safeEqual(a: string, b: string): boolean;
+/** The base64url HMAC of `message`, keyed by HMAC(secret, purpose). */
+export declare function sign(input: {
+    secret: string;
+    purpose: string;
+    message: string;
+}): Promise<string>;
+export declare function verify(input: {
+    secret: string;
+    purpose: string;
+    message: string;
+    signature: string;
+}): Promise<boolean>;
+/** The purpose live image URLs are signed for. Bump the suffix to retire every old link. */
+export declare const LIVE_IMAGE_PURPOSE = "live-image:v1";
+/**
+ * The exact string a live image signature covers: the path, then every query parameter except
+ * `sig`, sorted by name (then value) and percent-encoded the same way on both sides. Reordering
+ * the query or encoding a space as `+` or `%20` gives the same message.
+ */
+export declare function canonicalImageMessage(path: string, params: Iterable<[string, string]>): string;
+/**
+ * A signed live image URL, like `https://img.ideare.app/acme/sale.png?v=3&t.title=...&sig=...`.
+ * The brand's live-image secret signs it; text without a valid signature gets a 403.
+ */
+export declare function signImageUrl(input: {
+    secret: string;
+    /** The origin, like https://img.ideare.app. */
+    origin: string;
+    /** The path, like /acme/sale.png. */
+    path: string;
+    params: Record<string, string>;
+}): Promise<string>;
+/** Whether a request URL carries a valid live image signature. */
+export declare function verifyImageUrl(input: {
+    secret: string;
+    url: string | URL;
+}): Promise<boolean>;

package/dist/sign.js

@@ -0,0 +1,88 @@
+/**
+ * Purpose-keyed HMAC signing on Web Crypto, so the API, the worker, the SDK and a browser share
+ * one implementation (Node 20, Bun, Workers and browsers all have crypto.subtle). Copied from
+ * @gusnips/server's token.ts (MIT, same author) so the kit does not depend on a server package.
+ *
+ * **The purpose is in the key.** The signing key is HMAC(secret, purpose), so the secret never
+ * signs anything itself, and a signature made for one purpose never verifies for another.
+ */
+const encoder = new TextEncoder();
+/** HMAC-SHA256 as raw bytes. Throws on an empty key: Web Crypto refuses one anyway. */
+async function hmacBytes(key, message) {
+    // A copy, because Web Crypto takes only a view over a plain ArrayBuffer.
+    const raw = new Uint8Array(typeof key === "string" ? encoder.encode(key) : key);
+    if (raw.length === 0)
+        throw new TypeError("An HMAC key must not be empty");
+    const imported = await crypto.subtle.importKey("raw", raw, { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+    return new Uint8Array(await crypto.subtle.sign("HMAC", imported, encoder.encode(message)));
+}
+/** Equal in a time that does not depend on where they first differ. False when either is empty. */
+export function safeEqual(a, b) {
+    const left = encoder.encode(a);
+    const right = encoder.encode(b);
+    if (left.length === 0 || left.length !== right.length)
+        return false;
+    let difference = 0;
+    for (let i = 0; i < left.length; i++)
+        difference |= (left[i] ?? 0) ^ (right[i] ?? 0);
+    return difference === 0;
+}
+function base64Url(bytes) {
+    let binary = "";
+    for (const byte of bytes)
+        binary += String.fromCharCode(byte);
+    return btoa(binary).replaceAll("+", "-").replaceAll("/", "_").replace(/=+$/, "");
+}
+/** The base64url HMAC of `message`, keyed by HMAC(secret, purpose). */
+export async function sign(input) {
+    if (!input.purpose)
+        throw new TypeError("A signature's purpose must not be empty");
+    const key = await hmacBytes(input.secret, input.purpose);
+    return base64Url(await hmacBytes(key, input.message));
+}
+export async function verify(input) {
+    if (!/^[A-Za-z0-9_-]{43}$/.test(input.signature))
+        return false;
+    return safeEqual(input.signature, await sign(input));
+}
+/** The purpose live image URLs are signed for. Bump the suffix to retire every old link. */
+export const LIVE_IMAGE_PURPOSE = "live-image:v1";
+/**
+ * The exact string a live image signature covers: the path, then every query parameter except
+ * `sig`, sorted by name (then value) and percent-encoded the same way on both sides. Reordering
+ * the query or encoding a space as `+` or `%20` gives the same message.
+ */
+export function canonicalImageMessage(path, params) {
+    const pairs = [...params]
+        .filter(([name]) => name !== "sig")
+        .sort(([a, x], [b, y]) => (a < b ? -1 : a > b ? 1 : x < y ? -1 : x > y ? 1 : 0))
+        .map(([name, value]) => `${encodeURIComponent(name)}=${encodeURIComponent(value)}`);
+    return `${path}?${pairs.join("&")}`;
+}
+/**
+ * A signed live image URL, like `https://img.ideare.app/acme/sale.png?v=3&t.title=...&sig=...`.
+ * The brand's live-image secret signs it; text without a valid signature gets a 403.
+ */
+export async function signImageUrl(input) {
+    const entries = Object.entries(input.params);
+    const sig = await sign({
+        secret: input.secret,
+        purpose: LIVE_IMAGE_PURPOSE,
+        message: canonicalImageMessage(input.path, entries),
+    });
+    const query = new URLSearchParams([...entries, ["sig", sig]]);
+    return `${input.origin.replace(/\/$/, "")}${input.path}?${query.toString()}`;
+}
+/** Whether a request URL carries a valid live image signature. */
+export async function verifyImageUrl(input) {
+    const url = typeof input.url === "string" ? new URL(input.url) : input.url;
+    const signature = url.searchParams.get("sig");
+    if (!signature)
+        return false;
+    return verify({
+        secret: input.secret,
+        purpose: LIVE_IMAGE_PURPOSE,
+        message: canonicalImageMessage(url.pathname, url.searchParams.entries()),
+        signature,
+    });
+}