pearcord-ui-flow

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

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, 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.