Samples

A sample is a versioned page the model keeps from an Eval cell when you ask to see a design, report or comparison, served locally to your browser for pinned comments. The model supplies the content as typed blocks; Mercury draws the page. Each sample is kept per session, versioned, and opens again on request. Samples are off by default.

Sample controls

• Boot Menu Samples row: Turns samples on for new sessions.
• MERCURY_SAMPLES=1: Turns samples on when set in the environment before the session starts.
• /samples: Lists the session's samples, newest first, with the name, v<N>, the state and when it last changed. Enter opens the selected one and Esc returns.
• sample({ name, title?, doc, ask? }): Keeps a structured page from an Eval cell (Workshop). The same name appends a version to the same sample. Passing raw html from a cell is refused with an error pointing to doc; the model never writes raw HTML or CSS.
• /memory page: Renders your Memory library as a sample page, adding a new version each time you run it.
• Samples row of mercury health and /health: States which way the switch stands.

Enable samples

Turn on the Boot Menu's Samples row (or set MERCURY_SAMPLES=1) and start a new session. The session has sample({ name, title?, doc, ask? }) in Eval cells, the loopback listener and the /samples command.

Where a sample comes from and the nine blocks

The model writes the page's parts in an Eval cell and keeps them with sample({ name, title?, doc, ask? }). doc is { subtitle?, meta?, verdict?, parts: [...] }, where every part is one of the nine blocks below. Mercury renders the document into one self-contained HTML page and keeps that page as the version. The data stays in the cell, so a redraw is a small edit, and every redraw is the next version of the same sample. The cell's result lists each sample it saved (title, version and local URL) along with the prompt text passed in ask.

Blocks with a heading are numbered I, II, III and so on in order (numeral: "" suppresses one); three or more headed blocks get an outline under the title. The renderer accepts kind or type (with hyphens or underscores) and block aliases (before-after for diff, code and log for terminal, checks for checklist, decision for question). An unknown block kind or invalid field is refused with the offending field path named, and no version is saved.

The two surfaces and browser controls

Every page opens on the dark surface in the website's palette: blue-black ground, bone headings, steel-blue accent, square corners, dim glyphs in the flanks and the pixel helmet at the top. The Parchment button at the top right switches the page to aged paper with dark-brown ink and sepia hairlines; the choice is remembered for the session, and parchment is also used when printing. Code, diff and terminal blocks render as green-phosphor terminal windows on near-black on both surfaces. The page loads no remote font, script or image.

Inside the page j and k scroll, 1 through 9 jump to a numbered block, and the viewer's own keys (m, s, c, ?, ←, →) work from inside it:

• Version switcher: Selects a version (← and → move between versions).
• Code: Shows the version's HTML read-only.
• Copy: Puts the HTML on the clipboard.
• Download: Saves the version as <name>-v<N>.html.
• ?: Shows the keys.

Open a sample

Enter /samples, select a sample and press Enter. In the full layout, the status row beneath the chat shows the session's sample count (· 1 sample) after the model and effort, and /samples opens the list. In the compact layout, the line under the composer counts the session's samples (· 1 sample), and opening its detail view lists them. While the browser tab is open it refreshes automatically as the model redraws.

Send review marks

To send review marks:

1. Choose Edit with Mercury, or press m.
2. Click a spot on the page.
3. Enter the comment in the box that opens and press Enter to keep the pin (Esc removes a new pin).
4. Click an option on a question block to stage Decision (<heading>): <option> into the note, or add a note for the whole page in the foot.
5. Choose Approve or Changes needed, if wanted.
6. Choose Send marks to Mercury, or press s.

Every part of a rendered page carries a stable id (part-3-diff, part-3-a-2 for a line of its after pane, part-4-row-2 for a table row, part-8-item-3 for a checklist item), so a pin names the block, row, line or option it landed on, and the same id means the same place in the next version. Pins can be dragged, reopened and removed, and each remembers the element under it: its tag, id, class and first words. Mercury receives the pins, the staged decisions, the note and the verdict as one message in the session, as if typed. The model answers it in its next turn, and a message sent while a turn is running waits as any typed message does. The verdict moves the sample's state (approved, changes needed), and a new version opens it again.

Storage and local access

Samples live under the session in the config home, outside the project, at <config-home>/sessions/<session>/samples/<id>/:

• sample.json: The record: name, title, state and versions.
• v1.html, v2.html: Each version, the page Mercury rendered.
• marks-v2.json: The marks left on that version.

A sample stays on your machine. A listener on 127.0.0.1 serves the page while the session's process runs, on a port chosen fresh each time. Every address carries a token made once per session process and never written to disk, and a request without it answers 404. A session that cannot open a loopback port writes the page beside the version as a self-contained file, v<N>.page.html, with every version inlined, and opens that instead; its send button reads Copy for Mercury and puts the same message text on the clipboard for pasting into the composer.

Related pages

Workshop · Sessions · Using Mercury