@desert-ant-labs/shapes 0.1.0

package/LICENSE.md

@@ -0,0 +1,136 @@
+# Desert Ant Labs Source-Available License
+
+Version 1.0 · 2026-06-15
+
+Copyright © 2026 Studio Company B.V., trading as Desert Ant Labs (`desertant.ai`).
+
+This license governs Your use of the software, model weights, datasets, documentation, and associated assets in this repository (collectively, the **"Licensed Materials"**). It is a **source-available license intended for professional and business use**; it is not an OSI-approved open-source license. The rights granted here are subject to a per-Model usage cap and the other terms set out below.
+
+## Definitions
+
+- **"Desert Ant Labs"** (also "We", "Us", "Our") — Studio Company B.V., a private limited liability company (*besloten vennootschap*) incorporated under the laws of the Netherlands, with statutory seat in Amsterdam, registered with the Dutch Chamber of Commerce (KvK) under number **81228112**, trading as Desert Ant Labs.
+- **"Model"** — a set of trained weights published by Desert Ant Labs under a single HuggingFace repository (for example, `huggingface.co/desert-ant-labs/eye`). Each Model is a distinct work under this license.
+- **"Monthly Active User"** or **"MAU"** — a unique end user who interacts with a feature powered by a Model during a calendar month. Internal use by Your own employees and contractors does not count.
+- **"You"** — the individual or legal entity exercising rights under this license.
+
+## 0. Acceptance
+
+By downloading, accessing, using, copying, modifying, or distributing the Licensed Materials, You agree to be bound by this license. If You do not agree, You may not use the Licensed Materials.
+
+## 1. Grant
+
+Subject to Your continued compliance with this license, Desert Ant Labs grants You a worldwide, royalty-free, non-exclusive, non-transferable, non-sublicensable license to use, reproduce, modify, and distribute the Licensed Materials.
+
+## 2. Free-tier use
+
+You may use the Licensed Materials free of charge, including for commercial purposes, subject to the following per-Model threshold:
+
+> **For each Desert Ant Labs Model that Your products incorporate, the aggregate Monthly Active Users across all Your products must not exceed 100,000 in any calendar month.**
+
+The threshold applies independently to each Model. Two Models at 50,000 MAU each do not combine into 100,000 MAU; each is independently within its own free-tier limit.
+
+If a repository contains only software (no trained Model weights), no MAU threshold applies to that software on its own. The threshold attaches to the Models the software is used with.
+
+## 3. Research and academic use
+
+Use of the Licensed Materials for non-commercial scientific research and academic publications is exempt from the MAU threshold in Section 2, provided that any resulting publication credits "Desert Ant Labs" and links to the relevant Model repository.
+
+## 4. Commercial license
+
+If Your aggregate MAU for any Model exceeds 100,000 (or You expect it to within the next calendar month), You must obtain a commercial license from Desert Ant Labs before continuing to distribute or operate any product that incorporates that Model. A commercial license covers only the Models named in it; other Models remain under the free tier subject to their own thresholds.
+
+Contact: <licensing@desertant.ai>.
+
+## 5. Patent grant
+
+Each contributor to the Licensed Materials grants You a perpetual, worldwide, non-exclusive, royalty-free, irrevocable (except as stated in this Section) patent license to make, use, sell, offer to sell, and import the Licensed Materials, where such license applies only to those patent claims licensable by that contributor that are necessarily infringed by the Licensed Materials.
+
+**If You institute patent litigation against any entity** (including a cross-claim or counterclaim in a lawsuit) alleging that the Licensed Materials infringe a patent, **all patent licenses granted to You under this license terminate as of the date such litigation is filed.**
+
+## 6. Restrictions
+
+You may not:
+
+1. Sell, sublicense, or otherwise distribute the Licensed Materials themselves, or any substantially unmodified derivative of them, as a standalone product or hosted service.
+2. Use the Licensed Materials to train, distill, fine-tune, or otherwise derive a model that You release or distribute under any license more permissive than this license, including any OSI-approved open-source license. Internal research, personal fine-tuning, and use of derivative models that remain under this license are not restricted.
+3. Remove or alter the copyright, license, attribution, or third-party notices in the Licensed Materials.
+
+You may freely embed the Licensed Materials in Your own product, subject to Section 2 and the rest of this license.
+
+## 7. Attribution
+
+You must retain this LICENSE file and the copyright notice in all copies and substantial portions of the Licensed Materials. Where Your product surfaces acknowledgements, third-party notices, or "About" / "Credits" screens, please credit **"Desert Ant Labs (`desertant.ai`)"**.
+
+## 8. Modifications
+
+You may modify the Licensed Materials. If You distribute modified Licensed Materials, You must:
+
+(a) include a prominent notice stating that You have modified them, with the date of modification; and
+(b) ensure that Your distributed modifications are licensed under this license.
+
+This license governs the Licensed Materials and modifications to them. Applications and products that merely incorporate, link to, or call the Licensed Materials are Your own work; their structure, source, and license are not constrained by this license, subject only to Sections 2, 6, and 7.
+
+## 9. Reporting
+
+To enable Desert Ant Labs to administer the free tier, You agree:
+
+(a) to maintain reasonable records of Your aggregate MAU per Model; and
+(b) upon written request from Desert Ant Labs, to provide a reasonable summary of those records sufficient to confirm compliance with Section 2. Such requests will be made no more than once per calendar year per licensee, except in the case of a reasonable, specific suspicion of breach.
+
+You are encouraged — but not required — to notify Desert Ant Labs at <licensing@desertant.ai> when Your aggregate MAU for any Model first exceeds 80,000.
+
+## 10. Trademarks
+
+This license does not grant You any right to use the trade names, trademarks, service marks, or product names of Desert Ant Labs, except for the limited attribution use specified in Section 7. All goodwill arising from such attribution use inures to the benefit of Desert Ant Labs.
+
+## 11. Third-party components
+
+The Licensed Materials may include or derive from components licensed by third parties. Those components remain subject to their own licenses; nothing in this license overrides those terms. Notices for such components are provided in the model card or in a `THIRD_PARTY_NOTICES.md` file alongside the Licensed Materials.
+
+## 12. Termination
+
+This license terminates automatically and immediately upon any of the following:
+
+(a) Your aggregate MAU for any Model exceeds 100,000 and You do not obtain a commercial license within thirty (30) days;
+(b) Your breach of Section 6 (Restrictions); or
+(c) Your institution of patent litigation as described in Section 5.
+
+For any other curable breach, Desert Ant Labs will provide written notice; if the breach is not cured within thirty (30) days of receipt of that notice, this license terminates as of the date the notice was sent.
+
+Upon termination, You must cease using and distributing the Licensed Materials. Sections 7 (Attribution, with respect to copies already in the field), 10 (Trademarks), 11 (Third-Party Components), 13 (No Warranty), 14 (Limitation of Liability), and 15 (Governing Law) survive termination.
+
+## 13. No warranty
+
+THE LICENSED MATERIALS ARE 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 NON-INFRINGEMENT. Desert Ant Labs makes no representation that the Licensed Materials are error-free, secure, or suitable for any particular use.
+
+## 14. Limitation of liability
+
+IN NO EVENT SHALL DESERT ANT LABS BE LIABLE FOR ANY INDIRECT, INCIDENTAL, CONSEQUENTIAL, SPECIAL, OR EXEMPLARY DAMAGES (INCLUDING LOST PROFITS, LOSS OF DATA, OR BUSINESS INTERRUPTION) ARISING FROM OR IN CONNECTION WITH THE LICENSED MATERIALS, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
+
+DESERT ANT LABS' TOTAL CUMULATIVE LIABILITY UNDER OR IN CONNECTION WITH THIS LICENSE SHALL NOT EXCEED THE GREATER OF (A) ONE HUNDRED EUROS (€100) OR (B) THE TOTAL FEES PAID BY YOU TO DESERT ANT LABS UNDER A SEPARATE COMMERCIAL LICENSE IN THE TWELVE (12) MONTHS PRECEDING THE CLAIM.
+
+Nothing in this license limits or excludes liability to the extent such limitation or exclusion is not permitted by applicable mandatory law, including liability for willful misconduct (*opzet*) or gross negligence (*bewuste roekeloosheid*) and any mandatory provision of Dutch consumer-protection law.
+
+## 15. Governing law and jurisdiction
+
+This license is governed by the laws of the Netherlands, without regard to its conflict-of-laws provisions. The competent courts of Amsterdam, the Netherlands, have exclusive jurisdiction over any dispute arising under or in connection with this license, subject to mandatory provisions of applicable consumer-protection law.
+
+The United Nations Convention on Contracts for the International Sale of Goods (CISG, 1980) does not apply to this license.
+
+## 16. Miscellaneous
+
+(a) **Severability.** If any provision of this license is held unenforceable by a court of competent jurisdiction, the remaining provisions remain in full force and effect, and the unenforceable provision shall be interpreted to give effect to its intent to the greatest extent permitted by law.
+
+(b) **No waiver.** Failure or delay by Desert Ant Labs to enforce any right under this license is not a waiver of that right.
+
+(c) **Assignment.** You may not assign this license without Desert Ant Labs' prior written consent. Desert Ant Labs may freely assign this license to a successor in interest. This license binds and benefits each party's successors and permitted assigns.
+
+(d) **Entire agreement.** This license, together with any separate commercial license referenced in Section 4, is the entire agreement between You and Desert Ant Labs regarding the Licensed Materials and supersedes all prior agreements on the same subject matter.
+
+(e) **Language.** The authoritative version of this license is in English. Any translation is for convenience only; in the event of any conflict, the English version controls.
+
+---
+
+Commercial licensing inquiries: <licensing@desertant.ai>.
+
+© 2026 Studio Company B.V., trading as Desert Ant Labs. Statutory seat: Amsterdam, the Netherlands. KvK: **81228112**.

package/README.md

@@ -0,0 +1,115 @@
+# @desert-ant-labs/shapes
+
+On-device single-stroke shape recognition. Takes a hand-drawn stroke (a list of
+`[x, y]` points) and returns a clean geometric shape — fully in-process, no
+inference runtime.
+
+```ts
+import { recognize } from "@desert-ant-labs/shapes";
+
+const shape = await recognize(points); // points: [number, number][]
+// { type: "ellipse", center: [120, 90], semiMajor: 64, semiMinor: 40, rotation: 0.2 }
+// or null if the stroke isn't a recognizable shape
+```
+
+## Features
+
+- Pure-JS inference (no ONNX/WASM runtime) — recognition is a few ms
+- Recognizes `line`, `rectangle`, `triangle`, `ellipse`, and `star` (rejects scribbles)
+- Fits clean vector geometry and snaps it to axes, circles, squares, and 15° rotations
+- Model (~0.2 MB, 4-bit palettized) is fetched from the Hugging Face Hub at a **pinned revision**, then
+  cached — to the **filesystem** on Node and to **Cache Storage** in the browser, so
+  it loads once and runs offline after
+
+## Install
+
+```bash
+npm install @desert-ant-labs/shapes
+```
+
+## Importing
+
+Pure ESM and fully tree-shakeable. The **same import works everywhere** — Node, bundlers,
+browsers, and edge/worker runtimes — the right build is selected automatically:
+
+```ts
+import { recognize } from "@desert-ant-labs/shapes";
+```
+
+CommonJS consumers use dynamic import (`const { recognize } = await import("@desert-ant-labs/shapes")`);
+native `require()` works on Node ≥ 22.12.
+
+**Bring-your-own-bytes.** If you load the model files yourself, import the hub-free core
+from `@desert-ant-labs/shapes/core` — only the inference engine, with zero network/filesystem code:
+
+```ts
+import { createShapes } from "@desert-ant-labs/shapes/core";
+
+// weights is a Uint8Array (shapes.safetensors); meta is the parsed shapes_meta.json
+const shapes = createShapes({ weights, meta });
+shapes.recognize(points)?.type; // "triangle"
+```
+
+## Loading model
+
+Model files (`shapes.safetensors`, `shapes_meta.json`) are fetched from the Hugging Face Hub
+([`desert-ant-labs/shapes`](https://huggingface.co/desert-ant-labs/shapes)) at a pinned
+revision and cached.
+
+- **Node**: `recognize()` works zero-config; files cache under `~/.cache/shapes`. To run
+  fully offline, ship the files yourself and point at a folder with `env.localModelPath`
+  (or `SHAPES_LOCAL_PATH`).
+- **Browser**: same API; files cache in Cache Storage.
+
+```ts
+import { env, load, recognize } from "@desert-ant-labs/shapes";
+
+env.revision = "main";                 // or a commit SHA / tag
+env.localModelPath = "./shapes-model"; // Node: use local files, skip the Hub
+
+// or load an explicit instance (synchronous inference after it resolves)
+const shapes = await load();
+shapes.recognize(points)?.type;
+```
+
+## API
+
+```ts
+export function recognize(points: Point[]): Promise<Shape | null>;
+export function load(options?: Partial<ShapesEnv>): Promise<ShapesModel>;
+export function createShapes(buffers: { weights; meta }): ShapesModel; // raw buffers
+export function outline(shape: Shape, samples?: number): Point[];       // renderable polyline
+export const env: ShapesEnv;
+export function reset(): void; // clear the memoized model so the next recognize() re-reads env
+
+export type Point = [number, number];
+
+export type Shape =
+  | { type: "line"; from: Point; to: Point }
+  | { type: "rectangle"; corners: Point[] }
+  | { type: "triangle"; vertices: Point[] }
+  | { type: "ellipse"; center: Point; semiMajor: number; semiMinor: number; rotation: number }
+  | { type: "star"; center: Point; outerRadius: number; innerRadius: number; rotation: number; pointCount: number };
+```
+
+`recognize(points)` returns the snapped shape, or `null` when the stroke is rejected
+(not a shape) or degenerate. `ShapesModel.recognize` is synchronous once loaded.
+
+## Example
+
+[`Examples/ShapesExample`](Examples/ShapesExample) is a tldraw canvas demo: draw a shape,
+pause for the preview, then lift to snap on-device.
+
+```bash
+cd Examples/ShapesExample
+npm install
+npm run dev
+```
+
+## Model
+
+Published at [`desert-ant-labs/shapes`](https://huggingface.co/desert-ant-labs/shapes) on Hugging Face.
+
+## License
+
+See [`LICENSE.md`](LICENSE.md) — Desert Ant Labs Source-Available License v1.0. Free for commercial use up to 100,000 MAU per Model; <licensing@desertant.ai> above that.

package/dist/cache-node.d.ts

@@ -0,0 +1,5 @@
+import type { FileCache } from "./hub.js";
+/** Filesystem-backed cache (Node): downloaded files persist across runs. */
+export declare function fsCache(cacheDir: string): FileCache;
+/** Reads model files from a local directory (for `localModelPath`). */
+export declare function localReader(dir: string): (name: string) => Promise<Uint8Array | null>;

package/dist/cache-node.js

@@ -0,0 +1,32 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+const keyToPath = (cacheDir, key) => join(cacheDir, key.replace(/^https?:\/\//, "").replace(/[^a-zA-Z0-9._/-]/g, "_"));
+/** Filesystem-backed cache (Node): downloaded files persist across runs. */
+export function fsCache(cacheDir) {
+    return {
+        async get(key) {
+            try {
+                return new Uint8Array(await readFile(keyToPath(cacheDir, key)));
+            }
+            catch {
+                return null;
+            }
+        },
+        async put(key, data) {
+            const path = keyToPath(cacheDir, key);
+            await mkdir(dirname(path), { recursive: true });
+            await writeFile(path, data);
+        },
+    };
+}
+/** Reads model files from a local directory (for `localModelPath`). */
+export function localReader(dir) {
+    return async (name) => {
+        try {
+            return new Uint8Array(await readFile(join(dir, name)));
+        }
+        catch {
+            return null;
+        }
+    };
+}

package/dist/cache-web.d.ts

@@ -0,0 +1,3 @@
+import type { FileCache } from "./hub.js";
+/** Cache Storage-backed cache (browser): downloaded files persist across visits. */
+export declare function webCache(name?: string): FileCache;

package/dist/cache-web.js

@@ -0,0 +1,24 @@
+/** Cache Storage-backed cache (browser): downloaded files persist across visits. */
+export function webCache(name = "shapes-model") {
+    return {
+        async get(key) {
+            try {
+                const cache = await caches.open(name);
+                const res = await cache.match(key);
+                return res ? new Uint8Array(await res.arrayBuffer()) : null;
+            }
+            catch {
+                return null;
+            }
+        },
+        async put(key, data) {
+            try {
+                const cache = await caches.open(name);
+                await cache.put(key, new Response(data));
+            }
+            catch {
+                /* caching is best-effort */
+            }
+        },
+    };
+}

package/dist/fit.d.ts

@@ -0,0 +1,6 @@
+import type { Point, Shape, ShapeKind } from "./shape.js";
+/** Fit `kind` to the raw stroke and snap it. Returns the clean shape + residual. */
+export declare function fit(kind: ShapeKind, points: Point[]): {
+    shape: Shape;
+    residual: number;
+};