freshcoat 0.1.0

package/src/runtime.js

@@ -0,0 +1,44 @@
+import { paintScene } from "./canvaskit.js";
+// The "env owns disposal" seam: a server env encodes+disposes the output (PNG
+// bytes), a browser env hands back the live canvas untouched.
+export async function applyDisposePolicy(output, policy, encode) {
+    if (policy === "encode") {
+        // The format comes back from the encoder rather than being echoed from the
+        // request: a build without the WebP encoder answers in PNG, and the caller
+        // has to know which it got before it labels it.
+        const { bytes, format } = await output.encode(encode);
+        output.dispose();
+        return { bytes, format, warnings: output.warnings };
+    }
+    // "keep" hands back the live surface, which only a raster backend has. A
+    // document backend under this policy is a misconfigured runtime rather than a
+    // render that can degrade, so it says so here instead of returning a result
+    // whose `canvas` is undefined.
+    if (!output.canvas)
+        throw new Error('paint runtime policy "keep" requires a backend with a canvas');
+    return {
+        canvas: output.canvas,
+        warnings: output.warnings,
+        dispose: output.dispose,
+    };
+}
+// The in-tree Painter: CanvasKit-WASM with its instance bound. A second backend
+// supplies its own and is otherwise indistinguishable to the runtime.
+export const paintCanvasKit = (ck) => (commands, rt) => paintScene(ck, commands, rt);
+// Assemble a runtime from its I/O + canvas parts, a disposal policy and a
+// backend. paint() runs the Painter for one scene and applies the policy;
+// omitting the Painter selects CanvasKit, which is what every caller in the tree
+// does.
+export function makeRuntime(base, policy, encode, painter) {
+    const rt = {
+        ...base,
+        async paint(commands, ck) {
+            // Without a painter the backend is CanvasKit and `ck` is its instance,
+            // which is every caller in the tree. With one, the backend was chosen at
+            // construction and `ck` is not consulted.
+            const paint = painter ?? paintCanvasKit(ck);
+            return applyDisposePolicy(await paint(commands, rt), policy, encode);
+        },
+    };
+    return rt;
+}

package/src/squircle.d.ts

@@ -0,0 +1 @@
+export declare function squircleSvg(x: number, y: number, w: number, h: number, radius: number, smoothing: number): string;

package/src/squircle.js

@@ -0,0 +1,60 @@
+// Figma corner smoothing ("squircle") — an SVG path for a rounded rect whose
+// corners blend from a plain circular arc (smoothing 0) to a
+// continuous-curvature superellipse (smoothing → 1), matching Figma's
+// corner-smoothing control. Ported from figma-squircle (tienphaw/figma-squircle,
+// MIT), specialized to a uniform radius + smoothing.
+function toRadians(deg) {
+    return (deg * Math.PI) / 180;
+}
+function n(v) {
+    return v.toFixed(4);
+}
+function getPathParamsForCorner(cornerRadius, cornerSmoothing, budget) {
+    let p = (1 + cornerSmoothing) * cornerRadius;
+    const maxCornerSmoothing = budget / cornerRadius - 1;
+    const smoothing = Math.min(cornerSmoothing, maxCornerSmoothing);
+    p = Math.min(p, budget);
+    const arcMeasure = 90 * (1 - smoothing);
+    const arcSectionLength = Math.sin(toRadians(arcMeasure / 2)) * cornerRadius * Math.SQRT2;
+    const angleAlpha = (90 - arcMeasure) / 2;
+    const p3ToP4Distance = cornerRadius * Math.tan(toRadians(angleAlpha / 2));
+    const angleBeta = 45 * smoothing;
+    const c = p3ToP4Distance * Math.cos(toRadians(angleBeta));
+    const d = c * Math.tan(toRadians(angleBeta));
+    const b = (p - arcSectionLength - c - d) / 3;
+    const a = 2 * b;
+    return { a, b, c, d, p, arcSectionLength, cornerRadius };
+}
+function topRight({ cornerRadius: r, a, b, c, d, arcSectionLength: arc, }) {
+    return `c ${n(a)} 0 ${n(a + b)} 0 ${n(a + b + c)} ${n(d)} a ${n(r)} ${n(r)} 0 0 1 ${n(arc)} ${n(arc)} c ${n(d)} ${n(c)} ${n(d)} ${n(b + c)} ${n(d)} ${n(a + b + c)}`;
+}
+function bottomRight({ cornerRadius: r, a, b, c, d, arcSectionLength: arc, }) {
+    return `c 0 ${n(a)} 0 ${n(a + b)} ${n(-d)} ${n(a + b + c)} a ${n(r)} ${n(r)} 0 0 1 ${n(-arc)} ${n(arc)} c ${n(-c)} ${n(d)} ${n(-(b + c))} ${n(d)} ${n(-(a + b + c))} ${n(d)}`;
+}
+function bottomLeft({ cornerRadius: r, a, b, c, d, arcSectionLength: arc, }) {
+    return `c ${n(-a)} 0 ${n(-(a + b))} 0 ${n(-(a + b + c))} ${n(-d)} a ${n(r)} ${n(r)} 0 0 1 ${n(-arc)} ${n(-arc)} c ${n(-d)} ${n(-c)} ${n(-d)} ${n(-(b + c))} ${n(-d)} ${n(-(a + b + c))}`;
+}
+function topLeft({ cornerRadius: r, a, b, c, d, arcSectionLength: arc, }) {
+    return `c 0 ${n(-a)} 0 ${n(-(a + b))} ${n(d)} ${n(-(a + b + c))} a ${n(r)} ${n(r)} 0 0 1 ${n(arc)} ${n(-arc)} c ${n(c)} ${n(-d)} ${n(b + c)} ${n(-d)} ${n(a + b + c)} ${n(-d)}`;
+}
+// SVG path for a smoothed rounded rect at (x, y) sized w×h with a uniform radius
+// and smoothing in [0, 1]. Corners are identical, so one param set drives all four.
+export function squircleSvg(x, y, w, h, radius, smoothing) {
+    const budget = Math.min(w, h) / 2;
+    const r = Math.min(radius, budget);
+    if (r <= 0)
+        return `M ${n(x)} ${n(y)} H ${n(x + w)} V ${n(y + h)} H ${n(x)} Z`;
+    const cp = getPathParamsForCorner(r, smoothing, budget);
+    const p = cp.p;
+    return [
+        `M ${n(x + w - p)} ${n(y)}`,
+        topRight(cp),
+        `L ${n(x + w)} ${n(y + h - p)}`,
+        bottomRight(cp),
+        `L ${n(x + p)} ${n(y + h)}`,
+        bottomLeft(cp),
+        `L ${n(x)} ${n(y + p)}`,
+        topLeft(cp),
+        "Z",
+    ].join(" ");
+}

package/src/text-cache.d.ts

@@ -0,0 +1,14 @@
+import type { TextEngine } from "./text-engine.js";
+export type TextEngineCacheStats = {
+    hits: number;
+    misses: number;
+    size: number;
+};
+export type CachedTextEngine<E extends TextEngine> = E & {
+    cacheStats(): TextEngineCacheStats;
+};
+/** Wraps `engine` with a least-recently-used cache of `maxEntries` results per
+ *  method. The wrapped engine must not change the faces it shapes with. */
+export declare function memoizeTextEngine<E extends TextEngine>(engine: E, opts?: {
+    maxEntries?: number;
+}): CachedTextEngine<E>;

package/src/text-cache.js

@@ -0,0 +1,46 @@
+/** Wraps `engine` with a least-recently-used cache of `maxEntries` results per
+ *  method. The wrapped engine must not change the faces it shapes with. */
+export function memoizeTextEngine(engine, opts = {}) {
+    const max = opts.maxEntries ?? 4000;
+    const stats = { hits: 0, misses: 0 };
+    const caches = [];
+    const memo = (fn) => {
+        const cache = new Map();
+        caches.push(cache);
+        return (...args) => {
+            const key = JSON.stringify(args);
+            const hit = cache.get(key);
+            if (hit !== undefined) {
+                stats.hits++;
+                cache.delete(key);
+                cache.set(key, hit);
+                return hit;
+            }
+            stats.misses++;
+            const value = deepFreeze(fn(...args));
+            cache.set(key, value);
+            if (cache.size > max)
+                cache.delete(cache.keys().next().value);
+            return value;
+        };
+    };
+    return {
+        ...engine,
+        measureText: memo(engine.measureText),
+        measureSpanWidth: memo(engine.measureSpanWidth),
+        layoutText: memo(engine.layoutText),
+        ...(engine.layoutInline ? { layoutInline: memo(engine.layoutInline) } : {}),
+        cacheStats: () => ({
+            ...stats,
+            size: caches.reduce((n, c) => n + c.size, 0),
+        }),
+    };
+}
+function deepFreeze(value) {
+    if (value && typeof value === "object" && !Object.isFrozen(value)) {
+        Object.freeze(value);
+        for (const v of Object.values(value))
+            deepFreeze(v);
+    }
+    return value;
+}

package/src/text-engine.d.ts

@@ -0,0 +1,26 @@
+import type { MeasureText, TextLayout, TextLayoutInput } from "./text-types.js";
+import type { FontVMetrics } from "./types.js";
+export type SpanFont = TextLayoutInput["font"];
+export type InlineSpan = {
+    text: string;
+    font: SpanFont;
+};
+export type InlineFragment = {
+    spanIndex: number;
+    text: string;
+    x: number;
+    width: number;
+};
+export type InlineShapedLine = {
+    fragments: InlineFragment[];
+    width: number;
+};
+export type TextEngine = {
+    measureText: MeasureText;
+    measureSpanWidth: (text: string, font: SpanFont) => number;
+    layoutText: (input: TextLayoutInput) => TextLayout;
+    layoutInline?: (spans: InlineSpan[], maxWidth: number) => {
+        lines: InlineShapedLine[];
+    };
+    metricsFor?: (family: string) => FontVMetrics | undefined;
+};

package/src/text-engine.js

@@ -0,0 +1 @@
+export {};

package/src/text-types.d.ts

@@ -0,0 +1,30 @@
+import type { FontVariations, ResolvedFont } from "./types.js";
+export type MeasureText = (text: string, font: ResolvedFont, maxWidth: number | null) => {
+    width: number;
+    height: number;
+};
+export type TextLayoutInput = {
+    value: string;
+    font: {
+        family: string;
+        size: number;
+        weight?: number;
+        style?: string;
+        letterSpacing?: number;
+        variations?: FontVariations;
+    };
+    maxWidth: number;
+    maxHeight: number;
+    lineHeight: number;
+    fit: "shrink" | "clip" | undefined;
+};
+export type MeasuredLine = {
+    text: string;
+    width: number;
+};
+export type TextLayout = {
+    lines: MeasuredLine[];
+    totalHeight: number;
+    effectiveFontSize: number;
+    shrinkApplied: boolean;
+};

package/src/text-types.js

@@ -0,0 +1 @@
+export {};

package/src/types.d.ts

@@ -0,0 +1,406 @@
+import type { DecodedPixels } from "./decode.js";
+import type { PaintCache } from "./paint-cache.js";
+import type { EncodeFormat, EncodeOptions } from "./png.js";
+export type Vec2 = {
+    x: number;
+    y: number;
+};
+export type Size = {
+    width: number;
+    height: number;
+};
+export type BlendMode = "normal" | "multiply" | "screen" | "overlay" | "darken" | "lighten" | "color-dodge" | "color-burn" | "hard-light" | "soft-light" | "difference" | "exclusion" | "hue" | "saturation" | "color" | "luminosity" | "plus";
+export type FillRule = "nonzero" | "evenodd";
+export type FontWeight = 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900;
+export type FontVariations = Record<string, number>;
+export type FontFile = {
+    weight: FontWeight;
+    style?: "normal" | "italic";
+    src: string;
+};
+export type FontDescriptor = {
+    kind: "google";
+    family: string;
+    url: string;
+} | {
+    kind: "fontsource";
+    family: string;
+    url: string;
+} | {
+    kind: "local";
+    family: string;
+    files: FontFile[];
+};
+export type GradientStop = {
+    offset: number;
+    color: string;
+};
+export type FontRequest = {
+    family: string;
+} | {
+    family: string;
+    descriptor: FontDescriptor;
+};
+export type Shadow = {
+    color: string;
+    dx: number;
+    dy: number;
+    blur: number;
+    /** Grows the shadow's silhouette before it is blurred (negative shrinks it),
+     *  matching Figma's "Spread" and CSS's third box-shadow length. */
+    spread?: number;
+    /** Draw the shadow INSIDE the drawable instead of behind it — Figma's inner
+     *  shadow, CSS's `inset`. The silhouette is inverted, so the shadow falls
+     *  from the shape's own edges inward. */
+    inset?: boolean;
+};
+/** One shadow, or a stack of them painted bottom-up: the LAST entry is nearest
+ *  the viewer, mirroring how a fills array stacks. Figma lists effects
+ *  top-first, so a producer reverses them on the way in. */
+export type Shadows = Shadow | Shadow[];
+export type ClipOutset = {
+    top: number;
+    bottom: number;
+};
+export type AdjustLut = {
+    r: Uint8Array;
+    g: Uint8Array;
+    b: Uint8Array;
+};
+export type AdjustLut3d = {
+    size: number;
+    data: Uint8Array;
+};
+export type Adjust = {
+    colorMatrix?: number[];
+    lut?: AdjustLut;
+    lut3d?: AdjustLut3d;
+    sharpen?: number;
+    gamut?: "clip" | "preserve-hue";
+};
+export type ShapeMask = {
+    kind: "rect";
+    outset?: ClipOutset;
+} | {
+    kind: "rounded-rect";
+    radius: number;
+} | {
+    kind: "circle";
+} | {
+    kind: "ellipse";
+} | {
+    kind: "polygon";
+    sides: number;
+    rotation?: number;
+} | {
+    kind: "squircle";
+    radius: number;
+};
+export type CornerRadius = number | [number, number, number, number];
+export type ViewBox = {
+    x?: number;
+    y?: number;
+    width: number;
+    height: number;
+};
+export type Stroke = {
+    color: string;
+    width: number;
+    dash?: number[];
+    cap?: "butt" | "round" | "square";
+    join?: "round" | "bevel" | "miter";
+    align?: "inside" | "outside" | "center";
+};
+export type ResolvedFill = {
+    kind: "solid";
+    color: string;
+} | {
+    kind: "linear";
+    stops: GradientStop[];
+    from: Vec2;
+    to: Vec2;
+} | {
+    kind: "radial";
+    stops: GradientStop[];
+    center: Vec2;
+    radius: number;
+    radiusY?: number;
+    rotation?: number;
+} | {
+    kind: "angular";
+    stops: GradientStop[];
+    center: Vec2;
+    rotation: number;
+};
+export type ResolvedFont = {
+    family: string;
+    weight: number;
+    style: "normal" | "italic";
+    size: number;
+    letterSpacing?: number;
+    lineHeight: number;
+    autoLineHeight?: boolean;
+    decoration?: "underline" | "line-through";
+    variations?: FontVariations;
+};
+export type BakedTextLayout = {
+    font: ResolvedFont;
+    lines: TextLine[];
+    totalHeight: number;
+    shrinkApplied: boolean;
+};
+export type TextLine = {
+    text: string;
+    y: number;
+    baseline?: number;
+    spans: TextLineSpan[];
+};
+export type TextLineSpan = {
+    text: string;
+    x: number;
+    width: number;
+    font: ResolvedFont;
+    color: string;
+};
+export type SetupCommand = {
+    op: "createCanvas";
+    width: number;
+    height: number;
+    scale?: number;
+    supersample?: number;
+} | {
+    op: "loadFonts";
+    requests: FontRequest[];
+} | {
+    op: "loadImages";
+    srcs: string[];
+};
+export type FrameDither = number | {
+    amount: number;
+    seed?: number;
+    mode?: "per-channel" | "monochrome";
+};
+export type FrameFinish = {
+    whiteClamp?: number;
+    blackExtract?: number;
+    dither?: FrameDither;
+};
+export type FinishCommand = {
+    op: "finishFrame";
+    finish: FrameFinish;
+};
+export type DrawCommandBase = {
+    id?: string;
+    pos: Vec2;
+    size: Size;
+    rotation?: number;
+    opacity?: number;
+    blendMode?: BlendMode;
+    clip?: ShapeMask;
+    shadow?: Shadows;
+    blur?: number;
+    adjust?: Adjust;
+};
+export type DrawTextCommand = DrawCommandBase & {
+    op: "drawText";
+    layout: BakedTextLayout;
+    color: string;
+    fill?: ResolvedFill;
+};
+export type DrawImageCommand = DrawCommandBase & {
+    op: "drawImage";
+    src: string;
+    fit: "cover" | "contain" | "fill" | "tile";
+    stroke?: Stroke;
+};
+export type DrawBitmapCommand = DrawCommandBase & {
+    op: "drawBitmap";
+    pixels: Uint8Array;
+    pixelWidth: number;
+    pixelHeight: number;
+    role?: BitmapRole;
+};
+export type BitmapRole = "barcode";
+export type DrawQrCommand = DrawCommandBase & {
+    op: "drawQr";
+    modules: boolean[][];
+    foreground: string;
+    background?: string;
+    margin?: number;
+};
+export type DrawRectCommand = DrawCommandBase & {
+    op: "drawRect";
+    fills?: ResolvedFill[];
+    stroke?: Stroke;
+    cornerRadius?: CornerRadius;
+    cornerSmoothing?: number;
+};
+export type DrawPathCommand = DrawCommandBase & {
+    op: "drawPath";
+    d: string;
+    fills?: ResolvedFill[];
+    stroke?: Stroke;
+    viewBox?: ViewBox;
+    fillRule?: FillRule;
+};
+export type DrawGroupCommand = DrawCommandBase & {
+    op: "drawGroup";
+    children: DrawCommand[];
+};
+export type DrawMaskedCommand = DrawCommandBase & {
+    op: "drawMasked";
+    mask: DrawCommand;
+    children: DrawCommand[];
+    channel?: "alpha" | "luminance";
+    invert?: boolean;
+};
+export type DrawCommand = DrawTextCommand | DrawImageCommand | DrawBitmapCommand | DrawQrCommand | DrawRectCommand | DrawPathCommand | DrawGroupCommand | DrawMaskedCommand;
+export type Command = SetupCommand | DrawCommand | FinishCommand;
+export type FontVMetrics = {
+    ascent: number;
+    descent: number;
+    lineGap: number;
+    capHeight: number;
+};
+export type CanvasLike = {
+    width: number;
+    height: number;
+    getContext(type: "2d"): CanvasRenderingContext2DLike | null;
+};
+export type CanvasGradientLike = {
+    addColorStop(offset: number, color: string): void;
+};
+export type CanvasPatternLike = {
+    readonly __canvasPattern?: never;
+};
+export type LineCap = "butt" | "round" | "square";
+export type LineJoin = "round" | "bevel" | "miter";
+export type TextAlign = "start" | "end" | "left" | "right" | "center";
+export type TextBaseline = "top" | "hanging" | "middle" | "alphabetic" | "ideographic" | "bottom";
+export type CanvasRenderingContext2DLike = {
+    fillStyle: string | CanvasGradientLike | CanvasPatternLike;
+    strokeStyle: string;
+    lineWidth: number;
+    lineCap: LineCap;
+    lineJoin: LineJoin;
+    globalAlpha: number;
+    globalCompositeOperation: string;
+    font: string;
+    textAlign: TextAlign;
+    textBaseline: TextBaseline;
+    shadowColor: string;
+    shadowBlur: number;
+    shadowOffsetX: number;
+    shadowOffsetY: number;
+    filter: string;
+    imageSmoothingEnabled?: boolean;
+    imageSmoothingQuality?: "low" | "medium" | "high";
+    save(): void;
+    restore(): void;
+    translate(x: number, y: number): void;
+    rotate(angle: number): void;
+    fillRect(x: number, y: number, w: number, h: number): void;
+    strokeRect(x: number, y: number, w: number, h: number): void;
+    beginPath(): void;
+    closePath(): void;
+    rect(x: number, y: number, w: number, h: number): void;
+    fill(path?: unknown): void;
+    stroke(path?: unknown): void;
+    clip(): void;
+    measureText(text: string): {
+        width: number;
+    };
+    fillText(text: string, x: number, y: number): void;
+    drawImage(image: unknown, dx: number, dy: number, dw: number, dh: number): void;
+    drawImage(image: unknown, sx: number, sy: number, sw: number, sh: number, dx: number, dy: number, dw: number, dh: number): void;
+    roundRect(x: number, y: number, w: number, h: number, radius: number | number[]): void;
+    setLineDash(segments: number[]): void;
+    createLinearGradient(x0: number, y0: number, x1: number, y1: number): CanvasGradientLike;
+    createRadialGradient(x0: number, y0: number, r0: number, x1: number, y1: number, r1: number): CanvasGradientLike;
+    createConicGradient(startAngle: number, x: number, y: number): CanvasGradientLike;
+    createPattern(image: unknown, repetition: "repeat" | "repeat-x" | "repeat-y" | "no-repeat"): CanvasPatternLike | null;
+};
+export type ImageLike = {
+    width: number;
+    height: number;
+};
+export type PaintWarning = {
+    kind: "image_load_failed";
+    src: string;
+    error: string;
+} | {
+    kind: "font_load_failed";
+    family: string;
+    error: string;
+} | {
+    kind: "qr_generate_failed";
+    value: string;
+    error: string;
+} | {
+    kind: "barcode_unavailable";
+    symbology: string;
+    layer?: string;
+} | {
+    kind: "barcode_invalid";
+    symbology: string;
+    value: string;
+    message: string;
+    layer?: string;
+} | {
+    kind: "unhandled_op";
+    op: string;
+} | {
+    kind: "adjust_unsupported";
+    component: "lut" | "lut3d" | "sharpen" | "gamut";
+    layer?: string;
+} | {
+    kind: "gamut_compressed";
+    layer?: string;
+    clipped: number;
+    pullback: number;
+};
+export type PaintOutput = {
+    canvas?: CanvasLike;
+    warnings: PaintWarning[];
+    readPixels?(): DecodedPixels | null;
+    encode(opts?: EncodeOptions): Promise<{
+        bytes: Uint8Array;
+        format: EncodeFormat;
+    }>;
+    dispose(): void;
+};
+export type CanvasHost = {
+    createCanvas(width: number, height: number): CanvasLike;
+    decodeImage(bytes: Uint8Array): Promise<ImageLike>;
+    encode(canvas: CanvasLike): Uint8Array;
+};
+export type FontResolution = {
+    kind: "bytes";
+    bytes: Uint8Array[];
+} | {
+    kind: "descriptor";
+    descriptor: FontDescriptor;
+} | {
+    kind: "none";
+};
+export type PaintRuntime = {
+    resolveFont(req: FontRequest | string): FontResolution;
+    loadImageBytes(src: string): Promise<Uint8Array>;
+    loadImage?(src: string, ck: unknown): Promise<unknown | null>;
+    canvas?: CanvasHost;
+    registerFont?(family: string, res: FontResolution): void | Promise<void>;
+    cache?: PaintCache;
+    paint(commands: Command[], ck?: unknown): Promise<PaintResult>;
+};
+export type Painter = (commands: Command[], rt: PaintRuntime) => Promise<PaintOutput>;
+export type KeptPaintResult = {
+    canvas: CanvasLike;
+    warnings: PaintWarning[];
+    dispose(): void;
+};
+export type EncodedPaintResult = {
+    bytes: Uint8Array;
+    format: EncodeFormat;
+    warnings: PaintWarning[];
+};
+export type PaintResult = KeptPaintResult | EncodedPaintResult;

package/src/types.js

@@ -0,0 +1,13 @@
+// freshcoat's type vocabulary: the geometry primitives, the backend-agnostic
+// IR (Command / DrawCommand) the painters consume, the resolved style vocabulary
+// compile bakes and paint reads, and the paint runtime contract. Kept free of
+// zod / authoring (Template, Element) so a consumer can build a Command[] scene
+// and render it without pulling in the template-authoring layer. freshcoat paints
+// ONE scene per paint() — the notion of a card's multiple sides (named frames)
+// lives in coatfile, which drives paint() once per side.
+//
+// The geometry primitives (Vec2, Size, BlendMode, GradientStop, FontDescriptor,
+// FontFile) are hand-declared here as the canonical runtime shapes. coatfile
+// re-derives them via zod (schemas.ts) for authoring/validation; the two are kept
+// structurally identical.
+export {};

package/src/validate-commands.d.ts

@@ -0,0 +1,8 @@
+import type { Command } from "./types.js";
+export type IrIssue = {
+    code: string;
+    message: string;
+    path: string;
+    id?: string;
+};
+export declare function validateCommands(commands: Command[]): IrIssue[];