Add Block Preview

Add Block Preview Skill

You manage block visibility gating in Sim — hiding blocks from every discovery surface (toolbar, cmd+K search, copilot @-mentions, agent tool picker, mothership VFS/metadata/tools, Access Control list, public docs/catalog) while never gating execution of already-placed instances.

The model

Three levers, evaluated in apps/sim/lib/core/config/block-visibility.ts and folded into the registry accessors (apps/sim/blocks/registry.ts):

1. preview: true on the BlockConfig (static, in code) — the block is default-hidden EVERYWHERE (hosted, self-hosted, dev, SSR) until revealed. Fail-closed.

2. The hosted block-visibility AppConfig document — per-block rule keyed by the existing block type:

   {
     "<block-type>": {
       "enabled": false,        // required. true = GA (visible to everyone)
       "orgIds": ["org_..."],   // optional allowlist clauses (any match reveals)
       "userIds": ["user_..."],
       "adminEnabled": true     // platform admins (user.role === 'admin')
     }
   }

3. PREVIEW_BLOCKS env (comma-separated block types) — the off-AppConfig reveal path for self-hosters and local dev.

A revealed block that is not globally GA (enabled !== true, or env-revealed) renders with a " (Preview)" name suffix on discovery surfaces. getBlock() stays pure, so placed instances keep their canonical name and always execute.

Lifecycle of a preview block

1. Author the block normally (/add-block etc.) and set preview: true on its BlockConfig. Ship no BlockMeta and no docs until GA — check-block-registry deliberately skips preview blocks in meta coverage, and generate-docs skips them at every gate.

2. Local dev: set PREVIEW_BLOCKS=<block-type> in your env to see it (with the suffix).

3. Merge/deploy. The block's code is live everywhere but visible nowhere — no AppConfig rule exists and self-hosters have no env entry.

4. Hosted preview: add a rule to the block-visibility AppConfig document and start a deployment (no code deploy):

   • Admins only: { "enabled": false, "adminEnabled": true }
   • Design-partner org: { "enabled": false, "orgIds": ["org_123"] }
   • GA via config (code cleanup pending): { "enabled": true } — suffix disappears everywhere within ~30s (AppConfig TTL) + client refetch.

   Same runbook as feature-flags: edit the hosted document, aws appconfig start-deployment with the sim-<env>-fast strategy (see the infra README).

5. GA cleanup: delete preview: true from the block (now visible to self-hosters on their next upgrade), add its BlockMeta + regen docs, and drop the AppConfig entry. For a v2 upgrade, this is also when v1 gets hideFromToolbar: true and sunset: { status: 'legacy', replacedBy: '<v2-type>' } (the superseded-version paradigm). Both edits must land in the same commit as the preview: true removal — check-block-registry fails a sunset block whose replacedBy is still preview, so splitting them breaks the build in between. Also move the block's BLOCK_DISPLAY_WORKFLOWS entry (apps/docs/components/workflow-preview/block-display-workflows.ts) to the new type, or BlockPreview silently renders nothing on the docs page.