Agent guide to text outlines and typography

Read as Markdown

Read and run

Read the human guide, then the complete API reference. Begin with the minimal outline program. For editable points use Text outlines; for bending between two or more curves use Text envelope. These pages publish complete source and link the full-page experience and playground. Browse their visual results in the Text gallery.

Complete public package surface

All eight exports below come from @pibbl/text, not @pibbl/core. Their detailed definitions and constraints are in Text geometry.

Export	Role
loadOutlineFont	Asynchronously load explicit URL/bytes; returns an owned font.
createTextGeometry	Synchronously shape a single run into independent geometry and metadata.
OutlineFont	Font owner with idempotent dispose() and Symbol.dispose.
OutlineFontOptions	Abort signal and explicit monochrome fallback policy.
TextGeometryOptions	Positive font size, shaping features, direction, script, language, missing-glyph policy, segment limit.
TextGeometryResult	Mutable geometry plus conversion-time advance, ink bounds, and glyph records.
TextGlyph	Glyph ID, UTF-16 cluster, segment range, position, and advance.
InkBounds	Curve-extrema ink rectangle, distinct from layout advance.

Ordinary Text, Path, PathGeometry, envelopeTransform, transformPath, composeTransforms, and affineTransform come from @pibbl/core. Do not invent TextOnPath, a text-displacement API, or a private font-engine import.

Geometry pipeline

Shape the run once. Keep the source geometry immutable by convention while transforming copies. For envelope bending, use nonempty inkBounds as source; provide normalized guide positions with the first at 0 and last at 1. The existing playground adds intermediate guides, permits crossed/folded curves, and composes envelope mapping with affine rotation/skew before one transformPath approximation.

This changes real path geometry. It is different from a Canvas filter that only changes captured pixels. Increasing approximation precision can increase segment count and cost; retain explicit tolerance and segment limits. Guide dragging should recompute the transformation, not reload a font or reshape unchanged text. In-place path edits require a signal/state update to schedule repaint.

Assets and lifetime

• Serve an explicitly licensed outline TTF/OTF. CSS font names, WOFF/WOFF2, and system-font lookup are not accepted.
• Deploy the matching packaged engine and WASM. Verify a production build and non-root base path; the reference explains plain-esbuild placement. A successful development preview does not prove deployed asset URLs.
• Start async loading outside synchronous components. Use an AbortController on teardown, and dispose any font returned after its owner was removed.
• Retain a font across edits; dispose it after the last conversion. Geometry and metadata are JavaScript-owned and remain valid afterward.
• Dispose the Pibbl mount, native controls/listeners, and owned overlays when removing a demo. HtmlBox controls remain native HTML; they are not warped or captured by the Canvas effect.

Do not infer unsupported behavior

One run is not paragraph layout: no automatic fallback, wrapping, paragraph bidi, rich text, caret mapping, or variable-axis selection. Missing glyphs throw by default. Clusters are UTF-16 source offsets, not characters or carets. Metrics and segment ranges describe the initial conversion and do not update after path mutation. Empty/whitespace-only ink needs an explicit no-envelope state.

Verify adaptations

1. Check font and WASM requests, license deployment, and browser errors in production output.
2. Generate supported text, then exercise missing glyphs and empty/whitespace input without stale successful output.
3. Confirm a guide drag visibly changes the path while leaving original text geometry intact. Add a third guide and verify that it influences the interior.
4. Exercise typing, presets, rotation, skew, reset, and native keyboard controls. Check the full-page view at narrow widths.
5. Stop/restart or navigate away during font loading; confirm controls/overlays are removed and font/controller cleanup runs.

Use coverage.json for exact installed-checkout symbol destinations and llms.txt for static documentation discovery. Example availability is not evidence that every arbitrary font or guide arrangement is supported.

Documentation version

Documentation built with @pibbl/core 0.0.2, revision 2dccb19. ALPHA — NOT FOR PRODUCTION USE.