> ## Documentation Index
> Fetch the complete documentation index at: https://docs.saphion.co.uk/llms.txt
> Use this file to discover all available pages before exploring further.

# Apps

> Ask Beacon for a small interactive app, such as a calculator, explorer or simulation, open it beside your chat, and keep it up to date.

An app is a small interactive page that Beacon builds for you in a chat: a calculator, an explorer, a simulation, a 3D scene, a game or a tool shaped around one job. It runs inside Saphion, can show your live Saphion data, and stays in **Creations** so you can open it again.

> [!NOTE]
>
> Everyone with a Platform seat can make and open apps. An app shows only what the person looking at it is allowed to see.

> [!NOTE]
>
> An app can also run on a Whiteboard, in a Document or on a Dashboard, live for everyone who can open it. See [Place an App in a Creation](#place-an-app-in-a-creation).

## Make an app

**1. Ask for it**

Describe what it should do and who uses it. For example: "Make an app that lets me enter a deck's length and width and works out the joists and the cost." You can also choose **New**, then **App**, in **Creations**. That opens a new chat beside an empty pane that holds the app's place, in a Project's own chat if you start it from the Project. Nothing is saved until Beacon makes the app, and the finished app takes that pane.

**2. Watch it build**

The app is not drawn while it is being written. The frame says "Building app", then "Loading app", and the finished app appears in the answer.

**3. Try it and ask for changes**

Use the app in the chat, or open it in the side pane for the full height. Ask Beacon to change anything you do not like.

Beacon follows a design procedure for polished apps. Run it by name with `/design-app` for something substantial. It is meant for **bespoke** interaction. Where the answer is figures, a chart, a records list, a spreadsheet or places on a map, Beacon uses Saphion's own native views instead of drawing them inside an app.

An app is a single page that styles itself, in both light and dark themes. It can use a set of built-in drawing and charting libraries, such as `three`, `d3`, `chart.js` and `gsap`.

## Open an app

An app you or Beacon made appears as a card in the chat. Select it to open the app in the side pane beside the chat. Along the top of the pane you can switch between:

| View | What it shows |
| - | - |
| **Preview** | The running app. Switching views does not reload it, so it keeps its state. |
| **Code** | The app's own HTML, to read or copy. |
| **Sources** | Only where the app reads live Saphion data: each source, what it reads and where it stands. |

To find an app later, open **Creations** and filter by type. Selecting an app opens it in the chat that made it, while that chat still exists. The app's menu there is led by **View original chat** and then has the same choices as a file: **Copy link**, **Share**, **Rename**, **Export**, **Add to favourites**, **Version history**, **Move**, **Archive** and **Delete**. See [Files](https://docs.saphion.co.uk/work/files.md).

## Place an App in a Creation

An App you can open can be placed on a Whiteboard, in a Document or on a Dashboard, where it runs between the notes, paragraphs or charts. You place, move or remove one only on a Creation you may edit.

| Creation | How you place it |
| - | - |
| [Whiteboard](https://docs.saphion.co.uk/beacon/whiteboards.md) | Choose the **App** tool and pick one of your Apps. Drag its tab to move it and resize it like any element. |
| [Document](https://docs.saphion.co.uk/beacon/documents.md) | Type <kbd>/</kbd> or choose **Insert**, then **App**. It sits between paragraphs at the height you give it, between 120 and 1,200 pixels. |
| [Dashboard](https://docs.saphion.co.uk/work/dashboards.md) | Choose **Add widget**, then **App** under **Shown as**. It is a card on the board, at its place and width. |

* **It is placed by reference.** The App is kept once, in **Creations**. A change to the App shows in every Creation that holds it. Nothing is copied.
* **It opens for everyone who can open the Creation.** A colleague does not need the App shared with them separately. It still reads Saphion data as the person looking at it.
* **Shared state belongs to the placement.** A timer started on a Whiteboard ticks in every window that has the board open. The same App placed in two Documents keeps two separate states. Someone who can only view reads the state and cannot change it.
* **Beacon makes and places in one step.** With a Whiteboard, Document or Dashboard open, ask Beacon for an App and it makes it and places it in the same change. It is all or nothing: if any part is refused, Beacon says why and nothing is made or placed. A plain "start a timer" on a Whiteboard uses the board's own Timer, so ask for an App when you want one of your own.
* **The Bin and restore.** If you put an App in the Bin, every place that holds it says "This App is in the Bin." and comes back when you restore the App. Before you delete one, Saphion tells you which Creations hold it.
* **Exports carry a picture.** A Document that holds an App exports to Word and PDF with the App's picture and the note "a live App: open the Document to use it".

## Show live Saphion data

An app can read your Saphion records live instead of having them typed in. The app reads each source **as the person who has it open**, with that person's own access. A colleague who opens your app sees what they are allowed to see, not what you can.

The **Sources** view lists them:

| Column | What it shows |
| - | - |
| **Source** | The name its maker gave it. |
| **Reads** | What it reads, in Saphion's words. |
| **Where it stands** | When it was read ("Read at 10:42"), how many records exist ("120 in all") and "not all shown" where the app has the first rows only. If a read failed it says "Not read" or "Could not be read" and why. |

Sources are read when the app opens. Choose **Refresh** to read every source again.

> [!NOTE]
>
> When a source holds more rows than the app reads, the Sources view says "not all shown". Ask Beacon for exact totals when you need them.

### Data Beacon writes into the app

Some information is worked out rather than read: a daily summary, a status report. Beacon, or a scheduled task, writes it into the app's own data, and the app shows it for everyone who can open the app, with an "as of" time. The app is designed once and refreshed by writing data, not by rebuilding it.

### Files in an app

An app can show a picture or a table you attached or a file in Files, up to 8 files of PNG, JPEG, WebP, GIF or CSV and at most 15 MB each. It reads the file as the person viewing, so it shows a reason, not the file, to someone who may not open it.

### What an app remembers

An app can keep a person's settings between visits, kept per person for that app (about 1 MB). What one person sets is not shown to another.

## Change an app

Ask in the same chat or any other: "Add a column for VAT to the app I made yesterday." Beacon changes the same app in place and saves a new version, and its card opens the latest. It never makes a second copy. Ask it to put back the version before its last change if the change was wrong.

## If an app fails

If an app stops or throws an error, you see one message that names the app and carries its error. The app stays on screen. Choose **Fix with Beacon** to put the app and the error into the Beacon box for you to send, or **Reload** to run it again. Reload keeps what the app saved.

If a saved app cannot be opened, the frame says so inside the app's own space and offers **Try again**. An app made on an older engine says "This app uses an unsupported version. Please ask Beacon to recreate it."

## How it works

* **A sandbox.** An app runs in an isolated frame with no internet access. It cannot call other websites, change Saphion for you or act in your connected systems. Saphion's own screens do the saving and the acting.
* **No hidden copies.** An app's live figures are read when it opens, not stored in the app.
* **Calculations stay local.** An app works things out on your screen. It does not save business records.
* **It follows your access.** If you lose access to something an app reads, the app shows that source as not read.

## Ask Beacon

"Make an app that compares our open opportunities by stage and lets me filter by owner." Beacon builds the app, reading the opportunities live.

"The app I made last week shows the wrong total. Fix it." Beacon opens the app, finds the fault and saves a corrected version.

## FAQ

> [accordion] Who can open an app I made?
>
> You, until you share it. Share it from its menu in Creations, as you would a file. Everyone who opens it sees data as themselves.

> [accordion] Who can open an App I placed on a Creation?
>
> An App placed on a Whiteboard, in a Document or on a Dashboard opens for everyone who can open that Creation.

> [accordion] Can an app save records into Saphion?
>
> No. An app can show your data and keep a person's settings, but it cannot create or change records.

> [accordion] Why is the chart in my answer not an app?
>
> Beacon uses Saphion's native views for figures, charts and records, because they are checked and follow your access. It makes an app only for something bespoke.

> [accordion] Can I put a map in an app?
>
> Not a map. Beacon shows places with its own map view in the chat instead.

> [accordion] Where did my app go if I deleted the chat?
>
> It stays in Creations. Its menu loses **View original chat**, since that chat no longer exists.

## Related

* [Chat with Beacon](https://docs.saphion.co.uk/beacon/chat.md): Ask for an app, and change it in the same chat.
* [Favourites and Creations](https://docs.saphion.co.uk/work/favourites-and-creations.md): Find every app you made or were given.
* [Sharing and access](https://docs.saphion.co.uk/work/sharing-and-access.md): Who can open what you make.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.