RFC: Artifacts next steps: formats, templates, editing and experience

This is a design RFC with no code change to make yet. Start with docs/artifacts-tech-design.md, which the issue links, and with the open questions in the issue body. Done means the open questions are answered in discussion and each agreed track is split into its own issue. Research on the listed candidate editors is also open work, but it needs maintainer direction before a newcomer should start.

Summary

v0.8.0 shipped Artifacts, Design mode, the canvas and website clone (#229). This RFC collects what should come next, groups it into tracks, orders the tracks by what depends on what, and lists the questions to settle before anything is built. Nothing here is decided, and no research has been done yet.

Where we are

The agent keeps the pages, prototypes and canvases it makes as folders in the project's dc_artifacts/, each with an artifact.json. The Artifacts page lists them across projects, the Design page offers a library of 60 templates and 156 design systems, and /design interviews the user, offers templates in a card in the chat, and builds. The design and every deviation from it are in artifacts-tech-design.md.

What the current code does, since it shapes the work:

• Kinds. Only page and canvas. Slides were taken out on purpose, with notes on why they were not good enough: deck was only a label, the print-to-PDF export produced one page, and the templates page their slides in different ways (notes).
• Export. PDF, PNG and standalone HTML (BROWSER_EXPORT_FORMATS); a canvas exports one board at a time.
• History. dc_artifacts/ is excluded from git (ensureArtifactsDirExcluded). What exists is the session's file history: SDK file checkpointing with up to 100 snapshots, only for files changed with Write and Edit (enabled here, cap). It belongs to the session, not to the artifact. Board positions are written back by the sidecar (updateBoard), not through those tools.
• Templates and design systems. Templates carry params and acceptsDesignSystem (type) and ship with the app. A design system is chosen when the artifact is created and stored in the manifest as designSystem (field); changing it later is a manual edit. Ten templates load the Tailwind CDN at runtime and a few load Google Fonts.
• Page and app talk to each other only on the canvas, through JSON in console-message (listener).
• Desktop only. The Artifacts page and viewer need the Electron webview, so the Artifacts entry is not offered in the H5 view (gate).
• Checks. ArtifactCheck verifies files, references, the design system link and board files (checkArtifact); it does not look at layout or accessibility.
• Thumbnails are captured when an artifact is opened in the viewer (hook call), so a new artifact has none until someone opens it.
• Pointing at things. The built-in browser can pick an element or select text and add it to the chat (#189, selectionProbe.ts). The artifact viewer does not use it yet.
• Context cost. Checking a page means taking screenshots, and a screenshot-heavy session makes the context indicator show several times the real usage (#230).

Goals and non-goals

Goals: more kinds of artifacts people ask for; richer templates that can be reused; a way to change an artifact that fits a product where the agent writes; a better everyday experience.

Non-goals: choosing one editor in this RFC; rebuilding an office suite; changing the artifact folder model without a concrete reason; a schedule.

The central question: HTML first, or an engine per format?

• HTML first, then export. What we do today. Slides are a page per slide with a presentation mode and a PPTX export; dashboards and documents are pages. The format stays one thing, which the agent is good at. The cost is that export to PPTX, DOCX and XLSX has a ceiling on fidelity.
• A native engine per format. A spreadsheet needs formulas, selections and cells, which means building or embedding a spreadsheet engine, and that is tied to the editor question.

Proposal: slides, dashboards and documents stay HTML first. Spreadsheets are the dividing line and get their own research, so they are not decided together with the others. How slides relate to the canvas (boards are pages on one surface; slides are pages in sequence) has to be settled in the slides track.

Tracks

A. Foundations

Things the other tracks lean on.

• History per artifact. Today history is the session's file history (see above). The question is whether an artifact needs its own history, visible from the artifact and independent of the session, covering Bash and sidecar writes too, and what a user does with it (undo, compare, restore). An editor is hard to build without answers here.
• A general channel between an artifact and the agent. Generalise the canvas channel so a button or form in an artifact can send a message to the session or trigger a generation. This matters for dashboards, forms and sheets. Its security model (a whitelist of messages) is the main question, since artifacts run arbitrary HTML and scripts.
• Data. A dashboard needs data, not only a page. An artifact could carry data files (CSV, JSON) or declare a source, and be refreshed by the agent or by a script. The app already has scheduled tasks, so "regenerate this report every morning" could be a first-class use. Open: where the data lives, how it refreshes, and what an artifact may read.

B. Formats

• Slides. Its own entry, as the notes recommend, with a page-per-slide structure the app understands, an outline or sorter, a presentation mode, and a PPTX export.
• Dashboards (depends on the data and channel work in A), documents, and spreadsheets (research first, see above).

C. Editing

Two layers, in this order:

1. Point and tell. Select an element in the artifact viewer and tell the agent what to change. The building blocks exist in the built-in browser; this layer is far cheaper than an editor and fits a product where the agent writes.
2. Direct editing. Moving, resizing and restyling by hand, then a fuller editor per format. This is the large part and needs research into mature products first (see below).

D. Reuse

• Change the design system of an existing artifact.
• Save an artifact as a template, with its parameters; import and export templates so the community can share them.
• A project-level brand kit (a design system plus assets).
• Discovery as the library grows: search is by title, description and tags today.
• Make templates self-contained (local fonts and scripts instead of the CDN), together with a local asset library.

E. Reach

• Sharing and publishing: an archive of the folder, a static page, a link.
• View artifacts in H5 (the viewer must stop depending on the Electron webview there).
• Export fidelity for PPTX, DOCX and XLSX.

F. Experience and quality

• Thumbnails generated when an artifact is written, not when it is opened.
• Organising many artifacts: filters by project, template and design system; folders or tags.
• Variants: ask for several options and lay them out on a canvas to compare and pick.
• Deeper checks the agent can run on its own: several viewport sizes, contrast and basic accessibility, consistency with the design system's tokens.
• The cost of the screenshot loop: a screenshot budget, downscaling, and looking only at what changed (related to #230).

Order by dependency

A comes first, because history is needed before editing and the channel and data are needed before dashboards and sheets. B (slides), D and E (sharing) do not wait for A. C's first layer can start as soon as the artifact viewer can select an element. E's export fidelity depends on B. F is independent and can be taken any time.

Open questions

1. Does an artifact get its own history, or is the session's file history enough with a view on top of it?
2. What is the security model for the artifact-to-agent channel, and what may an artifact read when it has data sources?
3. Do slides share the canvas's board structure or get their own?
4. Do spreadsheets use an embedded engine, and which formats must they round-trip?
5. How far does "point and tell" go before direct editing is needed?
6. Who owns user-made templates: the project, the user, or a shared library?
7. How do we keep templates offline-capable without the app growing much larger?

Research (not started)

The projects below are candidates I know of, listed so the research has a starting point. They have not been checked for licence, size or fit.

• Canvas: tldraw, Excalidraw.
• Page editing: GrapesJS, Puck, Craft.js, Penpot (closer to a design tool).
• Documents: TipTap, Lexical.
• Spreadsheets: Univer, Handsontable.
• Slides: reveal.js, Slidev.
• Dashboards: Evidence, Observable Plot.

Criteria to evaluate them against: licence, bundle size, whether it works offline, whether an agent can edit its file format directly, accessibility, how actively it is maintained, and how it fits the HTML-first decision above.

How to take part

Each track can be taken on its own. Comments on the open questions are the most useful input now. Research notes on any of the candidates are welcome. Once the direction is agreed, each track becomes its own issue.