# SheevChat Marketplace Creator Contract

This is the public source of truth for choosing a Marketplace package type and understanding what SheevChat can run today. Detailed schemas live in the linked specialist references. Planned features must not be presented as active contract behavior.

## Choose a package type

| Package type | Use it for | Active boundary |
| --- | --- | --- |
| `action_library` | Connections, dynamic sources, callable actions, and bounded local event subscriptions | Schema version 1. See `docs/action-library-manifest-wiki.md`. |
| `widget_pack` | A new isolated overlay visual or a StreamElements custom-widget compatibility import | `sheevchat-widget-v1`, `streamelements`, or a SheevChat-owned native provider. |
| `theme_pack` | Presentation-only changes to a compatible built-in or Marketplace widget | `sheevchat-theme-v1`; themes cannot add app logic. |
| `community_pack` | Transparent dependency bundles and future opt-in recipes | Dependencies are active; applying recipes is still pending. |
| `chat_game` | Restricted command-driven games composed from host-owned operations | Schema version 2 with `sheevchat-chat-game-v2`. See `docs/chat-game-v2-creator-contract.md`. |

`overlay_pack` is deprecated. Paid checkout, subscriptions, entitlements, ratings, creator payouts, and public package submission are not active.

## Common package envelope

Non-action packages use a root `manifest.json`; Marketplace source releases also use `marketplace.json` for catalog-only metadata. IDs are stable lowercase package identifiers, versions use semantic-version text, all paths stay inside the package, and the packaged download may not exceed 25 MB.

Supported dependency types are:

- `action_library`
- `widget_pack`
- `theme_pack`
- `community_pack`
- `chat_game`
- `builtin_widget`

Supported publication trust values are:

- `official_sheevchat`
- `verified_partner`
- `verified_creator`
- `marketplace_verified`
- `community`
- `local_import`
- `unverified`

Trust is a publication and display label, not extra runtime authority. Community bundles inherit the lowest trust of required packaged dependencies.

## Active runtime contracts

### Action libraries

Action libraries can expose bounded local HTTP, WebSocket, IPC, UDP, TCP, and MQTT integrations; OAuth authorization-code-with-PKCE profiles; allowlisted remote HTTP hosts; authentication and request-signing declarations; instance, endpoint-file, response-pipeline, and mDNS discovery; dynamic/cascading sources; local event subscriptions; response ingestion; hotkeys; application launch; package-scoped file reads/writes; and SheevChat command execution. Use only the fields and limits in the Action Library Manifest Wiki.

### Widgets and themes

Developer widgets run in sandboxed iframes through `sheevchat-widget-v1`. The parent owns SheevChat connections, event routing, package assets, fonts, audio requests, and bounded package state. StreamElements exports use the separate `streamelements` compatibility host. Native `sheevchat` providers remain first-party only.

Themes use documented target data and may not change moderation, command processing, network behavior, or application state. Installed packages never mutate built-in widget schemas or defaults.

### Chat games

Chat games are JSON-only declarative packages. The v2 runtime supports managed commands and aliases, optional loyalty/package/inventory resources, weighted tables, prompt banks, host-approved cached remote prompts, scoped state, multiplayer sessions, community state, voting, leaderboards, transactions, and bounded overlay events. Games can use any combination of those capabilities, including no currency at all.

A game may name a separate `widget_pack` companion. The game remains authoritative; the widget can present committed events and snapshots but cannot choose outcomes or mutate balances. Game packages cannot include executable or script files.

## Installation and removal behavior

Installing a package registers only capabilities supported by the installed SheevChat version. Unknown runtimes remain unavailable instead of gaining fallback authority. Removing a package removes its installed files and unregisters its surfaces. Current chat-game database state remains retained for a later reinstall; packages cannot provide uninstall code or independently choose a deletion policy for persisted host data.

## Security boundaries

- No package receives Electron, Node, filesystem, database, shell, or unrestricted network access unless a documented bounded action-library capability explicitly provides the narrow operation.
- No package may store secrets in manifests, fields, previews, widget state, or catalog metadata.
- Chat games cannot ship JavaScript, SQL, executables, or arbitrary request URLs.
- Overlay widgets cannot settle game outcomes, grant rewards, or bypass command permissions.
- Unknown fields, capabilities, runtime IDs, provider IDs, unsafe paths, and unsupported dependency types must fail validation or remain unavailable.

## Creator validation checklist

1. Choose the narrowest correct package type.
2. Declare only capabilities actually used.
3. Keep IDs stable when upgrades must preserve settings or state.
4. Include useful descriptions, previews, compatibility, dependencies, and a changelog.
5. Validate both the source package and generated distribution.
6. Test the installed package in the minimum supported SheevChat version.
7. Document unavailable behavior as an unsupported gap instead of inventing schema fields.