peter/daybook
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
daybook/planning/framework_artifact_rendering.md

8.7 KiB
Raw Blame History

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:

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:

{
  "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:

{
  "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:

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:

@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

<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:

{
  "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?