pearcord-ui-flow

Pearcord desktop UI IPC dispatch and automated flow scenarios for Bare smokes. Mirrors apps/pearcord pear-pipe message handling.

v0.8.573 (Phase 610): send-message, upsert-guild-emoji, and upsert-guild-sticker emit composer-focus-channel re-verified for expression hub bundle. Bundle: npm run test:phase610-expression (app repo).

v0.8.572 (Phase 609): upsert-guild-sticker and remove-guild-sticker emit composer-focus-channel re-verified for stickers hub bundle. Bundle: npm run test:phase609-stickers (app repo).

v0.8.571 (Phase 608): upsert-guild-emoji and remove-guild-emoji emit composer-focus-channel re-verified for emoji hub bundle. Bundle: npm run test:phase608-emoji (app repo).

v0.8.570 (Phase 607): upsert-automation-hook and import-automation-manifest emit composer-focus-channel re-verified for automation hub bundle. Bundle: npm run test:phase607-automation (app repo).

v0.8.569 (Phase 606): create-bot-install-token and install-bot-token emit composer-focus-channel re-verified for bots hub bundle. Bundle: npm run test:phase606-bots (app repo).

v0.8.568 (Phase 605): register-slash-commands and delete-slash-command emit composer-focus-channel re-verified for slash hub bundle. Bundle: npm run test:phase605-slash (app repo).

v0.8.567 (Phase 604): create-channel-webhook, delete-channel-webhook, and execute-channel-webhook emit composer-focus-channel re-verified for webhooks hub bundle. Bundle: npm run test:phase604-webhooks (app repo).

v0.8.566 (Phase 603): fetch-audit-export-archive, sync-audit-export-csv, and set-digest-export-schedule emit composer-focus-channel in guild mode when activeChannelId is set. Bundle: npm run test:phase603-compliance (app repo).

v0.8.565 (Phase 602): set-audit-export-schedule and set-audit-log-export-filter emit composer-focus-channel in guild mode when activeChannelId is set. Bundle: npm run test:phase602-audit (app repo).

v0.8.561 (Phase 598): update-user-prefs and update-guild-settings emit composer-focus-channel in guild mode when activeChannelId is set. Bundle: npm run test:phase598-settings (app repo).

v0.8.560 (Phase 597): select-guild emits composer-focus-channel in guild mode when activeChannelId is set (matching join-invite guild switch behavior). Bundle: npm run test:phase597-session (app repo).

v0.8.559 (Phase 596): create-guild emits composer-focus-channel in guild mode when activeChannelId is set (matching existing join-invite behavior). Bundle: npm run test:phase596-onboarding (app repo).

v0.8.550 (Phase 587): pin-message and unpin-message emit composer-focus-channel in guild mode when activeChannelId is set. Bundle: npm run test:phase587-pins (app repo).

v0.8.516 (Phase 553): Cleared update-search (empty query) emits composer-focus-channel in guild mode when activeChannelId is set. Bundle: npm run test:phase553-search (app repo).

v0.8.515 (Phase 552): run-audit-export-now and sync-audit-export-csv emit composer-focus-channel in guild mode when activeChannelId is set. Bundle: npm run test:phase552-compliance (app repo).

v0.8.498 (Phase 535): ban-member, kick-member, and timeout-member emit composer-focus-channel in guild mode when activeChannelId is set. Bundle: npm run test:phase535-moderation (app repo).

v0.8.497 (Phase 534): create-guild-custom-role, update-guild-custom-role, upsert-channel-overwrite, and delete-channel-overwrite emit composer-focus-channel in guild mode when activeChannelId is set. Bundle: npm run test:phase534-roles (app repo).

v0.8.496 (Phase 533): delete-channel and reorder-channels emit composer-focus-channel when platform.mode === 'guild' and activeChannelId is set. Bundle: npm run test:phase533-guild-admin (app repo).

v0.8.495 (Phase 532): join-invite emits composer-focus-channel when platform.mode === 'guild' and activeChannelId is set. Bundle: npm run test:phase532-invites (app repo).

v0.8.490 (Phase 527): play-soundboard emits composer-focus-channel in guild mode. Bundle: npm run test:phase527-soundboard (app repo).

v0.8.489 (Phase 526): start-screen-share and stop-screen-share emit composer-focus-channel in guild mode. Bundle: npm run test:phase526-screen (app repo).

v0.8.488 (Phase 525): join-stage, request-stage-speak, approve-stage-speaker, and demote-stage-speaker emit composer-focus-channel in guild mode. Bundle: npm run test:phase525-stage (app repo).

v0.8.487 (Phase 524): join-voice, join-voice-listen, and leave-voice emit composer-focus-channel when platform.activeChannelId is set (guild mode), matching messaging/reaction focus behavior. Bundle: npm run test:phase524-voice (app repo).

Mission

Centralize the msg.type → platform.* routing table used by the Pear UI sidecar so smoke tests and tooling can drive the full platform surface without duplicating hundreds of if-branches in the app entrypoint.

When to use / not

Use when:

• Running Bare smokes that send JSON IPC lines to a headless platform instance.
• Adding a new UI IPC type—implement handler here and call from app shell.

Do not use when:

• You need platform business logic — implement on PearcordPlatform in pearcord-platform.
• You build non-Pear UIs — import platform directly.

Public API

Export	Role
dispatchUiMessage(platform, msg, hooks)	Returns true if msg.type handled
fromBase64(str)	Buffer for attachment/emoji bytes
normalizeEmojiImage(image)	Maps dataBase64 → data buffer

Hooks

{
  send: (obj) => {},      // reply events to UI pipe
  pushState: () => {}       // refresh serialized state
}

Returns false for unknown types (caller may log).

Coverage (grouped)

Area	Example msg.type values
Onboarding	register, create-guild, join-invite, select-guild
Automation	set-automod-config, upsert-automation-hook, export-automation-manifest, dry-run-automation-hook, schedule/export/dashboard IPC
Bots	create-bot-install-token, install-bot-token, register-slash-commands
Announcements	set-announcement-crosspost, set-announcement-hub-publish, subscribe-remote-announcement-hub, follow-announcement
Boosts / stickers	contribute-guild-boost, upsert-guild-sticker, upsert-sticker-pack
Profile	update-profile-cosmetics, set-profile-banner-image, step-up PIN types
Voice / screen	join-voice, join-voice-listen, leave-voice, join-stage, request-stage-speak, approve-stage-speaker, demote-stage-speaker, start-screen-share, stop-screen-share, play-soundboard, voice-capture-chunk, display-capture-frame
Notifications	mark-all-notifications-read (emits mark-all-notifications-read-cleared + composer-focus-channel, v0.8.407), mark-notification-read (calls platform.markNotificationRead, emits mark-notification-read-cleared + notificationChannelId, v0.8.407), open-notification (marks read via markNotificationRead, emits composer-focus-channel, v0.8.407), mark-channel-read (emits mark-channel-read-cleared + threadChannelId for threads, v0.8.287), refresh-notifications (v0.8.236)
Workers	export-integration-worker-script, run-worker-install-trial, announce-worker-release
Moderation / channels	ban-member, upsert-channel-overwrite, forum/thread types
Search	update-search, refresh-search, remove-search-recent (v0.8.140)

Uses USER_STATUS from pearcord-platform for presence IPC.

Dependencies

• pearcord-platform — PearcordPlatform instance (git dependency in package.json)
• pearcord-qr — optional QR SVG for device pair codes
• b4a — base64 decode in Bare

Platform integration

// apps/pearcord/index.js pattern:
const { dispatchUiMessage } = require('pearcord-ui-flow')

async function onPipeLine(line) {
  const msg = JSON.parse(line)
  const handled = await dispatchUiMessage(platform, msg, { send, pushState })
  if (!handled) send({ type: 'error', message: `unknown type ${msg.type}` })
}

P2P surface

None directly—all mesh behavior delegated to platform methods invoked by dispatch.

Tests

Primary consumer: Bare smoke suites under apps/pearcord that spawn platform + pipe JSON lines.

Adding handlers here keeps smokes and production UI in sync.

Code example

const { dispatchUiMessage, fromBase64 } = require('pearcord-ui-flow')

const replies = []
await dispatchUiMessage(
  platform,
  { type: 'dry-run-automod', content: 'discord.gg/test' },
  {
    send: (o) => replies.push(o),
    pushState: () => {}
  }
)
// replies[0].type === 'automod-dry-run'

Related modules

• pearcord-platform — implementation target for every branch
• All feature modules — reached indirectly through platform

v0.8.174: update-guild-settings IPC forwards nsfwGateEnabled to platform.updateGuildSettings.

Composer focus channel (v0.8.406+)

After create-thread, create-forum-post, mark-all-notifications-read, or open-notification, dispatch emits a sidecar event (not a full IPC round-trip from the UI):

send({ type: 'composer-focus-channel', channelId: thread.id })

**v0.8.420 (Phase 457):** `create-channel` selects the new channel and emits `composer-focus-channel` (see [CHANNELS.md](../../docs/CHANNELS.md)).
// mark-all: channelId = platform.activeChannelId
// open-notification: channelId = result.channelId || msg.channelId || platform.activeChannelId

The renderer handles composer-focus-channel and calls requestComposerAutofocusForChannel(channelId) so the message box focuses once the target channel is active. Smokes: test:composer-autofocus-after-thread-create, test:composer-autofocus-after-mark-all-notif, test:composer-autofocus-after-notif-navigate. See NOTIFICATIONS.md, MESSAGE_THREADS.md, and FORUM_CHANNELS.md.

Maintenance

When adding IPC in the Pear app, add the same msg.type branch here first (or simultaneously) so dispatchUiMessage remains the single routing table.