shtukbase
Format
FormatThe rules of the file formatReleasesDownload for Mac
Download for Mac
Format
Contents

HTML files

A bundle may hold HTML files anywhere, the same way it holds images: they are content, kept byte-for-byte. The product views HTML and never edits it — an HTML file is made in other tools and shown here. Design mockups, generated reports, small self-contained apps and saved pages all arrive this way.

Naming and metadata

The file needs nothing to work. Its name in the product is the <title> element; without one, the file name without its extension. A person never sees .html or a path.

Optional product metadata is one sb comment in the <head> — the same carrier Markdown blocks use, with the same YAML keys frontmatter would carry:

<head>
<title>The board — an infinite canvas among the views</title>
<!--sb
icon: 🗂️
view: immersive
-->

The comment is written by the author, read by the product, and never rewritten — the view-only rule keeps every byte the author's. A companion same-stem .md file for metadata was considered and rejected: two files for one thing drift apart, and on GitHub an HTML file shows as source anyway, so a comment costs nothing.

Viewing

Two view modes, chosen by the view key:

  1. page (default) — the workspace chrome stays: breadcrumbs and the top bar above, the HTML filling the content area below in a sandboxed frame.
  2. immersive — the HTML takes the whole content area; a thin, faint breadcrumb strip floats over the top edge and fades until hovered, so a person can always tell where they are and leave.

The product never restyles or "fixes" the document — what the author made is what everyone sees, in any theme. The one thing added at serving time is one appended navigation note that makes links leave the document correctly; the file on disk is never touched.

A marked link embeds an HTML file inside a page the same way it shows any file: the link is the block, settings ride an invisible comment.

[Board view](design/board-view.html)<!--sb height="480"-->

Files around the file

Relative references (./style.css, img/logo.png) resolve inside the containing folder and below it — a multi-file app is a folder with an .html entry and its assets beside it. The folder itself stays an ordinary folder; links point at the .html file, not the folder.

There is no reserved apps/ folder. A folder of HTML files is just a folder, and a sidebar section for it is the existing mechanism: a marked folder link shows what the folder holds.

Boundaries

  • Viewing is the default; light editing is deliberate. No codec touches HTML — viewed bytes never move. A person may enter a light edit mode: text in place via the browser's designMode, resize and move via Moveable handles (decision). Saving rewrites the file's source formatting, and the editor says so plainly. Open in editor stays beside it for real work on the source.
  • Sandboxed, scripts run. The frame has no access to the product's session, cookies or other files outside its folder. Scripts inside it run; one settings key turns execution off (decision).
  • Relative links to Markdown navigate. A link from the HTML to a .md file in the bundle opens that page in the product; external links open the browser.
  • Search sees the title. The name enters the derived index like any page's. Body text extraction is optional and derived, never authority.

Decisions to make

Open: HTML-2. Does the sandbox ever get a read-only API into the workspace (a report that renders live rows)? Out of scope for the first cut; if it comes, it is a declared capability in the sb comment, never ambient.

Open: HTML-3. May an HTML app opt into the product's look by reading --ds-* custom properties injected as CSS variables? Opt-in only — the default stays untouched bytes.

Open: HTML-1. Do scripts run? Decided 2026-08-15: they run, with a settings switch — the decision.

Open: HTML-4. Is view-only final? Decided 2026-08-15, twice: viewing is the default, and the light editor arrived as its own decision the same day — designMode for text, Moveable for arrangement.