@desert-ant-labs/shapes 0.1.0

package/dist/fit.js

@@ -0,0 +1,393 @@
+const sub = (a, b) => [a[0] - b[0], a[1] - b[1]];
+const add = (a, b) => [a[0] + b[0], a[1] + b[1]];
+const mul = (a, s) => [a[0] * s, a[1] * s];
+const dot = (a, b) => a[0] * b[0] + a[1] * b[1];
+const len = (a) => Math.hypot(a[0], a[1]);
+const rot = (v, ang) => {
+    const c = Math.cos(ang), s = Math.sin(ang);
+    return [c * v[0] - s * v[1], s * v[0] + c * v[1]];
+};
+function centroid(p) {
+    let x = 0, y = 0;
+    for (const q of p) {
+        x += q[0];
+        y += q[1];
+    }
+    return [x / p.length, y / p.length];
+}
+/** Larger/smaller eigenvalue + eigenvectors of the symmetric [[a,b],[b,c]]. */
+function symEig(a, b, c) {
+    const tr = a + c;
+    const disc = Math.hypot((a - c) / 2, b);
+    const l1 = tr / 2 + disc;
+    const vec = (l) => {
+        const v = Math.abs(b) > 1e-15 ? [l - c, b] : a >= c ? [1, 0] : [0, 1];
+        const n = len(v);
+        return n > 0 ? [v[0] / n, v[1] / n] : [1, 0];
+    };
+    const v1 = vec(l1);
+    return { v1, v2: [-v1[1], v1[0]] };
+}
+function resampleUniform(p, count) {
+    if (p.length <= 2)
+        return p;
+    const cum = [0];
+    for (let i = 1; i < p.length; i++)
+        cum.push(cum[i - 1] + len(sub(p[i], p[i - 1])));
+    const total = cum[cum.length - 1];
+    if (total <= 0)
+        return p;
+    const out = [];
+    let j = 0;
+    for (let i = 0; i < count; i++) {
+        const target = (total * i) / (count - 1);
+        while (j < p.length - 2 && cum[j + 1] < target)
+            j++;
+        const seg = cum[j + 1] - cum[j];
+        const t = seg > 0 ? (target - cum[j]) / seg : 0;
+        out.push(add(p[j], mul(sub(p[j + 1], p[j]), t)));
+    }
+    return out;
+}
+function bboxDiag(p) {
+    let lo = [p[0][0], p[0][1]];
+    let hi = [p[0][0], p[0][1]];
+    for (const q of p) {
+        lo = [Math.min(lo[0], q[0]), Math.min(lo[1], q[1])];
+        hi = [Math.max(hi[0], q[0]), Math.max(hi[1], q[1])];
+    }
+    const d = len(sub(hi, lo));
+    return d > 0 ? d : 1;
+}
+function ptSegDist(q, a, b) {
+    const ab = sub(b, a);
+    const l2 = dot(ab, ab);
+    if (l2 === 0)
+        return len(sub(q, a));
+    const t = Math.max(0, Math.min(1, dot(sub(q, a), ab) / l2));
+    return len(sub(q, add(a, mul(ab, t))));
+}
+function residual(stroke, poly, closed) {
+    const ring = closed ? [...poly, poly[0]] : poly;
+    let sumSq = 0;
+    for (const q of stroke) {
+        let best = Infinity;
+        for (let i = 0; i < ring.length - 1; i++)
+            best = Math.min(best, ptSegDist(q, ring[i], ring[i + 1]));
+        sumSq += best * best;
+    }
+    return Math.sqrt(sumSq / stroke.length) / bboxDiag(stroke);
+}
+function convexHull(points) {
+    const seen = new Set();
+    const pts = [];
+    for (const p of points) {
+        const key = `${Math.round(p[0] * 1e6)},${Math.round(p[1] * 1e6)}`;
+        if (!seen.has(key)) {
+            seen.add(key);
+            pts.push([p[0], p[1]]);
+        }
+    }
+    if (pts.length <= 2)
+        return pts;
+    pts.sort((a, b) => (a[0] === b[0] ? a[1] - b[1] : a[0] - b[0]));
+    const cross = (o, a, b) => (a[0] - o[0]) * (b[1] - o[1]) - (a[1] - o[1]) * (b[0] - o[0]);
+    const lower = [];
+    for (const p of pts) {
+        while (lower.length >= 2 && cross(lower[lower.length - 2], lower[lower.length - 1], p) <= 0)
+            lower.pop();
+        lower.push(p);
+    }
+    const upper = [];
+    for (let i = pts.length - 1; i >= 0; i--) {
+        const p = pts[i];
+        while (upper.length >= 2 && cross(upper[upper.length - 2], upper[upper.length - 1], p) <= 0)
+            upper.pop();
+        upper.push(p);
+    }
+    return lower.slice(0, -1).concat(upper.slice(0, -1));
+}
+// ---------------------------------------------------------------------------
+// Per-kind fitters
+// ---------------------------------------------------------------------------
+function fitLine(pts) {
+    const c = centroid(pts);
+    let sxx = 0, sxy = 0, syy = 0;
+    for (const p of pts) {
+        const d = sub(p, c);
+        sxx += d[0] * d[0];
+        sxy += d[0] * d[1];
+        syy += d[1] * d[1];
+    }
+    const dir = symEig(sxx, sxy, syy).v1;
+    let lo = Infinity, hi = -Infinity;
+    for (const p of pts) {
+        const t = dot(sub(p, c), dir);
+        lo = Math.min(lo, t);
+        hi = Math.max(hi, t);
+    }
+    const a = add(c, mul(dir, lo));
+    const b = add(c, mul(dir, hi));
+    return { shape: { type: "line", from: a, to: b }, residual: residual(pts, [a, b], false) };
+}
+function fitRectangle(pts) {
+    const hull = convexHull(pts);
+    if (hull.length < 3)
+        return fitLine(pts);
+    let best = null;
+    for (let i = 0; i < hull.length; i++) {
+        const edge = sub(hull[(i + 1) % hull.length], hull[i]);
+        const ang = Math.atan2(edge[1], edge[0]);
+        let loX = Infinity, loY = Infinity, hiX = -Infinity, hiY = -Infinity;
+        for (const h of hull) {
+            const r = rot(h, -ang);
+            loX = Math.min(loX, r[0]);
+            loY = Math.min(loY, r[1]);
+            hiX = Math.max(hiX, r[0]);
+            hiY = Math.max(hiY, r[1]);
+        }
+        const area = (hiX - loX) * (hiY - loY);
+        if (!best || area < best.area) {
+            const cr = [[loX, loY], [hiX, loY], [hiX, hiY], [loX, hiY]];
+            best = { area, corners: cr.map((p) => rot(p, ang)) };
+        }
+    }
+    const corners = best.corners;
+    return { shape: { type: "rectangle", corners }, residual: residual(pts, corners, true) };
+}
+function fitTriangle(pts) {
+    let hull = convexHull(pts);
+    if (hull.length < 3)
+        return fitLine(pts);
+    if (hull.length > 36) {
+        const idx = Array.from({ length: 36 }, (_, i) => Math.round((i * (hull.length - 1)) / 35));
+        const seen = new Set();
+        hull = idx.filter((k) => (seen.has(k) ? false : (seen.add(k), true))).map((k) => hull[k]);
+    }
+    let bestArea = -1;
+    let tri = [hull[0], hull[1], hull[2]];
+    for (let i = 0; i < hull.length; i++)
+        for (let j = i + 1; j < hull.length; j++)
+            for (let k = j + 1; k < hull.length; k++) {
+                const ab = sub(hull[j], hull[i]);
+                const ac = sub(hull[k], hull[i]);
+                const area = Math.abs(ab[0] * ac[1] - ab[1] * ac[0]) * 0.5;
+                if (area > bestArea) {
+                    bestArea = area;
+                    tri = [hull[i], hull[j], hull[k]];
+                }
+            }
+    return { shape: { type: "triangle", vertices: tri }, residual: residual(pts, tri, true) };
+}
+function ellipseOutline(c, major, minor, rotation) {
+    const cc = Math.cos(rotation), ss = Math.sin(rotation);
+    const out = [];
+    for (let i = 0; i < 160; i++) {
+        const t = (2 * Math.PI * i) / 160;
+        const x = major * Math.cos(t), y = minor * Math.sin(t);
+        out.push([c[0] + x * cc - y * ss, c[1] + x * ss + y * cc]);
+    }
+    return out;
+}
+function fitEllipse(pts) {
+    const c = centroid(pts);
+    let sxx = 0, sxy = 0, syy = 0;
+    for (const p of pts) {
+        const d = sub(p, c);
+        sxx += d[0] * d[0];
+        sxy += d[0] * d[1];
+        syy += d[1] * d[1];
+    }
+    const u = symEig(sxx, sxy, syy).v1;
+    const v = [-u[1], u[0]];
+    let uLo = Infinity, uHi = -Infinity, vLo = Infinity, vHi = -Infinity;
+    for (const p of pts) {
+        const tu = dot(sub(p, c), u), tv = dot(sub(p, c), v);
+        uLo = Math.min(uLo, tu);
+        uHi = Math.max(uHi, tu);
+        vLo = Math.min(vLo, tv);
+        vHi = Math.max(vHi, tv);
+    }
+    const center = add(add(c, mul(u, (uLo + uHi) / 2)), mul(v, (vLo + vHi) / 2));
+    const major = (uHi - uLo) / 2, minor = (vHi - vLo) / 2;
+    const rotation = Math.atan2(u[1], u[0]);
+    if (!(major > 0 && minor > 0 && isFinite(major) && isFinite(minor))) {
+        const r = pts.reduce((acc, p) => acc + len(sub(p, c)), 0) / pts.length;
+        return {
+            shape: { type: "ellipse", center: c, semiMajor: r, semiMinor: r, rotation: 0 },
+            residual: residual(pts, ellipseOutline(c, r, r, 0), true),
+        };
+    }
+    return {
+        shape: { type: "ellipse", center, semiMajor: major, semiMinor: minor, rotation },
+        residual: residual(pts, ellipseOutline(center, major, minor, rotation), true),
+    };
+}
+function starVertices(center, outer, inner, rotation) {
+    const out = [];
+    for (let i = 0; i < 10; i++) {
+        const a = rotation - Math.PI / 2 + (i * Math.PI) / 5;
+        const r = i % 2 === 0 ? outer : inner;
+        out.push([center[0] + r * Math.cos(a), center[1] + r * Math.sin(a)]);
+    }
+    return out;
+}
+function fitStar(pts) {
+    const center = centroid(pts);
+    const radii = pts.map((p) => len(sub(p, center)));
+    let sc = 0, ss = 0;
+    for (let i = 0; i < pts.length; i++) {
+        const a = Math.atan2(pts[i][1] - center[1], pts[i][0] - center[0]);
+        const w = radii[i] * radii[i];
+        sc += w * Math.cos(5 * a);
+        ss += w * Math.sin(5 * a);
+    }
+    const rot0 = Math.atan2(ss, sc) / 5 + Math.PI / 2;
+    const sorted = [...radii].sort((a, b) => a - b);
+    const top = Math.max(1, Math.floor(sorted.length / 5));
+    const outer = sorted.slice(sorted.length - top).reduce((a, b) => a + b, 0) / top;
+    const inner = outer * 0.4;
+    let best = { res: Infinity, angle: rot0 };
+    for (const angle of [rot0, rot0 + Math.PI / 5]) {
+        const res = residual(pts, starVertices(center, outer, inner, angle), true);
+        if (res < best.res)
+            best = { res, angle };
+    }
+    return {
+        shape: { type: "star", center, outerRadius: outer, innerRadius: inner, rotation: best.angle, pointCount: 5 },
+        residual: best.res,
+    };
+}
+// ---------------------------------------------------------------------------
+// Snapping (regularize to clean axes / angles / circles / squares)
+// ---------------------------------------------------------------------------
+const LINE_AXIS_DEG = 5;
+const ELLIPSE_CIRCLE_RATIO = 0.25;
+const ELLIPSE_ROT_DEG = 15;
+const RECT_SQUARE_RATIO = 0.25;
+const RECT_ROT_DEG = 15;
+const TRI_AXIS_DEG = 5;
+const TRI_EQUI_RATIO = 0.25;
+const TRI_ISO_RATIO = 0.25;
+const snapIncrement = (a, incDeg) => incDeg <= 0 ? a : Math.round(a / (incDeg * Math.PI / 180)) * (incDeg * Math.PI / 180);
+function snapAxis(a, thrDeg) {
+    if (thrDeg <= 0)
+        return null;
+    const q = Math.PI / 2;
+    const nearest = Math.round(a / q) * q;
+    return Math.abs(a - nearest) <= (thrDeg * Math.PI) / 180 ? nearest : null;
+}
+function snap(shape) {
+    switch (shape.type) {
+        case "line": {
+            const a = shape.from, b = shape.to;
+            const ang = Math.atan2(b[1] - a[1], b[0] - a[0]);
+            const snapped = snapAxis(ang, LINE_AXIS_DEG);
+            if (snapped == null)
+                return shape;
+            const mid = [(a[0] + b[0]) / 2, (a[1] + b[1]) / 2];
+            const half = len(sub(b, a)) / 2;
+            const d = [Math.cos(snapped), Math.sin(snapped)];
+            return { type: "line", from: sub(mid, mul(d, half)), to: add(mid, mul(d, half)) };
+        }
+        case "ellipse": {
+            const hi = Math.max(shape.semiMajor, shape.semiMinor);
+            const lo = Math.min(shape.semiMajor, shape.semiMinor);
+            if (ELLIPSE_CIRCLE_RATIO > 0 && hi > 0 && lo / hi >= 1 - ELLIPSE_CIRCLE_RATIO) {
+                const r = (shape.semiMajor + shape.semiMinor) / 2;
+                return { ...shape, semiMajor: r, semiMinor: r, rotation: 0 };
+            }
+            return { ...shape, rotation: snapIncrement(shape.rotation, ELLIPSE_ROT_DEG) };
+        }
+        case "rectangle": {
+            const p = shape.corners;
+            if (p.length !== 4)
+                return shape;
+            const center = [(p[0][0] + p[1][0] + p[2][0] + p[3][0]) / 4, (p[0][1] + p[1][1] + p[2][1] + p[3][1]) / 4];
+            let w = len(sub(p[1], p[0]));
+            let h = len(sub(p[3], p[0]));
+            let ang = Math.atan2(p[1][1] - p[0][1], p[1][0] - p[0][0]);
+            const hi = Math.max(w, h), lo = Math.min(w, h);
+            if (RECT_SQUARE_RATIO > 0 && hi > 0 && lo / hi >= 1 - RECT_SQUARE_RATIO) {
+                const s = (w + h) / 2;
+                w = s;
+                h = s;
+            }
+            ang = snapIncrement(ang, RECT_ROT_DEG);
+            const hw = w / 2, hh = h / 2;
+            const local = [[-hw, -hh], [hw, -hh], [hw, hh], [-hw, hh]];
+            return { type: "rectangle", corners: local.map((q) => add(center, rot(q, ang))) };
+        }
+        case "triangle":
+            return snapTriangle(shape.vertices);
+        case "star":
+            return shape;
+    }
+}
+const rel = (a, b) => {
+    const m = Math.max(a, b);
+    return m > 0 ? Math.abs(a - b) / m : 0;
+};
+function snapTriangle(verts) {
+    let v = verts.map((p) => [p[0], p[1]]);
+    const c = [(v[0][0] + v[1][0] + v[2][0]) / 3, (v[0][1] + v[1][1] + v[2][1]) / 3];
+    const lAB = len(sub(v[0], v[1])), lBC = len(sub(v[1], v[2])), lCA = len(sub(v[2], v[0]));
+    const sides = [lAB, lBC, lCA];
+    const mx = Math.max(...sides), mn = Math.min(...sides);
+    if (TRI_EQUI_RATIO > 0 && mx > 0 && (mx - mn) / mx <= TRI_EQUI_RATIO) {
+        const r = (len(sub(v[0], c)) + len(sub(v[1], c)) + len(sub(v[2], c))) / 3;
+        let sx = 0, sy = 0;
+        for (let i = 0; i < 3; i++) {
+            const a = Math.atan2(v[i][1] - c[1], v[i][0] - c[0]) - (i * 2 * Math.PI) / 3;
+            sx += Math.cos(a);
+            sy += Math.sin(a);
+        }
+        const base = Math.atan2(sy, sx);
+        v = [0, 1, 2].map((i) => [c[0] + r * Math.cos(base + (i * 2 * Math.PI) / 3), c[1] + r * Math.sin(base + (i * 2 * Math.PI) / 3)]);
+    }
+    else if (TRI_ISO_RATIO > 0) {
+        const cand = [[0, 1, 2, lAB, lCA], [1, 0, 2, lAB, lBC], [2, 0, 1, lCA, lBC]];
+        let bi = 0;
+        for (let i = 1; i < 3; i++)
+            if (rel(cand[i][3], cand[i][4]) < rel(cand[bi][3], cand[bi][4]))
+                bi = i;
+        const best = cand[bi];
+        if (rel(best[3], best[4]) <= TRI_ISO_RATIO) {
+            const apex = v[best[0]];
+            const avg = (best[3] + best[4]) / 2;
+            const leg = (to) => {
+                const d = sub(v[to], apex);
+                const n = len(d);
+                return add(apex, mul(n > 0 ? [d[0] / n, d[1] / n] : d, avg));
+            };
+            v[best[1]] = leg(best[1]);
+            v[best[2]] = leg(best[2]);
+        }
+    }
+    // axis-align the longest edge
+    const edges = [[v[0], v[1]], [v[1], v[2]], [v[2], v[0]]];
+    let longest = edges[0];
+    for (const e of edges)
+        if (len(sub(e[1], e[0])) > len(sub(longest[1], longest[0])))
+            longest = e;
+    const ang = Math.atan2(longest[1][1] - longest[0][1], longest[1][0] - longest[0][0]);
+    const snapped = snapAxis(ang, TRI_AXIS_DEG);
+    if (snapped == null)
+        return { type: "triangle", vertices: v };
+    const cen = [(v[0][0] + v[1][0] + v[2][0]) / 3, (v[0][1] + v[1][1] + v[2][1]) / 3];
+    const delta = snapped - ang;
+    return { type: "triangle", vertices: v.map((p) => add(cen, rot(sub(p, cen), delta))) };
+}
+const FITTERS = {
+    line: fitLine,
+    rectangle: fitRectangle,
+    triangle: fitTriangle,
+    ellipse: fitEllipse,
+    star: fitStar,
+};
+/** Fit `kind` to the raw stroke and snap it. Returns the clean shape + residual. */
+export function fit(kind, points) {
+    const pts = resampleUniform(points, 256);
+    const { shape, residual: res } = FITTERS[kind](pts);
+    return { shape: snap(shape), residual: res };
+}

package/dist/hub.d.ts

@@ -0,0 +1,31 @@
+import { ShapesModel } from "./model.js";
+export declare const DEFAULT_HOST = "https://huggingface.co";
+export declare const DEFAULT_REPO = "desert-ant-labs/shapes";
+/** Pinned revision of the model repo (a commit SHA). */
+export declare const DEFAULT_REVISION = "2a45f451571c17cfd86d52e063d98e724036881d";
+/** Resolution + caching configuration (mutate the exported `env` to change defaults). */
+export interface ShapesEnv {
+    /** Hugging Face host serving the model repo. */
+    host: string;
+    /** Model repo id, e.g. `"desert-ant-labs/shapes"`. */
+    repo: string;
+    /** Pinned revision (commit SHA, tag, or branch). */
+    revision: string;
+    /** Allow fetching from the Hugging Face Hub. Set `false` to require a local copy. */
+    allowRemote: boolean;
+    /** Cache downloaded files (filesystem on Node, Cache Storage in the browser). */
+    useCache: boolean;
+    /** Directory of pre-downloaded model files to use instead of the Hub (Node). */
+    localModelPath?: string;
+    /** Filesystem cache directory (Node). */
+    cacheDir?: string;
+    /** Optional Hugging Face access token (Node) — needed while the repo is private. */
+    token?: string;
+}
+/** A key/value store for cached file bytes, keyed by resolve URL. */
+export interface FileCache {
+    get(key: string): Promise<Uint8Array | null>;
+    put(key: string, data: Uint8Array): Promise<void>;
+}
+/** Resolves all model files (local dir → cache → Hub) and builds a {@link ShapesModel}. */
+export declare function loadModel(env: ShapesEnv, cache: FileCache | null, readLocal?: (name: string) => Promise<Uint8Array | null>): Promise<ShapesModel>;

package/dist/hub.js

@@ -0,0 +1,42 @@
+import { createShapes } from "./model.js";
+export const DEFAULT_HOST = "https://huggingface.co";
+export const DEFAULT_REPO = "desert-ant-labs/shapes";
+/** Pinned revision of the model repo (a commit SHA). */
+export const DEFAULT_REVISION = "2a45f451571c17cfd86d52e063d98e724036881d";
+const FILES = ["shapes.safetensors", "shapes_meta.json"];
+function resolveUrl(env, name) {
+    return `${env.host}/${env.repo}/resolve/${env.revision}/${name}`;
+}
+async function fetchFile(env, name, cache, readLocal) {
+    if (readLocal) {
+        const local = await readLocal(name);
+        if (local)
+            return local;
+    }
+    const url = resolveUrl(env, name);
+    if (cache && env.useCache) {
+        const hit = await cache.get(url);
+        if (hit)
+            return hit;
+    }
+    if (!env.allowRemote)
+        throw new Error(`shapes: ${name} unavailable locally and remote loading is disabled`);
+    const res = await fetch(url, env.token ? { headers: { Authorization: `Bearer ${env.token}` } } : undefined);
+    if (!res.ok)
+        throw new Error(`shapes: failed to fetch ${name} from ${url} (${res.status} ${res.statusText})`);
+    const data = new Uint8Array(await res.arrayBuffer());
+    if (cache && env.useCache) {
+        try {
+            await cache.put(url, data);
+        }
+        catch {
+            /* caching is best-effort */
+        }
+    }
+    return data;
+}
+/** Resolves all model files (local dir → cache → Hub) and builds a {@link ShapesModel}. */
+export async function loadModel(env, cache, readLocal) {
+    const [weights, meta] = await Promise.all(FILES.map((name) => fetchFile(env, name, cache, readLocal)));
+    return createShapes({ weights, meta: JSON.parse(new TextDecoder().decode(meta)) });
+}

package/dist/index.browser.d.ts

@@ -0,0 +1,18 @@
+import { type ShapesEnv } from "./hub.js";
+import { type ShapesModel } from "./model.js";
+import type { Point, Shape } from "./shape.js";
+export { createShapes, ShapesModel, type ShapesMeta } from "./model.js";
+export { outline, type Point, type Shape, type ShapeKind } from "./shape.js";
+export { type PreprocessConfig } from "./preprocess.js";
+export { loadModel, type ShapesEnv, type FileCache } from "./hub.js";
+/** Loading configuration. Mutate before the first call, or pass overrides to {@link load}. */
+export declare const env: ShapesEnv;
+/** Loads the model from the Hugging Face Hub (cached in Cache Storage). */
+export declare function load(options?: Partial<ShapesEnv>): Promise<ShapesModel>;
+/**
+ * Recognizes a single stroke (ordered `[x, y]` points) as a clean {@link Shape},
+ * or `null` if rejected. The model is loaded (and cached) lazily on first call.
+ */
+export declare function recognize(points: Point[]): Promise<Shape | null>;
+/** Clears the memoized model so the next {@link recognize} call re-reads `env`. */
+export declare function reset(): void;

package/dist/index.browser.js

@@ -0,0 +1,36 @@
+import { webCache } from "./cache-web.js";
+import { DEFAULT_HOST, DEFAULT_REPO, DEFAULT_REVISION, loadModel } from "./hub.js";
+export { createShapes, ShapesModel } from "./model.js";
+export { outline } from "./shape.js";
+export { loadModel } from "./hub.js";
+/** Loading configuration. Mutate before the first call, or pass overrides to {@link load}. */
+export const env = {
+    host: DEFAULT_HOST,
+    repo: DEFAULT_REPO,
+    revision: DEFAULT_REVISION,
+    allowRemote: true,
+    useCache: true,
+};
+/** Loads the model from the Hugging Face Hub (cached in Cache Storage). */
+export async function load(options = {}) {
+    const e = { ...env, ...options };
+    return loadModel(e, e.useCache ? webCache() : null);
+}
+let modelPromise = null;
+/**
+ * Recognizes a single stroke (ordered `[x, y]` points) as a clean {@link Shape},
+ * or `null` if rejected. The model is loaded (and cached) lazily on first call.
+ */
+export async function recognize(points) {
+    if (!modelPromise) {
+        modelPromise = load().catch((err) => {
+            modelPromise = null;
+            throw err;
+        });
+    }
+    return (await modelPromise).recognize(points);
+}
+/** Clears the memoized model so the next {@link recognize} call re-reads `env`. */
+export function reset() {
+    modelPromise = null;
+}

package/dist/index.node.d.ts

@@ -0,0 +1,18 @@
+import { type ShapesEnv } from "./hub.js";
+import { type ShapesModel } from "./model.js";
+import type { Point, Shape } from "./shape.js";
+export { createShapes, ShapesModel, type ShapesMeta } from "./model.js";
+export { outline, type Point, type Shape, type ShapeKind } from "./shape.js";
+export { type PreprocessConfig } from "./preprocess.js";
+export { loadModel, type ShapesEnv, type FileCache } from "./hub.js";
+/** Loading configuration. Mutate before the first call, or pass overrides to {@link load}. */
+export declare const env: ShapesEnv;
+/** Loads the model: a local dir if configured, else the Hugging Face Hub (cached to disk). */
+export declare function load(options?: Partial<ShapesEnv>): Promise<ShapesModel>;
+/**
+ * Recognizes a single stroke (ordered `[x, y]` points) as a clean {@link Shape},
+ * or `null` if rejected. The model is loaded (and cached) lazily on first call.
+ */
+export declare function recognize(points: Point[]): Promise<Shape | null>;
+/** Clears the memoized model so the next {@link recognize} call re-reads `env`. */
+export declare function reset(): void;

package/dist/index.node.js

@@ -0,0 +1,43 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { fsCache, localReader } from "./cache-node.js";
+import { DEFAULT_HOST, DEFAULT_REPO, DEFAULT_REVISION, loadModel } from "./hub.js";
+export { createShapes, ShapesModel } from "./model.js";
+export { outline } from "./shape.js";
+export { loadModel } from "./hub.js";
+/** Loading configuration. Mutate before the first call, or pass overrides to {@link load}. */
+export const env = {
+    host: DEFAULT_HOST,
+    repo: DEFAULT_REPO,
+    revision: DEFAULT_REVISION,
+    allowRemote: true,
+    useCache: true,
+    cacheDir: process.env.SHAPES_CACHE_DIR ?? join(homedir(), ".cache", "shapes"),
+    localModelPath: process.env.SHAPES_LOCAL_PATH,
+    token: process.env.HF_TOKEN ?? process.env.HUGGING_FACE_HUB_TOKEN,
+};
+/** Loads the model: a local dir if configured, else the Hugging Face Hub (cached to disk). */
+export async function load(options = {}) {
+    const e = { ...env, ...options };
+    const cache = e.useCache && e.cacheDir ? fsCache(e.cacheDir) : null;
+    const readLocal = e.localModelPath ? localReader(e.localModelPath) : undefined;
+    return loadModel(e, cache, readLocal);
+}
+let modelPromise = null;
+/**
+ * Recognizes a single stroke (ordered `[x, y]` points) as a clean {@link Shape},
+ * or `null` if rejected. The model is loaded (and cached) lazily on first call.
+ */
+export async function recognize(points) {
+    if (!modelPromise) {
+        modelPromise = load().catch((err) => {
+            modelPromise = null;
+            throw err;
+        });
+    }
+    return (await modelPromise).recognize(points);
+}
+/** Clears the memoized model so the next {@link recognize} call re-reads `env`. */
+export function reset() {
+    modelPromise = null;
+}

package/dist/model.d.ts

@@ -0,0 +1,48 @@
+import { type PreprocessConfig } from "./preprocess.js";
+import type { Point, Shape } from "./shape.js";
+export type { Point, Shape, ShapeKind } from "./shape.js";
+export { outline } from "./shape.js";
+/** Parsed `shapes_meta.json`: classes, gates, preprocessing constants, dims. */
+export interface ShapesMeta {
+    classes: string[];
+    gates: Record<string, {
+        conf: number;
+        resid: number;
+    }>;
+    preprocess: PreprocessConfig;
+    model: {
+        width: number;
+        heads: number;
+        layers: number;
+        in_channels: number;
+        pool_factor: number;
+    };
+}
+/** Loads the portable model and runs stroke recognition. Construct once and reuse. */
+export declare class ShapesModel {
+    readonly meta: ShapesMeta;
+    private readonly t;
+    private readonly D;
+    private readonly H;
+    private readonly dh;
+    private readonly scale;
+    private readonly layers;
+    constructor(weights: Uint8Array, meta: ShapesMeta);
+    private get;
+    /**
+     * Recognize a single stroke (ordered `[x, y]` points). Returns the snapped
+     * {@link Shape}, or `null` when the stroke is rejected or degenerate.
+     */
+    recognize(points: Point[]): Shape | null;
+    private classify;
+    private conv1d;
+    private relu;
+    private pool;
+    private linear;
+    private encoderLayer;
+}
+/** Creates a {@link ShapesModel} from raw buffers (lowest-level entry). */
+export declare function createShapes(buffers: {
+    weights: Uint8Array;
+    meta: ShapesMeta;
+}): ShapesModel;