pearcord-ui-flow

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

Phase 692 (v0.8.667): relay-json-modal-open, sync-digest-relay-handoff-json, clear-digest-relay-handoff-json, push-archive-peer-export-json with composer focus. Bundle: npm run test:ci-phase692.

Phase 691 (v0.8.666): digest-json-modal-open, sync-hook-failure-digest-json, clear-hook-failure-digest-json, export-compliance-snapshot with composer focus. Bundle: npm run test:ci-phase691.

Phase 690 (v0.8.665): audit-json-modal-open, clear-mod-digest-notify, sync-audit-export-json composer focus. Bundle: npm run test:ci-phase690.

Phase 687 (v0.8.662): worker-modal-open → worker-modal-opened; composer focus after worker modal. Bundle: npm run test:ci-phase687.

Phase 685 (v0.8.660): webhook-modal-open → webhook-modal-opened; composer focus after webhook modal. Bundle: npm run test:ci-phase685.

Phase 684 (v0.8.659): bot-modal-open → bot-modal-opened; uninstall-bot composer focus. Bundle: npm run test:ci-phase684.

Phase 683 (v0.8.658): slash-modal-open → slash-modal-opened; slash command create/invoke IPC. Bundle: npm run test:ci-phase683.

Phase 682 (v0.8.657): member-roles-modal-open → member-roles-modal-opened; set-member-custom-roles composer focus. Bundle: npm run test:ci-phase682.

Phase 681 (v0.8.656): permissions-modal-open → permissions-modal-opened; update-guild-custom-role passes mentionable. Bundle: npm run test:ci-phase681.

Phase 680 (v0.8.655): announcement-follow-changed, retry-announcement-crosspost IPC + composer blur sidecar. Bundle: npm run test:ci-phase680.

Phase 679 (v0.8.654): thread-modal-open → thread-modal-opened; create-thread passes autoArchiveMinutes. Bundle: npm run test:ci-phase679.

Phase 668 (v0.8.643): IPC composer-embed-prefetch → platform prefetchComposerEmbed; composer-embed-preview-clear → clearComposerEmbedPreview. Bundle: npm run test:ci-phase668.

Phase 665 batch 2 (v0.8.640): IPC cancel-attachment-download, forward-attachment, open-attachment-in-viewer; download progress polling via attachment-download-progress event. Bundle: npm run test:phase665-media-batch2.

v0.8.638 (Phase 659): Added DM poll IPC routes: vote-dm-poll (optional voted desired-state) -> dm-poll-voted, edit-dm-poll -> dm-poll-edited, close-dm-poll -> dm-poll-closed, and delete-dm-poll -> dm-poll-deleted.

v0.8.638 (Phase 659): Added DM scheduled-message IPC routes: create-dm-scheduled-message, list-dm-scheduled-messages, cancel-dm-scheduled-message, and send-now-dm-scheduled-message.

v0.8.638 (Phase 658): Added audit-dm-thread-p2p IPC -> dm-thread-p2p-audit event to expose DM-thread topic safety diagnostics from platform.

v0.8.628 (Phase 655 batch 2): IPC rename-group-dm, start-dm-voice, start-dm-video; open-dm passes sidebarFilterActive. See DM_INBOX.md.

Phase 654 now active with 50 swarm/repl/sync items; composer production UI (autofocus, send btn, autogrow) landed with manual agentctl + BOOT_OK verification; platform/swarm-manager changes for adaptive retry + discovery aid.

v0.8.624 (Phase 652): export-mesh-replication-diagnostics → mesh-replication-diagnostics-exported; hub subscribe + composer focus. Bundle: npm run test:phase652-live-mesh-churn (app repo).

v0.8.617 (Phase 645): request-member-page → member-page-requested; archive-thread → thread-archive-result + composer focus. Bundle: npm run test:phase645-large-guild-mesh (app repo).

v0.8.622 (Phase 650): refresh-discovery-explore-scoped → discovery-explore-scoped-refreshed; async federation export. Bundle: npm run test:phase650-live-federation-mesh.

v0.8.621 (Phase 649): export-federation-sync-diagnostics → federation-sync-diagnostics-exported. Bundle: npm run test:phase649-federation-discovery (app repo).

v0.8.620 (Phase 648): export-multi-guild-sync-diagnostics → multi-guild-sync-diagnostics-exported. Bundle: npm run test:phase648-multi-guild-mesh (app repo).

v0.8.619 (Phase 647): export-partition-heal-diagnostics → partition-heal-diagnostics-exported; partition heal throttled result toast. Bundle: npm run test:phase647-production-mesh (app repo).

v0.8.618 (Phase 646): run-partition-heal-sync → partition-heal-result + composer focus. Bundle: npm run test:phase646-partition-heal (app repo).

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

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