daybook/planning/framework_artifact_rendering.md

# Framework-Aware Artifact Rendering Ideas

Daybook currently supports a useful split between server-owned rendering and agent-owned rendering:

- `markdown`: agent sends Markdown; Daybook renders and wraps it.
- `html_fragment`: agent sends body-only HTML; Daybook owns the shell and theme CSS.
- `html_full`: agent sends the complete HTML document and owns all presentation.
- `deck`: agent sends slide sections; Daybook wraps them as a simple deck.

The next design question is how to let agents use established CSS/component frameworks without making every artifact depend on arbitrary external assets or custom page shells.

## Core Principle

Agents should publish content, not storage paths or app internals.

For framework-aware artifacts, the preferred model is:

```text
Agent sends framework-compatible body markup
Daybook selects/owns the framework CSS and page shell
Browser renders a consistent artifact preview
```

This preserves the Daybook principle while giving LLMs a known design vocabulary.

## Current Option: `html_full`

Agents can already use any framework by posting `html_full` and including the framework assets themselves.

Example with Bootstrap CDN:

```json
{
  "persona": "athena",
  "kind": "html_full",
  "title": "Bootstrap Report",
  "content": "<!doctype html><html lang=\"en\"><head><meta charset=\"utf-8\"><meta name=\"viewport\" content=\"width=device-width, initial-scale=1\"><title>Bootstrap Report</title><link href=\"https://cdn.jsdelivr.net/npm/bootstrap@5.3.3/dist/css/bootstrap.min.css\" rel=\"stylesheet\"></head><body><main class=\"container py-4\"><div class=\"alert alert-success\">Bootstrap artifact rendered by Daybook.</div></main></body></html>"
}
```

Pros:

- Works today.
- Gives the agent total layout control.
- Supports any CSS/JS framework.

Cons:

- CDN dependencies may fail offline.
- External assets can change or disappear.
- Agents must generate a correct full HTML document.
- Visual consistency across artifacts is weaker.
- Security/trust boundaries are looser if arbitrary scripts are included.

## Preferred Future Option: Framework Themes For `html_fragment`

Add Daybook-owned themes that include vendored framework CSS.

Example payload:

```json
{
  "persona": "athena",
  "kind": "html_fragment",
  "theme": "bootstrap",
  "title": "Run Summary",
  "content": "<main class=\"container py-4\"><div class=\"alert alert-success\">Run complete</div></main>"
}
```

In this model:

- Agent sends body-only framework-compatible markup.
- Daybook wraps it in the HTML shell.
- Daybook links local framework CSS from `static/vendor/...` or `static/themes/...`.
- Daybook remains responsible for stable rendering.

Pros:

- Keeps artifacts self-hosted and predictable.
- Lets agents use known class vocabularies.
- Avoids requiring every agent to write `<head>` boilerplate.
- Preserves the current `html_fragment` contract.

Cons:

- Daybook must vendor and maintain selected frameworks.
- Agents must know which theme/framework is selected.
- Some frameworks expect JavaScript or build tooling.

## Candidate Frameworks

| Framework | Best for | Fit for Daybook |
|---|---|---|
| Bootstrap | Reports, cards, grids, alerts, forms | Strong first candidate. Familiar to LLMs and humans. |
| Pico CSS | Clean semantic documents | Excellent for low-class, readable reports. |
| Bulma | CSS-only layouts/components | Good middle ground; no JS required. |
| Tufte CSS | Research notes, essays, analytical reports | Good specialized report style. |
| Water.css | Simple semantic HTML styling | Good for zero-effort readable HTML. |
| MVP.css | Semantic HTML documents | Good for basic generated reports. |
| Sakura.css | Minimal text-heavy documents | Good for simple readable pages. |
| Tailwind CSS | Highly custom layouts | Powerful but less ideal without a build step. CDN possible for experiments. |
| DaisyUI | Tailwind components | Useful but depends on Tailwind. Better later. |
| Flowbite | Tailwind components | Useful but heavier and Tailwind-dependent. |
| UIKit | Polished dashboards/docs | Possible but less common. |
| Shoelace | Web components | Rich components, but requires JS custom elements. Better later. |
| Reveal.js | Real slide decks | Strong future replacement/upgrade for current `deck`. |
| Mermaid | Diagrams | Not CSS, but important for diagram artifacts. |
| Prism.js / Highlight.js | Code artifacts | Needed for future code renderer. |
| Tabulator / DataTables | CSV/table artifacts | Needed for future table renderer. |
| JSON viewer libraries | JSON artifacts | Needed for future structured JSON renderer. |

## Recommended Initial Set

Start small with CSS-only or mostly CSS-only frameworks:

1. `bootstrap`
2. `pico`
3. `bulma`
4. `tufte`

Reasons:

- No build step required.
- Easy for LLMs to emit usable classes/semantic HTML.
- Useful for the most common artifact types: reports, cards, summaries, dashboards, and notes.
- Can be vendored locally and served through Django static files.

Defer heavier or JS-dependent frameworks until there is a concrete artifact need.

## Theme Naming Idea

Existing themes:

- `report`
- `tasks`
- `deck`
- `base`

Potential additions:

- `bootstrap`
- `pico`
- `bulma`
- `tufte`
- `water`

Agents would specify the theme in the existing `theme` field for `html_fragment` and `markdown` where appropriate.

## Storage/Vendoring Idea

Use local static assets rather than CDN links:

```text
static/
  vendor/
    bootstrap/
      bootstrap.min.css
    bulma/
      bulma.min.css
    pico/
      pico.min.css
    tufte/
      tufte.min.css
  themes/
    bootstrap.css
    bulma.css
    pico.css
    tufte.css
```

Theme files can either be the vendored framework directly or thin wrappers that import vendor CSS and add Daybook-specific print/preview fixes.

Example:

```css
@import url("/static/vendor/bootstrap/bootstrap.min.css");

body.artifact {
  background: #f8f9fa;
}
```

## CDN Policy

CDN links are acceptable for quick experiments using `html_full`, but should not be the default for reliable self-hosted deployments.

Recommended policy:

- MVP experimentation: allow `html_full` with CDN links.
- Durable/self-hosted rendering: prefer vendored local CSS themes.
- Deployment docs should warn that CDN-dependent artifacts may not render offline.

## Security Notes

Framework CSS is relatively safe. Framework JavaScript needs more care.

Riskier artifact types:

- `html_full` with arbitrary scripts.
- JS component frameworks.
- Web components loaded from CDNs.

Current MVP assumes trusted local/self-hosted use. If Daybook later supports untrusted artifact authors or sharing, it should revisit sandboxing and CSP policies.

## Relationship To Future Renderers

Framework themes are separate from future dedicated renderers.

Future renderers likely need their own artifact kinds:

- `json`: collapsible JSON viewer, raw source preserved.
- `csv`: searchable/sortable table, raw CSV preserved.
- `code`: syntax-highlighted code, raw source preserved.
- `diagram`: Mermaid/Graphviz/PlantUML source rendered to SVG/HTML, raw source preserved.
- `audio`: browser audio player.
- `video`: browser video player.

These should use established libraries rather than custom viewers:

- JSON viewer library for JSON.
- Tabulator or DataTables for CSV/table artifacts.
- Prism.js or Highlight.js for code.
- Mermaid for Mermaid diagrams.
- Native `<audio controls>` and `<video controls>` for media.

## Recommended Implementation Order

1. Keep `html_full` as the escape hatch for total agent control.
2. Add one vendored CSS framework theme first, probably Bootstrap.
3. Document exact usage for `theme=bootstrap` with `html_fragment`.
4. Add a sample Bootstrap artifact.
5. Add Pico CSS as a low-complexity report/document theme.
6. Add Bulma or Tufte only if real artifacts need them.
7. Later, add dedicated renderers for JSON, CSV, code, and diagrams.

## Example Bootstrap Fragment

```html
<main class="container py-4">
  <div class="row g-3">
    <section class="col-md-8">
      <div class="card">
        <div class="card-body">
          <h1 class="card-title">Run Summary</h1>
          <p class="card-text">The agent completed all checks successfully.</p>
        </div>
      </div>
    </section>
    <aside class="col-md-4">
      <div class="alert alert-success">Status: green</div>
    </aside>
  </div>
</main>
```

Payload:

```json
{
  "persona": "athena",
  "kind": "html_fragment",
  "theme": "bootstrap",
  "title": "Bootstrap Run Summary",
  "content": "<main class=\"container py-4\">...</main>"
}
```

## Open Questions

- Should framework themes be available for `markdown`, or only `html_fragment`?
- Should Daybook allow framework JavaScript, or CSS only?
- Should `html_full` artifacts be sandboxed more strictly in iframes later?
- Should agents be able to query `/api/capabilities` for supported themes?
- Should themes be exposed as a first-class API field in capabilities?