html

NAME

html — working with HTML in SLICC: creation, serving, conversion, and scraping

DESCRIPTION

HTML is central to SLICC. Sprinkles are HTML. Reports, web apps, and interactive cards are HTML. The agent can create, serve, scrape, screenshot, and convert HTML using built-in shell commands. This page ties together the tools and workflows for working with HTML across the platform.

CREATING HTML

Write HTML files anywhere on the VFS using write_file or edit_file. Common use cases:

Single-page reports or documents
Multi-file web applications (HTML + CSS + JS)
Sprinkle panels (.shtml files for persistent UI)
Data visualizations, dashboards, and interactive tools

There are no restrictions on the HTML you write — full documents with <!DOCTYPE html>, fragments, or anything in between. External CDN scripts and stylesheets work when served in a browser tab.

SERVING

Two commands open HTML in the browser:

open <file.html>

Open a single file in a new browser tab via the preview service worker. Best for standalone pages, reports, or quick previews. Returns a targetId for subsequent playwright-cli interaction.
serve <directory>

Serve an entire directory (defaults to index.html). Use for multi-file apps where relative paths between HTML, CSS, and JS files must resolve correctly. The --project flag makes root-relative paths resolve against the served directory (useful for frameworks). The --entry flag overrides the default entry file.

Both commands open content via SLICC's preview service worker — no external server required. The resulting tab can be automated with playwright-cli.

SPRINKLES

Sprinkles are persistent UI panels built from .shtml files. They live in /shared/sprinkles/<name>/<name>.shtml and appear as sidebar tabs in the SLICC UI. Sprinkles have a bridge API for two-way communication with the agent — the agent pushes data via sprinkle send, and the user triggers actions via slicc.lick().

Sprinkles can be HTML fragments (using built-in .sprinkle-* CSS classes) or full documents with custom CSS and JavaScript. They are managed with the sprinkle shell command.

See man sprinkle for the command reference and man shtml for the file format.

INLINE WIDGETS

Agents can embed interactive HTML directly in chat messages using ```shtml fenced code blocks. These render as sandboxed iframes after streaming completes. Inline widgets have a minimal bridge (lick-only) and are ephemeral — they don't persist across sessions.

The sprinkle chat command is a blocking variant: it renders an inline card and waits for the user to click a button, returning the action as JSON. Use it for confirmations, choices, and quick interactive prompts during tool execution.

# Blocking confirmation card
sprinkle chat '<div class="sprinkle-action-card">
  <div class="sprinkle-action-card__header">Proceed?</div>
  <div class="sprinkle-action-card__actions">
    <button class="sprinkle-btn" data-action="no">No</button>
    <button class="sprinkle-btn sprinkle-btn--primary" data-action="yes">Yes</button>
  </div>
</div>'
# → returns {"action":"yes","data":{}}

SCRAPING

SLICC provides multiple approaches for extracting content from web pages:

playwright-cli snapshot --url <url>

Get the accessibility tree of a page — a structured text representation of all visible elements, roles, and text content. Best for understanding page structure and reading content without rendering.
playwright-cli eval --url <url> <expression>

Execute JavaScript in the page context. Use for targeted DOM queries like document.querySelector('.price').textContent or extracting structured data.
curl <url> | html-to-markdown

Fetch raw HTML and convert it to readable Markdown. Fast and simple — no browser required. Best for text-heavy pages where you need the content without interactivity.

SCREENSHOTS

Capture rendered pages as images for visual inspection:

# Screenshot a URL
playwright-cli screenshot --url https://example.com -o page.png

# Screenshot a served VFS page
serve my-app
playwright-cli screenshot --tab $targetId -o preview.png

# View the screenshot (returns image inline for agent vision)
open --view preview.png

The open --view flag returns the image as base64 so the agent can visually inspect rendered output — useful for verifying layouts, catching visual bugs, or reviewing designs.

CONVERSION

html-to-markdown converts HTML to Markdown. It handles headings, paragraphs, links, images, lists, code blocks, blockquotes, bold, italic, and horizontal rules.

# Convert a file
html-to-markdown page.html

# Convert from stdin
echo '<h1>Title</h1><p>Hello world</p>' | html-to-markdown

# Pipe from curl
curl -s https://example.com | html-to-markdown > content.md

Options:

-b, --bullet=CHAR — bullet character for unordered lists (-, +, or *)
-c, --code=FENCE — fence style for code blocks (``` or ~~~)
-r, --hr=STRING — string for horizontal rules (default: ---)
--heading-style=STYLE — atx (default, # headings) or setext (underlined)

EXAMPLES

Create and view a report

cat <<'EOF' > report.html
<!DOCTYPE html>
<html>
<head><title>Q4 Report</title>
<style>body{font-family:system-ui;max-width:800px;margin:2rem auto}</style>
</head>
<body>
  <h1>Q4 Results</h1>
  <p>Revenue grew 23% year-over-year.</p>
  <table><tr><th>Metric</th><th>Value</th></tr>
  <tr><td>Revenue</td><td>$4.2M</td></tr></table>
</body>
</html>
EOF
open report.html

Serve a multi-file web app

mkdir -p my-app
cat <<'EOF' > my-app/index.html
<!DOCTYPE html>
<html>
<head><link rel="stylesheet" href="style.css"></head>
<body>
  <div id="app"></div>
  <script src="app.js"></script>
</body>
</html>
EOF
# ... write style.css and app.js ...
serve my-app

Scrape a page and extract text

# Quick text extraction
curl -s https://example.com/article | html-to-markdown

# Structured extraction via DOM query
playwright-cli eval --url https://example.com \
  "JSON.stringify([...document.querySelectorAll('.item')].map(e => e.textContent))"

# Full accessibility tree
playwright-cli snapshot --url https://example.com

# In agent output, use a fenced shtml block:
```shtml
<div class="sprinkle-action-card">
  <div class="sprinkle-action-card__header">File uploaded</div>
  <div class="sprinkle-action-card__body">
    <span class="sprinkle-badge sprinkle-badge--positive">success</span>
    report.pdf (2.4 MB)
  </div>
  <div class="sprinkle-action-card__actions">
    <button class="sprinkle-btn sprinkle-btn--primary"
            onclick="slicc.lick('open-file')">Open</button>
  </div>
</div>
```

Screenshot and verify a page

playwright-cli screenshot --url https://example.com -o shot.png
open --view shot.png
# Agent can now visually inspect the rendered page