An ephemeral viewer: request, Core worker, escaped HTML · r1

Archived revision r1, recorded 2026-10-12T08:14:42.249Z. Current page: An ephemeral viewer: request, Core worker, escaped HTML.

A viewer, not a hosted document library

The existing web renderer solves a narrow problem: let a person inspect a submitted .gram file in a browser without requiring an account or storing a document collection. The API accepts a multipart POST containing source bytes or text, sends it through Core, and returns render data. The /view path returns a page. Since a later GET cannot recover an earlier submission, the browser must submit the file again when it asks for another revision. This is a distinct product shape from Vault, which owns identity and storage APIs.

The separation is important for both product expectations and privacy. There is no document ID registry, account session, sync service, database, or saved sharing link in this viewer contract. The server handles submitted bytes in request memory and forgets them after responding. Request logs are documented as a fixed schema without query, header, or body values. That reduces persistence surfaces, but it does not mean the server never receives the document: the user explicitly submits bytes to the service.

Request path

A browser or command-line client sends a multipart/form-data POST to /api/v1/render, /api/v1/search, or /view. A field chooses one input representation (file or source) and optional selectors such as revision, at, history, history_offset, or html. The service validates field cardinality and size, then invokes Core in a fresh worker process. The worker receives document input on stdin and returns structured results on stdout. Time, memory and concurrency limits bound the work; failures are explicit errors such as E_LIMIT, E_STALE, E_BUSY, or E_TIMEOUT.

Core history and replay supply the selected source and projections. The HTML renderer escapes document values, restricts links to safe schemes, and does not emit document-provided scripts, styles, or images. Unsupported blocks are retained as source with an unsupported-content indication. The browser keeps a selected file in tab memory and posts it again for state changes; the documented implementation avoids browser Storage APIs, service workers, and putting document text in the URL. A content security policy and no-store responses further constrain page behavior.

Example: render one selected historical state

For a local file named plan.gram, a client can submit file=@plan.gram and revision=2 to /api/v1/render; to ask for an HTML fragment, include html=1. A caller should handle a 422 Core history error, a 413 size cap, and temporary 503 worker saturation rather than claiming every source produces a complete view. The renderer may return summary metadata for old states while some detailed change projections are bounded by a source-byte budget. A rendered view is a projection, not a rewrite of the original document.

The brand checkout is not a second service claim

thegram-web-render-brand contains the same documented API contract and deployment README currently examined for thegram-web-render; its README also describes the branded viewer surface. This repository evidence does not establish an independent identity store, separately operating deployment, or different retention model. The existence of a brand-oriented fork is a source-code distinction, not proof of a second public product. Compare actual code, pinned Core and deployment configuration before describing it as an independent service.

Tradeoffs and limits

A stateless renderer avoids account friction and server-side document libraries, but it requires sending the bytes on every interaction and does not create a durable share URL. HTML output is safe by default and may omit unsupported rich content or show raw source; this is not a full fidelity promise for every format construct. Resource caps protect service availability but mean a large file or busy worker pool can fail. Public access and ephemeral handling do not equal confidentiality guarantees beyond the described processing and logging boundary. A user handling sensitive data should decide whether the service is appropriate before submitting it.

Read docs/api.md for the exact multipart contract and error codes, README.md for browser behavior and fidelity, and deploy/README.md for deployment controls recorded by that checkout. Do not infer current deployment status from source configuration alone.

Sources

Implementation claims use both renderer checkouts' README, API and deployment documentation.

Source

Source: Renderer README and browser flow

Reference: https://github.com/clab-one/thegram-web-render/blob/main/README.md

Source: Renderer HTTP API contract

Reference: https://github.com/clab-one/thegram-web-render/blob/main/docs/api.md

Source: Renderer deployment configuration documentation

Reference: https://github.com/clab-one/thegram-web-render/blob/main/deploy/README.md

Source: Branded renderer README

Reference: https://github.com/clab-one/thegram-web-render-brand/blob/main/README.md

Source: Branded renderer API contract

Reference: https://github.com/clab-one/thegram-web-render-brand/blob/main/docs/api.md

Source: Branded renderer deployment documentation

Reference: https://github.com/clab-one/thegram-web-render-brand/blob/main/deploy/README.md

Knowledge

Knowledge: Renderer processes submitted documents ephemerally

The request path uses worker processes and in-memory document processing without a persistent document store in the documented contract.

Reference: → Supports: A bounded worker turns Core output into HTML

Knowledge: A bounded worker turns Core output into HTML

Fresh workers, resource limits, escaping and restricted browser behavior constrain untrusted document rendering.

Reference: → Supports: The branded checkout is not proof of a separate service

Knowledge: The branded checkout is not proof of a separate service

Similar API and deployment docs describe a checkout distinction; operational independence requires separate evidence.

Reference: → Supports: Renderer processes submitted documents ephemerally

Knowledge: A stateless viewer still receives document bytes

No storage does not mean no transmission; a user must decide whether the chosen document is appropriate to submit.

Reference: → Supports: Renderer processes submitted documents ephemerally

Source and renderer evidence

Canonical source SHA-256

7bb5a07a799d92c53a11d0a2ffba01002978c85e89fc69b9911b1b5d13d4a010

Selected revision

r1 · sha256:64c03e3b88acb4c02fb6abc0488f2e8c136f2ce419790d66948b345616adbe57

Local renderer

configured local Thegram renderer · API thegram-web-render/1

Core source

git+https://github.com/clab-one/thegram-format.git?rev=b16489e1d0d77d38f82d2f61776524737aa31557#b16489e1d0d77d38f82d2f61776524737aa31557

Canonical source: 1.gram