cloudswg 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gideon Needleman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS 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 NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,98 @@
+# cloudswg
+
+Procedurally generate SVG clouds. A single seeded call returns a clean, standalone `<svg>` string built from minimal, smooth bezier geometry — deterministic per seed, dependency-free, and usable in both Node and the browser.
+
+Three cloud types are supported: **cumulus**, **stratus**, and **cirrus**.
+
+## Install
+
+```bash
+npm install cloudswg
+```
+
+## Usage
+
+```ts
+import { generateCloud } from 'cloudswg'
+
+const { svg } = generateCloud({ type: 'cumulus', seed: 42, puffiness: 0.7 })
+// → '<svg xmlns="..." viewBox="0 0 300 180" ...>...</svg>'
+```
+
+The same seed always produces the same SVG; omit `seed` for a random cloud:
+
+```ts
+generateCloud({ type: 'cumulus' })            // random every call
+generateCloud({ type: 'cumulus', seed: 42 })  // reproducible
+```
+
+In the browser you can get a live DOM node instead of a string:
+
+```ts
+const cloud = generateCloud({ type: 'stratus', seed: 7 })
+document.body.appendChild(cloud.element())    // returns an SVGSVGElement
+```
+
+> `element()` requires a browser environment (uses `DOMParser`) and throws in Node. Use `svg` to write files or render server-side.
+
+## Options
+
+```ts
+generateCloud({
+  type: 'cumulus',        // 'cumulus' | 'stratus' | 'cirrus'
+  seed: 42,               // number; omit for random
+  puffiness: 0.7,         // 0..1, effect is per-type (see below)
+  width: 300,             // optional; sensible per-type default
+  height: 180,            // optional; sensible per-type default
+  style: {
+    fill: 'white',        // any CSS color
+    stroke: 'none',       // outline color
+    strokeWidth: 1,
+    opacity: 1,
+  },
+})
+```
+
+| Option | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `type` | `CloudType` | `'cumulus'` | Cloud morphology. |
+| `seed` | `number` | random | Same seed ⇒ identical output. |
+| `puffiness` | `number` | random per seed | 0–1; per-type meaning (turret count, band thickness, curl, tower height). Omit for a value drawn from the seed (deterministic per seed). |
+| `width` / `height` | `number` | per-type | Viewbox size. Defaults: cumulus `300×180`, cirrus `400×200`, stratus `1200×120`. |
+| `style` | `CloudStyle` | `{}` | Fill, stroke, and opacity. No blur filter is baked in — soften at the consumer via CSS `filter: blur()`. |
+
+### Return value
+
+```ts
+interface CloudResult {
+  svg: string              // serialized <svg> string
+  element(): SVGSVGElement // browser-only; parses svg into a DOM node
+}
+```
+
+## Cloud types
+
+- **cumulus** — puffy fair-weather cloud with a flat base and cauliflower turrets that boom upward off-center, so each seed looks distinct. `puffiness` drives turret count.
+- **stratus** — a long, wavy horizontal band with gently lumpy edges and rounded ends. Uses a wide default viewBox (`1200×120`). `puffiness` drives thickness and edge lumpiness.
+- **cirrus** — a field of filled, hooked "mares'-tail" wisps (cirrus uncinus): tapered comma shapes that curl up at the head. `puffiness` drives hook strength and head fatness. Ships crisp; for a soft look apply CSS `filter: blur()` at the consumer.
+
+## Types
+
+`CloudOptions`, `CloudResult`, `CloudType`, and `CloudStyle` are all exported for TypeScript consumers.
+
+## Development
+
+```bash
+npm run build      # bundle to dist/ (ESM + CJS + .d.ts) and rebuild the demo bundle
+npm run dev        # rebuild on change
+npm test           # run the test suite (vitest)
+npm run typecheck  # tsc --noEmit
+```
+
+Open `examples/index.html` in a browser (after `npm run build`) for a no-server gallery of all cloud types with download buttons.
+
+See [CLAUDE.md](./CLAUDE.md) for architecture and internals.
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,550 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  generateCirrus: () => generateCirrus2,
+  generateCloud: () => generateCloud,
+  generateCumulus: () => generateCumulus2,
+  generateStratus: () => generateStratus2
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/rng.ts
+function createRng(seed) {
+  let s = seed >>> 0;
+  return function() {
+    s += 1831565813;
+    let t = s;
+    t = Math.imul(t ^ t >>> 15, t | 1);
+    t ^= t + Math.imul(t ^ t >>> 7, t | 61);
+    return ((t ^ t >>> 14) >>> 0) / 4294967296;
+  };
+}
+
+// src/svg.ts
+function buildPathAttrs(style) {
+  const attrs = [];
+  attrs.push(`fill="${style.fill ?? "white"}"`);
+  if (style.stroke && style.stroke !== "none") {
+    attrs.push(`stroke="${style.stroke}"`);
+    attrs.push(`stroke-width="${style.strokeWidth ?? 1}"`);
+  }
+  if (style.opacity !== void 0 && style.opacity !== 1) {
+    attrs.push(`opacity="${style.opacity}"`);
+  }
+  return attrs.join(" ");
+}
+function assembleSvg(width, height, paths, style) {
+  const attrs = buildPathAttrs(style);
+  const pathElements = paths.filter((d) => d.length > 0).map((d) => `<path d="${d}" ${attrs}/>`).join("\n  ");
+  return [
+    `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${width} ${height}" width="${width}" height="${height}">`,
+    `  ${pathElements}`,
+    `</svg>`
+  ].join("\n");
+}
+function makeResult(svgString) {
+  return {
+    svg: svgString,
+    element() {
+      if (typeof DOMParser === "undefined") {
+        throw new Error("element() requires a browser environment with DOMParser");
+      }
+      const doc = new DOMParser().parseFromString(svgString, "image/svg+xml");
+      return doc.documentElement;
+    }
+  };
+}
+
+// src/generators/cumulus.ts
+function fmt(n) {
+  return Number(n.toFixed(3)).toString();
+}
+function topY(c, x) {
+  const dx2 = (x - c.x) ** 2;
+  const r2 = c.r * c.r;
+  if (dx2 > r2 + 1e-9) return Infinity;
+  return c.y - Math.sqrt(Math.max(0, r2 - dx2));
+}
+function arcToBeziers(cx, cy, r, thetaStart, thetaEnd) {
+  const total = thetaEnd - thetaStart;
+  const pieces = Math.max(1, Math.ceil(Math.abs(total) / (Math.PI / 2)));
+  const step = total / pieces;
+  const k = 4 / 3 * Math.tan(step / 4);
+  let out = "";
+  for (let i = 0; i < pieces; i++) {
+    const a = thetaStart + step * i;
+    const b = a + step;
+    const cosA = Math.cos(a);
+    const sinA = Math.sin(a);
+    const cosB = Math.cos(b);
+    const sinB = Math.sin(b);
+    const ex = cx + r * cosB;
+    const ey = cy + r * sinB;
+    const c1x = cx + r * cosA - k * r * sinA;
+    const c1y = cy + r * sinA + k * r * cosA;
+    const c2x = ex + k * r * sinB;
+    const c2y = ey - k * r * cosB;
+    out += ` C ${fmt(c1x)},${fmt(c1y)} ${fmt(c2x)},${fmt(c2y)} ${fmt(ex)},${fmt(ey)}`;
+  }
+  return out;
+}
+function generateCumulus(width, height, puffiness, rng) {
+  const rBase = height * (0.135 + rng() * 0.035);
+  const rMax = rBase * 1.15;
+  const rMin = rBase * 0.8;
+  const rAvg = rBase;
+  const margin = rMax;
+  const xLeft = margin;
+  const xRight = width - margin;
+  const baseY = height * 0.95;
+  const topMargin = height * 0.02;
+  let rLeft = rAvg + rng() * (rMax - rAvg);
+  let rRight = rAvg + rng() * (rMax - rAvg);
+  if (rLeft / rRight > 1.5) rLeft = rRight * 1.5;
+  else if (rRight / rLeft > 1.5) rRight = rLeft * 1.5;
+  const leftCircle = { x: xLeft, y: baseY - rLeft, r: rLeft };
+  const rightCircle = { x: xRight, y: baseY - rRight, r: rRight };
+  const spanCenters = xRight - xLeft;
+  const fillCount = Math.max(3, Math.min(8, Math.round(spanCenters / (1.2 * rAvg)) - 1));
+  const fillCircles = [];
+  const spacing = spanCenters / (fillCount + 1);
+  for (let i = 0; i < fillCount; i++) {
+    const t = (i + 1) / (fillCount + 1);
+    const r = rBase * (0.9 + rng() * 0.2);
+    const rawX = xLeft + t * spanCenters + (rng() - 0.5) * spacing * 0.3;
+    const x = Math.max(xLeft, Math.min(xRight, rawX));
+    fillCircles.push({ x, y: baseY - r, r });
+  }
+  const allCircles = [leftCircle, ...fillCircles, rightCircle];
+  allCircles.sort((a, b) => a.x - b.x);
+  if (allCircles.length > 2) {
+    const leftNbr = allCircles[1];
+    const rEdgeL = allCircles[0].r;
+    leftNbr.r = Math.max(0.85 * rEdgeL, Math.min(rEdgeL, leftNbr.r));
+    leftNbr.y = baseY - leftNbr.r;
+    const rightNbr = allCircles[allCircles.length - 2];
+    const rEdgeR = allCircles[allCircles.length - 1].r;
+    rightNbr.r = Math.max(0.85 * rEdgeR, Math.min(rEdgeR, rightNbr.r));
+    rightNbr.y = baseY - rightNbr.r;
+  }
+  for (let i = 1; i < allCircles.length; i++) {
+    const prev = allCircles[i - 1];
+    const curr = allCircles[i];
+    const overlapTarget = 0.4 * Math.min(prev.r, curr.r);
+    const need = curr.x - prev.x + overlapTarget - (prev.r + curr.r);
+    if (need > 0) {
+      if (i === 1) {
+        curr.r += need;
+        curr.y = baseY - curr.r;
+      } else if (i === allCircles.length - 1) {
+        prev.r += need;
+        prev.y = baseY - prev.r;
+      } else {
+        prev.r += need / 2;
+        prev.y = baseY - prev.r;
+        curr.r += need / 2;
+        curr.y = baseY - curr.r;
+      }
+    }
+  }
+  for (let i = 1; i < allCircles.length - 1; i++) {
+    const c = allCircles[i];
+    if (c.y < c.r + topMargin) c.y = c.r + topMargin;
+  }
+  const outerLeft = leftCircle.x - leftCircle.r;
+  const outerRight = rightCircle.x + rightCircle.r;
+  const envAt = (px) => {
+    let m = Infinity;
+    for (const c of allCircles) {
+      const y = topY(c, px);
+      if (y < m) m = y;
+    }
+    return m;
+  };
+  const topLimit = topMargin + height * 0.1;
+  const numTurrets = Math.round(puffiness * (3 + rng() * 1.5));
+  for (let turret = 0; turret < numTurrets; turret++) {
+    let cx = outerLeft + rBase + rng() * (outerRight - outerLeft - 2 * rBase);
+    const turretR = rBase * (1.15 + rng() * 0.55);
+    const halfW0 = turretR * (0.8 + rng() * 0.8);
+    const drama = rng() ** 1.8;
+    const baseTop = envAt(cx);
+    if (!isFinite(baseTop)) continue;
+    const targetTop = baseTop - drama * (baseTop - topLimit);
+    if (targetTop >= baseTop) continue;
+    for (let step2 = 0; step2 < 16; step2++) {
+      const envY = envAt(cx);
+      if (!isFinite(envY) || envY <= targetTop) break;
+      const frac = (envY - targetTop) / (baseTop - targetTop);
+      const halfW = turretR * 0.5 + halfW0 * Math.max(0, frac);
+      const count = Math.max(1, Math.round(2 * halfW / (0.85 * turretR)));
+      for (let j = 0; j < count; j++) {
+        const t = count === 1 ? 0.5 : j / (count - 1);
+        const px = Math.max(
+          outerLeft,
+          Math.min(outerRight, cx - halfW + t * 2 * halfW + (rng() - 0.5) * turretR * 0.3)
+        );
+        const overlapFrac = 0.46 + rng() * 0.1;
+        const rRaw = turretR * (0.85 + rng() * 0.3);
+        const envYp = envAt(px);
+        if (!isFinite(envYp) || envYp <= topLimit) continue;
+        let r = Math.min(rRaw, (envYp - topLimit) / (1 - overlapFrac));
+        for (let k = 0; k < 8 && r > rMin * 0.6; k++) {
+          const support = Math.max(envAt(px - r * 0.8), envAt(px + r * 0.8));
+          if (isFinite(support) && support - envYp <= 0.5 * r) break;
+          r *= 0.85;
+        }
+        if (r < rMin * 0.6) continue;
+        allCircles.push({ x: px, y: envYp + r * overlapFrac, r });
+      }
+      cx += (rng() - 0.5) * turretR * 0.5;
+      cx = Math.max(outerLeft + turretR, Math.min(outerRight - turretR, cx));
+    }
+  }
+  const domAt = (px) => {
+    let best = 0;
+    let minY = Infinity;
+    for (let k = 0; k < allCircles.length; k++) {
+      const y = topY(allCircles[k], px);
+      if (y < minY) {
+        minY = y;
+        best = k;
+      }
+    }
+    return best;
+  };
+  const span = outerRight - outerLeft;
+  const nSamples = Math.max(400, Math.ceil(span * 4));
+  const step = span / nSamples;
+  const segs = [];
+  let segStart = outerLeft;
+  let prevDom = domAt(outerLeft);
+  let prevX = outerLeft;
+  for (let s = 1; s <= nSamples; s++) {
+    const x = outerLeft + s * step;
+    const dom = domAt(x);
+    if (dom !== prevDom) {
+      let lo = prevX;
+      let hi = x;
+      for (let k = 0; k < 40; k++) {
+        const mid = (lo + hi) / 2;
+        if (domAt(mid) === prevDom) lo = mid;
+        else hi = mid;
+      }
+      const tx = (lo + hi) / 2;
+      segs.push({ x0: segStart, x1: tx, ci: prevDom });
+      segStart = tx;
+      prevDom = dom;
+    }
+    prevX = x;
+  }
+  segs.push({ x0: segStart, x1: outerRight, ci: prevDom });
+  let topPath = "";
+  for (let i = segs.length - 1; i >= 0; i--) {
+    const { x0, x1, ci } = segs[i];
+    const top = allCircles[ci];
+    const cx1 = Math.max(top.x - top.r, Math.min(top.x + top.r, x1));
+    const cx0 = Math.max(top.x - top.r, Math.min(top.x + top.r, x0));
+    const yStart = topY(top, cx1);
+    const yEnd = topY(top, cx0);
+    let thetaStart = Math.atan2(yStart - top.y, cx1 - top.x);
+    let thetaEnd = Math.atan2(yEnd - top.y, cx0 - top.x);
+    if (thetaStart > 0) thetaStart -= 2 * Math.PI;
+    if (thetaEnd > 0) thetaEnd -= 2 * Math.PI;
+    topPath += arcToBeziers(top.x, top.y, top.r, thetaStart, thetaEnd);
+  }
+  const rL = leftCircle.r;
+  const rR = rightCircle.r;
+  const rightOuter = arcToBeziers(xRight, baseY - rR, rR, Math.PI / 2, 0);
+  const leftOuter = arcToBeziers(xLeft, baseY - rL, rL, Math.PI, Math.PI / 2);
+  return [
+    `M ${fmt(xLeft)},${fmt(baseY)}`,
+    `L ${fmt(xRight)},${fmt(baseY)}`,
+    rightOuter.trim(),
+    topPath.trim(),
+    leftOuter.trim(),
+    "Z"
+  ].join(" ");
+}
+
+// src/geometry.ts
+function smoothPolygon(pts, alpha = 0.5) {
+  const n = pts.length;
+  const segments = [];
+  const knot = (a, b) => Math.max(Math.hypot(b.x - a.x, b.y - a.y), 1e-9) ** alpha;
+  for (let i = 0; i < n; i++) {
+    const p0 = pts[(i - 1 + n) % n];
+    const p1 = pts[i];
+    const p2 = pts[(i + 1) % n];
+    const p3 = pts[(i + 2) % n];
+    const d1 = knot(p0, p1);
+    const d2 = knot(p1, p2);
+    const d3 = knot(p2, p3);
+    const m1x = ((p1.x - p0.x) / d1 - (p2.x - p0.x) / (d1 + d2) + (p2.x - p1.x) / d2) * d2;
+    const m1y = ((p1.y - p0.y) / d1 - (p2.y - p0.y) / (d1 + d2) + (p2.y - p1.y) / d2) * d2;
+    const m2x = ((p2.x - p1.x) / d2 - (p3.x - p1.x) / (d2 + d3) + (p3.x - p2.x) / d3) * d2;
+    const m2y = ((p2.y - p1.y) / d2 - (p3.y - p1.y) / (d2 + d3) + (p3.y - p2.y) / d3) * d2;
+    const cp1 = { x: p1.x + m1x / 3, y: p1.y + m1y / 3 };
+    const cp2 = { x: p2.x - m2x / 3, y: p2.y - m2y / 3 };
+    segments.push({ p: p2, cp1, cp2 });
+  }
+  return segments;
+}
+
+// src/path.ts
+function fmt2(n) {
+  return Number(n.toFixed(3)).toString();
+}
+function p(pt) {
+  return `${fmt2(pt.x)},${fmt2(pt.y)}`;
+}
+function polygonToPath(polygon) {
+  if (polygon.length < 3) return "";
+  const segments = smoothPolygon(polygon);
+  const start = polygon[0];
+  let d = `M ${p(start)}`;
+  for (const seg of segments) {
+    d += ` C ${p(seg.cp1)} ${p(seg.cp2)} ${p(seg.p)}`;
+  }
+  d += " Z";
+  return d;
+}
+
+// src/generators/stratus.ts
+var TWO_PI = Math.PI * 2;
+function makeWave(rng, fundamental, harmonics, decay) {
+  const terms = [];
+  let norm = 0;
+  for (let k = 1; k <= harmonics; k++) {
+    const weight = 1 / k ** decay;
+    norm += weight;
+    terms.push({ freq: fundamental * k, weight, phase: rng() * TWO_PI });
+  }
+  const wave = (u) => {
+    let v = 0;
+    for (const t of terms) v += t.weight * Math.sin(TWO_PI * t.freq * u + t.phase);
+    return v / norm;
+  };
+  const maxFreq = fundamental * harmonics;
+  return { wave, maxFreq };
+}
+function smoothstep(t) {
+  if (t <= 0) return 0;
+  if (t >= 1) return 1;
+  return t * t * (3 - 2 * t);
+}
+function generateStratus(width, height, puffiness, rng) {
+  const midY = height / 2;
+  const topMargin = height * 0.06;
+  const lumpAmp = 0.08 + puffiness * 0.24;
+  let maxHalf = height * (0.1 + puffiness * 0.18);
+  const capR = maxHalf * (0.85 + rng() * 0.1);
+  let waveAmp = height * (0.07 + rng() * 0.04);
+  waveAmp = Math.min(waveAmp, maxHalf * 0.7);
+  let maxOffset = maxHalf * (1 + lumpAmp);
+  const halfBudget = height / 2 - topMargin;
+  if (waveAmp + maxOffset > halfBudget) {
+    waveAmp = Math.max(0, halfBudget - maxOffset);
+    if (waveAmp + maxOffset > halfBudget) {
+      maxOffset = halfBudget - waveAmp;
+      maxHalf = maxOffset / (1 + lumpAmp);
+    }
+  }
+  const margin = width * 0.02;
+  const capBuffer = capR * (1 + lumpAmp) + 1;
+  const x0 = margin + capBuffer;
+  const x1 = width - margin - capBuffer;
+  const span = x1 - x0;
+  const spineWave = makeWave(rng, 1 + rng() * 1, 3, 1.5);
+  const spineY = (u) => midY + waveAmp * spineWave.wave(u);
+  const edgeEase = 0.12;
+  const baseHalf = (u) => {
+    let e;
+    if (u < edgeEase) e = smoothstep(u / edgeEase);
+    else if (u > 1 - edgeEase) e = smoothstep((1 - u) / edgeEase);
+    else e = 1;
+    return capR + (maxHalf - capR) * e;
+  };
+  const lumpUp = makeWave(rng, 2 + rng() * 1, 2, 1);
+  const lumpLo = makeWave(rng, 2 + rng() * 1, 2, 1);
+  const upperOffset = (u) => baseHalf(u) * (1 + lumpAmp * lumpUp.wave(u));
+  const lowerOffset = (u) => baseHalf(u) * (1 + lumpAmp * lumpLo.wave(u));
+  const maxFreq = Math.max(spineWave.maxFreq, lumpUp.maxFreq, lumpLo.maxFreq);
+  const N = Math.max(14, Math.min(26, Math.round(maxFreq * 3.5) + 2));
+  const upper = [];
+  const lower = [];
+  for (let i = 0; i < N; i++) {
+    const u = i / (N - 1);
+    const x = x0 + u * span;
+    const sy = spineY(u);
+    upper.push({ x, y: sy - upperOffset(u) });
+    lower.push({ x, y: sy + lowerOffset(u) });
+  }
+  const capN = 4;
+  function cap(u, x, topOff, botOff, side) {
+    const sy = spineY(u);
+    const pts = [];
+    for (let k = 1; k <= capN; k++) {
+      const t = k / (capN + 1);
+      const angle = -Math.PI / 2 + t * Math.PI;
+      const r = topOff + (botOff - topOff) * t;
+      pts.push({ x: x + side * r * Math.cos(angle), y: sy + r * Math.sin(angle) });
+    }
+    return pts;
+  }
+  const loop = [...upper];
+  loop.push(...cap(1, x1, upperOffset(1), lowerOffset(1), 1));
+  for (let i = N - 1; i >= 0; i--) loop.push(lower[i]);
+  loop.push(...cap(0, x0, upperOffset(0), lowerOffset(0), -1).reverse());
+  return polygonToPath(loop);
+}
+
+// src/generators/cirrus.ts
+function smoothstep2(t) {
+  if (t <= 0) return 0;
+  if (t >= 1) return 1;
+  return t * t * (3 - 2 * t);
+}
+function generateCirrus(width, height, puffiness, rng) {
+  const margin = Math.min(width, height) * 0.05;
+  const availW = width - 2 * margin;
+  const availH = height - 2 * margin;
+  const frameDiag = Math.hypot(width, height);
+  const baseTheta = -0.3 + (rng() - 0.5) * 0.4;
+  const K = 3 + Math.floor(rng() * 4);
+  const paths = [];
+  for (let w = 0; w < K; w++) {
+    const theta0 = baseTheta + (rng() - 0.5) * 0.25;
+    const curl = 0.6 + rng() * 0.5 + puffiness * 0.6;
+    const curlStart = 0.55 + rng() * 0.15;
+    const L = frameDiag * (0.28 + rng() * 0.24);
+    const maxHalf = L * (0.026 + rng() * 0.022) * (0.7 + puffiness * 0.7);
+    const uPeak = 0.66 + rng() * 0.12;
+    const lumpAmt = 0.1 + rng() * 0.08;
+    const lumpFreq = 2 + Math.floor(rng() * 2);
+    const lumpPhase = rng() * Math.PI * 2;
+    const N = 9;
+    const spine = [];
+    let px = 0;
+    let py = 0;
+    const ds = L / (N - 1);
+    for (let i = 0; i < N; i++) {
+      const u = i / (N - 1);
+      spine.push({ x: px, y: py });
+      const h = theta0 - curl * smoothstep2((u - curlStart) / (1 - curlStart));
+      px += ds * Math.cos(h);
+      py += ds * Math.sin(h);
+    }
+    const halfT = (u) => {
+      const bump = smoothstep2(Math.min(u / uPeak, (1 - u) / (1 - uPeak)));
+      const lump = 1 + lumpAmt * Math.sin(lumpFreq * Math.PI * u + lumpPhase);
+      return maxHalf * bump * lump;
+    };
+    const upper = [];
+    const lower = [];
+    for (let i = 0; i < N; i++) {
+      const u = i / (N - 1);
+      const a = spine[Math.max(0, i - 1)];
+      const b = spine[Math.min(N - 1, i + 1)];
+      const tx = b.x - a.x;
+      const ty = b.y - a.y;
+      const len = Math.hypot(tx, ty) || 1;
+      const nx = -ty / len;
+      const ny = tx / len;
+      const t = halfT(u);
+      upper.push({ x: spine[i].x + t * nx, y: spine[i].y + t * ny });
+      lower.push({ x: spine[i].x - t * nx, y: spine[i].y - t * ny });
+    }
+    const loop = [spine[0]];
+    for (let i = 1; i < N - 1; i++) loop.push(upper[i]);
+    loop.push(spine[N - 1]);
+    for (let i = N - 2; i >= 1; i--) loop.push(lower[i]);
+    let minX = Infinity;
+    let minY = Infinity;
+    let maxX = -Infinity;
+    let maxY = -Infinity;
+    for (const pt of loop) {
+      if (pt.x < minX) minX = pt.x;
+      if (pt.y < minY) minY = pt.y;
+      if (pt.x > maxX) maxX = pt.x;
+      if (pt.y > maxY) maxY = pt.y;
+    }
+    const bw = maxX - minX || 1;
+    const bh = maxY - minY || 1;
+    const s = Math.min(1, availW / bw, availH / bh);
+    const placedW = s * bw;
+    const placedH = s * bh;
+    const ox = margin + rng() * (availW - placedW);
+    const oy = margin + rng() * (availH - placedH);
+    const placed = loop.map((pt) => ({
+      x: ox + (pt.x - minX) * s,
+      y: oy + (pt.y - minY) * s
+    }));
+    paths.push(polygonToPath(placed));
+  }
+  return paths;
+}
+
+// src/index.ts
+var DEFAULT_DIMS = {
+  cumulus: { width: 300, height: 180 },
+  stratus: { width: 1200, height: 120 },
+  cirrus: { width: 400, height: 200 }
+};
+function buildCloudResult(dims, buildPaths, options) {
+  const { seed = Math.floor(Math.random() * 4294967295), style = {} } = options;
+  const { width = dims.width, height = dims.height } = options;
+  const rng = createRng(seed);
+  const puffiness = options.puffiness ?? rng();
+  const paths = buildPaths(width, height, puffiness, rng);
+  const svg = assembleSvg(width, height, paths, style);
+  return makeResult(svg);
+}
+function generateCumulus2(options = {}) {
+  return buildCloudResult(DEFAULT_DIMS.cumulus, (w, h, p2, r) => [generateCumulus(w, h, p2, r)], options);
+}
+function generateStratus2(options = {}) {
+  return buildCloudResult(DEFAULT_DIMS.stratus, (w, h, p2, r) => [generateStratus(w, h, p2, r)], options);
+}
+function generateCirrus2(options = {}) {
+  return buildCloudResult(DEFAULT_DIMS.cirrus, generateCirrus, options);
+}
+function generateCloud(options = {}) {
+  const { type = "cumulus" } = options;
+  switch (type) {
+    case "cumulus":
+      return generateCumulus2(options);
+    case "stratus":
+      return generateStratus2(options);
+    case "cirrus":
+      return generateCirrus2(options);
+    default:
+      throw new Error(`Unknown cloud type: ${type}`);
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  generateCirrus,
+  generateCloud,
+  generateCumulus,
+  generateStratus
+});

package/dist/index.d.cts

@@ -0,0 +1,27 @@
+type CloudType = 'cumulus' | 'stratus' | 'cirrus';
+interface CloudStyle {
+    fill?: string;
+    stroke?: string;
+    strokeWidth?: number;
+    opacity?: number;
+}
+interface CloudOptions {
+    type?: CloudType;
+    width?: number;
+    height?: number;
+    seed?: number;
+    puffiness?: number;
+    style?: CloudStyle;
+}
+type CloudTypeOptions = Omit<CloudOptions, 'type'>;
+interface CloudResult {
+    svg: string;
+    element(): SVGSVGElement;
+}
+
+declare function generateCumulus(options?: CloudTypeOptions): CloudResult;
+declare function generateStratus(options?: CloudTypeOptions): CloudResult;
+declare function generateCirrus(options?: CloudTypeOptions): CloudResult;
+declare function generateCloud(options?: CloudOptions): CloudResult;
+
+export { type CloudOptions, type CloudResult, type CloudStyle, type CloudType, type CloudTypeOptions, generateCirrus, generateCloud, generateCumulus, generateStratus };

package/dist/index.d.ts

@@ -0,0 +1,27 @@
+type CloudType = 'cumulus' | 'stratus' | 'cirrus';
+interface CloudStyle {
+    fill?: string;
+    stroke?: string;
+    strokeWidth?: number;
+    opacity?: number;
+}
+interface CloudOptions {
+    type?: CloudType;
+    width?: number;
+    height?: number;
+    seed?: number;
+    puffiness?: number;
+    style?: CloudStyle;
+}
+type CloudTypeOptions = Omit<CloudOptions, 'type'>;
+interface CloudResult {
+    svg: string;
+    element(): SVGSVGElement;
+}
+
+declare function generateCumulus(options?: CloudTypeOptions): CloudResult;
+declare function generateStratus(options?: CloudTypeOptions): CloudResult;
+declare function generateCirrus(options?: CloudTypeOptions): CloudResult;
+declare function generateCloud(options?: CloudOptions): CloudResult;
+
+export { type CloudOptions, type CloudResult, type CloudStyle, type CloudType, type CloudTypeOptions, generateCirrus, generateCloud, generateCumulus, generateStratus };

package/dist/index.js

@@ -0,0 +1,520 @@
+// src/rng.ts
+function createRng(seed) {
+  let s = seed >>> 0;
+  return function() {
+    s += 1831565813;
+    let t = s;
+    t = Math.imul(t ^ t >>> 15, t | 1);
+    t ^= t + Math.imul(t ^ t >>> 7, t | 61);
+    return ((t ^ t >>> 14) >>> 0) / 4294967296;
+  };
+}
+
+// src/svg.ts
+function buildPathAttrs(style) {
+  const attrs = [];
+  attrs.push(`fill="${style.fill ?? "white"}"`);
+  if (style.stroke && style.stroke !== "none") {
+    attrs.push(`stroke="${style.stroke}"`);
+    attrs.push(`stroke-width="${style.strokeWidth ?? 1}"`);
+  }
+  if (style.opacity !== void 0 && style.opacity !== 1) {
+    attrs.push(`opacity="${style.opacity}"`);
+  }
+  return attrs.join(" ");
+}
+function assembleSvg(width, height, paths, style) {
+  const attrs = buildPathAttrs(style);
+  const pathElements = paths.filter((d) => d.length > 0).map((d) => `<path d="${d}" ${attrs}/>`).join("\n  ");
+  return [
+    `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${width} ${height}" width="${width}" height="${height}">`,
+    `  ${pathElements}`,
+    `</svg>`
+  ].join("\n");
+}
+function makeResult(svgString) {
+  return {
+    svg: svgString,
+    element() {
+      if (typeof DOMParser === "undefined") {
+        throw new Error("element() requires a browser environment with DOMParser");
+      }
+      const doc = new DOMParser().parseFromString(svgString, "image/svg+xml");
+      return doc.documentElement;
+    }
+  };
+}
+
+// src/generators/cumulus.ts
+function fmt(n) {
+  return Number(n.toFixed(3)).toString();
+}
+function topY(c, x) {
+  const dx2 = (x - c.x) ** 2;
+  const r2 = c.r * c.r;
+  if (dx2 > r2 + 1e-9) return Infinity;
+  return c.y - Math.sqrt(Math.max(0, r2 - dx2));
+}
+function arcToBeziers(cx, cy, r, thetaStart, thetaEnd) {
+  const total = thetaEnd - thetaStart;
+  const pieces = Math.max(1, Math.ceil(Math.abs(total) / (Math.PI / 2)));
+  const step = total / pieces;
+  const k = 4 / 3 * Math.tan(step / 4);
+  let out = "";
+  for (let i = 0; i < pieces; i++) {
+    const a = thetaStart + step * i;
+    const b = a + step;
+    const cosA = Math.cos(a);
+    const sinA = Math.sin(a);
+    const cosB = Math.cos(b);
+    const sinB = Math.sin(b);
+    const ex = cx + r * cosB;
+    const ey = cy + r * sinB;
+    const c1x = cx + r * cosA - k * r * sinA;
+    const c1y = cy + r * sinA + k * r * cosA;
+    const c2x = ex + k * r * sinB;
+    const c2y = ey - k * r * cosB;
+    out += ` C ${fmt(c1x)},${fmt(c1y)} ${fmt(c2x)},${fmt(c2y)} ${fmt(ex)},${fmt(ey)}`;
+  }
+  return out;
+}
+function generateCumulus(width, height, puffiness, rng) {
+  const rBase = height * (0.135 + rng() * 0.035);
+  const rMax = rBase * 1.15;
+  const rMin = rBase * 0.8;
+  const rAvg = rBase;
+  const margin = rMax;
+  const xLeft = margin;
+  const xRight = width - margin;
+  const baseY = height * 0.95;
+  const topMargin = height * 0.02;
+  let rLeft = rAvg + rng() * (rMax - rAvg);
+  let rRight = rAvg + rng() * (rMax - rAvg);
+  if (rLeft / rRight > 1.5) rLeft = rRight * 1.5;
+  else if (rRight / rLeft > 1.5) rRight = rLeft * 1.5;
+  const leftCircle = { x: xLeft, y: baseY - rLeft, r: rLeft };
+  const rightCircle = { x: xRight, y: baseY - rRight, r: rRight };
+  const spanCenters = xRight - xLeft;
+  const fillCount = Math.max(3, Math.min(8, Math.round(spanCenters / (1.2 * rAvg)) - 1));
+  const fillCircles = [];
+  const spacing = spanCenters / (fillCount + 1);
+  for (let i = 0; i < fillCount; i++) {
+    const t = (i + 1) / (fillCount + 1);
+    const r = rBase * (0.9 + rng() * 0.2);
+    const rawX = xLeft + t * spanCenters + (rng() - 0.5) * spacing * 0.3;
+    const x = Math.max(xLeft, Math.min(xRight, rawX));
+    fillCircles.push({ x, y: baseY - r, r });
+  }
+  const allCircles = [leftCircle, ...fillCircles, rightCircle];
+  allCircles.sort((a, b) => a.x - b.x);
+  if (allCircles.length > 2) {
+    const leftNbr = allCircles[1];
+    const rEdgeL = allCircles[0].r;
+    leftNbr.r = Math.max(0.85 * rEdgeL, Math.min(rEdgeL, leftNbr.r));
+    leftNbr.y = baseY - leftNbr.r;
+    const rightNbr = allCircles[allCircles.length - 2];
+    const rEdgeR = allCircles[allCircles.length - 1].r;
+    rightNbr.r = Math.max(0.85 * rEdgeR, Math.min(rEdgeR, rightNbr.r));
+    rightNbr.y = baseY - rightNbr.r;
+  }
+  for (let i = 1; i < allCircles.length; i++) {
+    const prev = allCircles[i - 1];
+    const curr = allCircles[i];
+    const overlapTarget = 0.4 * Math.min(prev.r, curr.r);
+    const need = curr.x - prev.x + overlapTarget - (prev.r + curr.r);
+    if (need > 0) {
+      if (i === 1) {
+        curr.r += need;
+        curr.y = baseY - curr.r;
+      } else if (i === allCircles.length - 1) {
+        prev.r += need;
+        prev.y = baseY - prev.r;
+      } else {
+        prev.r += need / 2;
+        prev.y = baseY - prev.r;
+        curr.r += need / 2;
+        curr.y = baseY - curr.r;
+      }
+    }
+  }
+  for (let i = 1; i < allCircles.length - 1; i++) {
+    const c = allCircles[i];
+    if (c.y < c.r + topMargin) c.y = c.r + topMargin;
+  }
+  const outerLeft = leftCircle.x - leftCircle.r;
+  const outerRight = rightCircle.x + rightCircle.r;
+  const envAt = (px) => {
+    let m = Infinity;
+    for (const c of allCircles) {
+      const y = topY(c, px);
+      if (y < m) m = y;
+    }
+    return m;
+  };
+  const topLimit = topMargin + height * 0.1;
+  const numTurrets = Math.round(puffiness * (3 + rng() * 1.5));
+  for (let turret = 0; turret < numTurrets; turret++) {
+    let cx = outerLeft + rBase + rng() * (outerRight - outerLeft - 2 * rBase);
+    const turretR = rBase * (1.15 + rng() * 0.55);
+    const halfW0 = turretR * (0.8 + rng() * 0.8);
+    const drama = rng() ** 1.8;
+    const baseTop = envAt(cx);
+    if (!isFinite(baseTop)) continue;
+    const targetTop = baseTop - drama * (baseTop - topLimit);
+    if (targetTop >= baseTop) continue;
+    for (let step2 = 0; step2 < 16; step2++) {
+      const envY = envAt(cx);
+      if (!isFinite(envY) || envY <= targetTop) break;
+      const frac = (envY - targetTop) / (baseTop - targetTop);
+      const halfW = turretR * 0.5 + halfW0 * Math.max(0, frac);
+      const count = Math.max(1, Math.round(2 * halfW / (0.85 * turretR)));
+      for (let j = 0; j < count; j++) {
+        const t = count === 1 ? 0.5 : j / (count - 1);
+        const px = Math.max(
+          outerLeft,
+          Math.min(outerRight, cx - halfW + t * 2 * halfW + (rng() - 0.5) * turretR * 0.3)
+        );
+        const overlapFrac = 0.46 + rng() * 0.1;
+        const rRaw = turretR * (0.85 + rng() * 0.3);
+        const envYp = envAt(px);
+        if (!isFinite(envYp) || envYp <= topLimit) continue;
+        let r = Math.min(rRaw, (envYp - topLimit) / (1 - overlapFrac));
+        for (let k = 0; k < 8 && r > rMin * 0.6; k++) {
+          const support = Math.max(envAt(px - r * 0.8), envAt(px + r * 0.8));
+          if (isFinite(support) && support - envYp <= 0.5 * r) break;
+          r *= 0.85;
+        }
+        if (r < rMin * 0.6) continue;
+        allCircles.push({ x: px, y: envYp + r * overlapFrac, r });
+      }
+      cx += (rng() - 0.5) * turretR * 0.5;
+      cx = Math.max(outerLeft + turretR, Math.min(outerRight - turretR, cx));
+    }
+  }
+  const domAt = (px) => {
+    let best = 0;
+    let minY = Infinity;
+    for (let k = 0; k < allCircles.length; k++) {
+      const y = topY(allCircles[k], px);
+      if (y < minY) {
+        minY = y;
+        best = k;
+      }
+    }
+    return best;
+  };
+  const span = outerRight - outerLeft;
+  const nSamples = Math.max(400, Math.ceil(span * 4));
+  const step = span / nSamples;
+  const segs = [];
+  let segStart = outerLeft;
+  let prevDom = domAt(outerLeft);
+  let prevX = outerLeft;
+  for (let s = 1; s <= nSamples; s++) {
+    const x = outerLeft + s * step;
+    const dom = domAt(x);
+    if (dom !== prevDom) {
+      let lo = prevX;
+      let hi = x;
+      for (let k = 0; k < 40; k++) {
+        const mid = (lo + hi) / 2;
+        if (domAt(mid) === prevDom) lo = mid;
+        else hi = mid;
+      }
+      const tx = (lo + hi) / 2;
+      segs.push({ x0: segStart, x1: tx, ci: prevDom });
+      segStart = tx;
+      prevDom = dom;
+    }
+    prevX = x;
+  }
+  segs.push({ x0: segStart, x1: outerRight, ci: prevDom });
+  let topPath = "";
+  for (let i = segs.length - 1; i >= 0; i--) {
+    const { x0, x1, ci } = segs[i];
+    const top = allCircles[ci];
+    const cx1 = Math.max(top.x - top.r, Math.min(top.x + top.r, x1));
+    const cx0 = Math.max(top.x - top.r, Math.min(top.x + top.r, x0));
+    const yStart = topY(top, cx1);
+    const yEnd = topY(top, cx0);
+    let thetaStart = Math.atan2(yStart - top.y, cx1 - top.x);
+    let thetaEnd = Math.atan2(yEnd - top.y, cx0 - top.x);
+    if (thetaStart > 0) thetaStart -= 2 * Math.PI;
+    if (thetaEnd > 0) thetaEnd -= 2 * Math.PI;
+    topPath += arcToBeziers(top.x, top.y, top.r, thetaStart, thetaEnd);
+  }
+  const rL = leftCircle.r;
+  const rR = rightCircle.r;
+  const rightOuter = arcToBeziers(xRight, baseY - rR, rR, Math.PI / 2, 0);
+  const leftOuter = arcToBeziers(xLeft, baseY - rL, rL, Math.PI, Math.PI / 2);
+  return [
+    `M ${fmt(xLeft)},${fmt(baseY)}`,
+    `L ${fmt(xRight)},${fmt(baseY)}`,
+    rightOuter.trim(),
+    topPath.trim(),
+    leftOuter.trim(),
+    "Z"
+  ].join(" ");
+}
+
+// src/geometry.ts
+function smoothPolygon(pts, alpha = 0.5) {
+  const n = pts.length;
+  const segments = [];
+  const knot = (a, b) => Math.max(Math.hypot(b.x - a.x, b.y - a.y), 1e-9) ** alpha;
+  for (let i = 0; i < n; i++) {
+    const p0 = pts[(i - 1 + n) % n];
+    const p1 = pts[i];
+    const p2 = pts[(i + 1) % n];
+    const p3 = pts[(i + 2) % n];
+    const d1 = knot(p0, p1);
+    const d2 = knot(p1, p2);
+    const d3 = knot(p2, p3);
+    const m1x = ((p1.x - p0.x) / d1 - (p2.x - p0.x) / (d1 + d2) + (p2.x - p1.x) / d2) * d2;
+    const m1y = ((p1.y - p0.y) / d1 - (p2.y - p0.y) / (d1 + d2) + (p2.y - p1.y) / d2) * d2;
+    const m2x = ((p2.x - p1.x) / d2 - (p3.x - p1.x) / (d2 + d3) + (p3.x - p2.x) / d3) * d2;
+    const m2y = ((p2.y - p1.y) / d2 - (p3.y - p1.y) / (d2 + d3) + (p3.y - p2.y) / d3) * d2;
+    const cp1 = { x: p1.x + m1x / 3, y: p1.y + m1y / 3 };
+    const cp2 = { x: p2.x - m2x / 3, y: p2.y - m2y / 3 };
+    segments.push({ p: p2, cp1, cp2 });
+  }
+  return segments;
+}
+
+// src/path.ts
+function fmt2(n) {
+  return Number(n.toFixed(3)).toString();
+}
+function p(pt) {
+  return `${fmt2(pt.x)},${fmt2(pt.y)}`;
+}
+function polygonToPath(polygon) {
+  if (polygon.length < 3) return "";
+  const segments = smoothPolygon(polygon);
+  const start = polygon[0];
+  let d = `M ${p(start)}`;
+  for (const seg of segments) {
+    d += ` C ${p(seg.cp1)} ${p(seg.cp2)} ${p(seg.p)}`;
+  }
+  d += " Z";
+  return d;
+}
+
+// src/generators/stratus.ts
+var TWO_PI = Math.PI * 2;
+function makeWave(rng, fundamental, harmonics, decay) {
+  const terms = [];
+  let norm = 0;
+  for (let k = 1; k <= harmonics; k++) {
+    const weight = 1 / k ** decay;
+    norm += weight;
+    terms.push({ freq: fundamental * k, weight, phase: rng() * TWO_PI });
+  }
+  const wave = (u) => {
+    let v = 0;
+    for (const t of terms) v += t.weight * Math.sin(TWO_PI * t.freq * u + t.phase);
+    return v / norm;
+  };
+  const maxFreq = fundamental * harmonics;
+  return { wave, maxFreq };
+}
+function smoothstep(t) {
+  if (t <= 0) return 0;
+  if (t >= 1) return 1;
+  return t * t * (3 - 2 * t);
+}
+function generateStratus(width, height, puffiness, rng) {
+  const midY = height / 2;
+  const topMargin = height * 0.06;
+  const lumpAmp = 0.08 + puffiness * 0.24;
+  let maxHalf = height * (0.1 + puffiness * 0.18);
+  const capR = maxHalf * (0.85 + rng() * 0.1);
+  let waveAmp = height * (0.07 + rng() * 0.04);
+  waveAmp = Math.min(waveAmp, maxHalf * 0.7);
+  let maxOffset = maxHalf * (1 + lumpAmp);
+  const halfBudget = height / 2 - topMargin;
+  if (waveAmp + maxOffset > halfBudget) {
+    waveAmp = Math.max(0, halfBudget - maxOffset);
+    if (waveAmp + maxOffset > halfBudget) {
+      maxOffset = halfBudget - waveAmp;
+      maxHalf = maxOffset / (1 + lumpAmp);
+    }
+  }
+  const margin = width * 0.02;
+  const capBuffer = capR * (1 + lumpAmp) + 1;
+  const x0 = margin + capBuffer;
+  const x1 = width - margin - capBuffer;
+  const span = x1 - x0;
+  const spineWave = makeWave(rng, 1 + rng() * 1, 3, 1.5);
+  const spineY = (u) => midY + waveAmp * spineWave.wave(u);
+  const edgeEase = 0.12;
+  const baseHalf = (u) => {
+    let e;
+    if (u < edgeEase) e = smoothstep(u / edgeEase);
+    else if (u > 1 - edgeEase) e = smoothstep((1 - u) / edgeEase);
+    else e = 1;
+    return capR + (maxHalf - capR) * e;
+  };
+  const lumpUp = makeWave(rng, 2 + rng() * 1, 2, 1);
+  const lumpLo = makeWave(rng, 2 + rng() * 1, 2, 1);
+  const upperOffset = (u) => baseHalf(u) * (1 + lumpAmp * lumpUp.wave(u));
+  const lowerOffset = (u) => baseHalf(u) * (1 + lumpAmp * lumpLo.wave(u));
+  const maxFreq = Math.max(spineWave.maxFreq, lumpUp.maxFreq, lumpLo.maxFreq);
+  const N = Math.max(14, Math.min(26, Math.round(maxFreq * 3.5) + 2));
+  const upper = [];
+  const lower = [];
+  for (let i = 0; i < N; i++) {
+    const u = i / (N - 1);
+    const x = x0 + u * span;
+    const sy = spineY(u);
+    upper.push({ x, y: sy - upperOffset(u) });
+    lower.push({ x, y: sy + lowerOffset(u) });
+  }
+  const capN = 4;
+  function cap(u, x, topOff, botOff, side) {
+    const sy = spineY(u);
+    const pts = [];
+    for (let k = 1; k <= capN; k++) {
+      const t = k / (capN + 1);
+      const angle = -Math.PI / 2 + t * Math.PI;
+      const r = topOff + (botOff - topOff) * t;
+      pts.push({ x: x + side * r * Math.cos(angle), y: sy + r * Math.sin(angle) });
+    }
+    return pts;
+  }
+  const loop = [...upper];
+  loop.push(...cap(1, x1, upperOffset(1), lowerOffset(1), 1));
+  for (let i = N - 1; i >= 0; i--) loop.push(lower[i]);
+  loop.push(...cap(0, x0, upperOffset(0), lowerOffset(0), -1).reverse());
+  return polygonToPath(loop);
+}
+
+// src/generators/cirrus.ts
+function smoothstep2(t) {
+  if (t <= 0) return 0;
+  if (t >= 1) return 1;
+  return t * t * (3 - 2 * t);
+}
+function generateCirrus(width, height, puffiness, rng) {
+  const margin = Math.min(width, height) * 0.05;
+  const availW = width - 2 * margin;
+  const availH = height - 2 * margin;
+  const frameDiag = Math.hypot(width, height);
+  const baseTheta = -0.3 + (rng() - 0.5) * 0.4;
+  const K = 3 + Math.floor(rng() * 4);
+  const paths = [];
+  for (let w = 0; w < K; w++) {
+    const theta0 = baseTheta + (rng() - 0.5) * 0.25;
+    const curl = 0.6 + rng() * 0.5 + puffiness * 0.6;
+    const curlStart = 0.55 + rng() * 0.15;
+    const L = frameDiag * (0.28 + rng() * 0.24);
+    const maxHalf = L * (0.026 + rng() * 0.022) * (0.7 + puffiness * 0.7);
+    const uPeak = 0.66 + rng() * 0.12;
+    const lumpAmt = 0.1 + rng() * 0.08;
+    const lumpFreq = 2 + Math.floor(rng() * 2);
+    const lumpPhase = rng() * Math.PI * 2;
+    const N = 9;
+    const spine = [];
+    let px = 0;
+    let py = 0;
+    const ds = L / (N - 1);
+    for (let i = 0; i < N; i++) {
+      const u = i / (N - 1);
+      spine.push({ x: px, y: py });
+      const h = theta0 - curl * smoothstep2((u - curlStart) / (1 - curlStart));
+      px += ds * Math.cos(h);
+      py += ds * Math.sin(h);
+    }
+    const halfT = (u) => {
+      const bump = smoothstep2(Math.min(u / uPeak, (1 - u) / (1 - uPeak)));
+      const lump = 1 + lumpAmt * Math.sin(lumpFreq * Math.PI * u + lumpPhase);
+      return maxHalf * bump * lump;
+    };
+    const upper = [];
+    const lower = [];
+    for (let i = 0; i < N; i++) {
+      const u = i / (N - 1);
+      const a = spine[Math.max(0, i - 1)];
+      const b = spine[Math.min(N - 1, i + 1)];
+      const tx = b.x - a.x;
+      const ty = b.y - a.y;
+      const len = Math.hypot(tx, ty) || 1;
+      const nx = -ty / len;
+      const ny = tx / len;
+      const t = halfT(u);
+      upper.push({ x: spine[i].x + t * nx, y: spine[i].y + t * ny });
+      lower.push({ x: spine[i].x - t * nx, y: spine[i].y - t * ny });
+    }
+    const loop = [spine[0]];
+    for (let i = 1; i < N - 1; i++) loop.push(upper[i]);
+    loop.push(spine[N - 1]);
+    for (let i = N - 2; i >= 1; i--) loop.push(lower[i]);
+    let minX = Infinity;
+    let minY = Infinity;
+    let maxX = -Infinity;
+    let maxY = -Infinity;
+    for (const pt of loop) {
+      if (pt.x < minX) minX = pt.x;
+      if (pt.y < minY) minY = pt.y;
+      if (pt.x > maxX) maxX = pt.x;
+      if (pt.y > maxY) maxY = pt.y;
+    }
+    const bw = maxX - minX || 1;
+    const bh = maxY - minY || 1;
+    const s = Math.min(1, availW / bw, availH / bh);
+    const placedW = s * bw;
+    const placedH = s * bh;
+    const ox = margin + rng() * (availW - placedW);
+    const oy = margin + rng() * (availH - placedH);
+    const placed = loop.map((pt) => ({
+      x: ox + (pt.x - minX) * s,
+      y: oy + (pt.y - minY) * s
+    }));
+    paths.push(polygonToPath(placed));
+  }
+  return paths;
+}
+
+// src/index.ts
+var DEFAULT_DIMS = {
+  cumulus: { width: 300, height: 180 },
+  stratus: { width: 1200, height: 120 },
+  cirrus: { width: 400, height: 200 }
+};
+function buildCloudResult(dims, buildPaths, options) {
+  const { seed = Math.floor(Math.random() * 4294967295), style = {} } = options;
+  const { width = dims.width, height = dims.height } = options;
+  const rng = createRng(seed);
+  const puffiness = options.puffiness ?? rng();
+  const paths = buildPaths(width, height, puffiness, rng);
+  const svg = assembleSvg(width, height, paths, style);
+  return makeResult(svg);
+}
+function generateCumulus2(options = {}) {
+  return buildCloudResult(DEFAULT_DIMS.cumulus, (w, h, p2, r) => [generateCumulus(w, h, p2, r)], options);
+}
+function generateStratus2(options = {}) {
+  return buildCloudResult(DEFAULT_DIMS.stratus, (w, h, p2, r) => [generateStratus(w, h, p2, r)], options);
+}
+function generateCirrus2(options = {}) {
+  return buildCloudResult(DEFAULT_DIMS.cirrus, generateCirrus, options);
+}
+function generateCloud(options = {}) {
+  const { type = "cumulus" } = options;
+  switch (type) {
+    case "cumulus":
+      return generateCumulus2(options);
+    case "stratus":
+      return generateStratus2(options);
+    case "cirrus":
+      return generateCirrus2(options);
+    default:
+      throw new Error(`Unknown cloud type: ${type}`);
+  }
+}
+export {
+  generateCirrus2 as generateCirrus,
+  generateCloud,
+  generateCumulus2 as generateCumulus,
+  generateStratus2 as generateStratus
+};

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "cloudswg",
+  "version": "0.1.0",
+  "description": "Procedurally generate SVG clouds",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "devDependencies": {
+    "playwright-core": "^1.61.1",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^2.0.0"
+  },
+  "keywords": [
+    "svg",
+    "cloud",
+    "procedural",
+    "generative"
+  ],
+  "license": "MIT",
+  "author": "Gideon Needleman",
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitlab.com/gideonneedleman/clouds.git"
+  },
+  "homepage": "https://gitlab.com/gideonneedleman/clouds",
+  "bugs": {
+    "url": "https://gitlab.com/gideonneedleman/clouds/-/issues"
+  }
+}