Icons, previews, and exports

The editor, Finder artwork, and exported document should feel like the same object. They can have different layouts while reading the same saved data and theme.

Declare capture views

Import your components and register view, optional export, and optional icon in defineSlop. The CLI generates the entry from those roles; filenames are up to you. Export receives mode: "preview" | "export":

<main class="note-editor">
  <input aria-label="Title" use:bindText={doc.fields.title} />
  <button onclick={addItem}>Add item</button>
</main>

An export component (here Export.svelte, registered as export):

<script lang="ts">
  import doc from "./schema";
</script>
<article class="note-export">
  <h1>{doc.current.title}</h1>
  <ul>{#each doc.current.tasks as task (task.$id)}<li>{task.text}</li>{/each}</ul>
</article>

Icon.svelte:

<script lang="ts">
  import doc from "./schema";
</script>
<div class="note-icon">{doc.current.tasks.length}</div>

Use the app’s existing document facade in capture components. Captures render saved data in a fresh read-only page. If an export should show a selected tab or report, save that choice in the document; transient editor state is not carried into the capture. Without an export view, a fresh rendering of your view with its default local state is the fallback. An export or icon component that throws fails that capture without changing the live editor. A later attempt gets a fresh rendering page.

Design an icon at 512 × 512

The native icon canvas is 512 × 512, and the host centers the artwork in it. Give the design breathing room; for example, a tile around 456 pixels wide. Prefer a recognizable silhouette and a few strong marks over tiny text or a screenshot of every control. The icon may summarize current content. Use the same theme colors as the editor, so a person’s palette carries into the icon.

The artwork can be rectangular or another shape; only the canvas must be square. Size the artwork to fit within the canvas, including its shadows. For example, a square tile can use:

.note-icon {
  width: 456px;
  height: 456px;
  display: grid;
  place-items: center;
  background: var(--slop-accent);
}

An absent icon is optional. If you declare an icon and it throws, capture fails rather than silently hiding the broken view.

Make exports readable

Give export content natural height and normal document flow. Remove selection handles, menus, empty inputs, hover controls, and scroll containers. With an export view, the editor is never captured. If no dedicated export view is declared, a fresh App rendering saved data is the fallback: mark editing-only elements with data-slop-export="hide", and native text inputs render as wrapping text. Dedicated exports and icons ignore the window’s shape mask.

The host sets html[data-slop-capture="static"] during capture. Use it for deliberate static layout adjustments:

html[data-slop-capture="static"] .note-export {
  height: auto;
  overflow: visible;
}

Export from the host or CLI

Use the native hover toolbar, File menu, or:

bunx hitslop export My.slop --format png --output My.png
bunx hitslop export My.slop --format pdf --output My.pdf

An export never replaces the document it renders. For an open document, hitSlop sends unsent text, saves and copies the document before rendering that copy in a fresh page. Closed documents also render from saved state. Both use default local UI state and the saved theme. The open editor is not used as the rendering workspace.

The editor barrier lasts through saving and copying; rendering then proceeds independently. Capture waits for fonts, visible images and a stable layout in the fresh page. The live editor’s focus, selection and scroll remain unchanged. PNG renders at 2×, up to 16,384 pixels per side and 24 megapixels. PDF keeps searchable text and vectors on one continuous page, scaled to at most 14,400 points per side.

Completed captures publish atomically before their deadline. If the acknowledgement is lost, inspect the destination before retrying.

Quick Look and Finder artwork

Registration, or slop build --artwork native, captures the initial preview and, when declared, icon into the template; files you put in artwork/preview.png and artwork/icon.png are used instead (see Finder artwork). Closing a writable document refreshes both images from its saved contents and theme and stores them in the document. Quick Look shows the preview when you press Space, and Finder, Mail and the share sheet show the icon, including on a Mac that received the file. A document without artwork shows hitSlop’s document icon. Recents follows the document too. Templates keep their initial artwork. Failed captures retain the previous images. Artwork is a derived preview, not document state.

Test normal and narrow windows, empty and populated data, themed output, default local views, saved view choices, and exports from open and closed documents. Check both PNG and PDF; a good editor screenshot alone does not prove a good exported layout.