freshcoat 0.1.0

package/src/node.d.ts

@@ -0,0 +1,139 @@
+import type { Adjust, BitmapRole, BakedTextLayout, BlendMode, CornerRadius, FillRule, ResolvedFill, ResolvedFont, Shadows, ShapeMask, Size, Stroke, Vec2, ViewBox } from "./types.js";
+export type Padding = number | [top: number, right: number, bottom: number, left: number];
+export type Align = "start" | "center" | "end" | "stretch";
+export type Justify = "start" | "center" | "end" | "space-between" | "space-around" | "space-evenly";
+export type TrackSize = number | "auto" | `${number}fr`;
+export type FlexLayout = {
+    type: "flex";
+    direction: "row" | "column";
+    gap?: number;
+    crossGap?: number;
+    padding?: Padding;
+    align?: Align;
+    justify?: Justify;
+    wrap?: boolean;
+};
+export type GridLayout = {
+    type: "grid";
+    columns: TrackSize[];
+    rows?: TrackSize[];
+    gap?: number | [number, number];
+    padding?: Padding;
+};
+export type Layout = FlexLayout | GridLayout;
+export type ChildLayout = {
+    width?: "fill" | "hug" | number;
+    height?: "fill" | "hug" | number;
+    grow?: number;
+    alignSelf?: Align;
+    absolute?: boolean;
+    min?: {
+        width?: number;
+        height?: number;
+    };
+    max?: {
+        width?: number;
+        height?: number;
+    };
+    column?: number | [start: number, end: number];
+    row?: number | [start: number, end: number];
+};
+export type Transform = {
+    id?: string;
+    pos?: Vec2;
+    size?: Size;
+    rotation?: number;
+    opacity?: number;
+    blendMode?: BlendMode;
+    shadow?: Shadows;
+    blur?: number;
+    adjust?: Adjust;
+    layoutChild?: ChildLayout;
+};
+export type RectNode = Transform & {
+    kind: "rect";
+    fills?: ResolvedFill[];
+    stroke?: Stroke;
+    cornerRadius?: CornerRadius;
+    cornerSmoothing?: number;
+};
+export type EllipseNode = Transform & {
+    kind: "ellipse";
+    fills?: ResolvedFill[];
+    stroke?: Stroke;
+};
+export type PathNode = Transform & {
+    kind: "path";
+    d: string;
+    fills?: ResolvedFill[];
+    stroke?: Stroke;
+    viewBox?: ViewBox;
+    fillRule?: FillRule;
+};
+export type ImageNode = Transform & {
+    kind: "image";
+    src: string;
+    fit: "cover" | "contain" | "fill" | "tile";
+    stroke?: Stroke;
+    mask?: ShapeMask;
+};
+export type BitmapNode = Transform & {
+    kind: "bitmap";
+    pixels: Uint8Array;
+    pixelWidth: number;
+    pixelHeight: number;
+    role?: BitmapRole;
+};
+export type TextNode = Transform & {
+    kind: "text";
+    text?: string;
+    spans?: {
+        text: string;
+        font?: Partial<ResolvedFont>;
+        color?: string;
+    }[];
+    font: ResolvedFont;
+    color?: string;
+    fill?: ResolvedFill;
+    align?: "left" | "center" | "right";
+    verticalAlign?: "top" | "middle" | "bottom";
+    fit?: "shrink" | "clip";
+    maxLines?: number;
+    leadingTrim?: boolean;
+    layout?: BakedTextLayout;
+};
+export type GroupNode = Transform & {
+    kind: "group";
+    children: Node[];
+    layout?: Layout;
+    fills?: ResolvedFill[];
+    clip?: boolean;
+    cornerRadius?: CornerRadius;
+    cornerSmoothing?: number;
+};
+export type MaskNode = Transform & {
+    kind: "mask";
+    mask: Node;
+    children: Node[];
+    channel?: "alpha" | "luminance";
+    invert?: boolean;
+};
+export type Node = RectNode | EllipseNode | PathNode | ImageNode | BitmapNode | TextNode | GroupNode | MaskNode;
+export declare const createRect: (p: Omit<RectNode, "kind">) => RectNode;
+export declare const createEllipse: (p: Omit<EllipseNode, "kind">) => EllipseNode;
+export declare const createCircle: (p: Omit<EllipseNode, "kind">) => EllipseNode;
+export declare const createPath: (p: Omit<PathNode, "kind">) => PathNode;
+export declare const createImage: (p: Omit<ImageNode, "kind">) => ImageNode;
+export declare const createBitmap: (p: Omit<BitmapNode, "kind">) => BitmapNode;
+export declare const createText: (p: Omit<TextNode, "kind">) => TextNode;
+export declare const createGroup: (children: Node[], opts?: Omit<GroupNode, "kind" | "children">) => GroupNode;
+export declare const createMask: (mask: Node, children: Node[], opts?: Omit<MaskNode, "kind" | "mask" | "children">) => MaskNode;
+export declare function createFrame(opts: {
+    background?: Node;
+    children: Node[];
+    clip?: boolean;
+    cornerRadius?: CornerRadius;
+    layout?: Layout;
+} & Omit<Transform, "layoutChild">): GroupNode;
+export declare const autoLayout: (g: GroupNode, cfg: Omit<FlexLayout, "type">) => GroupNode;
+export declare const gridLayout: (g: GroupNode, cfg: Omit<GridLayout, "type">) => GroupNode;

package/src/node.js

@@ -0,0 +1,47 @@
+// ─────────────── constructors ───────────────
+export const createRect = (p) => ({
+    kind: "rect",
+    ...p,
+});
+export const createEllipse = (p) => ({
+    kind: "ellipse",
+    ...p,
+});
+// Circle = square-box ellipse; the caller supplies an equal width/height.
+export const createCircle = (p) => ({
+    kind: "ellipse",
+    ...p,
+});
+export const createPath = (p) => ({
+    kind: "path",
+    ...p,
+});
+export const createImage = (p) => ({
+    kind: "image",
+    ...p,
+});
+export const createBitmap = (p) => ({
+    kind: "bitmap",
+    ...p,
+});
+export const createText = (p) => ({
+    kind: "text",
+    ...p,
+});
+export const createGroup = (children, opts) => ({ kind: "group", children, ...opts });
+export const createMask = (mask, children, opts) => ({ kind: "mask", mask, children, ...opts });
+// Frame is a helper, not a kind: group + background child + self-clip.
+export function createFrame(opts) {
+    const { background, children, clip, cornerRadius, layout, ...rest } = opts;
+    return {
+        kind: "group",
+        children: background ? [background, ...children] : children,
+        clip,
+        cornerRadius,
+        layout,
+        ...rest,
+    };
+}
+// ─────────────── layout annotators ───────────────
+export const autoLayout = (g, cfg) => ({ ...g, layout: { type: "flex", ...cfg } });
+export const gridLayout = (g, cfg) => ({ ...g, layout: { type: "grid", ...cfg } });

package/src/paint-cache.d.ts

@@ -0,0 +1,49 @@
+import type { CanvasLike } from "./types.js";
+export type PaintCacheStats = {
+    paints: number;
+    surfaceCreates: number;
+    fontProviderBuilds: number;
+    imageDecodes: number;
+};
+export type PaintCache = {
+    clear(): void;
+    dispose(): void;
+    stats(): PaintCacheStats;
+};
+type CK = any;
+type FontKey = {
+    family: string;
+    bytes: Uint8Array;
+}[];
+type CachedSurface = {
+    surface: CK;
+    canvas: CanvasLike;
+    loseContext: () => void;
+    width: number;
+    height: number;
+    hosted: boolean;
+};
+export type PaintCacheState = {
+    stats: PaintCacheStats;
+    fonts: {
+        key: FontKey;
+        provider: CK;
+    } | null;
+    images: Map<string, CK>;
+    surface: CachedSurface | null;
+    disposed: boolean;
+};
+export declare function createPaintCache(): PaintCache;
+export declare function paintCacheState(cache: PaintCache): PaintCacheState;
+export declare function cachedFontProvider(state: PaintCacheState, loaded: FontKey, build: () => CK): CK;
+export declare function cachedSurface(state: PaintCacheState, want: {
+    width: number;
+    height: number;
+    hosted: boolean;
+}, make: () => {
+    surface: CK;
+    canvas: CanvasLike;
+    loseContext: () => void;
+}): CachedSurface;
+export declare function evictUnusedImages(state: PaintCacheState, used: string[]): void;
+export {};

package/src/paint-cache.js

@@ -0,0 +1,109 @@
+// An opt-in cache a runtime carries across paints of the same scene, for an
+// interactive caller that repaints many times a second. It keeps the three things
+// paintScene would otherwise rebuild on every paint: the font provider, the
+// decoded images and the output surface. A runtime without one paints exactly as
+// it always has, building and freeing all three per paint.
+// The state lives here rather than on the cache object so the public type stays
+// three methods and nothing outside render-kit can reach into it.
+const states = new WeakMap();
+export function createPaintCache() {
+    const state = {
+        stats: {
+            paints: 0,
+            surfaceCreates: 0,
+            fontProviderBuilds: 0,
+            imageDecodes: 0,
+        },
+        fonts: null,
+        images: new Map(),
+        surface: null,
+        disposed: false,
+    };
+    const clear = () => {
+        const fonts = state.fonts;
+        state.fonts = null;
+        if (fonts)
+            tryFree(() => fonts.provider.delete());
+        for (const img of state.images.values())
+            tryFree(() => img.delete());
+        state.images.clear();
+        const surface = state.surface;
+        state.surface = null;
+        if (surface)
+            releaseSurface(surface);
+    };
+    const cache = {
+        clear,
+        dispose() {
+            clear();
+            state.disposed = true;
+        },
+        stats: () => ({ ...state.stats }),
+    };
+    states.set(cache, state);
+    return cache;
+}
+// paintScene's handle on a cache. Throws for a disposed one, so a paint through
+// it fails before it allocates anything the cache would then leak.
+export function paintCacheState(cache) {
+    const state = states.get(cache);
+    if (!state)
+        throw new Error("render-kit: not a cache from createPaintCache()");
+    if (state.disposed)
+        throw new Error("render-kit: paint cache is disposed");
+    return state;
+}
+// The provider is keyed on the loaded list itself, family and byte-array
+// identity in order, so a caller that keeps its fonts map stable keeps its
+// provider.
+export function cachedFontProvider(state, loaded, build) {
+    const hit = state.fonts;
+    if (hit &&
+        hit.key.length === loaded.length &&
+        hit.key.every((f, i) => f.family === loaded[i]?.family && f.bytes === loaded[i]?.bytes))
+        return hit.provider;
+    state.fonts = null;
+    if (hit)
+        tryFree(() => hit.provider.delete());
+    const provider = build();
+    state.stats.fontProviderBuilds++;
+    state.fonts = { key: [...loaded], provider };
+    return provider;
+}
+// Reused only when it was made the same way (for a host canvas, or offscreen)
+// at the same device size; anything else replaces it.
+export function cachedSurface(state, want, make) {
+    const hit = state.surface;
+    if (hit &&
+        hit.width === want.width &&
+        hit.height === want.height &&
+        hit.hosted === want.hosted)
+        return hit;
+    state.surface = null;
+    if (hit)
+        releaseSurface(hit);
+    const made = make();
+    state.stats.surfaceCreates++;
+    state.surface = { ...made, ...want };
+    return state.surface;
+}
+// Deletes the cached images this paint's scene did not use.
+export function evictUnusedImages(state, used) {
+    const keep = new Set(used);
+    for (const [src, img] of state.images) {
+        if (keep.has(src))
+            continue;
+        state.images.delete(src);
+        tryFree(() => img.delete());
+    }
+}
+function releaseSurface(s) {
+    tryFree(() => s.surface.dispose());
+    tryFree(s.loseContext);
+}
+function tryFree(free) {
+    try {
+        free();
+    }
+    catch { }
+}

package/src/paint-helpers.d.ts

@@ -0,0 +1,21 @@
+import type { CornerRadius, FontVariations, Stroke } from "./types.js";
+export declare function fontVariationList(weight: number | undefined, variations: FontVariations | undefined): {
+    axis: string;
+    value: number;
+}[];
+export declare function fitRect(iw: number, ih: number, dx: number, dy: number, dw: number, dh: number, fit: "cover" | "contain" | "fill"): {
+    sx: number;
+    sy: number;
+    sw: number;
+    sh: number;
+    dx: number;
+    dy: number;
+    dw: number;
+    dh: number;
+};
+export declare function strokeInset(stroke: Stroke): number;
+export declare function insetCorner(cr: CornerRadius | undefined, inset: number): CornerRadius;
+export declare function decorationLine(size: number, decoration: string, baseline: number): {
+    top: number;
+    thickness: number;
+};

package/src/paint-helpers.js

@@ -0,0 +1,71 @@
+// The variation axes a text style instantiates its face at. The weight goes
+// first as `wght`: `fontStyle.weight` only PICKS among registered faces, and a
+// variable font registers as its default instance, so without the axis a 700
+// span would get that instance under synthetic bold. A static face has no axes
+// and ignores all of them. Shared by the Paragraph engine and the painter, which
+// must shape identically.
+export function fontVariationList(weight, variations) {
+    const axes = { wght: weight || 400, ...variations };
+    return Object.entries(axes).map(([axis, value]) => ({ axis, value }));
+}
+// Source/dest rects for object-fit.
+export function fitRect(iw, ih, dx, dy, dw, dh, fit) {
+    if (fit === "fill")
+        return { sx: 0, sy: 0, sw: iw, sh: ih, dx, dy, dw, dh };
+    const ir = iw / ih;
+    const dr = dw / dh;
+    if (fit === "cover") {
+        if (ir > dr) {
+            const sw = ih * dr;
+            return { sx: (iw - sw) / 2, sy: 0, sw, sh: ih, dx, dy, dw, dh };
+        }
+        const sh = iw / dr;
+        return { sx: 0, sy: (ih - sh) / 2, sw: iw, sh, dx, dy, dw, dh };
+    }
+    // contain
+    if (ir > dr) {
+        const h = dw / ir;
+        return {
+            sx: 0,
+            sy: 0,
+            sw: iw,
+            sh: ih,
+            dx,
+            dy: dy + (dh - h) / 2,
+            dw,
+            dh: h,
+        };
+    }
+    const w = dh * ir;
+    return { sx: 0, sy: 0, sw: iw, sh: ih, dx: dx + (dw - w) / 2, dy, dw: w, dh };
+}
+// Stroke-edge offset for alignment: +w/2 pulls it inside, -w/2 outside, 0 center.
+export function strokeInset(stroke) {
+    if (stroke.align === "inside")
+        return stroke.width / 2;
+    if (stroke.align === "outside")
+        return -stroke.width / 2;
+    return 0;
+}
+// Shrink (or grow) corner radii to match an inset/outset stroke rect.
+export function insetCorner(cr, inset) {
+    if (cr === undefined)
+        return 0;
+    if (typeof cr === "number")
+        return Math.max(0, cr - inset);
+    return [
+        Math.max(0, cr[0] - inset),
+        Math.max(0, cr[1] - inset),
+        Math.max(0, cr[2] - inset),
+        Math.max(0, cr[3] - inset),
+    ];
+}
+// Underline/strike geometry from the alphabetic baseline + font size. Kept in
+// lockstep between both painters so they draw the same line.
+export function decorationLine(size, decoration, baseline) {
+    const thickness = Math.max(1, size * 0.06);
+    const center = decoration === "line-through"
+        ? baseline - size * 0.28
+        : baseline + size * 0.1;
+    return { top: center - thickness / 2, thickness };
+}

package/src/paragraph-layout.d.ts

@@ -0,0 +1,6 @@
+import type { TextEngine } from "./text-engine.js";
+type CK = any;
+export declare function createParagraphEngine(ck: CK, fonts: Map<string, Uint8Array[]>): TextEngine & {
+    dispose(): void;
+};
+export {};