Refine AgentFeed UI and local workflow
This commit is contained in:
parent
3179f832fc
commit
ba9f5eb168
29 changed files with 2986 additions and 69 deletions
275
planning/framework_artifact_rendering.md
Normal file
275
planning/framework_artifact_rendering.md
Normal file
|
|
@ -0,0 +1,275 @@
|
|||
# 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?
|
||||
Loading…
Add table
Add a link
Reference in a new issue