foomchat Docs

1. Introduction

foomchat is a chat app whose interface you can reshape by asking — the assistant writes installable features (HTML/CSS/JS modules) that change the app you're chatting in, from small styling tweaks to total redesigns.

The core app handles authentication, conversations, billing, and feature lifecycle; installed features layer behavior and visuals on top. Features can be submitted for review and, once approved, published for others to install.

2. Getting Started

Chat tab: send messages and manage conversations.

Browse tab: discover and install public features.

Account tab: credits, API key, username, and subscription controls.

Use the Features button in the top tab bar (or the Manage Features button in the sidebar) to enable/disable installed features and inspect versions. The tab-bar button is always available, even if a custom sidebar feature is broken or disabled.

3. Chat Workflow

Start a new chat from the sidebar, send messages in the input area, and revisit past conversations from the conversation list.

The environment toggle near the input controls whether installed-feature context is included in the model prompt for feature generation tasks.

4. Feature System

Feature: a package of HTML/CSS/JS + install_config.

Install ID: stable identity in install_config.id — the feature's permanent name across revisions, used for dependency matching and upgrades.

Slot: the only mount points. Multi slots (like app.root or chat.feature-container) accept many features ordered by order. Single slots (chat.sidebar, chat.window, chat.input) are claimed by one feature at a time — claiming hides the built-in UI and disabling the feature restores it automatically.

Status: every installation is exactly one of enabled, disabled, or uninstalled. Enabled features are mounted live; disabled features keep their saved state; uninstalled features disappear from your list but can be reinstalled from Browse.

Exclusive groups: features can declare exclusive_group (all themes use "theme") — enabling one automatically disables the others in the group, so themes never stack.

JavaScript lifecycle: feature JS registers via FeatureAPI.defineFeature({ id, mount, unmount }). The runtime mounts it when everything it needs exists and fully cleans up on disable. A feature that throws during mount gets an Errored badge in Manage Features instead of breaking the page.

Versions: semver in install_config.version. Updating a feature bumps the version and the runtime remounts it live; old versions stay in History for one-click rollback.

Dependencies: features can require other features by install ID + optional version range. Validated when the feature is saved and resolved (with a confirmation) when installed.

5. My Features Modal

List: one feed of all your features.

By slot: groups by mount location to debug overlap/conflicts.

Badges: category, slot, system/prototype, and semantic version.

Status: enabled features are mounted live; disabled features remain saved but inactive.

Actions: enable/disable, submit for review (publishing is hand-reviewed; approved features go live in Browse), unpublish, history (owned features), uninstall for non-owned installs.

6. Browse and Install

Browse shows public features, including system features. Installation status and dependency intent are shown before install.

If a feature is disabled (not uninstalled), you can re-enable it without reinstalling. If fully uninstalled, install again from Browse.

Some uninstall operations can require a cascade when other installed features depend on the selected feature.

7. Account and Billing

Account includes username management, API key management, and subscription/top-up controls.

If your own API key is configured, chat can run against that key rather than system credits.

8. Troubleshooting

Sidebar looks wrong: the default sidebar is built in — if a custom sidebar feature took it over, disable that feature from the tab bar's Features button and the default returns automatically.

Feature not visible: confirm it is enabled and mounted to the expected slot. Features with an Errored badge failed to mount — use Ask AI to fix on the card.

Install blocked: check dependency requirements and install missing dependencies first.

Unexpected layout behavior: switch My Features to By slot and inspect competing features in the same slot.

Broken UI after experimenting: reload with ?safe=1 in the URL to mount only system features, then disable the culprit.