@liiift-studio/steadygray 0.0.1

package/README.md

@@ -0,0 +1,23 @@
+# Steady Gray
+
+**[steadygray.com](https://steadygray.com)** · [npm](https://www.npmjs.com/package/@liiift-studio/steadygray) · [GitHub](https://github.com/Liiift-Studio/SteadyGray)
+
+---
+
+## Install
+
+```bash
+npm install @liiift-studio/steadygray
+```
+
+See [steadygray.com](https://steadygray.com) for full API docs and a live demo.
+
+---
+
+## Dev notes
+
+### `next` in root devDependencies
+
+`package.json` at the repo root lists `next` as a devDependency. This is a **Vercel detection workaround** — not a real dependency of the npm package. Vercel's build system inspects the root `package.json` to detect the framework; without `next` present it falls back to a static build and skips the Next.js pipeline, breaking the `/site` subdirectory deploy.
+
+The package itself has zero runtime dependencies. Do not remove this entry.

package/dist/index.cjs

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const w=require("react"),W=require("react/jsx-runtime"),L={word:"gv-word",line:"gv-line"},C={targetDensity:"auto",method:"letter-spacing",maxAdjustment:.05,calibrationFactor:2};function z(o){const r=getComputedStyle(o),s=r.fontWeight,a=r.fontSize,t=r.fontFamily.split(",")[0].replace(/['"]/g,"").trim();return`${s} ${a} ${t}`}function v(o,r,s,a,t){const i=t.getContext("2d");if(!i)return 0;t.width=Math.max(1,Math.ceil(s)),t.height=Math.max(1,Math.ceil(a)),i.clearRect(0,0,t.width,t.height),i.fillStyle="white",i.fillRect(0,0,t.width,t.height),i.fillStyle="black",i.font=r,i.fillText(o,0,t.height*.75);const c=i.getImageData(0,0,t.width,t.height).data;let p=0;const f=t.width*t.height;for(let u=0;u<c.length;u+=4){const A=c[u],b=c[u+1],y=c[u+2];(A<200||b<200||y<200)&&p++}return f>0?p/f:0}function G(o){const r=o.cloneNode(!0);return r.querySelectorAll(`.${L.word}, .${L.line}`).forEach(a=>{const t=a.parentNode;if(t){for(;a.firstChild;)t.insertBefore(a.firstChild,a);t.removeChild(a)}}),r.querySelectorAll("br[data-gv-break]").forEach(a=>a.remove()),r.innerHTML}function V(o,r,s={},a){if(typeof window>"u")return;const t=window.scrollY,i=s.targetDensity??C.targetDensity,d=s.method??C.method,c=s.maxAdjustment??C.maxAdjustment,p=s.calibrationFactor??C.calibrationFactor;if(o.innerHTML=r,!o.offsetWidth){requestAnimationFrame(()=>{Math.abs(window.scrollY-t)>2&&window.scrollTo({top:t,behavior:"instant"})});return}const f=o.offsetWidth,u=parseFloat(getComputedStyle(o).fontSize)||16,A=z(o),b=[];(function n(e){e.nodeType===Node.TEXT_NODE?b.push(e):e.childNodes.forEach(n)})(o);const y=[];for(const n of b){const e=n.textContent??"";if(!e.trim())continue;const l=e.split(/(\S+)/),D=document.createDocumentFragment();for(let h=0;h<l.length;h+=2){const N=l[h],S=l[h+1];if(!S)continue;const M=l[h+3]===void 0?l[h+2]??"":"",x=document.createElement("span");x.className=L.word,x.style.cssText="display:inline-block;white-space:nowrap;",x.appendChild(document.createTextNode(N+S+M)),D.appendChild(x),y.push(x)}n.parentNode.replaceChild(D,n)}if(y.length===0){requestAnimationFrame(()=>{Math.abs(window.scrollY-t)>2&&window.scrollTo({top:t,behavior:"instant"})});return}const m=[];let F=null,g=null;for(const n of y){const e=n.getBoundingClientRect(),l=Math.round(e.top);F===null||l!==F?(F=l,g={text:"",width:e.width,height:e.height||u,spans:[n]},m.push(g)):(g.width+=e.width,e.height>g.height&&(g.height=e.height),g.spans.push(n))}for(const n of m)n.text=n.spans.map(e=>e.textContent??"").join("").trim();if(m.length===0){requestAnimationFrame(()=>{Math.abs(window.scrollY-t)>2&&window.scrollTo({top:t,behavior:"instant"})});return}const k=a??document.createElement("canvas"),T=m.map(n=>v(n.text,A,f,n.height||u,k));let E;if(typeof i=="number")E=i;else{const n=T.reduce((e,l)=>e+l,0);E=T.length>0?n/T.length:0}const Y=T.map(n=>{const e=(E-n)*p;return Math.max(-c,Math.min(c,e))});o.innerHTML=r;const H="display:inline-block;white-space:nowrap;vertical-align:top;";let R="";m.forEach((n,e)=>{const l=Y[e],h=`${H}${d==="word-spacing"?"word-spacing":"letter-spacing"}:${l}em;`,N=n.spans.map((S,j)=>{const M=S.textContent??"";return j===0?M.replace(/^[^\S\u00a0]+/,""):M}).join("");R+=`<span class="${L.line}" style="${h}">${N}</span>`,e<m.length-1&&(R+='<br data-gv-break="1">')}),o.innerHTML=R,requestAnimationFrame(()=>{Math.abs(window.scrollY-t)>2&&window.scrollTo({top:t,behavior:"instant"})})}function P(o,r){o.innerHTML=r}function $(o){const r=w.useRef(null),s=w.useRef(null),a=w.useRef(o);a.current=o;const t=w.useCallback(()=>{const i=r.current;i&&(s.current===null&&(s.current=G(i)),V(i,s.current,a.current))},[]);return w.useLayoutEffect(()=>{t();let i=0,d=0;const c=new ResizeObserver(p=>{const f=Math.round(p[0].contentRect.width);f!==i&&(i=f,cancelAnimationFrame(d),d=requestAnimationFrame(t))});return c.observe(r.current),()=>{c.disconnect(),cancelAnimationFrame(d)}},[t]),r}const q=w.forwardRef(function({children:r,className:s,style:a,as:t="p",...i},d){const c=$(i);return W.jsx(t,{ref:c,className:s,style:a,children:r})});q.displayName="GrayValueText";exports.GrayValueText=q;exports.applyGrayValue=V;exports.getCleanHTML=G;exports.measureLineDensity=v;exports.removeGrayValue=P;exports.useGrayValue=$;

package/dist/index.d.ts

@@ -0,0 +1,106 @@
+import { default as default_2 } from 'react';
+import { RefObject } from 'react';
+
+/**
+ * Applies gray-value optical density equalization to an element.
+ *
+ * Algorithm (7 passes):
+ *  1. Reset — restore original HTML
+ *  2. Word wrap — wrap each word in a gv-word span
+ *  3. Read phase — group words into visual lines via BCR
+ *  4. Measure — render each line to Canvas and compute density ratio
+ *  5. Target — compute target density (average or user-specified)
+ *  6. Adjust — calculate per-line letter-spacing via linear approximation
+ *  7. Write — rebuild HTML with gv-line spans carrying adjusted spacing
+ *
+ * Note: binary-search refinement of the spacing value is a future enhancement.
+ * The linear approximation (calibrationFactor × density delta) is sufficient for v1
+ * because relative density comparison between lines is what matters most.
+ *
+ * @param element      - Live DOM element to adjust (must be rendered and visible)
+ * @param originalHTML - HTML snapshot taken before the first adjustment run
+ * @param options      - GrayValueOptions (merged with defaults)
+ * @param _canvas      - Optional injectable Canvas for testing (creates one if absent)
+ */
+export declare function applyGrayValue(element: HTMLElement, originalHTML: string, options?: GrayValueOptions, _canvas?: HTMLCanvasElement): void;
+
+/**
+ * Returns the innerHTML of an element with all gray-value injected spans removed,
+ * unwrapping their children in place. Safe for complex markup. Idempotent.
+ *
+ * @param el - Element that may contain gray-value markup
+ */
+export declare function getCleanHTML(el: HTMLElement): string;
+
+/** Options controlling the gray-value density-equalization algorithm */
+export declare interface GrayValueOptions {
+    /**
+     * Target optical density ratio (0–1).
+     * 'auto' = average of all measured line densities (default).
+     */
+    targetDensity?: number | 'auto';
+    /**
+     * Which CSS spacing property to adjust per line.
+     * Default: 'letter-spacing'.
+     */
+    method?: 'letter-spacing' | 'word-spacing';
+    /**
+     * Maximum spacing adjustment in em units.
+     * Positive and negative adjustments are both clamped to this magnitude.
+     * Default: 0.05
+     */
+    maxAdjustment?: number;
+    /**
+     * Acceptable density difference before a line is considered equalized.
+     * Default: 0.01
+     */
+    tolerance?: number;
+    /**
+     * Linear scaling factor: em spacing change per 1.0 density unit difference.
+     * Increase to apply stronger corrections, decrease to be more conservative.
+     * Default: 2.0
+     */
+    calibrationFactor?: number;
+}
+
+/**
+ * Drop-in component that applies the gray-value effect to its children.
+ */
+export declare const GrayValueText: default_2.ForwardRefExoticComponent<GrayValueTextProps & default_2.RefAttributes<HTMLElement>>;
+
+declare interface GrayValueTextProps extends GrayValueOptions {
+    children: default_2.ReactNode;
+    className?: string;
+    style?: default_2.CSSProperties;
+    as?: default_2.ElementType;
+}
+
+/**
+ * Measures the optical density (ink pixel ratio) of a single line of text
+ * by rendering it to a Canvas and counting non-white pixels.
+ *
+ * Returns a value in [0, 1] where 0 = no ink and 1 = fully black.
+ *
+ * @param text        - The text content of the line
+ * @param fontStyle   - Canvas-compatible font string (e.g. "400 18px Georgia")
+ * @param targetWidth - Width of the canvas in CSS pixels
+ * @param lineHeight  - Height of the canvas in CSS pixels
+ * @param canvas      - Canvas element to render into (reused across calls)
+ */
+export declare function measureLineDensity(text: string, fontStyle: string, targetWidth: number, lineHeight: number, canvas: HTMLCanvasElement): number;
+
+/**
+ * Remove gray-value markup and restore original HTML.
+ *
+ * @param element      - Element previously adjusted by applyGrayValue
+ * @param originalHTML - The clean HTML snapshot passed to applyGrayValue
+ */
+export declare function removeGrayValue(element: HTMLElement, originalHTML: string): void;
+
+/**
+ * React hook that applies the gray-value effect to a ref'd element.
+ * Automatically re-runs on resize (width changes only).
+ */
+export declare function useGrayValue(options: GrayValueOptions): RefObject<HTMLElement | null>;
+
+export { }

package/dist/index.js

@@ -0,0 +1,161 @@
+import { useRef as R, useCallback as Y, useLayoutEffect as q, forwardRef as G } from "react";
+import { jsx as V } from "react/jsx-runtime";
+const A = {
+  word: "gv-word",
+  line: "gv-line"
+}, M = {
+  targetDensity: "auto",
+  method: "letter-spacing",
+  maxAdjustment: 0.05,
+  calibrationFactor: 2
+};
+function W(o) {
+  const i = getComputedStyle(o), a = i.fontWeight, s = i.fontSize, t = i.fontFamily.split(",")[0].replace(/['"]/g, "").trim();
+  return `${a} ${s} ${t}`;
+}
+function H(o, i, a, s, t) {
+  const r = t.getContext("2d");
+  if (!r) return 0;
+  t.width = Math.max(1, Math.ceil(a)), t.height = Math.max(1, Math.ceil(s)), r.clearRect(0, 0, t.width, t.height), r.fillStyle = "white", r.fillRect(0, 0, t.width, t.height), r.fillStyle = "black", r.font = i, r.fillText(o, 0, t.height * 0.75);
+  const c = r.getImageData(0, 0, t.width, t.height).data;
+  let p = 0;
+  const f = t.width * t.height;
+  for (let h = 0; h < c.length; h += 4) {
+    const C = c[h], x = c[h + 1], w = c[h + 2];
+    (C < 200 || x < 200 || w < 200) && p++;
+  }
+  return f > 0 ? p / f : 0;
+}
+function z(o) {
+  const i = o.cloneNode(!0);
+  return i.querySelectorAll(
+    `.${A.word}, .${A.line}`
+  ).forEach((s) => {
+    const t = s.parentNode;
+    if (t) {
+      for (; s.firstChild; ) t.insertBefore(s.firstChild, s);
+      t.removeChild(s);
+    }
+  }), i.querySelectorAll("br[data-gv-break]").forEach((s) => s.remove()), i.innerHTML;
+}
+function _(o, i, a = {}, s) {
+  if (typeof window > "u") return;
+  const t = window.scrollY, r = a.targetDensity ?? M.targetDensity, d = a.method ?? M.method, c = a.maxAdjustment ?? M.maxAdjustment, p = a.calibrationFactor ?? M.calibrationFactor;
+  if (o.innerHTML = i, !o.offsetWidth) {
+    requestAnimationFrame(() => {
+      Math.abs(window.scrollY - t) > 2 && window.scrollTo({ top: t, behavior: "instant" });
+    });
+    return;
+  }
+  const f = o.offsetWidth, h = parseFloat(getComputedStyle(o).fontSize) || 16, C = W(o), x = [];
+  (function n(e) {
+    e.nodeType === Node.TEXT_NODE ? x.push(e) : e.childNodes.forEach(n);
+  })(o);
+  const w = [];
+  for (const n of x) {
+    const e = n.textContent ?? "";
+    if (!e.trim()) continue;
+    const l = e.split(/(\S+)/), N = document.createDocumentFragment();
+    for (let u = 0; u < l.length; u += 2) {
+      const D = l[u], T = l[u + 1];
+      if (!T) continue;
+      const S = l[u + 3] === void 0 ? l[u + 2] ?? "" : "", y = document.createElement("span");
+      y.className = A.word, y.style.cssText = "display:inline-block;white-space:nowrap;", y.appendChild(document.createTextNode(D + T + S)), N.appendChild(y), w.push(y);
+    }
+    n.parentNode.replaceChild(N, n);
+  }
+  if (w.length === 0) {
+    requestAnimationFrame(() => {
+      Math.abs(window.scrollY - t) > 2 && window.scrollTo({ top: t, behavior: "instant" });
+    });
+    return;
+  }
+  const m = [];
+  let F = null, g = null;
+  for (const n of w) {
+    const e = n.getBoundingClientRect(), l = Math.round(e.top);
+    F === null || l !== F ? (F = l, g = {
+      text: "",
+      width: e.width,
+      height: e.height || h,
+      spans: [n]
+    }, m.push(g)) : (g.width += e.width, e.height > g.height && (g.height = e.height), g.spans.push(n));
+  }
+  for (const n of m)
+    n.text = n.spans.map((e) => e.textContent ?? "").join("").trim();
+  if (m.length === 0) {
+    requestAnimationFrame(() => {
+      Math.abs(window.scrollY - t) > 2 && window.scrollTo({ top: t, behavior: "instant" });
+    });
+    return;
+  }
+  const j = s ?? document.createElement("canvas"), b = m.map(
+    (n) => H(
+      n.text,
+      C,
+      f,
+      n.height || h,
+      j
+    )
+  );
+  let L;
+  if (typeof r == "number")
+    L = r;
+  else {
+    const n = b.reduce((e, l) => e + l, 0);
+    L = b.length > 0 ? n / b.length : 0;
+  }
+  const v = b.map((n) => {
+    const e = (L - n) * p;
+    return Math.max(-c, Math.min(c, e));
+  });
+  o.innerHTML = i;
+  const k = "display:inline-block;white-space:nowrap;vertical-align:top;";
+  let E = "";
+  m.forEach((n, e) => {
+    const l = v[e], u = `${k}${d === "word-spacing" ? "word-spacing" : "letter-spacing"}:${l}em;`, D = n.spans.map((T, $) => {
+      const S = T.textContent ?? "";
+      return $ === 0 ? S.replace(/^[^\S\u00a0]+/, "") : S;
+    }).join("");
+    E += `<span class="${A.line}" style="${u}">${D}</span>`, e < m.length - 1 && (E += '<br data-gv-break="1">');
+  }), o.innerHTML = E, requestAnimationFrame(() => {
+    Math.abs(window.scrollY - t) > 2 && window.scrollTo({ top: t, behavior: "instant" });
+  });
+}
+function U(o, i) {
+  o.innerHTML = i;
+}
+function P(o) {
+  const i = R(null), a = R(null), s = R(o);
+  s.current = o;
+  const t = Y(() => {
+    const r = i.current;
+    r && (a.current === null && (a.current = z(r)), _(r, a.current, s.current));
+  }, []);
+  return q(() => {
+    t();
+    let r = 0, d = 0;
+    const c = new ResizeObserver((p) => {
+      const f = Math.round(p[0].contentRect.width);
+      f !== r && (r = f, cancelAnimationFrame(d), d = requestAnimationFrame(t));
+    });
+    return c.observe(i.current), () => {
+      c.disconnect(), cancelAnimationFrame(d);
+    };
+  }, [t]), i;
+}
+const I = G(
+  function({ children: i, className: a, style: s, as: t = "p", ...r }, d) {
+    const c = P(r);
+    return /* @__PURE__ */ V(t, { ref: c, className: a, style: s, children: i });
+  }
+);
+I.displayName = "GrayValueText";
+export {
+  I as GrayValueText,
+  _ as applyGrayValue,
+  z as getCleanHTML,
+  H as measureLineDensity,
+  U as removeGrayValue,
+  P as useGrayValue
+};

package/package.json

@@ -0,0 +1,68 @@
+{
+	"name": "@liiift-studio/steadygray",
+	"version": "0.0.1",
+	"description": "Paragraph optical density equalization — measure actual glyph area per line and equalize visual density across all lines",
+	"type": "module",
+	"main": "dist/index.cjs",
+	"module": "dist/index.js",
+	"types": "dist/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js",
+			"require": "./dist/index.cjs"
+		}
+	},
+	"files": [
+		"dist"
+	],
+	"scripts": {
+		"build": "vite build",
+		"test": "vitest",
+		"test:run": "vitest run",
+		"lint": "tsc --noEmit",
+		"prepublishOnly": "npm run test:run && npm run build"
+	},
+	"peerDependencies": {
+		"react": ">=17",
+		"react-dom": ">=17"
+	},
+	"peerDependenciesMeta": {
+		"react": {
+			"optional": true
+		},
+		"react-dom": {
+			"optional": true
+		}
+	},
+	"devDependencies": {
+		"@types/react": "^19.0.0",
+		"@vitejs/plugin-react": "^4.0.0",
+		"happy-dom": "^12.0.0",
+		"next": "16.2.2",
+		"react": "^19.0.0",
+		"typescript": "^5.0.0",
+		"vite": "^6.0.0",
+		"vite-plugin-dts": "^4.0.0",
+		"vitest": "^3.0.0"
+	},
+	"keywords": [
+		"typography",
+		"gray-value",
+		"optical-density",
+		"typesetting",
+		"react",
+		"typescript"
+	],
+	"author": "Quinn Keaveney <quinn@liiift.studio>",
+	"license": "MIT",
+	"homepage": "https://steadygray.com",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/Liiift-Studio/SteadyGray.git"
+	},
+	"bugs": {
+		"url": "https://github.com/Liiift-Studio/SteadyGray/issues"
+	},
+	"sideEffects": false
+}