Picture postcard
A postcard of Goa with a typed name on it: a 3:2 card with a picture drawn by one of the library's scenes, the name set under it in any script, a perforated stamp and a postmark with an event's words, and a line saying where to make your own.
quiet warm playful
Open the live demo
npx @susegad/cli add picture-postcard
Stands on: Engine, Export, Dar, Ferry, Mithagar, Posta, Rampon, Saanj, Tinto, Tokens, Type tier
The prompt
the prompt
A postcard of Goa with a typed name on it, made in the browser, saved as a picture or a moving GIF.
The prompt
Build a postcard maker for Goa, with an event's words if there is one, from Susegad UI parts. A name field and a picture picker sit beside a live preview of a 3:2 landscape postcard, drawn on one canvas at 1800 by 1200. The card is warm paper. On the left is a framed picture, which is the still of one of the library's scenes of Goa (the old post office, the ferry, the salt pans, a village square, a green door in a lime-washed wall, an evening at the shore), taken from the scene's own model() and createRenderer() and cropped to fill a 3:2 mat. Under it, in the display face, is the typed name, centred. On the right are a perforated stamp in the top corner that carries the event's words, a round postmark over its left edge with the place along the top, the dates along the bottom and cancellation waves trailing to the left, three ruled lines for a message, and, small in the corner, a line saying where to make your own. The event's words (stamp, place, dates, an optional line) live in one config file, not in the code. The card is paper and ink, the same on a light page and a dark one.
The name is never corrected, only made to fit. It is set on one line as large as it can be (never smaller than 84 px there), then wrapped on two or three lines at a smaller size, and as a last resort broken inside a word, so a 60-letter name and a one-letter name both sit inside their place without touching the picture or the stamp. Names in Devanagari, Kannada, Malayalam, Tamil, Bengali and Urdu lay out the same way: the library's faces cover Latin, Devanagari and Kannada, any other script is drawn in the first system face that has it, and Urdu is set right to left. Cut a name at 60 characters, by grapheme, never inside a conjunct. Wait for the web fonts before drawing (canvas text does not trigger a font download) with fontReady from the type package, which gives up after four seconds.
The same name and the same scene make the same card: the paper, the stamp's tilt, the postmark and the scene are all seeded from the name, and nothing on the card reads the clock. Three buttons do the work. Save picture writes a PNG. Save GIF makes a three-second looping GIF, ten frames a second, 900 by 600: the name, the stamp and the postmark are drawn once and the GIF encodes only the picture's rectangle after its first frame, so it stays under 5 MB (try fewer colours if it does not). Make the GIF a frame at a time with the page breathing between steps, show a progress bar and say the stage in a status line, move focus to a Cancel button, and let Cancel stop it at the next step and say so. Share sends the file to the system share sheet where the browser has one and falls back to a download. Every file reports what it really is: read the type from the first bytes and name the file after them, such as postcard-asha-naik.png. Say plainly what was made. Under reduced motion, offer the GIF but do not play it on the page. Nothing leaves the device: typing a name, making a card and saving it send no request. Make the preview an image whose label reads the card, for example "A postcard of the ferry across the river for Asha, stamped Goa, postmarked Panjim 22–23 Oct 2026." With no JavaScript, say that cards are drawn in the browser.
Prove it with a check, in Chromium and in WebKit: the same name twice makes the same pixels and another name does not; long, one-letter, 60-letter and six-script names each sit inside their place and leave the rest of the card as it was; the PNG is a PNG and the GIF is a GIF89a of 30 frames under 5 MB whose first frame is the PNG's picture and whose name and stamp never move; no frame jumps from the one before; making the GIF never holds the page still for long and a cancel stops it; the keyboard journey; axe with the GIF in progress; no sideways scroll at 390 px; and not one network request after load.
Words to code
| When you say | Technique | What happens |
|---|---|---|
| a 3:2 postcard | CARD, layout() in postcard.core.js | 1800 by 1200. layout({ name, scene, seed, event, measure }) returns where everything goes; it draws nothing and runs in Node. |
| the picture is a scene's still | SCENES in scenes.js, openPicture | One line per scene. The scene's own createRenderer draws into an off-screen canvas; its still is cropped to the mat by coverRect. |
| the event's words, in one file | events/goa-oct-2026.js | { stamp, place, dates, line }. Another event is another file passed to mountPostcard(root, { event }). |
| the name as large as it can be, then wrapped, then broken | fitName, fitLines, breakLines | One line down to 84 px, then two and three lines down to 56 px, then inside a word. Every line is within 1056 px. |
| any script, Urdu right to left | scriptOf, STACKS | Names the script and whether it runs right to left; the canvas falls back glyph by glyph through the font stacks. |
| cut at 60, never inside a conjunct | normaliseName, graphemes | Intl.Segmenter graphemes; controls and bidi overrides are removed; case is never changed. |
| the same name, the same card | seedFor, rng | The name's hash seeds paper, tilt, postmark and scene. |
| a stamp with holes, a postmark | stampImage, postmarkInk | The perforations are cut out of the stamp's own canvas; the postmark is lettered along arcs by arcText. |
| a three-second looping GIF under 5 MB | makeGif, GIF, gifTimes | Draws the base once, the picture 30 times, one shared palette, then writes each frame; tries fewer colours if over budget. |
| only the picture changes | createGifEncoder().addFrame(indices, delay, rect) | After the first full frame, each frame is just the picture's rectangle. |
| a frame at a time, never freezing | breathe, addFrameSliced, indexSliced | A message-channel pause between steps; the large steps are cut into slices. |
| show progress, let it be cancelled | onProgress, AbortSignal | { stage, done, total } after each step; signal stops at the next step with an AbortError. |
| the type it really is | sniff, fileName | PNG and GIF89a told apart by their first bytes; the extension follows. |
| share where the browser can | deliver(out, { share: true }) | navigator.share({ files }) after canShare; a download otherwise; a closed sheet is "cancelled", not an error. |
| nothing leaves the device | no request | The page only reads its own static files; the check watches the network. |
A postcard of Goa with a name on it. Type a name, pick a picture, and a 3:2 card is drawn in the browser: a scene from the library in a framed mat, the name under it in any script, a perforated stamp and a postmark carrying an event's words, and a line saying where to make your own. Save it as a PNG, or as a three-second looping GIF, or send it to the share sheet. Nothing leaves the device, and the same name makes the same card.
It is a small gift of Goa, and it fits any occasion: the words on the stamp and postmark are one config file. events/goa-oct-2026.js is the one the /postcard page uses.
It composes:
| Piece | Used for |
|---|---|
the scenes (posta, ferry, mithagar, tinto, saanj, dar, rampon) | the picture, by each scene's own model() and createRenderer() |
packages/engine | the seeded paper (paper) and random numbers (rng, hashSeed) |
packages/type | fontReady, which waits for the faces and gives up after four seconds |
packages/export | canvasToPng, and gif.stream.js for the GIF a frame at a time |
The prompt
See recipe.prompt.md: the words an agent needs to build this, and a table from each phrase to the code that answers it.
Use
import { preparePostcard, exportPng, makeGif, deliver, mountPostcard, CONCLAVE_2026 } from './recipe.js';
// the page: wires #name, #scene, #card, the buttons and the status line
mountPostcard(document, { event: CONCLAVE_2026 });
// or by hand
const pc = await preparePostcard({ name: 'Asha Naik', scene: 'ferry', event: CONCLAVE_2026 });
const canvas = document.createElement('canvas'); await pc.paint(canvas);
const png = await exportPng(canvas, 'Asha Naik'); // { blob, bytes, type, filename }
const gif = await makeGif(pc, { onProgress, signal }); // { blob, bytes, frames: 30, width: 900, ms, withinBudget }
await deliver(gif, { share: true }); // share sheet with the file, else a download
pc.destroy();
Making your own
- Another event: copy
events/goa-oct-2026.js, change the four fields (stamp,place,dates,line), and pass it tomountPostcard. There is no logo: an organiser's mark needs their files and permission, so the card's own drawn stamp stands in. - Other scenes:
scenes.jsis one array, one line a scene. The order is the order of the picker. A scene must draw a good still at 3:2 and must not lean onctx.filterblur (WebKit keeps the value and draws sharp).blurbfinishes "A postcard of ..." for the alt text.gif: { from }is for a scene whose still is not where it should start moving (the card then shows that moment too, so the GIF's first frame is the PNG's picture; posta starts at 1 s, when the clerk is at the window);still: trueis for a scene that does not move (dar) or whose GIF is too costly (saanj), which is offered as a picture only;gif.warmis how many milliseconds of live frames to draw first for a scene that loads its motion late (shet).
Files
| File | What it is |
|---|---|
index.html, recipe.css | The page and the demo. Reads ?register, ?theme and ?palette. |
recipe.js | exportPng, makeGif, deliver, digest, mountPostcard. |
postcard.core.js | The pure part, runs in Node: layout, fitName, fitLines, breakLines, scriptOf, normaliseName, seedFor, sniff, slug, fileName, gifTimes. |
postcard.draw.js | The drawing: preparePostcard, drawPostcard, the stamp, the postmark, breathe. |
scenes.js | The scene list. |
events/conclave-2026.js | The event's words (default, awaiting the owner). |
postcard.test.js | Node tests of the core and its text fitting. |
recipe.check.mjs | The proof, in SG_ENGINE=chromium or webkit. --sheet writes twelve names across six scenes, as PNG and as GIF first frames, with GIF times, to .shots/postcard/<engine>/. --break=<mode> plants a fault the check must catch. |
gif-read.mjs | A small independent GIF reader the check decodes the GIF with. |
The GIF
Thirty frames, ten a second, 900 by 600, looping. The base (paper, name, stamp, postmark) is drawn once; the picture is drawn thirty times; one palette is cut from all of it; frame one is the whole card, the rest are just the picture's rectangle. If the first pass is over 4.8 MB it tries 128, then 64, then 32 colours. A made GIF is 1.9 to 3.3 MB in the scenes that move. Work goes in steps with the page breathing between them (a message-channel pause, not a timer), the large steps are sliced, progress is reported after each, and an AbortSignal stops it at the next step. The one cost it cannot cut is a scene's first render, which is the scene's own.
Notes
- Same name, same card holds within one browser. Fonts and encoders differ between engines, so the check compares within an engine and compares the GIF's first frame to the PNG's picture by a tolerance.
- A scene that has drawn its still does not start moving cleanly afterwards (shet stays a bare mat), so a card whose GIF is drawn live and warmed opens a second copy of the scene for it.
- Under reduced motion the PNG is the default and the GIF is offered but not played on the page.
- The pitch's "32 scenes" and the registry's 33 or 34 are not this recipe's business; it offers seven: posta, ferry, mithagar, tinto, saanj, dar and rampon.
shetis left out (default, awaiting owner): its GIF takes 5 s, 12 s in WebKit and about 20 s at 4x CPU throttle.