textpour 0.1.1 → 0.1.2

package/README.md

@@ -3,16 +3,18 @@
 A render-agnostic **text-geometry kernel** on top of
 [`@chenglou/pretext`](https://github.com/chenglou/pretext).
 
-- **Shape-flow**: pour text into arbitrary 2D regions — circles, polygons, holes, boolean
-  combinations, SVG paths, glyph outlines, and raster alpha masks — by routing Pretext's
-  line-breaking through per-row spans. (CSS `shape-inside` never shipped; this does it.)
-- **Typographic quality** (the moat): justification (`align: 'justify'`), soft-hyphenation,
-  balanced lines, auto-fit (binary-search font size), and conservative band sampling so glyphs
-  never poke outside tight curves.
+- **Shape-flow — the reusable core.** Turn any 2D region — circles, ellipses, polygons, boolean
+  unions/intersections/**holes**, SVG paths, glyph outlines, raster alpha masks — into the per-row
+  spans Pretext fills, threading one cursor across the *several disjoint spans* a single row can have
+  (around a hole, through a glyph's counters). This shape→spans geometry is the part worth a library.
+  (CSS `shape-inside` never shipped; this does it.)
 - **Cursor ↔ point mapping**: map pixel positions to exact grapheme positions and back, for
   caret/hit-testing in custom-rendered text.
-- **Pluggable paint**: the kernel computes geometry; `Renderer`s paint it. Canvas2D works today;
-  an HTML-in-Canvas adapter (for high-fidelity, accessible, 3D-surface paint) is stubbed for later.
+- **Conveniences over the line breaker** (nice-to-haves, *not* the moat): justification, soft-
+  hyphenation, balanced lines, auto-fit, conservative band sampling — pragmatic implementations over
+  the *published* `@chenglou/pretext@0.0.1`; Pretext's fuller API does several of these natively.
+- **Pluggable paint**: the kernel computes geometry; `Renderer`s paint it. Canvas2D today; an
+  HTML-in-Canvas adapter (high-fidelity, accessible, 3D-surface paint) is stubbed for later.
 
 The design bet is the **plan/paint split**: Pretext plans cheaply every frame (no DOM reflow); an
 expensive high-fidelity backend paints only when the plan changes.
@@ -24,6 +26,12 @@ prepared pass reused on every frame:
 
 ![textpour demo: text flowing into a circle and a donut, reflowing live](assets/textpour-demo.gif)
 
+A gallery of practical demos lives in `demo/` — serve over http (`npm run build` first) and open
+**`demo/gallery.html`**. Start with **Anatomy**, which runs raw Pretext and textpour *side by side*:
+identical pixels for a circle (just inline the loop), and the spans function ballooning into a
+rasterizer for a glyph (reuse the library). The rest — Islands, Letterform, Ghostwriter, Reflow,
+Touchpoint — isolate one capability each, with a "textpour vs raw Pretext" code panel on every page.
+
 ## Why not just Pretext?
 
 Pretext is the line-breaking and measurement engine — a very good one. It breaks lines at a width
@@ -53,7 +61,18 @@ balanced-lines are pragmatic implementations over that minimal surface — when
 richer API (Knuth–Plass justify, real hyphenation, `walkLineRanges`), textpour will defer to those
 and keep only the geometry it uniquely contributes.
 
-In one line: **Pretext breaks the lines; textpour decides the shape those lines fill.**
+In one line: **Pretext breaks the lines; textpour decides the shape those lines fill.** The flow loop
+on top is ~12 lines you could inline — what textpour actually packages is `region.spansAt(y)` for
+shapes Pretext has no concept of. A convenience kernel, not a new capability. (See the **Anatomy**
+demo for the side-by-side proof.)
+
+## What this is (and isn't)
+
+A **hobby + learning project** — as much an excuse to learn the npm release loop (publish, semver,
+CI-on-tag) as a library. It's a thin geometry layer **on top of** Pretext, **not** a replacement for
+or competitor to it: Pretext does the hard part (shaping, line-breaking, measurement); textpour just
+turns shapes into spans. Treat it as a niche convenience, not infrastructure — fun if you're pouring
+text into odd shapes, but don't build anything load-bearing on it.
 
 ## Quickstart
 
@@ -63,7 +82,7 @@ npm test          # builds, runs the pure-logic test suite (56 specs)
 npm run build     # emits dist/
 # demo (needs a browser + http):
 npx http-server . # or any static server
-# open /demo/index.html
+# open /demo/gallery.html
 ```
 
 ## Status
@@ -80,17 +99,33 @@ flagship "shaped CSS text on a 3D surface" demo (Phase 3).
 - **SPEC.md** — the full design, API reference, and the relationship to Pretext + HTML-in-Canvas.
 - **ROADMAP.md** — phased tasks with acceptance + kill criteria.
 
-## Example
+## Example — Pretext vs textpour
+
+Pour text into a column with a hole, both ways — the contrast every demo shows ([live](demo/gallery.html)):
+
+```js
+// raw Pretext: you write the loop AND the geometry
+let cur = { segmentIndex: 0, graphemeIndex: 0 };
+const spansAt = (yc) => {                                  // column minus the hole's chord
+  const h = 90 * 90 - (yc - 200) ** 2;
+  return h <= 0 ? [[0, 600]] : [[0, 300 - Math.sqrt(h)], [300 + Math.sqrt(h), 600]];
+};
+for (let y = 0; y + 26 <= 400; y += 26)
+  for (const [x0, x1] of spansAt(y + 13)) {
+    const line = layoutNextLine(prepared, cur, x1 - x0);  // one cursor across the gap
+    if (!line) break;
+    ctx.fillText(line.text, x0, y + 20); cur = line.end;
+  }
+```
 
 ```ts
-import { shapeFlow, circle, subtract, Canvas2DRenderer, PretextLineSource } from 'textpour';
-
-const source = new PretextLineSource(longText, '17px Georgia'); // one prepare pass
-const region = subtract(circle(220, 220, 160), circle(220, 220, 67)); // a donut
-const result = shapeFlow(source, region, { lineHeight: 24, ascent: 18 });
-
-new Canvas2DRenderer('17px Georgia', { color: '#1a1a1a' }).render(result, ctx);
-// result.overflow / result.endCursor drive auto-fit and multi-region pagination
+// textpour: describe the shape, pour
+const region = subtract(rect(0, 0, 600, 400), circle(300, 200, 90));
+const result = shapeFlow(source, region, { lineHeight: 26, ascent: 20, multiSpan: 'fill' });
+renderer.render(result, ctx);
 ```
 
+Same output. The loop is glue; **`region` is the part textpour gives you** — and it scales to glyphs,
+masks, and booleans without touching `spansAt`. [Anatomy](demo/anatomy.html) runs both, pixel-for-pixel.
+
 MIT.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "textpour",
-  "version": "0.1.1",
-  "description": "Pour text into arbitrary shapes — a render-agnostic text-geometry kernel on top of @chenglou/pretext (shape-flow + cursor<->point mapping, pluggable paint adapters).",
+  "version": "0.1.2",
+  "description": "Hobby/learning project: a small geometry layer on top of @chenglou/pretext — turn any 2D shape (holes, glyphs, image masks) into the per-row spans it fills, plus cursor<->point mapping. Not a Pretext replacement.",
   "type": "module",
   "main": "./dist/src/index.js",
   "types": "./dist/src/index.d.ts",