# Conversation Designer

A visual editor for **scripted, branching conversations**, and an offline standalone chat-style player. This is not a chatbot: every message, choice and action is authored by you. No AI, accounts, analytics, APIs, server or persistent browser storage.

## Open on an Ubuntu laptop

```sh
git clone ssh://forgejo@forgejo.ai.34a.xyz/ai-controller-0.02/conversation-designer.git
cd conversation-designer
firefox index.html
```

Alternatively clone using HTTPS (Forgejo sign-in required):

```sh
git clone https://forgejo.ai.34a.xyz/ai-controller-0.02/conversation-designer.git
cd conversation-designer
firefox index.html
```

Use your existing Forgejo access; SSH cloning requires a key registered with Forgejo. After cloning, **no internet, installation, build command, extensions or webserver are needed**. Open `index.html` through Firefox's File → Open File, or double-click it. Keep the adjacent `.js` and `.css` files together. All runtime code is included, with **zero third-party runtime dependencies** and no CDN or external font requests.

**Try it:** click **Try the example conversation →** on the welcome screen, then **Preview**. The example is editable and is also provided separately as [`example.json`](example.json). Restart between experiments to reset the transcript.

## Make a conversation

1. Click **Create New**. Select the Welcome step and write **Message 1** in the properties panel. Each message becomes a separate bubble.
2. Use **Add message** for consecutive messages. Plain text and line breaks are preserved. Use `**bold**`, `*italic*` and backticks for `code`. This is a deliberately small formatting vocabulary, not full Markdown or HTML. Nested formatting and authored HTML are not interpreted.
3. Click **Add step**, name it, and write its message. New steps are placed without overlapping existing steps and are brought into view. **Find a step…** locates any step by name.
4. Return to Welcome. Click **Add response**, write the button label, and select **Go to node**. Choose its **Destination**, or click the response's blue **●** on the canvas and then the destination step. Click a different destination to reconnect; Escape cancels connection mode. Multiple responses can share the same destination, including earlier steps or the same step.
5. **Create & connect a new step** is a shortcut within each Go-to response. Use Find a step to select the new step and edit it.
6. Drag a node to reposition it. Drag empty canvas to pan; use the wheel or **− / +** to zoom. **Fit** frames the flow. The dropdown offers a keyboard-friendly alternative to selecting nodes on the canvas. Focus a step and press Enter to select it or complete a connection.
7. Select **Make starting step** to change where playback begins. The starting node has a green **START** badge.
8. A step with no responses ends the conversation. Mark **Intentional ending** to acknowledge that this is deliberate; otherwise the checker warns about a dead end. Visitors always have a Restart button.

Messages and responses can be reordered with their **↑** button. Removing messages, responses or steps requires confirmation. Deleting a destination clears its incoming connections so that you can deliberately reconnect them; Undo restores them.

### Response actions

| Action | Parameter | Behaviour |
| --- | --- | --- |
| Go to node | Destination step | Adds a visitor bubble, then shows the destination's messages and choices. |
| Open URL | Absolute `https://` or `http://` address | Opens a new tab without opener/referrer access. A manual link is available if the popup is blocked. |
| Open URI | e.g. `mailto:hello@example.org` or `myapp://path` | Asks for confirmation, then follows the URI. Requires a supported, registered application. Dangerous browser/script/file schemes are rejected. |
| Copy text | Any text | Tries the Clipboard API. If unavailable or denied, shows a selected read-only text box for Ctrl+C / ⌘C. |
| Restart | None | Clears transcript and visited steps and starts over. |

URL, URI and Copy actions keep the current choices available; they do not silently advance to another step. No integrations are performed. Opening a website naturally requires network access to that website; the designer and player do not.

### Appearance and typing

Open **Appearance & typing** to configure title, speaker, embedded avatar, page/text/bubble/button colours, corner radius, local font family, font size and maximum conversation width. Use Preview to check colour contrast; there is no automatic contrast enforcement. Avatar uploads support PNG, JPEG, WebP and GIF up to 2 MB, embedded directly in JSON and exported HTML (no external image dependencies).

Choose a default typing style:

- **Instant:** the complete formatted message appears at once.
- **Typewriter:** characters appear at a steady rate.
- **Natural typing:** variable character timing, with extra punctuation pauses.

Each message can override the default. Configure milliseconds per character (smaller = faster), delay before the first message, delay between consecutive messages and an optional animated three-dot indicator. Turning animation off makes all messages Instant, but **configured delays still apply**. A node transition's first bubble has no extra delay, except the initial conversation message. **Skip animation** reveals the current message immediately and can also skip its pending delay. Text space is reserved before characters appear, preserving line wraps and formatting. Screen readers receive the complete message rather than character-by-character announcements. The dot animation respects reduced-motion preferences; authors can disable text animation globally.

### Preview

**Preview** uses the **same player function and CSS** as exported HTML. It is not a separate approximation. The transcript stays visible, scrolls automatically as messages arrive, and shows visitor choices on the right. Responses appear only after all of a step's messages finish. **Mobile view** narrows the preview to 390px; it does not reset playback.

Returning to an already visited node shows its response options again **without duplicating messages already in the transcript**. Visited state lasts only until Restart or closing Preview. Restart cancels pending typing/delays; closing Preview also cancels playback.

## Save, reopen and export

- **Save JSON** downloads a human-readable, versioned editable document including content, action parameters, settings, embedded avatar and node positions. This allows unfinished conversations (e.g. missing destinations) to be saved. Save early and often. The browser chooses the download location; the application cannot confirm whether you kept the download or overwrite a previous file automatically.
- **Open JSON** uses the browser's normal file picker. A malformed/unsupported file shows an error and leaves the current conversation intact. Import validates document structure; **Check flow** diagnoses content problems.
- **Check flow** reports missing destinations, empty labels and invalid/unsafe URL/URI values as errors. Unreachable nodes, empty messages, empty copy values and unacknowledged dead ends are warnings. Cycles are allowed. Intent cannot be inferred: the author must review warnings and test every path.
- **Export HTML** runs the checker. Fix errors first. Warnings require an explicit **Export anyway**. Download the single self-contained `.html`, then open it directly in Firefox independently of the designer. It includes all data, code, styling and avatar; it exposes no editing controls. It is not a secrecy boundary: like any client-only document its authored content can be inspected in page source.
- Keep the JSON too: the editor opens **JSON**, not exported HTML. Save JSON and Export HTML are separate operations. Exporting does not mark your editable document as saved.
- To publish later, copy the exported HTML to any ordinary static host; rename it `index.html` if desired. It needs no API or server-side features. This repository does not publish or deploy anything for you. A host that adds a restrictive Content Security Policy must permit the exported inline script/style and `data:` images.

No localStorage, IndexedDB or filesystem-access permissions are used. Closing a dirty document triggers the browser's unsaved-changes warning where supported. **There is no automatic recovery after a crash.** New/Open/Home also ask before discarding unsaved work. Undo/redo keep up to 100 editing snapshots in memory; pan/zoom and preview actions do not count as document edits.

### Shortcuts

| Key | Operation |
| --- | --- |
| Ctrl/⌘+S | Save JSON |
| Ctrl/⌘+O | Open JSON |
| Ctrl/⌘+Z / Ctrl/⌘+Shift+Z | Document undo / redo outside text fields |
| Ctrl/⌘+Y | Redo outside text fields |
| N / Delete | Add / delete step outside text fields |
| F | Fit canvas outside text fields |
| Escape | Cancel connection or close an open dialog |

Text fields retain native browser text undo; the toolbar's **Undo/Redo** always operates on the document. The toolbar also works without shortcuts.

## Files and architecture

- `index.html`, `editor.css`, `editor.js`: static editor UI, custom DOM/SVG flow canvas, bounded document history and browser file operations.
- `model.js`: document creation, structural import validation and semantic graph validation, independent of DOM/player state.
- `player.js`: generic runtime and its CSS. Export serializes this exact self-contained function and embeds a snapshot of the authored document, safely escaped. It has no dependency on editor/model/example code.
- `example.json`: canonical editable example; `example-data.js`: a checked, generated copy for one-click local loading. This avoids `fetch()`/module/CORS restrictions on local files; the example is **not hardcoded into the player**.
- [`FORMAT.md`](FORMAT.md): version 1 JSON specification.
- [`TESTING.md`](TESTING.md): tests, actual verification and browser limitations.

A custom canvas is used rather than shipping a graph framework: the scope is deliberately small, works directly from `file://`, and avoids library assets, licences and build tooling. Classic scripts (not modules) and local stylesheets work with Firefox's normal local-file security settings. Do not relax those settings.

## Limits and browser differences

- Intended for small/medium authored conversations: 500 steps, 100 messages and 100 responses per step; 50,000 characters per message/action value, 300 per title/name/button label, 10 MB imported JSON. Very large transcripts or embedded images consume memory; keep individual messages short for a good visitor experience. The limits are guardrails, not a performance guarantee at their combined maximum.
- System fonts depend on the laptop; font binaries are not embedded. Mobile Preview is a sizing aid, not an emulator of every phone/browser. The editor is usable with stacked panels on narrow screens but larger screens are more comfortable for flow design.
- URI launch, URL popups and clipboard permissions remain browser/OS-controlled. No web page can install an application handler or bypass permission prompts. Clipboard fallback does not require changing Firefox preferences. Copying a file to another machine carries no active playback state.
- There are no variables, conditions, embeds, analytics, integrations or AI features.

## Licence

MIT. See [LICENSE](LICENSE). No third-party runtime assets are bundled.
