# Placeholder System Guidelines This note is the working guideline for Lumi placeholder and variable support. Future placeholder work should follow this model unless the architecture is explicitly revised. ## Architecture Placeholders are registered server-side through `src/services/placeholders.js`. The frontend must not declare placeholder permissions, allowed plugins, or sensitivity. Editable fields reference a trusted `field_id`, and the server uses that field policy to decide which placeholders are available. Core and plugins can register: - placeholder definitions with metadata and a resolver function - field policies for template/input destinations that support placeholders Catalog, preview, save validation, and runtime rendering must share the same permission-checking path. Saved templates are not trusted permanently; they must be revalidated at render time because plugin availability, policies, settings, or sensitivity can change. ## Naming Use namespaced double-brace tokens: - `{{core.main.bot_name}}` - `{{core.main.command_prefix}}` - `{{core.command.rng}}` - `{{custom.stream.title}}` - `{{user.public.display_name}}` - `{{platform.discord.guild.member_count}}` - `{{okf.file.community.currency.primary_name}}` - `{{plugin.throne_wishlist.item_name}}` Avoid unqualified names for new work. Compatibility aliases may exist for old templates, but the catalog should present canonical namespaced tokens. Admin-managed values live under `{{custom.*}}`. Admins create them under Settings > Reusable text values; names are validated, cannot collide with system/plugin namespaces, and are stored in the update-preserved settings database. ## Core Namespaces Current core-owned namespaces include: - `core.main.*`: safe Lumi core settings such as bot/site name and command prefix - `core.command.*`: values created for one command execution, such as a Random Reply RNG roll - `custom.*`: admin-managed reusable values with explicit user, moderator, or admin visibility - `user.public.*`: safe viewer/triggering-user display information - `platform.discord.guild.*`: safe Discord guild statistics from the configured guild - `platform.twitch.channel.*`: safe locally configured Twitch channel/runtime values - `platform.youtube.channel.*`: safe locally configured or hydrated YouTube channel/runtime values - `okf.file.*`: file-backed OKF frontmatter values, with legacy aliases such as `{{community.currency.primary_name}}` Each platform namespace exposes a public-safe `data_status` value. Current values are `live_cache`, `connected`, `configured_not_connected`, or `unavailable`, depending on the integration. Discord statistics read only the connected client's guild cache; placeholder rendering never triggers a Discord fetch. Twitch follower/subscriber counts and Twitch/YouTube scheduled-start values remain intentionally unavailable. The current Twitch integration is chat-only, and the YouTube runtime does not maintain those statistics. Add them only after a background refresh service stores value, fetched-at time, expiry/stale state, and last error. Rendering must read that cache without a provider API call and return a safe unavailable/stale result when credentials or rate limits prevent refresh. ## Sensitivity Supported sensitivity levels: - `public_safe`: safe in user-visible output - `user`: user-specific content, only for fields whose output audience allows it - `moderator`: moderator/support visible content - `admin`: admin-only content - `internal`: internal implementation/runtime content - `secret_never_render`: must not be registered, listed, previewed, or rendered Never expose API keys, tokens, cookies, passwords, database URLs, session IDs, raw secrets, private file paths, sensitive query strings, or unredacted raw diagnostics through placeholders. If diagnostics are needed, register explicit redacted safe variants. ## Field Policies Every placeholder-compatible input must use a stable `field_id` whose policy is registered by trusted backend code. A field policy should define: - `field_id` - label and field type - output audience - minimum editor role - allowed namespaces or placeholder IDs - maximum sensitivity Security is based on the intersection of: - current editor role/capability during catalog, preview, and save - field policy - output audience that will see rendered content - placeholder sensitivity - placeholder minimum viewer role - plugin availability - runtime context Current trusted field policies: | Field ID | Destination | Editor | Output | Allowed values | | --- | --- | --- | --- | --- | | `core.custom_commands.static_response` | Static and Random Reply custom-command replies | Moderator | User | Public-safe `core.main.*`, `core.command.*`, `custom.*`, and `user.public.*` | | `plugin.throne_wishlist.message_template` | Throne event announcements | Admin | User | Public-safe Throne event placeholders | | `okf.markdown` | SQLite/community OKF Markdown | OKF contributor | Selected role | Permission-filtered core, platform, and visible OKF values | The current WebUI contains no inline JSON placeholder catalogs; double-brace editors use these server-owned IDs. Welcome Messages and Auto VC retain their older `{username}` and `[username]` runtime token formats for compatibility. They are not treated as generic placeholders until their event-context renderers and saved templates are migrated together; adding only autocomplete would advertise tokens those runtimes cannot safely resolve. An admin editing a user-visible template is not enough to allow admin-only placeholders. The output audience still limits what can render. Custom values use the same catalog, validation, preview, and runtime checks as code-registered placeholders. Values marked for moderators or admins do not appear in lower-privilege catalogs and cannot render into user-visible command replies. The `custom` namespace is reserved for this registry; plugins must use their own `plugin.*` namespace. ## Plugin Registration Plugins should register placeholders during backend plugin initialization using the placeholder service passed to `init` or available through `web.placeholders`. Plugin definitions should include `plugin_id` so disabled or missing plugins can fail safely. Resolvers must return safe display values and avoid leaking raw internal data. Renderers that send chat messages or HTML should still sanitize or escape for their output context after placeholder resolution. ## Frontend Frontend fields use: ```html data-placeholder-field="plugin.example.message_template" data-placeholder-output-audience="user" ``` The frontend requests `/api/placeholders/catalog?field_id=...` and uses the returned catalog for autocomplete and tree browsing. Inline JSON placeholder lists are a transitional fallback only and should not be used for new fields. ## Validation Templates must be checked: - when the editor opens a catalog - during preview - before save - at runtime before rendering output Unauthorized placeholders should fail closed. User-visible output should show a generic unavailable marker or leave legacy unknown tokens unchanged, depending on the existing renderer contract, but it must not reveal the restricted value. Async resolvers are bounded by a short timeout (1.5 seconds by default). Duplicate and adjacent tokens are resolved by source position, and resolver output is inserted literally rather than scanned again. A failed, unavailable, forbidden, or timed-out value therefore affects only that token and renders the caller's safe fallback.