--- name: publish-content description: Publish, update, diff, or prepare interactive bits on Differ, or a creator's place behind their profile. Not Git pushes or generic hosting. --- # Publish content Making and previewing do not imply publishing intent. When the human asks to publish, do it without requiring an account. Ask what they want to make if no brief was given. A bit is one piece on Differ; each upload of it is a new version, and a published version never changes. Each bit has its own origin on differ.page and normal browser storage and capabilities, subject to the browser's permission prompts. Private audiences and arbitrary Node servers are unsupported. For shared durable state, use the document runtime described in [participation](references/participation.md). A bit is at most 256 files and 20 MiB. Files under `data/` need a root `rules.html`, since only live participation serves them; a bundle with them and no `rules.html` is refused with the code data_without_rules, so put static assets in another folder, such as `assets/`. The folders `-/`, `v/`, `uploads/`, `__differ/` and `__dfr/` are Differ's: a bundle with files there is refused. Guests can publish and interact locally; the bit must be claimed before signed-in visitors can contribute shared state. ## Caption and title Every public version carries a caption: the maker's own words shown over the bit, 1–200 characters, at most 3 line breaks. Suggest one from what the human said, in their voice, and let them confirm or rewrite it. In Differ the maker confirms it again when publishing a draft or claiming a guest bit. Never write a title. Differ names each bit itself after it has looked at it; until then the bit has no name. Keep the bit's own `` and headings whatever the piece needs. ## The feed and the open bit A bundle has a root `index.html`, the open bit, and may have a root `preview.html`, what the feed shows of it. - The open bit fills the phone. Its size varies by device, so it must be responsive; check it at 390×693 CSS px. - `preview.html` is a 390×520 CSS px interactive preview, laid out at exactly that size. Without it the feed shows `index.html` laid out at 390×693 and scaled into that box. It may use any file in the bundle and is checked like any page. A tap on it should show the piece's promise and lead into the open bit. - In the preview, people only tap, hold and drag sideways: vertical swipes belong to the feed. Use pointer events only, never touch events. No native range, select or text inputs, no scrolling area, and nothing that needs `:hover` or `:active`. No sound, permission requests, keyboard or participation. Keep the top-right 48×48 px free for Differ's open button. Keep it light: it loads while people scroll. Differ adds its SDK to every page of a bit as the global `differ`; never include or reference anything under `/__differ/`. - `differ.page` is `'preview'` on `preview.html`, else `'index'`; `differ.inFeed` is true inside Differ; `differ.hidden` is the current visibility. - On the preview, `differ.open(state)` opens the bit. `state` is any JSON value of at most 4096 bytes; the open bit receives it. A click on an element with a `data-differ-open` attribute, or inside one, calls `differ.open(value || null)` with that attribute's value. - On the open bit, `differ.close()` returns to the feed. - `differ.on('open', fn)` calls `fn(state)` when the bit opens (`null` when Differ's own control opened it); `differ.on('show', fn)` and `differ.on('hide', fn)` follow visibility. Each returns a function that unsubscribes. - Inside Differ a page starts hidden and not opened, so start motion, sound and timers on `show` and pause them on `hide`, and read the open state from `open`. A late subscriber still gets the last show or hide and the last open once. Outside Differ the page starts shown, the open bit counts as opened with `null`, and `open` and `close` do nothing. ## A creator's place A connected creator also has one place: their own page, shown full screen behind their profile. It isn't a bit and has no caption. To make or update it, read [place](references/place.md). ## Choose the path - If the human supplied a Differ prompt with a reserved bit and upload pass, follow that prompt's upload instructions. Do not create a second bit; its original browser owns the claim, and the upload pass cannot claim it. - With the Differ helper (the plugin's `publish_directory` tool or its `differ.cjs` script), follow [helper](references/helper.md). It reads files from disk, so prefer it whenever it is available, except as below. - With the Differ connector (`start_bit`, `publish_bit`, `publish_as_me`), follow [connector](references/connector.md). - With both, when `get_profile` names a connected creator and the helper is not already connected, publish through the connector. Its sign-in belongs to the human's account and lasts across sessions; the helper's is saved on this machine, so in a cloud or disposable sandbox it is lost when the session ends. Do not start the helper's connection there. - With neither, say publishing needs the Differ helper, the Differ connector or a prompt copied from Differ's Create page. Never invent an upload URL. To install the helper or add the connector, read [setup](references/setup.md). Each path's reference says how to connect an account. ## On every path 1. Publish as a guest unless an account is connected. Guest publishing needs no setup; do not block or nag for sign-in first. Never ask for credentials in chat. A guest upload's caption is optional and provisional: the maker confirms it when claiming. 2. Return the confirmed public URL. When you hold an unclaimed bit's private claim link, also prominently return it with the **actual expiry deadline**: “Live by link. Claim it before [deadline] to keep it and add it to the feed.” Never publish that private link inside the content or share it as the public bit link. A connected creator's upload, new bit or update, is saved as a draft (`"draft": true` in its receipt): nothing public changes yet. Say so plainly, “Saved as a draft, not published yet. Preview it, confirm its caption and publish: [url]”, using the receipt's `url`. The draft keeps the caption you suggested. Set `publish` only when the human explicitly asked to publish now without previewing; it then needs the caption they confirmed. A place's upload is a draft too, until the creator publishes it or explicitly asks you to. 3. Connecting an account makes future new bits the creator's. It never claims earlier guest bits; those still need their own claim links. A claimed bit refuses its guest upload pass; update it as its connected owner. An expired or revoked connection stops and asks to reconnect; never silently switch to guest. 4. When you build a publishing request yourself, save its request identifier before sending and, after an uncertain response, retry the identical request; the helper does this for you. On a version conflict, compare the current bit before deliberately continuing; never silently overwrite or turn an update into a new bit. 5. A diff names both its parent bit and that bit's exact version, and carries its own caption, never the parent's. Another person's source or public link grants no edit rights. Diffs start from authored files and seeds, never accumulated visitor data or identities. Updates preserve participation: change its meaning only in a diff. 6. Check the actual frames: the preview at 390×520 and the open bit at 390×693, as the helper's preview shows them; in your own Playwright checks `scripts/browser.mjs` (see "Get the example code" in references/participation.md) opens them with `previewer` and `viewer`. The Differ's controls sit outside the content. Separate committed publication, HTTP verification, and interaction actually observed in a browser. Follow connection errors' recovery. Restricted networking needs normal network permission, not new credentials: see [when Differ can't be reached](#when-differ-cant-be-reached). Do not routinely patch the publisher, edit DNS, rebuild Differ or switch hosts during content work. Preserve files and pending identity when blocked; local readiness is not publication. ## When Differ can't be reached Differ's own refusals are JSON with a `code` and `message`. A request that fails before Differ answers (a proxy's 403, "Tunnel connection failed", a DNS or connection error) was stopped by this environment's network policy, which cloud sandboxes apply to hosts they do not know. Retrying, new credentials or another route will not help. Tell the human once, naming the host from the upload URL: allow it in this environment's network settings, a one-time change (in Claude Code on the web, the environment menu in the session's title bar, then Edit, then Network access). Keep the files and the saved request, and retry the identical request once it is allowed. Until then, a bit small enough for the connector's call can still publish that way, since the call travels through the host rather than the sandbox; otherwise give the human a .zip of the content with `index.html` at its root, which they can drop on Differ's Create page, or in a bit's Update dialog to save it as a draft.