# share_appearance

Make a share link for one of the shooter's own themes or layouts (not a log share).

## What it is for

`share_appearance` makes a share link to one of the shooter's own themes or layouts. The link holds a frozen copy of one version. It is not a log share: for those see [list_shared_with_me](list_shared_with_me.md). The tool makes the link and says it aloud. It never imports a link for anyone and changes no theme or layout. Everything the share tools have in common is on [the family page](appearance.md).

## What to know first

**The address is given once, and every call makes another link.** The reply holds the whole address, in the spoken line and in `url`. No tool shows it again; [list_shares](list_shares.md) lists a link without it. Calling again makes a second link, and the first keeps running until it is stopped.

**A link freezes one version.** The latest version, or the one written `<id>@<version>` in `ref`. A later edit does not change what the link gives, and deleting the theme or layout later does not stop it.

**Anyone with the address can open it, signed out.** They can preview it and import their own copy. A theme's background picture goes too, without its photo details (place, camera, time). It is read each time the link is opened: one deleted later is missing.

**The copy holds the content only.** The name is part of the content and goes with it. The version number, the notes, the history and the owner do not. The reply's `name` is the name that version had when it was saved, which can differ from the record's name today.

**Built-ins are refused, and `kind` must match the record.** A theme asked for as a layout, or the other way round, is not found.

## Generated table

**Tool:** `share_appearance` · **Family:** Appearance · **Scope:** `appearance` · **Save scope:** none · **Changes:** share links (one made or stopped on the server; no theme, layout or other record is saved) · **Runs:** no solver work in the connector

**Description** (what the connector sends to an assistant, word for word):

```text
Make a share link for one of the shooter's own themes or layouts (not a log share). To stop a link use revoke_share. Saves a link to a frozen copy of one version, which anyone with the link can preview and import as their own copy; needs the appearance permission. Read the URL back: it is given only in this reply, and every call makes another link. The copy carries the content with its own name and titles, not who made it, the notes or the history; a background image goes without its photo details (place, camera, time). Never import anything on someone else's behalf. Guide: share_appearance.
```

**Inputs** (2; read from the input schema the connector sends):

| Input | Type | Required | Bounds | Field |
|---|---|---|---|---|
| `kind` | `"theme"` or `"layout"` | yes | - | - (selects a record) |
| `ref` | text | yes | - | - (selects a record) |

**Sent with the inputs** (each input's own description, word for word; an input not listed is sent without one):

```text
kind: Which kind ref names
ref: The theme or layout id or name from list_appearance; "<id>@<version>" shares that version
```

## When to use it, and when not

| The shooter wants | Use | Why |
|---|---|---|
| A look or arrangement given to someone as a link | `share_appearance` | A frozen copy they import |
| To see the links already made, or how often each was imported | [list_shares](list_shares.md) | Lists without addresses |
| A link stopped | [revoke_share](revoke_share.md) | By the link's id |
| To know the ids and names of the themes and layouts | [list_appearance](list_appearance.md) | The names `ref` takes |
| To read what someone shared of their profile or log | [list_shared_with_me](list_shared_with_me.md) | Those are log shares, not links to a theme |

Ask which theme or layout, if more than one fits. A built-in needs no link: everyone has them. `create_theme` or `create_layout` first makes an editable copy of one.

## The inputs

**`kind`** is `theme` or `layout`. It must be the kind of the record `ref` names.

**`ref`** is an id or a name, as in the family page ([names and versions](appearance.md)). `Dusk@1` shares version 1. A name is the record's name today; an older version is reached by today's name or the id, then `@` and the number. A name that two records share is answered as no such record; give the id. With no `@`, the version is the latest the connector reads from the account. Nothing else sets a version, a name or a password: the tool has no input for them.

## What it returns

Spoken: `Here's a link to '<name>' v<version>: <address> — anyone who opens it can preview it and import their own copy. Later edits don't change what the link gives; revoke_share stops it.` The address is said whole. A name that is a short code stands in the tool's own apostrophes; any other is in quotation marks, cut to 40 characters ([the connector overview](connector.md), "How a reply is shaped").

| Key | Holds |
|---|---|
| `share_id` | The link's id: what [revoke_share](revoke_share.md) takes |
| `url` | The address, ending `#/import/<code>` |
| `kind` | `theme` or `layout` |
| `name` | The name of the shared record, as stored (not marked in the details) |
| `version` | The version frozen in the link |

## Worked examples

In these examples the id and the address are the made-up account's; a real id is 36 characters and a real code 22.

Every example below was run by the documentation generator against a made-up account, never a real one. Numbers are rounded to three places; generated ids and times are shown as placeholders. Two things are printed more briefly than the tool sent them, and nothing else is changed. A list of plain values stands on one line, whole up to 12 entries (a longer one, and a list of objects past 3, ends with a count of the rest). A reply that puts stored text in quotation marks also carries a note saying so, which an example leaves out and marks instead; no reply below carried it.

## When it refuses

| Reply starts | Cause | Tell or ask |
|---|---|---|
| No theme (or layout) with the reference, then `list_appearance shows the` | No record of that kind has that id or name today, two have the name, an own record is named like a built-in, or the version after `@` is not stored or was deleted | Ask which one; give the id |
| `is built in, so everyone already has it; there's nothing to share.` | A built-in | Offer a copy of their own |
| `isn't on the server yet; open the app so it syncs, then ask again.` | The version was there when the tool looked and gone when it asked for the link | Ask again |
| `No link made — ` and the server's words | The server turned the link down, for example at 200 active links | Say the words. Stop a link to make room |

Any other failure of the server is not worded by the tool: the reply is the server's own answer in quotation marks, braces included, with the note about stored text. Say that the link was not made. The input check's refusals are on [the connector overview](connector.md); here `kind` must be `theme` or `layout`.

## What it reads and changes

**Reads** the account's themes and layouts, to find the record and its version. **Changes** one thing on the server: a new share link, which holds a hash of its code, the kind and a copy of that version's content. It holds no record id and no version number, so nothing later says which version a link gives. No theme, layout or setting changes. It sends no command to a device. The link counts against 200 active links per account.

## Below this page

- [list_shares](list_shares.md) and [revoke_share](revoke_share.md): see and stop links.
- [list_appearance](list_appearance.md): the ids to share.
- [list_shared_with_me](list_shared_with_me.md): the other kind of sharing.
- [the connector overview](connector.md), [the family page](appearance.md)

## Worked examples

**1. A link for the latest version of a theme**

Starting point: a theme at version 2, a layout, one uploaded image of 48 kB, two share links (one for the theme, and a later one for the layout that was stopped) and one phone. Link scopes: `read`, `appearance`.

Call:
```json
{"kind":"theme","ref":"Dusk"}
```

Spoken line:
```text
Here's a link to 'Dusk' v2: https://coldborelab.app/#/import/AbCdEfGh1234567890_-x1 — anyone who opens it can preview it and import their own copy. Later edits don't change what the link gives; revoke_share stops it.
```

Details:
```json
{
 "share_id": "s1",
 "url": "https://coldborelab.app/#/import/AbCdEfGh1234567890_-x1",
 "kind": "theme",
 "name": "Dusk",
 "version": 2
}
```

Made a share link: a row on the server. No theme, layout or other record was saved.

**2. A link for an earlier version**

Starting point: one theme whose stored versions are 1 (named Dawn, saved in the app), 2 (deleted), 3 (named Dusk, saved by Claude with the note larger text) and 4 (named Dusk, saved in the app); one layout at versions 1 and 2, the second with a title on its first section; and one phone. Link scopes: `read`, `appearance`.

Call:
```json
{"kind":"theme","ref":"Dusk@1"}
```

Spoken line:
```text
Here's a link to 'Dawn' v1: https://coldborelab.app/#/import/AbCdEfGh1234567890_-x1 — anyone who opens it can preview it and import their own copy. Later edits don't change what the link gives; revoke_share stops it.
```

Details:
```json
{
 "share_id": "s1",
 "url": "https://coldborelab.app/#/import/AbCdEfGh1234567890_-x1",
 "kind": "theme",
 "name": "Dawn",
 "version": 1
}
```

Made a share link: a row on the server. No theme, layout or other record was saved.

**3. A built-in theme**

Starting point: one theme and one layout of the shooter's, and one phone. Link scopes: `read`, `appearance`.

Call:
```json
{"kind":"theme","ref":"builtin:dark"}
```

The tool refuses:
```text
Dark is built in, so everyone already has it; there's nothing to share. create_theme makes a copy of your own that you can share.
```

**4. A name two themes have**

Starting point: three themes of the shooter's (two named Dusk, and one named Daylight, as a built-in theme is), three layouts (two named Bench, and one named Compact, as a built-in layout is) and one phone. Link scopes: `read`, `appearance`.

Call:
```json
{"kind":"theme","ref":"Dusk"}
```

The tool refuses:
```text
No theme Dusk. list_appearance shows the themes.
```

**5. A theme asked for as a layout**

Starting point: a theme at version 2, a layout, one uploaded image of 48 kB, two share links (one for the theme, and a later one for the layout that was stopped) and one phone. Link scopes: `read`, `appearance`.

Call:
```json
{"kind":"layout","ref":"Dusk"}
```

The tool refuses:
```text
No layout Dusk. list_appearance shows the layouts.
```

---

[All reference pages](index.md)