# Giftable creator kit: instructions for AI coding agents You are building a "giftable": one interactive web page that a person sends by link and the recipient opens on a phone, like unwrapping a gift. Follow this file and the page can be reviewed and published in the catalog at https://giftable.love/templates. Start from the working example: https://giftable.love/creator-kit/starter.html.txt (save it as `.html`). It already does everything under "Contract" below. Keep its plumbing, replace its look, ritual and words. The author submits the finished file at https://giftable.love/creators. Every submission is reviewed by the Giftable team before it goes live. Authors earn 30% of the revenue from every paid send of their giftable; the page above has the details. ## What to deliver - ONE file, `.html`. `` is lowercase kebab-case, for example `paper-boat`. - Inline CSS and vanilla JavaScript. No build step, no framework, no npm, no external scripts, no analytics, no trackers. - Fonts: Google Fonts only (fonts.googleapis.com / fonts.gstatic.com), two families at most, with a real fallback stack. Pick families that have `latin-ext`; `cyrillic` too if you can, because the page is translated into ten languages. - Art: inline SVG, CSS, emoji or small data URIs. Raster files only as `./img/-.webp`, each 130 KB or less; send them in a .zip with the page. - Size: the HTML is 150 KB or less. - It works opened straight from disk or any static server with no parameters, and then shows a believable demo, never a blank screen and never "Lorem ipsum". ## The experience: three acts 1. **Opening.** An interactive ritual, not a button: something is torn, untied, lit, wound, scratched, blown out. The first screen intrigues and does not show the message yet. Three to five deliberate gestures is the usual length. 2. **Reveal.** The sender's message with the recipient's name, plus whatever the page is about (a date and place, wishes, photos). 3. **Reply.** The recipient answers with one tap (or a few words) and the sender gets that answer. Then a thank-you and a way to play it again. What makes a giftable worth sending: one clear idea, its own palette and motion, and a ritual the recipient remembers. Two pages that look alike are one page too many. ## Contract ### Phone first - Design for 390x844 and let it stretch to desktop. The page never scrolls sideways. No scroll-jacking. - The control the recipient touches first carries the attribute `data-giftable-primary`, and its one-line hint carries `data-giftable-hint`. Both must fit on the first screen without scrolling at 390x844 and at 326x666 (the size of the catalog preview). - Tap targets are at least 44px. Interactive elements have an `aria-label` or visible text. Text contrast is real. - `prefers-reduced-motion: reduce` turns off everything decorative; states land at once. ### Inputs Read everything with `new URLSearchParams(location.search)`: | param | meaning | | -------- | ---------------------------------------------------- | | to | recipient's name, 60 chars at most | | from | sender's name, 60 chars at most | | msg | the personal message, 600 chars at most | | date | ISO date-time, optional | | place | optional | | occasion | optional key such as `birthday`, `love`, `thank-you` | | lang | `en es de fr it nl pl pt ru ua` | | wishes | optional JSON array of up to 10 short strings | | photos | optional JSON array of `{url, type, caption?}`, up to 12; `type` is a MIME type | | g | the published card's id, set by Giftable | When `g` is present, before showing act 1: ```js var response = await fetch('/api/postcards/share/' + encodeURIComponent(g), { headers: { 'x-dont-count-as-view': 'true' } }); var json = await response.json(); var card = json.postcard || json; var params = card.visualSettings.template.params; // the same keys as the table above ``` - A URL parameter wins over `params`, and `params` win over the page's own default. - `card.recipientName` and `card.senderMessage` are the fallbacks for `to` and `msg`. - If the fetch fails or takes longer than 2.5 s, use the URL parameters and defaults. - **A sender's words are text, never markup.** Put them on the page with `textContent`. Never pass a parameter to `innerHTML`, `eval`, a URL or a style. - A name may be empty. Have a line that reads well without it ("For you"). ### Language Every string lives in one dictionary at the top of the script: ```js var I18N = { en: {...}, es: {...} }; var L = I18N[lang] || I18N.en; ``` `lang` comes from `?lang=`, then the first two letters of `navigator.language`, then `en`. Ship `en` and `es` written natively, not machine-translated word for word. Giftable adds the other eight languages at review. Set `` and `` from the dictionary. Format dates with `toLocaleDateString(lang)`. Leave room: German and Russian lines run about 30% longer than English. ### The default message With no `msg`, the page shows its own default. Write it as a greeting anyone could send to anyone: one to three sentences, no names, no invented shared memories, no dates or places, nothing that assumes the gender of either person. Expose it so the editor can send the page as it is: ```js window.giftable = { id: 'paper-boat', lang: lang, goto: goto, autoplay: autoplay, defaults: { msg: L.msg }, questions: ownQuestions }; ``` This object is how Giftable recognises a finished page. Set it once the page is ready: - `goto(act)` shows act `1`, `2` or `3` at once, with no animation. The catalog preview, the editor and the viewer all step the page with it, and none of them works without it. - `defaults` holds the page's own words for `msg` (and `wishes`, if the page shows a list). - `questions` is the page's own question set, in the shape described below. ### The reply Act 3 is drawn from a list of questions, so that a sender can replace yours with their own: ```js var ownQuestions = [{ id: 'reaction', type: 'single', prompt: 'How did it land?', options: ['Made my day', 'I am smiling', 'Call me'] }]; ``` - `type` is `single` (one tap on one of `options`), `multi` (toggle several, then confirm) or `text` (one input, 240 characters at most). Render all three. - Take the list from the first of these that exists: the `questions` URL parameter (a JSON array), `params.questions`, `card.visualSettings.invitation.questions`, then your own. - An answer row is `{ index, id?, answer }`: `index` is the question's position in the list, `answer` is the option text, an array of option texts for `multi`, or the typed words. When the recipient has answered every question, tell the host: ```js parent.postMessage({ type: 'giftable:answers', answers: [{ index: 0, id: 'reaction', answer: 'Made my day' }], recipientName: to, locale: lang }, location.origin); ``` and when the page is not in a frame (`window.parent === window`) and `g` is present, deliver it yourself: ```js fetch('/api/postcards/' + encodeURIComponent(g) + '/reply', { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ kind: 'answers', answers: answers, recipientName: to, locale: lang }), }); ``` If the request fails, say so and let them try again; never show a thank-you for an answer that was not delivered. Also post `{type: 'giftable:ready'}` when act 1 is on screen, `{type: 'giftable:opened'}` when the ritual is done and `{type: 'giftable:replay'}` on replay. Only post to a parent frame, and always with `location.origin` as the target. ### Autoplay: the page demonstrates itself The catalog and the editor show a "watch it open" mode. Provide: ```js window.giftable.autoplay({ onStep, signal, pace }) // returns a Promise ``` - Play act 1 the way a recipient would, through the same handlers a finger uses, at a pace a viewer can follow. Never jump to the finished state. - Then act 2, held long enough to read (about 2 s a line, 8 s at most), then act 3 with the options on screen and nothing answered. - 12 to 20 seconds in total. **Never send anything during autoplay.** - `onStep({ act: 1 | 2 | 3, label })` reports progress with a localized label. - `signal` is an `AbortSignal`: stop where you are and leave the page usable. - `pace` (1 to 3, default 1) multiplies every wait. Keep one wait helper. ### Not allowed - Camera, location, notifications, clipboard reads, payment or login prompts. A microphone only behind an explicit button, with a tap that does the same thing. - Cookies or storage of anything personal. Requests to any host other than the two Giftable endpoints above and Google Fonts. - Other people's characters, logos, music or photos; real people's likenesses; text or art you have no right to publish. - Anything a person would be upset to receive: scares, insults, fake warnings. ## How to check your work 1. Open the file with no parameters: the demo plays through all three acts. 2. Open it with `?to=Ana&from=Leo&msg=Hola&lang=es`: names and message appear, in Spanish. 3. Try `?to=<img src=x onerror=alert(1)>`: the text shows as typed and nothing runs. 4. At 390x844 and 326x666 the first control and its hint are fully visible. 5. In the console: `await window.giftable.autoplay({ onStep: console.log })` runs 12-20 s and sends no network request, and `window.giftable.goto(3)` shows the question at once. Try `?questions=[{"type":"text","prompt":"Say something"}]` too: the page asks that instead of its own question. 6. With reduced motion on, it is still usable. 7. Nothing in the network panel but the page itself and Google Fonts. ## What Giftable does at review You do not need to do these: we add the guard and bridge scripts, the other eight languages, the catalog entry, the preview stills and the page in the catalog, and we test on real phones. If something has to change, we write back with what and why. ## Submit https://giftable.love/creators : attach the `.html` (or a `.zip` with `./img`) or paste a link to a repository or gist.