Lumi/docs/placeholder-system.md

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:

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.