pagerite/docs/messages.md

Contact messages

Visitor→admin messaging built into the site: a {contact: Label} directive in article Markdown renders a button that opens a chat-style panel; messages are stored in the kanta database and answered from the admin inbox on /_a. Visitors are anonymous — a localStorage session token identifies their thread — and everything realtime rides the two existing WebSockets; there is no REST polling anywhere.

• pagerite/messages.py — the feature's core: the strict message renderer, thread store ops, wire payloads, both socket protocols and the /_contact/files upload route.
• pagerite/data.py — Data.contact (ContactThread/ContactMessage).
• pagerite/tracking.py — the sockets the protocol rides (see below).
• pagerite/views.py — the {contact:} directive (_contact_tag) and the on-demand bundle's asset config.
• frontend/src/contact-main.js + ContactPanel.vue — the visitor panel, imported on demand by pagerite.js on trigger clicks.
• frontend/src/Composer.vue + richtext.js — the shared composer and its DOM→Markdown serializer.
• frontend/src/MessagesView.vue — the admin inbox (the messages tab of AnalyticsView.vue on /_a).

Trigger

A lone {contact: Label} line in article Markdown (the block-directive machinery of markdown.py) renders <button class="contact-trigger">Label</button> ("Contact us" when the label is empty). pagerite.js click-delegates these buttons and lazy-loads the contact bundle; the editor preview renders the same button inert, and description/card mining resolves the tag to nothing. The label lives in the chunk, so translated pages localize it like any other text. Feeds render the tag as its literal source (no directive context).

Visitor side

The token is crypto.randomUUID() in localStorage (pagerite-contact-token), generated on first use; the server stores only its blake3 hash as the thread key. Pages are shared/cached renders, so the thread UI is entirely client-side. A per-browser "seen" timestamp (pagerite-contact-seen) drives the unread dot on trigger buttons when an admin reply arrives while the panel is closed.

The panel rides the public /_ws activity socket via a bridge in pagerite.js (register/send, sharing its queue and reconnect pacing — no extra connection). Frames to the server:

• {token} — register/resync; the current thread state is pushed back. pagerite.js re-sends this on every socket (re)connect, which is the resync mechanism (the socket idle-closes after 5 min and reconnects on activity).
• {token, msg, fr} — append a message; msg is the Markdown-subset source, fr the page path it was sent from (stored for context).

Frames from the server: {type: "thread", id, created, unread, messages: [{id, t, admin, html, page}]} — a full thread snapshot (replace/upsert by id), or {type: "contact-error", detail}.

Admin side

Admins watch the inbox as the messages tab on /_a, served by the existing /_api/ws/analytics socket (admin-gated like all of /_api). Analytics payloads keep their type-less snapshot shape; messaging frames always carry a type field, and that is how the client tells them apart. On connect the server sends {type: "threads", threads: [...]} (100 most recently active); new messages and replies push single-thread updates. Admin→server frames: {type: "reply", id, text} and {type: "read", id}. Replies are authored with the SSO remote-user name and mark the thread read; unread on a thread means its last message is the visitor's and newer than the admin's last read.

Message format and the XSS model

Bodies are a Markdown subset — emphasis, links, lists, code, plus /_f/ image and file references — serialized client-side from a constrained contenteditable composer (plain-text paste only; formatting via toolbar; uploads insert image/attachment-chip nodes).

No user HTML is ever rendered or sanitized. Sanitizing arbitrary HTML is unwinnable, so the design never attempts it: the composer serializes to text, and the server re-renders that text with a strict MarkdownIt instance (messages.py): html=False (the page renderer's trusted-author raw passthrough does not apply here), no plugins. Every byte of the stored html is markdown-it output from the constrained grammar. markdown-it also validates link protocols (javascript: & co. never become hrefs); the link rule adds rel="nofollow ugc noopener" + target="_blank" (and download + a chip class for /_f/ attachment links); images are restricted to /_f/ store names, anything else collapses to its alt text. Both panels inject this server-rendered HTML verbatim (v-html) — the one injection point, fed only by the strict renderer.

Uploads

PUT /_contact/files/{name} (public, like the messaging socket) stores panel uploads in the content-addressed file store: raster images through the usual AVIF/WebP/JPEG derivative pipeline, anything else as-is, rendering as a download chip in the thread. The one exclusion is script carriers (svg/html/xhtml/js/xml…) — an attachment URL can always be opened directly in the site's origin, where such a file would execute. Gates today: a session-shaped x-contact-token header, a 20 MB size cap and the type blocklist. Admin uploads from the same composer go to the admin-gated /_api/files instead. Files uploaded but never referenced by a sent message currently linger (no orphan GC).

Storage

Data.contact: dict[bytes, ContactThread] in the kanta database, keyed by the 12-byte blake3 hash of the session token (never the token itself). A thread is created, admin_read, and messages: dict[str, ContactMessage] keyed by a sortable timestamp-random id (dict-keyed, so a save's database diff touches only the appended message). Each message stores t, the Markdown source md, its strict rendering html, admin ("" = visitor, else the SSO name) and page. Appends are single transactions (contact / contact:reply / contact:read).

Limits and deliberate gaps (MVP)

• Message source ≤ 8000 chars; uploads ≤ 20 MB; payloads cap at 100 threads × last 200 messages.
• No proof-of-work yet: the send and upload paths are the two seams where the PoW stamp plugs in (challenge on token registration, verify on msg/upload; one stamp may cover several messages).
• No thread moderation (delete/block), no orphan-upload GC, panel strings are English-only, and the admin inbox lists threads by token-hash prefix rather than enriched visitor identity.