> Tillcast is live: the API at https://api.tillcast.com/v1 and the dashboard at https://dashboard.tillcast.com. A key prints on real printers, so do not call the API unless asked. A job carries its receipt as "document", an array of blocks (the recommended way), or as "receiptline", ReceiptLine text, exactly one of the two: read https://docs.tillcast.com/create-a-print-job.md and https://docs.tillcast.com/concepts/documents.md before you write a job body. Do not code against what does not exist yet: webhooks, a template language, stored templates (a job has no template field), OAuth connections and connectors for Make, Zapier and n8n, and OAuth sign-in for the MCP server. SDKs for TypeScript (@tillcast/sdk, version 0.2.0 or later for blocks) and Python (tillcast) exist as pre-1.0 versions. To show a receipt in a web page without printing, there are the npm packages @tillcast/preview and @tillcast/html-render (0.x, no API key, no call to Tillcast to draw): read https://docs.tillcast.com/preview-a-receipt.md. The docs are the source of truth: check the index https://docs.tillcast.com/llms.txt and https://docs.tillcast.com/roadmap.md before you code against anything. For clean Markdown of any page, append .md to the page URL. The Tillcast MCP server is live at https://api.tillcast.com/mcp and takes an API key as a bearer token (setup: https://docs.tillcast.com/connect-an-ai-assistant.md). It acts on the live account and its tools print on real paper, so do not connect to it or call its tools unless the owner asked you to. The MCP server at https://docs.tillcast.com/_mcp/server is a different one: it only searches these docs and cannot call the Tillcast API.

# Preview a receipt in your app

> Show a Tillcast receipt in a web page: install @tillcast/preview, give it blocks or ReceiptLine text, and it draws the receipt as it would print on 80 mm paper, in the browser, with no call to Tillcast.

> **An early release**
>
> Both packages are `0.x`: the API can change between minor versions, so pin the version you test. They are licensed under Apache-2.0.

`@tillcast/preview` draws a receipt in your page. It is a React component and a function for any other page. It takes the same **blocks** as the `document` of a [print job](/concepts/documents), or ReceiptLine text, and draws what a printer would print on 80 mm paper (48 characters a line) or 58 mm paper.

It runs in the browser, with the renderer that Tillcast uses, compiled to WebAssembly. It needs **no API key** and makes **no call to Tillcast to draw**: the renderer is a file that your own page serves, fetched once. It stores nothing and sends nothing. It does not print. The picture is not the printed receipt: the font and the paper differ, and the printer's own output is the only exact one. To print, [create a print job](/create-a-print-job).

There is no preview call in the REST API. The MCP server has `preview_document`, which draws a receipt as text for an assistant that its owner connected. To show a receipt in your own page or code, or to draw one without an MCP client, use these packages.

## Install

```bash
npm install @tillcast/preview
```

The renderer, `@tillcast/html-render`, is a dependency and comes with it. You need React 19 for the component only, and a bundler or a server that serves a `.wasm` file. Recent versions of Vite and Next.js need no configuration.

## Draw a receipt

#### React

```tsx
import { ReceiptPreview, type Block } from "@tillcast/preview";

const blocks: Block[] = [
  { type: "text", text: "Harbour Cafe", align: "center", bold: true, size: 2 },
  { type: "table", columns: ["*", { width: 9, align: "right" }], rows: [["Flat white", "3.40"], ["Lemon cake", "4.20"]] },
];

export function Order() {
  return <ReceiptPreview source={{ blocks }} label="Receipt 1042" />;
}
```

#### Any other page

```ts
import { mountReceiptPreview } from "@tillcast/preview/mount";

const view = mountReceiptPreview(document.getElementById("receipt")!, { source: { receiptline: "Tea|2.10" } });
view.update({ source: { receiptline: "Coffee|3.00" } }); // draws the new source
view.destroy(); // removes what it made
```

The preview never throws. A source it cannot draw, or a page whose policy blocks WebAssembly, is a visible message in the preview and a call of `onError`, never a blank box.

## Preview and Content Security Policy

The preview draws with WebAssembly. A page that sends a `Content-Security-Policy` blocks WebAssembly unless the policy allows it, so a strict page needs two things, and the second is the one that is forgotten:

* **`'wasm-unsafe-eval'` in `script-src`** (or in `default-src`, which `script-src` falls back to). The word lets the browser compile WebAssembly and nothing else: it does not allow `eval`, `new Function` or an inline script, and it is not `'unsafe-eval'`.
* **`connect-src 'self'`**, or the origin that serves the `.wasm` file. The file is fetched once, from your own origin and never from Tillcast. Under `default-src 'none'` the browser refuses the fetch.

A QR code, a barcode or an image on a receipt is a `data:` picture, so `img-src` needs `data:` as well.

Change the `script-src` and `connect-src` your policy already has: a browser ignores a second directive of the same name. A page that uses a nonce and `'strict-dynamic'` keeps both and adds the word:

```text
script-src 'nonce-{random}' 'strict-dynamic' 'wasm-unsafe-eval'
```

Whether your page's policy changes is your decision. If it should not, draw the receipt on your own server instead, as shown below.

### In the browser

A page with a strict policy. This policy works the same in a `<meta>` tag as in a header:

```html
<!doctype html>
<meta http-equiv="Content-Security-Policy"
      content="default-src 'none'; script-src 'self' 'wasm-unsafe-eval'; connect-src 'self'; img-src 'self' data:">
<div id="receipt"></div>
<script type="module" src="/assets/main.js"></script>
```

```ts
// main.ts, built by your bundler to /assets/main.js
import { mountReceiptPreview, type Block } from "@tillcast/preview/mount";

const blocks: Block[] = [
  { type: "text", text: "Harbour Cafe", align: "center", bold: true, size: 2 },
  { type: "table", columns: ["*", { width: 9, align: "right" }], rows: [["Flat white", "3.40"], ["Lemon cake", "4.20"]] },
];

mountReceiptPreview(document.getElementById("receipt")!, { source: { blocks } });
```

The React component needs the same policy. Both were tried in Chromium 141, built with Vite from the published packages, under `script-src 'self' 'wasm-unsafe-eval'` and under a nonce with `'strict-dynamic'`.

Without the word, the preview does not throw and does not leave a blank box. It draws this in place of the receipt:

> The preview cannot start: this page's Content-Security-Policy blocks WebAssembly, which draws the receipt in the browser. Add 'wasm-unsafe-eval' to the script-src directive of the policy. That source expression allows compiling WebAssembly; it does not allow eval, new Function or inline script.

It also calls `onError` with `kind: "csp-script"`, `fix: "script-src 'self' 'wasm-unsafe-eval'"` (an example of the line, not a replacement: add the word to the `script-src` you have) and `cause`, whose message ends with what the browser said. Chromium 141 said this, and reported a `securitypolicyviolation` event for `script-src`:

```text
CompileError: WebAssembly.instantiateStreaming(): Refused to compile or instantiate WebAssembly module because 'unsafe-eval' is not an allowed source of script in the following Content Security Policy directive: "script-src 'self'"
```

Other browsers use their own words. Without a `connect-src` under `default-src 'none'`, the preview says that the page may not fetch the `.wasm` file (`kind: "csp-connect"`, `fix: "connect-src 'self'"`), and the console of Chromium 141 says, with the address of your file:

```text
Refused to connect to 'https://example.com/assets/receiptline_wasm_bg-1a2b3c4d.wasm' because it violates the following Content Security Policy directive: "default-src 'none'". Note that 'connect-src' was not explicitly set, so 'default-src' is used as a fallback.
```

### On your own server

The renderer under the preview, `@tillcast/html-render`, also runs in Node. Draw the receipt there, in your own process, and send the page HTML and a stylesheet: the page has no script and no WebAssembly, so it needs no `'wasm-unsafe-eval'`. This runs in your own process: nothing is sent to Tillcast, no key is needed, and the REST API has no preview call.

```ts
// server.ts: Node 22.18 or later runs it as it is (set "type": "module" in package.json)
import { createServer } from "node:http";
import { createRenderer, isError, type Block } from "@tillcast/html-render";

const blocks: Block[] = [
  { type: "text", text: "Harbour Cafe", align: "center", bold: true, size: 2 },
  { type: "table", columns: ["*", { width: 9, align: "right" }], rows: [["Flat white", "3.40"], ["Lemon cake", "4.20"]] },
];

const renderer = await createRenderer();
const shown = renderer.render({ document: blocks, profile: "paper-80mm", format: "html" });
if (isError(shown)) throw new Error(`${shown.error.code}: ${shown.error.message}`);

createServer((request, response) => {
  if (request.url === "/receipt.css") {
    response.writeHead(200, { "content-type": "text/css" }).end(shown.stylesheet);
    return;
  }
  response.writeHead(200, {
    "content-type": "text/html; charset=utf-8",
    "content-security-policy": "default-src 'none'; style-src 'self'; img-src data:",
  });
  response.end(
    `<!doctype html><link rel="stylesheet" href="/receipt.css">` +
      `<div role="group" aria-label="Receipt preview">${shown.content}</div>`,
  );
}).listen(3000);
```

`format: "html"` gives `content`, the HTML of the paper, and `stylesheet`, its CSS. The markup has no `style` attribute, so `style-src 'self'` with the stylesheet served as a file is enough. The renderer escapes the text of the receipt, so `content` goes into the page as it is. This page shows the same receipt as the browser example. (`email_html` has inline styles: it is for mail.)

## The renderer on its own

`@tillcast/html-render` is what draws. In a browser, a worker or Node it turns blocks or ReceiptLine text into HTML for a screen, HTML for a mail, or text, for the layout of a printer profile. A server of your own can use it to prepare the body of an e-mail. It does not print and it does not send mail. Its README on npm has the request, the answer and the limits.

## Not part of these packages

* **Printing.** A job prints, through the API or an SDK. See [SDKs](/getting-started/sdks).
* **An editor.** See the [roadmap](/roadmap).