From 0c80ef99c59d8afbc774bc97d05410977e95b225 Mon Sep 17 00:00:00 2001 From: Tim <6703801+timzifer@users.noreply.github.com> Date: Thu, 10 Sep 2026 15:01:05 +0200 Subject: [PATCH] docs: point at the hosted endpoint, and at what it cannot do MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A reader who wants a mark in a README should not have to write a program to get one, and there is now an endpoint that serves them. It runs this code: the deploy compares every response against a go run of the same version, byte for byte, and refuses to ship on a disagreement. What it cannot do is worth as much as what it can. The deployment has ten milliseconds of CPU per request, which SVG does not notice — its cost is the renderer's own maths and is flat in the requested size — and which PNG feels immediately, because rasterising and deflating cost the square of the edge length. Hence measured per-renderer ceilings, and hence flowfield being absent from PNG entirely: its streamline integration costs the same at sixteen pixels as at five hundred. Said plainly here because the alternative is someone concluding the library has those limits. It does not. That distinction is the reason to depend on a library with no dependencies rather than on somebody's endpoint. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01SU6ycrqMbQ8AVxzxYgdC5C --- README.md | 43 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 43 insertions(+) diff --git a/README.md b/README.md index 2b4fa7e..98b8ebf 100644 --- a/README.md +++ b/README.md @@ -155,6 +155,49 @@ blazon dist -r truchet Colour is derived in OKLCH with gamut mapping, held in a lightness band that keeps contrast on both a white page and a dark terminal. +## Hosted marks + +If all you want is a mark in a README, there is an endpoint for it: + +``` +https://api.blazon.build/v1/mark/1.4.2.svg +https://api.blazon.build/v1/mark/1.4.2.svg?renderer=flowfield&bg=dark +https://api.blazon.build/v1/mark/1.4.2.png?renderer=bishop&size=112 +``` + +`/v1/mark/{version}.{svg|png|txt}`, with `renderer`, `size`, `padding`, +`policy`, `palette`, `bg`, `cols` and `nocolor` spelled exactly as the CLI +spells them. `/v1/renderers` lists what exists and the current size ceilings; +`/v1/healthz` reports which release is deployed. A mark is a pure function of +its URL, so the answers are cacheable forever and are served that way. + +It runs the same code this repository publishes — the deploy compares every +response against a `go run` of the same version, byte for byte, and refuses to +ship on a disagreement. So the marks are the marks. What differs is the budget. + +**Prefer SVG.** It is the format the service is comfortable with: its cost is +whatever the renderer's own maths costs and does not grow with the requested +size, so it is served at any size up to 1024 with no per-renderer limit. + +**PNG is capped**, because rasterising and deflating cost the square of the +edge length and the deployment has ten milliseconds of CPU per request. The +ceilings are measured, published at `/v1/renderers`, and currently run from 48 +to 112 pixels depending on the renderer. `flowfield` is not served as PNG at +all: its streamline integration costs the same at sixteen pixels as at +five hundred, so there is no size at which it fits. + +These are limits of one small deployment, not of the library. `blazon.PNG` has +no ceiling, no renderer is excluded, and rendering locally costs a few +milliseconds: + +```go +data, err := blazon.PNG("1.4.2", blazon.Options{Renderer: "flowfield", Size: 1024}) +``` + +The service is best effort and carries no availability promise. Anything that +matters should render its own marks — that is the whole point of a library +with no dependencies. + ## Gallery Generated by `blazon gallery` and verified in CI: if the committed images stop