pearcord-ui-flow

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

Phase 853 (v0.8.820): sync-guild-mesh-quad-offline-heal composite recovery IPC. Bundle: npm run test:ci-phase853.

Phase 852 (v0.8.819): sync-guild-mesh-quad-recovery-heal composite recovery IPC. Bundle: npm run test:ci-phase852.

Phase 851 (v0.8.818): sync-guild-mesh-quad-churn-heal composite recovery IPC. Bundle: npm run test:ci-phase851.

Phase 850 (v0.8.817): sync-guild-mesh-quad-partition-heal recovery IPC. Bundle: npm run test:ci-phase850.

Phase 849 (v0.8.816): sync-guild-mesh-quad-expression-soak composite IPC. Bundle: npm run test:ci-phase849.

Phase 848 (v0.8.815): sync-guild-mesh-quad-channel-lifecycle channel IPC. Bundle: npm run test:ci-phase848.

Phase 847 (v0.8.814): sync-guild-mesh-quad-sounds soundboard IPC. Bundle: npm run test:ci-phase847.

Phase 846 (v0.8.813): sync-guild-mesh-quad-channel-settings settings IPC. Bundle: npm run test:ci-phase846.

Phase 845 (v0.8.812): sync-guild-mesh-quad-topic topic IPC. Bundle: npm run test:ci-phase845.

Phase 844 (v0.8.811): sync-guild-mesh-quad-stickers sticker IPC. Bundle: npm run test:ci-phase844.

Phase 843 (v0.8.810): sync-guild-mesh-quad-emojis emoji IPC. Bundle: npm run test:ci-phase843.

Phase 842 (v0.8.809): sync-guild-mesh-quad-offline-recovery recovery IPC. Bundle: npm run test:ci-phase842.

Phase 841 (v0.8.808): sync-guild-mesh-quad-sync-health recovery IPC. Bundle: npm run test:ci-phase841.

Phase 840 (v0.8.807): sync-guild-mesh-quad-sync-pending recovery IPC. Bundle: npm run test:ci-phase840.

Phase 839 (v0.8.806): sync-guild-mesh-quad-roster-complete recovery IPC. Bundle: npm run test:ci-phase839.

Phase 838 (v0.8.805): sync-guild-mesh-quad-pins recovery IPC. Bundle: npm run test:ci-phase838.

Phase 837 (v0.8.804): sync-guild-mesh-quad-roles recovery IPC. Bundle: npm run test:ci-phase837.

Phase 836 (v0.8.803): sync-guild-mesh-quad-reactions recovery IPC. Bundle: npm run test:ci-phase836.

Phase 835 (v0.8.802): sync-guild-mesh-quad-typing recovery IPC. Bundle: npm run test:ci-phase835.

Phase 834 (v0.8.801): sync-guild-mesh-quad-voice recovery IPC. Bundle: npm run test:ci-phase834.

Phase 833 (v0.8.800): sync-guild-mesh-quad-unread recovery IPC. Bundle: npm run test:ci-phase833.

Phase 832 (v0.8.799): sync-guild-mesh-quad-roster recovery IPC. Bundle: npm run test:ci-phase832.

Phase 831 (v0.8.798): sync-guild-mesh-quad-presence recovery IPC. Bundle: npm run test:ci-phase831.

Phase 830 (v0.8.797): sync-guild-mesh-quad-recovery-burst recovery IPC. Bundle: npm run test:ci-phase830.

Phase 829 (v0.8.796): sync-guild-mesh-quad-churn-rejoin recovery IPC. Bundle: npm run test:ci-phase829.

Phase 828 (v0.8.795): sync-guild-mesh-quad-sync-burst recovery IPC. Bundle: npm run test:ci-phase828.

Phase 827 (v0.8.794): sync-guild-mesh-quad mesh IPC. Bundle: npm run test:ci-phase827.

Phase 826 (v0.8.793): sync-guild-mesh-triple-churn-rejoin recovery IPC. Bundle: npm run test:ci-phase826.

Phase 825 (v0.8.792): sync-guild-mesh-triple-recovery-burst recovery IPC. Bundle: npm run test:ci-phase825.

Phase 824 (v0.8.791): sync-guild-mesh-triple-sync-burst recovery IPC. Bundle: npm run test:ci-phase824.

Phase 823 (v0.8.790): sync-guild-mesh-triple-push-halt-clear recovery IPC. Bundle: npm run test:ci-phase823.

Phase 822 (v0.8.789): sync-guild-mesh-triple-topology light IPC. Bundle: npm run test:ci-phase822.

Phase 821 (v0.8.788): sync-guild-mesh-triple-ack-watermark recovery IPC. Bundle: npm run test:ci-phase821.

Phase 820 (v0.8.787): sync-guild-mesh-triple-roster-complete recovery IPC. Bundle: npm run test:ci-phase820.

Phase 819 (v0.8.786): sync-guild-mesh-triple-sync-pending recovery IPC. Bundle: npm run test:ci-phase819.

Phase 818 (v0.8.785): sync-guild-mesh-triple-sync-health recovery IPC. Bundle: npm run test:ci-phase818.

Phase 817 (v0.8.784): sync-guild-mesh-triple-offline-recovery recovery IPC. Bundle: npm run test:ci-phase817.

Phase 816 (v0.8.783): sync-guild-mesh-triple-partition-heal recovery IPC. Bundle: npm run test:ci-phase816.

Phase 815 (v0.8.782): sync-guild-mesh-triple-loading recovery IPC. Bundle: npm run test:ci-phase815.

Phase 814 (v0.8.781): sync-guild-mesh-triple-messages recovery IPC. Bundle: npm run test:ci-phase814.

Phase 813 (v0.8.780): sync-guild-mesh-triple-roster recovery IPC. Bundle: npm run test:ci-phase813.

Phase 812 (v0.8.779): sync-guild-mesh-triple-presence recovery IPC. Bundle: npm run test:ci-phase812.

Phase 811 (v0.8.778): sync-guild-mesh-triple-unread recovery IPC. Bundle: npm run test:ci-phase811.

Phase 810 (v0.8.777): sync-guild-mesh-triple-voice recovery IPC. Bundle: npm run test:ci-phase810.

Phase 809 (v0.8.776): sync-guild-mesh-triple-reconnect recovery IPC. Bundle: npm run test:ci-phase809.

Phase 808 (v0.8.775): sync-guild-mesh-triple-roles recovery IPC. Bundle: npm run test:ci-phase808.

Phase 807 (v0.8.774): sync-guild-mesh-triple-typing recovery IPC. Bundle: npm run test:ci-phase807.

Phase 806 (v0.8.773): sync-guild-mesh-triple-reactions recovery IPC. Bundle: npm run test:ci-phase806.

Phase 805 (v0.8.772): sync-guild-mesh-triple-pins recovery IPC. Bundle: npm run test:ci-phase805.

Phase 804 (v0.8.771): sync-guild-mesh-triple-sounds recovery IPC. Bundle: npm run test:ci-phase804.

Phase 803 (v0.8.770): sync-guild-mesh-triple-stickers recovery IPC. Bundle: npm run test:ci-phase803.

Phase 802 (v0.8.769): sync-guild-mesh-triple-emojis recovery IPC. Bundle: npm run test:ci-phase802.

Phase 801 (v0.8.768): sync-guild-mesh-triple-channel-delete recovery IPC. Bundle: npm run test:ci-phase801.

Phase 800 (v0.8.767): sync-guild-channel-lifecycle, sync-guild-mesh-triple-channels recovery IPC. Bundle: npm run test:ci-phase800.

Phase 799 (v0.8.766): sync-guild-mesh-triple-channel-settings → topology + channelSettings recovery. Bundle: npm run test:ci-phase799.

Phase 798 (v0.8.765): sync-guild-mesh-triple-topic → topology + channelTopic recovery. Bundle: npm run test:ci-phase798.

Phase 797 (v0.8.764): sync-guild-channel-topic → topic guild-sync-ready + structural push. Bundle: npm run test:ci-phase797.

Phase 796 (v0.8.763): sync-guild-partition-heal → force heal + structural push. Bundle: npm run test:ci-phase796.

Phase 795 (v0.8.762): sync-guild-mesh-triple → guild-mesh-topology emit + structural push. Bundle: npm run test:ci-phase795.

Phase 794 (v0.8.761): sync-guild-channel-settings → channel-settings emit + structural push. Bundle: npm run test:ci-phase794.

Phase 793 (v0.8.760): sync-guild-sounds → guild-sound emit + structural push. Bundle: npm run test:ci-phase793.

Phase 792 (v0.8.759): sync-guild-pins → pin emit + structural push. Bundle: npm run test:ci-phase792.

Phase 791 (v0.8.758): sync-guild-stickers → guild-sticker emit + structural push. Bundle: npm run test:ci-phase791.

Phase 790 (v0.8.757): sync-guild-emojis → guild-emoji emit + structural push. Bundle: npm run test:ci-phase790.

Phase 789 (v0.8.756): sync-guild-reactions → reaction emit + structural push. Bundle: npm run test:ci-phase789.

Phase 788 (v0.8.755): sync-guild-mesh-reconnect → offline recovery + structural push. Bundle: npm run test:ci-phase788.

Phase 787 (v0.8.754): sync-guild-roles → guild-member-roles emit + structural push. Bundle: npm run test:ci-phase787.

Phase 786 (v0.8.753): sync-guild-typing → typing emit + light push. Bundle: npm run test:ci-phase786.

Phase 785 (v0.8.752): sync-guild-voice → voice-state emit + fanout + structural push. Bundle: npm run test:ci-phase785.

Phase 784 (v0.8.751): sync-guild-unread → notification emit + fanout + structural push. Bundle: npm run test:ci-phase784.

Phase 783 (v0.8.750): sync-guild-sync-health → clear push halt + fanout + structural push. Bundle: npm run test:ci-phase783.

Phase 782 (v0.8.749): sync-guild-presence → requestGuildSyncFanout + structural push. Bundle: npm run test:ci-phase782.

Phase 780 (v0.8.747): sync-guild-loading → structural push + mesh join nudge (ui-loading-watchdog) when 0 peers. Bundle: npm run test:ci-phase780.

Phases 766–779 (v0.8.746): Settings IPC — settings-open, settings-close, settings-section-change, settings-save, settings-discard → settings-opened / settings-section-changed / settings-saved / settings-discarded. Role editor — role-editor-open, role-editor-close, role-editor-select, role-editor-save, role-editor-discard. Docs: UI_FLOW.md, IPC.md.

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.