@awiki/dsh-plugin 0.2.4 → 0.3.0-rc.1

package/lib/types/client/controller.js

@@ -1,4 +1,5 @@
 /** React-free browser controller for the deployment's one AWiki identity. */
+import { IndexedDbAwikiBrowserImageCache, } from "./image-cache.js";
 /** Turn a registration rejection into an actionable message without exposing remote response text. */
 function registrationFailureMessage(failure) {
     switch (failure.code) {
@@ -11,7 +12,7 @@ function registrationFailureMessage(failure) {
         case 'challenge-expired':
             return '验证码状态已失效，请重新获取验证码后再注册。';
         case 'handle-unavailable':
-            return '该 Handle 已存在，无法重复注册。请更换一个未使用的 Handle，并重新获取验证码。';
+            return '该 Handle 刚刚已被注册。请返回身份入口，再按恢复流程重新获取验证码。';
         case 'conflict':
             return '注册冲突：服务端可能已收到上次注册请求，或该手机号 / Handle 已绑定其他身份。请保留当前页面并再次提交；若仍失败，请勿清除本机身份数据，联系管理员并提供失败时间。';
         case 'rate-limited':
@@ -43,19 +44,40 @@ function registrationOtpFailureMessage(failure) {
             return registrationFailureMessage(failure);
     }
 }
+function identityAccessInspectionFailureMessage(failure) {
+    switch (failure.code) {
+        case 'invalid-request':
+            return 'Handle 格式不正确，请检查后重试。';
+        case 'network':
+            return '无法连接 AWiki 服务，暂时不能确认该 Handle 是否已经存在。';
+        case 'remote':
+            return 'AWiki 服务暂时无法确认该 Handle 的状态，请稍后重试。';
+        default:
+            return `${failure.code}：${failure.message}`;
+    }
+}
 const INITIAL_VIEW = Object.freeze({
     status: 'cold',
     sessionStatus: 'unregistered',
     identity: null,
+    profile: null,
     conversations: Object.freeze([]),
     conversationsHasMore: false,
     selectedConversationId: null,
+    selectedGroup: null,
+    groupMembers: Object.freeze([]),
+    groupMembersHasMore: false,
+    groupRecovery: null,
     messages: Object.freeze([]),
     historyHasMore: false,
+    localPending: false,
+    refreshing: false,
     pending: null,
     error: null,
     attachmentMaxBytes: 0,
     summaries: Object.freeze({}),
+    recoveryOperationId: null,
+    recoveryProgress: null,
 });
 /** Turn a closed Host summary failure into one actionable Chinese message. */
 function summaryFailureMessage(failure) {
@@ -68,12 +90,72 @@ function summaryFailureMessage(failure) {
         default: return `${failure.code}：${failure.message}`;
     }
 }
+/** Turn closed mail failures into safe, actionable browser messages. */
+function mailFailureMessage(failure) {
+    switch (failure.code) {
+        case 'invalid-request': return '邮件信息不完整或格式不正确，请检查后重试。';
+        case 'not-registered': return '请先注册 AWiki 身份后使用邮箱。';
+        case 'signed-out': return '当前 AWiki 身份已退出，请重新进入后使用邮箱。';
+        case 'forbidden': return '当前 AWiki 身份没有执行此邮件操作的权限。';
+        case 'not-found': return '该邮件不存在或已经不可访问。';
+        case 'rate-limited': return '邮件请求过于频繁，请稍后重试。';
+        case 'delivery-unknown': return '发送结果未知，请先检查已发送邮件再决定是否重试。';
+        case 'network': return '无法连接 AWiki 邮件服务，请检查网络后重试。';
+        default: return 'AWiki 邮件服务暂时不可用，请稍后重试。';
+    }
+}
+/** Turn a rejected group create into a concrete next step instead of exposing Host error text. */
+function groupCreateFailureMessage(failure) {
+    switch (failure.code) {
+        case 'invalid-request': return '群聊名称或首批成员格式不正确，请检查后重试。';
+        case 'not-registered': return '请先注册 AWiki 身份后创建群聊。';
+        case 'signed-out': return '当前 AWiki 身份已退出，请重新进入后创建群聊。';
+        case 'forbidden': return '当前 AWiki 身份没有创建群聊的权限。';
+        case 'rate-limited': return '创建群聊过于频繁，请稍后重试。';
+        case 'network': return '无法连接 AWiki 服务，请检查网络后重试。';
+        case 'conflict': return '群聊创建状态发生冲突，请刷新群聊列表后确认是否已经创建。';
+        case 'remote': return 'AWiki 服务暂时无法创建群聊，请稍后重试。';
+        default: return `${failure.code}：${failure.message}`;
+    }
+}
+/** Keep group authorization failures actionable without exposing raw service text. */
+function groupReadFailureMessage(failure) {
+    switch (failure.code) {
+        case 'group-membership-required':
+            return '当前身份暂时无法访问这个群聊。若刚完成身份恢复，请返回会话列表重试群聊身份恢复；若持续出现，可能已不再是群成员。';
+        case 'group-identity-stale':
+            return '群聊身份正在恢复，请稍候后重试。';
+        case 'not-found':
+            return '这个群聊不存在，或当前身份已经无法访问。';
+        case 'forbidden':
+            return '当前身份没有访问这个群聊的权限。';
+        case 'network':
+            return '无法连接 AWiki 群聊服务，请检查网络后重试。';
+        case 'remote':
+            return 'AWiki 暂时无法读取这个群聊，请稍后重试。';
+        default:
+            return `${failure.code}：${failure.message}`;
+    }
+}
+function groupRecoveryFailureMessage(failure) {
+    return failure.code === 'network'
+        ? '无法连接 AWiki 服务，暂时不能恢复旧群聊身份。'
+        : '暂时不能检查旧群聊身份，请稍后重试。';
+}
+function groupRecoveryView(summary) {
+    if (summary.blocked > 0) {
+        return { status: 'blocked', pending: summary.pending, blocked: summary.blocked };
+    }
+    return summary.pending > 0
+        ? { status: 'pending', pending: summary.pending, blocked: 0 }
+        : null;
+}
 /** Flatten the carrier and business result once for every controller caller. */
-async function call(operation, failureMessage = failure => `${failure.code}：${failure.message}`) {
+async function call(operation, failureMessage = failure => `${failure.code}：${failure.message}`, carrierFailureMessage = message => `连接 AWiki Host 失败：${message}`) {
     try {
         const carried = await operation();
         if (!carried.ok)
-            return { ok: false, error: `连接 AWiki Host 失败：${carried.error.message}` };
+            return { ok: false, error: carrierFailureMessage(carried.error.message) };
         if (!carried.value.ok) {
             return { ok: false, error: failureMessage(carried.value.error) };
         }
@@ -86,6 +168,11 @@ async function call(operation, failureMessage = failure => `${failure.code}：${
         };
     }
 }
+function recoveryCarrierFailureMessage(message) {
+    return message.includes('business result failed boundary validation')
+        ? '恢复信息已验证，但暂时无法读取恢复状态。请稍后重试。'
+        : `连接 AWiki Host 失败：${message}`;
+}
 /** Append unique values while retaining existing references. */
 function appendUnique(current, incoming, id) {
     const seen = new Set(current.map(id));
@@ -99,18 +186,75 @@ function appendUnique(current, incoming, id) {
     }
     return [...current, ...appended];
 }
-/** Prepend unique values while retaining the existing tail. */
-function prependUnique(current, incoming, id) {
-    const seen = new Set(current.map(id));
-    const prepended = [];
-    for (const value of incoming) {
-        const key = id(value);
-        if (seen.has(key))
-            continue;
-        seen.add(key);
-        prepended.push(value);
+/** Keep one last-wins value per canonical id without changing the page's order. */
+function canonicalMessagePage(incoming) {
+    const byId = new Map();
+    for (const message of incoming)
+        byId.set(message.id, message);
+    return [...byId.values()];
+}
+/** Replace the newest loaded window while preserving older messages before it. */
+function mergeLatestMessages(current, incoming) {
+    const page = canonicalMessagePage(incoming);
+    const incomingIds = new Set(page.map(message => message.id));
+    return [...current.filter(message => !incomingIds.has(message.id)), ...page];
+}
+/** Prepend one chronological continuation page while exact-updating any overlap. */
+function mergeOlderMessages(current, incoming) {
+    const page = canonicalMessagePage(incoming);
+    const incomingIds = new Set(page.map(message => message.id));
+    return [...page, ...current.filter(message => !incomingIds.has(message.id))];
+}
+/** Append a newly committed message, or enrich its existing canonical row in place. */
+function appendMessageById(current, incoming) {
+    const index = current.findIndex(message => message.id === incoming.id);
+    if (index < 0)
+        return [...current, incoming];
+    return current.map((message, currentIndex) => currentIndex === index ? incoming : message);
+}
+/** Explain a background failure without implying that visible local messages were lost. */
+function refreshFailureMessage(messages, error) {
+    return messages.length > 0 ? `刷新失败，当前显示本地数据。${error}` : error;
+}
+/** Reject a page that attempts to cross the selected canonical conversation boundary. */
+function pageBelongsToConversation(conversationId, messages) {
+    return messages.every(message => message.conversationId === conversationId);
+}
+function timingStart() {
+    return globalThis.performance?.now() ?? Date.now();
+}
+function clearConversationTimings() {
+    const performance = globalThis.performance;
+    if (performance === undefined)
+        return;
+    try {
+        for (const name of [
+            'conversation.select.local_timeline_ms',
+            'conversation.select.first_paint_ms',
+            'conversation.select.remote_history_ms',
+        ])
+            performance.clearMeasures(name);
+    }
+    catch {
+        // Performance measurement is optional in restricted browser/test runtimes.
+    }
+}
+/** Keep only one secret-free development measure for each selected-conversation phase. */
+function recordTiming(name, startedAt, success) {
+    const performance = globalThis.performance;
+    if (performance === undefined)
+        return;
+    try {
+        performance.clearMeasures(name);
+        performance.measure(name, {
+            start: startedAt,
+            end: performance.now(),
+            detail: { success, count: 1 },
+        });
+    }
+    catch {
+        // Performance measurement is optional in restricted browser/test runtimes.
     }
-    return [...prepended, ...current];
 }
 /** Strip surrounding space and a leading @ from a Handle the user typed. */
 function normalizeHandle(value) {
@@ -122,6 +266,34 @@ function sameIdentity(identity, peer) {
     const target = peer.toLowerCase();
     return own === target || own.startsWith(`${target}.`) || target.startsWith(`${own}.`);
 }
+/** Bounded readiness window for a newly projected group conversation. */
+const GROUP_HISTORY_RETRY_DELAYS_MS = [250, 750, 1_500, 2_500];
+/** Runtime-only decoded-byte budget that prevents repeat Host calls while browsing. */
+const BROWSER_IMAGE_ATTACHMENT_CACHE_MAX_BYTES = 32 * 1024 * 1024;
+const RECOVERY_OPERATION_STORAGE_KEY = 'awiki.handle-recovery.operation.v1';
+function storedRecoveryOperation() {
+    try {
+        return globalThis.localStorage?.getItem(RECOVERY_OPERATION_STORAGE_KEY) ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+function storeRecoveryOperation(operationId) {
+    try {
+        if (operationId === null)
+            globalThis.localStorage?.removeItem(RECOVERY_OPERATION_STORAGE_KEY);
+        else
+            globalThis.localStorage?.setItem(RECOVERY_OPERATION_STORAGE_KEY, operationId);
+    }
+    catch {
+        // Recovery remains durable in Core even when browser storage is unavailable.
+    }
+}
+/** Wait between group-history readiness probes without retaining controller state. */
+function delay(milliseconds) {
+    return new Promise(resolve => setTimeout(resolve, milliseconds));
+}
 /** Keys that can identify one direct peer in the current roster. */
 function directPeerKeys(conversation) {
     const keys = [conversation.peerDid, conversation.title];
@@ -136,18 +308,23 @@ function findDirect(conversations, peer) {
     const key = peer.toLowerCase();
     return conversations.find((conversation) => (conversation.kind === 'direct' && directPeerKeys(conversation).includes(key)));
 }
-/** Keep a profile refreshed from WNS when a slower roster page still carries an older message snapshot. */
-function preserveDirectProfile(incoming, current) {
-    if (incoming.kind !== 'direct' || current?.kind !== 'direct')
-        return incoming;
-    const displayName = current.displayName ?? incoming.displayName;
-    const peerHandle = current.peerHandle ?? incoming.peerHandle;
-    return {
-        ...incoming,
-        title: displayName ?? peerHandle ?? incoming.title,
-        ...(peerHandle === undefined ? {} : { peerHandle }),
-        ...(displayName === undefined ? {} : { displayName }),
-    };
+function groupMemberKey(member) {
+    return member.membershipId ?? member.did ?? member.credentialDid ?? member.handle ?? `${member.role ?? ''}:${member.joinedAt ?? ''}`;
+}
+/** True when a group title contains presentation data instead of a protocol fallback. */
+function hasDisplayableGroupTitle(conversation) {
+    if (conversation.kind !== 'group')
+        return false;
+    const title = conversation.title.trim();
+    return title !== '' && title !== conversation.groupDid && title !== conversation.id;
+}
+/** True when a direct title is richer than its routing identifiers. */
+function hasDisplayableDirectTitle(conversation) {
+    const title = conversation.title.trim().replace(/^@/u, '');
+    if (title === '')
+        return false;
+    return ![conversation.id, conversation.peerDid, conversation.peerHandle]
+        .some(value => value !== undefined && value.trim().replace(/^@/u, '') === title);
 }
 /** Resolve one listed conversation into the send target accepted by AWiki. */
 function targetOf(conversation) {
@@ -158,21 +335,37 @@ function targetOf(conversation) {
 /** Browser object layer for identity, conversations, history, and polling. */
 export class AwikiController {
     remote;
+    persistentImageCache;
     view = INITIAL_VIEW;
     listeners = new Set();
     config = null;
     conversationsCursor;
     historyCursor;
+    groupMembersCursor;
     timer;
     generation = 0;
+    selectionRevision = 0;
     disposed = false;
     polling = false;
     markReadInFlight = new Map();
     unreadAtOpen = new Map();
     summaryBaselines = new Map();
-    /** @param remote - generated Host Remote namespace. */
-    constructor(remote) {
+    /** Last trustworthy direct profile for the active identity, keyed by canonical peer DID. */
+    directProfiles = new Map();
+    /** Last trustworthy group title for the active identity, keyed by canonical Group DID. */
+    groupTitles = new Map();
+    /** Verified image payloads retained outside observable state for instant remounts. */
+    imageAttachments = new Map();
+    imageAttachmentCacheBytes = 0;
+    presentationCacheOwnerDid = null;
+    groupRecoveryOperation;
+    /**
+     * @param remote - generated Host Remote namespace.
+     * @param persistentImageCache - browser-origin verified preview cache.
+     */
+    constructor(remote, persistentImageCache = new IndexedDbAwikiBrowserImageCache()) {
         this.remote = remote;
+        this.persistentImageCache = persistentImageCache;
     }
     /** Return the cached immutable view. */
     getSnapshot = () => this.view;
@@ -181,11 +374,8 @@ export class AwikiController {
         this.listeners.add(listener);
         return () => { this.listeners.delete(listener); };
     };
-    /**
-     * Load Host policy and identity, then start polling while the drawer remains open.
-     * @returns successful readiness or one display-safe Host failure.
-     */
-    async open() {
+    /** Load Host policy and the shared identity state without starting drawer polling. */
+    async loadSession() {
         if (this.disposed)
             return { ok: false, error: 'AWiki 插件已卸载' };
         this.close();
@@ -204,21 +394,52 @@ export class AwikiController {
         if (!session.ok)
             return this.fail(session.error);
         const identity = session.value.status === 'active' ? session.value.identity : null;
+        this.activatePresentationCache(identity);
         this.publish({
             ...this.view,
             status: 'ready',
             sessionStatus: session.value.status,
-            identity,
+            identity: session.value.status === 'active' ? session.value.identity : null,
             error: null,
             attachmentMaxBytes: config.value.attachmentMaxBytes,
+            recoveryOperationId: storedRecoveryOperation(),
         });
         if (identity !== null) {
-            const listed = await this.refreshConversations(generation);
+            const profile = await call(() => this.remote.getProfile());
+            if (this.current(generation) && profile.ok)
+                this.publish({ ...this.view, profile: profile.value });
+        }
+        else {
+            const operationId = storedRecoveryOperation();
+            if (operationId !== null) {
+                const recovery = await call(() => this.remote.getRecoveryStatus({ operationId }));
+                if (this.current(generation) && recovery.ok) {
+                    this.publish({ ...this.view, recoveryOperationId: operationId, recoveryProgress: recovery.value });
+                    if (recovery.value.phase === 'applied') {
+                        storeRecoveryOperation(null);
+                        return this.loadSession();
+                    }
+                }
+            }
+        }
+        return { ok: true, value: undefined };
+    }
+    /**
+     * Load Host policy and identity, then start polling while the drawer remains open.
+     * @returns successful readiness or one display-safe Host failure.
+     */
+    async open() {
+        const loaded = await this.loadSession();
+        if (!loaded.ok)
+            return loaded;
+        const generation = this.generation;
+        if (this.view.identity !== null) {
+            const listed = await this.refreshConversationsAndRecoverGroups(generation);
             if (!listed.ok)
                 return listed;
         }
         if (this.current(generation)) {
-            this.timer = setInterval(() => { void this.poll(generation); }, this.config.pollIntervalMs);
+            this.timer = setInterval(() => { void this.poll(generation); }, this.config?.pollIntervalMs ?? 3_000);
         }
         return { ok: true, value: undefined };
     }
@@ -233,6 +454,7 @@ export class AwikiController {
         this.conversationsCursor = undefined;
         this.historyCursor = undefined;
         this.summaryBaselines.clear();
+        this.clearPresentationCache();
         this.publish({
             ...INITIAL_VIEW,
             status: 'ready',
@@ -256,11 +478,13 @@ export class AwikiController {
     /** Stop polling and invalidate all in-flight drawer work. */
     close() {
         this.generation += 1;
+        this.selectionRevision += 1;
         if (this.timer !== undefined)
             clearInterval(this.timer);
         this.timer = undefined;
         this.polling = false;
         this.markReadInFlight.clear();
+        this.groupMembersCursor = undefined;
     }
     /**
      * Request one phone verification challenge.
@@ -270,6 +494,10 @@ export class AwikiController {
     async sendRegistrationOtp(request) {
         return this.withPending('发送验证码', () => call(() => this.remote.sendRegistrationOtp(request), registrationOtpFailureMessage));
     }
+    /** Classify one Handle before sending exactly one registration or recovery OTP. */
+    async inspectIdentityAccess(request) {
+        return this.withPending('检查身份', () => call(() => this.remote.inspectIdentityAccess(request), identityAccessInspectionFailureMessage));
+    }
     /**
      * Register the deployment identity and populate the initial conversation list.
      * @param request - verified Handle, phone number, and one-time code.
@@ -282,8 +510,9 @@ export class AwikiController {
             return result;
         if (!this.current(generation))
             return result;
+        this.activatePresentationCache(result.value);
         this.publish({ ...this.view, sessionStatus: 'active', identity: result.value, error: null });
-        await this.refreshConversations(generation);
+        await this.refreshConversationsAndRecoverGroups(generation);
         return result;
     }
     /**
@@ -305,6 +534,135 @@ export class AwikiController {
         this.publish({ ...this.view, identity: result.value, error: null });
         return result;
     }
+    /** Save all supported public profile fields and keep identity/profile projections aligned. */
+    async updateProfile(request) {
+        const displayName = request.displayName.trim();
+        const bio = request.bio.trim();
+        const tags = request.tags.map(tag => tag.trim()).filter(tag => tag !== '');
+        if (displayName === '' || Array.from(displayName).length > 50)
+            return this.fail('昵称需要填写且不能超过 50 个字符');
+        if (Array.from(bio).length > 100)
+            return this.fail('个人简介不能超过 100 个字符');
+        if (tags.length > 5 || new Set(tags.map(tag => tag.toLocaleLowerCase())).size !== tags.length) {
+            return this.fail('最多填写 5 个不重复的标签');
+        }
+        const generation = this.generation;
+        const result = await this.withPending('保存资料', () => call(() => this.remote.updateProfile({ displayName, bio, tags })));
+        if (!result.ok || !this.current(generation))
+            return result;
+        const identity = this.view.identity === null ? null : { ...this.view.identity, displayName: result.value.displayName };
+        this.publish({ ...this.view, identity, profile: result.value, error: null });
+        return result;
+    }
+    /** Request a recovery OTP and persist only its secret-free operation id in the browser. */
+    async sendRecoveryOtp(request) {
+        const result = await this.withPending('发送恢复验证码', () => call(() => this.remote.sendRecoveryOtp(request), registrationOtpFailureMessage));
+        if (!result.ok)
+            return result;
+        storeRecoveryOperation(result.value.operationId);
+        this.publish({ ...this.view, recoveryOperationId: result.value.operationId, recoveryProgress: null });
+        return result;
+    }
+    /** Verify the recovery OTP without attempting the remote identity mutation yet. */
+    async prepareRecovery(request) {
+        const operationId = this.view.recoveryOperationId;
+        if (operationId === null)
+            return this.fail('请先获取恢复验证码');
+        const result = await this.withPending('验证恢复信息', () => call(() => this.remote.prepareRecovery({ ...request, operationId }), registrationFailureMessage, recoveryCarrierFailureMessage));
+        if (result.ok)
+            this.publish({ ...this.view, recoveryProgress: result.value });
+        return result;
+    }
+    /** Commit the prepared operation once. Unknown outcomes remain available through status refresh. */
+    async activateRecovery() {
+        const operationId = this.view.recoveryOperationId;
+        if (operationId === null)
+            return this.fail('没有可继续的身份恢复操作');
+        if (this.view.recoveryProgress?.phase !== 'ready_to_commit')
+            return this.fail('请先完成恢复信息验证');
+        const result = await this.withPending('恢复身份', () => call(() => this.remote.activateRecovery({ operationId }), registrationFailureMessage, recoveryCarrierFailureMessage));
+        if (!result.ok)
+            return result;
+        this.publish({ ...this.view, recoveryProgress: result.value });
+        if (result.value.phase === 'applied') {
+            storeRecoveryOperation(null);
+            this.publish({ ...this.view, recoveryOperationId: null, recoveryProgress: result.value });
+            await this.open();
+        }
+        return result;
+    }
+    /** Refresh Core status without repeating activation. */
+    async refreshRecoveryStatus() {
+        const operationId = this.view.recoveryOperationId;
+        if (operationId === null)
+            return this.fail('没有可查询的身份恢复操作');
+        const result = await this.withPending('刷新恢复状态', () => call(() => this.remote.getRecoveryStatus({ operationId }), undefined, recoveryCarrierFailureMessage));
+        if (!result.ok)
+            return result;
+        this.publish({ ...this.view, recoveryProgress: result.value });
+        if (result.value.phase === 'applied') {
+            storeRecoveryOperation(null);
+            this.publish({ ...this.view, recoveryOperationId: null, recoveryProgress: result.value });
+            await this.open();
+        }
+        return result;
+    }
+    /** Resume only a Core-declared retryable or uncertain phase. */
+    async resumeRecovery() {
+        const operationId = this.view.recoveryOperationId;
+        const progress = this.view.recoveryProgress;
+        if (operationId === null || progress === null)
+            return this.fail('请先刷新恢复状态');
+        if (!progress.retryable && !['remote_outcome_unknown', 'remote_committed', 'identity_transition_pending'].includes(progress.phase)) {
+            return this.fail('当前恢复状态不能重试');
+        }
+        const result = await this.withPending('继续恢复身份', () => call(() => this.remote.resumeRecovery({ operationId }), registrationFailureMessage, recoveryCarrierFailureMessage));
+        if (!result.ok)
+            return result;
+        this.publish({ ...this.view, recoveryProgress: result.value });
+        if (result.value.phase === 'applied') {
+            storeRecoveryOperation(null);
+            this.publish({ ...this.view, recoveryOperationId: null, recoveryProgress: result.value });
+            await this.open();
+        }
+        return result;
+    }
+    /** Discard only a pre-attempt operation. */
+    async discardRecovery() {
+        const operationId = this.view.recoveryOperationId;
+        if (operationId === null)
+            return { ok: true, value: undefined };
+        const phase = this.view.recoveryProgress?.phase;
+        if (phase !== undefined && phase !== 'awaiting_factor' && phase !== 'ready_to_commit') {
+            return this.fail('当前恢复状态不能取消');
+        }
+        const result = await this.withPending('取消身份恢复', () => call(() => this.remote.discardRecovery({ operationId })));
+        if (!result.ok)
+            return result;
+        storeRecoveryOperation(null);
+        this.publish({ ...this.view, recoveryOperationId: null, recoveryProgress: null });
+        return { ok: true, value: undefined };
+    }
+    /** Read the active deployment identity's public mailbox state. */
+    getMailAccount() {
+        return call(() => this.remote.getMailAccount(), mailFailureMessage);
+    }
+    /** List one browser-requested mailbox page without background polling. */
+    listMailInbox(request = {}) {
+        return call(() => this.remote.listMailInbox(request), mailFailureMessage);
+    }
+    /** Read one selected plain-text mail message without marking it read. */
+    readMail(request) {
+        return call(() => this.remote.readMail(request), mailFailureMessage);
+    }
+    /** Mark mail read only after the browser supplied an explicit selected id. */
+    markMailRead(request) {
+        return call(() => this.remote.markMailRead(request), mailFailureMessage);
+    }
+    /** Send one user-confirmed plain-text mail without retrying. */
+    sendMail(request) {
+        return call(() => this.remote.sendMail(request), mailFailureMessage);
+    }
     /**
      * Load another page of the conversation roster.
      * @returns successful pagination or one display-safe failure.
@@ -317,13 +675,24 @@ export class AwikiController {
         if (!this.current(generation))
             return { ok: true, value: undefined };
         this.conversationsCursor = result.value.nextCursor;
+        const conversations = result.value.items.map(incoming => this.cacheConversation(incoming, this.view.conversations.find(current => current.id === incoming.id)));
         this.publish({
             ...this.view,
-            conversations: appendUnique(this.view.conversations, result.value.items, value => value.id),
+            conversations: appendUnique(this.view.conversations, conversations, value => value.id),
             conversationsHasMore: result.value.hasMore && result.value.nextCursor !== undefined,
         });
         return { ok: true, value: undefined };
     }
+    /** Synchronize account projections, then retry Core's durable group-rebind journal. */
+    async retryGroupRebindRecovery() {
+        const generation = this.generation;
+        return this.withPending('恢复群聊身份', async () => {
+            const listed = await this.refreshConversations(generation, true);
+            if (!listed.ok)
+                return { ok: false, error: listed.error };
+            return this.resumeGroupRebindRecovery(generation);
+        });
+    }
     /**
      * Look up a Handle or DID, then open the matching direct conversation.
      * @param handle - peer Handle or DID typed by the user.
@@ -360,14 +729,14 @@ export class AwikiController {
             ?? findDirect(this.view.conversations, resolved.value.did);
         if (listed !== undefined)
             return this.selectConversation(listed.id);
-        const conversation = {
+        const conversation = this.cacheConversation({
             kind: 'direct',
             id: resolved.value.conversationId,
             peerDid: resolved.value.did,
             title: resolved.value.displayName ?? resolved.value.handle ?? resolved.value.did,
             ...resolved.value.handle === undefined ? {} : { peerHandle: resolved.value.handle },
             ...resolved.value.displayName === undefined ? {} : { displayName: resolved.value.displayName },
-        };
+        });
         this.publish({
             ...this.view,
             conversations: [conversation, ...this.view.conversations],
@@ -375,52 +744,395 @@ export class AwikiController {
         });
         return this.selectConversation(conversation.id);
     }
+    /**
+     * Create one group, add its initial members, and open the new canonical conversation.
+     * Group selection owns a bounded readiness retry so a fresh empty group can settle before
+     * its first history failure becomes visible.
+     * @param name - user-visible group name.
+     * @param members - Handle or DID values entered by the user.
+     * @returns the created group and settled invitation outcomes.
+     */
+    async createGroup(name, members) {
+        if (this.disposed)
+            return { ok: false, error: 'AWiki 插件已卸载' };
+        const normalizedName = name.trim();
+        if (normalizedName === '')
+            return this.fail('请输入群聊名称');
+        if (Array.from(normalizedName).length > 100)
+            return this.fail('群聊名称不能超过 100 个字符');
+        const normalizedMembers = [...new Set(members.map(normalizeHandle).filter(member => member !== ''))];
+        if (normalizedMembers.length > 50)
+            return this.fail('首批群成员不能超过 50 位');
+        const identity = this.view.identity;
+        if (identity === null)
+            return this.fail('请先注册 AWiki 身份');
+        if (normalizedMembers.some(member => member === identity.did || sameIdentity(identity, member))) {
+            return this.fail('群成员列表不需要包含自己');
+        }
+        const generation = this.generation;
+        const result = await this.withPending('创建群聊', () => call(() => this.remote.createGroup({
+            name: normalizedName,
+            members: normalizedMembers,
+        }), groupCreateFailureMessage));
+        if (!result.ok || !this.current(generation))
+            return result;
+        const conversation = this.cacheConversation(result.value.conversation);
+        this.publish({
+            ...this.view,
+            conversations: appendUnique([conversation], this.view.conversations, value => value.id),
+            error: null,
+        });
+        const selected = await this.selectConversation(result.value.conversation.id);
+        if (!this.current(generation))
+            return result;
+        const failed = result.value.failedMembers.map(item => item.member);
+        const warning = failed.length === 0
+            ? selected.ok ? null : '群聊已创建，但暂时无法打开消息历史。'
+            : `群聊已创建，但以下成员未加入：${failed.join('、')}`;
+        if (warning !== null)
+            this.publish({ ...this.view, error: warning });
+        return result;
+    }
+    /** Join one open group by its canonical DID, then select the refreshed conversation. */
+    async joinGroup(groupDidInput) {
+        const groupDid = groupDidInput.trim();
+        if (!groupDid.startsWith('did:'))
+            return this.fail('请输入有效的群 DID');
+        const generation = this.generation;
+        const result = await this.withPending('加入群聊', () => call(() => this.remote.joinGroup({ groupDid })));
+        if (!result.ok || !this.current(generation))
+            return result;
+        await this.refreshConversations(generation);
+        if (!this.current(generation))
+            return result;
+        const conversation = this.view.conversations.find(value => value.kind === 'group' && value.groupDid === groupDid)
+            ?? this.cacheConversation({
+                kind: 'group',
+                id: result.value.conversationId,
+                groupDid,
+                title: result.value.title,
+                unreadCount: 0,
+            });
+        this.publish({
+            ...this.view,
+            conversations: appendUnique([conversation], this.view.conversations, value => value.id),
+        });
+        await this.selectConversation(conversation.id);
+        return result;
+    }
+    /** Refresh the selected group's authoritative snapshot and first member page. */
+    async refreshSelectedGroup() {
+        const conversation = this.selectedConversation();
+        if (conversation?.kind !== 'group')
+            return this.fail('请先打开一个群聊');
+        return this.withPending('刷新群成员', async () => {
+            const refreshed = await this.loadGroupState(conversation, true);
+            return refreshed.ok ? { ok: true, value: undefined } : refreshed;
+        });
+    }
+    /** Load the next authoritative member page using Core's opaque cursor. */
+    async loadMoreGroupMembers() {
+        const group = this.view.selectedGroup;
+        if (group === null || this.groupMembersCursor === undefined)
+            return { ok: true, value: undefined };
+        const result = await this.withPending('加载更多群成员', () => call(() => this.remote.listGroupMembers({
+            groupDid: group.groupDid,
+            cursor: this.groupMembersCursor,
+            limit: 50,
+        })));
+        if (!result.ok)
+            return result;
+        if (result.value.pageGroup !== undefined && result.value.pageGroup !== group.groupDid) {
+            return this.fail('群成员分页归属不一致，请刷新后重试');
+        }
+        this.groupMembersCursor = result.value.nextCursor;
+        this.publish({
+            ...this.view,
+            groupMembers: appendUnique(this.view.groupMembers, result.value.items, groupMemberKey),
+            groupMembersHasMore: result.value.hasMore && result.value.nextCursor !== undefined,
+        });
+        return { ok: true, value: undefined };
+    }
+    /** Invite one ordinary member, then replace snapshot and roster with authoritative reads. */
+    async addSelectedGroupMember(memberInput) {
+        const group = this.view.selectedGroup;
+        const member = normalizeHandle(memberInput);
+        if (group === null)
+            return this.fail('请先打开一个群聊');
+        if (member === '')
+            return this.fail('请输入成员 Handle 或 DID');
+        if (this.view.identity !== null && (member === this.view.identity.did || sameIdentity(this.view.identity, member))) {
+            return this.fail('群成员列表不需要包含自己');
+        }
+        return await this.withPending('邀请群成员', async () => {
+            const invited = await call(() => this.remote.addGroupMember({
+                groupDid: group.groupDid,
+                member,
+            }));
+            if (!invited.ok)
+                return invited;
+            const refreshed = await this.reloadSelectedGroupAfterMutation(group.groupDid);
+            if (!refreshed.ok) {
+                return {
+                    ok: false,
+                    error: `已提交对 ${member} 的邀请，但成员列表刷新失败。请点击刷新查看最新状态。`,
+                };
+            }
+            return invited;
+        });
+    }
+    /** Remove one authorized member, then refresh count, roles, and roster from Core. */
+    async removeSelectedGroupMember(member) {
+        const group = this.view.selectedGroup;
+        const reference = member.did ?? member.handle;
+        if (group === null || reference === undefined)
+            return this.fail('该成员缺少可用的身份标识');
+        const result = await this.withPending('移除群成员', () => call(() => this.remote.removeGroupMember({
+            groupDid: group.groupDid,
+            member: reference,
+        })));
+        if (result.ok)
+            await this.reloadSelectedGroupAfterMutation(group.groupDid);
+        return result;
+    }
+    /** Leave the selected group; Core prevents the owner from leaving. */
+    async leaveSelectedGroup() {
+        const group = this.view.selectedGroup;
+        if (group === null)
+            return this.fail('请先打开一个群聊');
+        const generation = this.generation;
+        const result = await this.withPending('退出群聊', () => call(() => this.remote.leaveGroup({ groupDid: group.groupDid })));
+        if (!result.ok)
+            return result;
+        if (!this.current(generation))
+            return { ok: true, value: undefined };
+        this.groupMembersCursor = undefined;
+        this.publish({
+            ...this.view,
+            selectedConversationId: null,
+            selectedGroup: null,
+            groupMembers: [],
+            groupMembersHasMore: false,
+            messages: [],
+        });
+        await this.refreshConversations(generation);
+        return { ok: true, value: undefined };
+    }
     /**
      * Select a conversation and load its newest history page.
      * @param conversationId - selected conversation, or `null` to return to the roster.
      * @returns successful selection or one display-safe history failure.
      */
     async selectConversation(conversationId) {
+        clearConversationTimings();
+        const selectStartedAt = timingStart();
+        const previousConversationId = this.view.selectedConversationId;
+        const sameConversation = conversationId !== null && previousConversationId === conversationId;
+        const selectionRevision = ++this.selectionRevision;
         this.historyCursor = undefined;
+        this.groupMembersCursor = undefined;
         const selected = conversationId === null
             ? undefined
             : this.view.conversations.find(conversation => conversation.id === conversationId);
         if (selected !== undefined)
             this.unreadAtOpen.set(selected.id, selected.unreadCount ?? 0);
-        this.publish({ ...this.view, selectedConversationId: conversationId, messages: [], historyHasMore: false, error: null });
+        this.publish({
+            ...this.view,
+            selectedConversationId: conversationId,
+            selectedGroup: null,
+            groupMembers: [],
+            groupMembersHasMore: false,
+            messages: sameConversation ? this.view.messages : [],
+            historyHasMore: false,
+            localPending: conversationId !== null,
+            refreshing: false,
+            error: null,
+        });
+        if (selected?.kind === 'group')
+            void this.loadGroupState(selected, true);
         if (conversationId === null)
             return { ok: true, value: undefined };
         const generation = this.generation;
-        const profile = selected?.kind === 'direct'
-            ? call(() => this.remote.resolvePeer({ peer: selected.peerDid }))
-            : Promise.resolve(null);
-        const [loaded, refreshed] = await Promise.all([this.loadHistory(false), profile]);
-        if (refreshed?.ok
-            && this.current(generation)
-            && this.view.selectedConversationId === conversationId
-            && selected?.kind === 'direct'
-            && refreshed.value.did === selected.peerDid
-            && refreshed.value.conversationId === selected.id) {
+        const localStartedAt = timingStart();
+        const local = await call(() => this.remote.getLocalHistory({ conversationId }));
+        recordTiming('conversation.select.local_timeline_ms', localStartedAt, local.ok);
+        if (!this.currentSelection(generation, selectionRevision, conversationId)) {
+            return local.ok ? { ok: true, value: undefined } : local;
+        }
+        if (!local.ok) {
             this.publish({
                 ...this.view,
-                conversations: this.view.conversations.map((conversation) => {
-                    if (conversation.id !== conversationId || conversation.kind !== 'direct')
-                        return conversation;
-                    const displayName = refreshed.value.displayName ?? conversation.displayName;
-                    const peerHandle = refreshed.value.handle ?? conversation.peerHandle;
-                    return {
-                        ...conversation,
-                        title: displayName ?? peerHandle ?? conversation.title,
-                        ...(peerHandle === undefined ? {} : { peerHandle }),
-                        ...(displayName === undefined ? {} : { displayName }),
-                    };
-                }),
+                localPending: false,
+                refreshing: true,
+                error: local.error,
             });
+            void this.reconcileSelectedConversation(conversationId, generation, selectionRevision);
+            void this.refreshSelectedDirectProfile(selected, generation, selectionRevision);
+            return local;
         }
-        if (!loaded.ok)
-            return loaded;
+        if (!pageBelongsToConversation(conversationId, local.value.items)) {
+            return this.failSelectedConversation(generation, selectionRevision, conversationId, 'AWiki 本地消息归属不一致，请重新打开会话。');
+        }
+        this.publish({
+            ...this.view,
+            messages: mergeLatestMessages(this.view.messages, local.value.items),
+            localPending: false,
+            refreshing: true,
+            error: null,
+        });
+        recordTiming('conversation.select.first_paint_ms', selectStartedAt, true);
+        void this.reconcileSelectedConversation(conversationId, generation, selectionRevision);
+        void this.refreshSelectedDirectProfile(selected, generation, selectionRevision);
         return { ok: true, value: undefined };
     }
+    async loadGroupState(conversation, reset) {
+        const generation = this.generation;
+        const selectionRevision = this.selectionRevision;
+        const snapshot = await call(() => this.remote.getGroup({ groupDid: conversation.groupDid }), groupReadFailureMessage);
+        if (!snapshot.ok) {
+            if (this.currentSelection(generation, selectionRevision, conversation.id)) {
+                this.publish({ ...this.view, error: snapshot.error });
+            }
+            return snapshot;
+        }
+        const members = await call(() => this.remote.listGroupMembers({ groupDid: conversation.groupDid, limit: 50 }), groupReadFailureMessage);
+        if (!members.ok) {
+            if (this.currentSelection(generation, selectionRevision, conversation.id)) {
+                this.publish({ ...this.view, error: members.error });
+            }
+            return members;
+        }
+        if (!this.currentSelection(generation, selectionRevision, conversation.id))
+            return snapshot;
+        if (members.value.pageGroup !== undefined && members.value.pageGroup !== conversation.groupDid) {
+            return this.fail('群成员列表归属不一致，请刷新后重试');
+        }
+        this.groupMembersCursor = members.value.nextCursor;
+        this.publish({
+            ...this.view,
+            selectedGroup: snapshot.value,
+            groupMembers: reset
+                ? members.value.items
+                : appendUnique(this.view.groupMembers, members.value.items, groupMemberKey),
+            groupMembersHasMore: members.value.hasMore && members.value.nextCursor !== undefined,
+        });
+        return snapshot;
+    }
+    async reloadSelectedGroupAfterMutation(expectedGroupDid) {
+        const conversation = this.selectedConversation();
+        if (conversation?.kind !== 'group' || conversation.groupDid !== expectedGroupDid) {
+            return { ok: true, value: undefined };
+        }
+        const generation = this.generation;
+        const group = await this.loadGroupState(conversation, true);
+        if (!group.ok)
+            return group;
+        if (!this.current(generation))
+            return { ok: true, value: undefined };
+        await this.refreshConversations(generation, true);
+        return { ok: true, value: undefined };
+    }
+    async reconcileSelectedConversation(conversationId, generation, selectionRevision) {
+        const selected = this.view.conversations.find(conversation => conversation.id === conversationId);
+        const remoteStartedAt = timingStart();
+        const remote = await this.readRemoteHistoryWithGroupReadiness(selected, conversationId, generation, selectionRevision);
+        recordTiming('conversation.select.remote_history_ms', remoteStartedAt, remote.ok);
+        if (!this.currentSelection(generation, selectionRevision, conversationId))
+            return;
+        if (!remote.ok) {
+            this.publish({
+                ...this.view,
+                refreshing: false,
+                error: refreshFailureMessage(this.view.messages, remote.error),
+            });
+            return;
+        }
+        if (!pageBelongsToConversation(conversationId, remote.value.items)) {
+            this.failSelectedConversation(generation, selectionRevision, conversationId, 'AWiki 远端消息归属不一致，请重新打开会话。');
+            return;
+        }
+        this.historyCursor = remote.value.nextCursor;
+        const committed = await call(() => this.remote.getLocalHistory({ conversationId }));
+        if (!this.currentSelection(generation, selectionRevision, conversationId))
+            return;
+        if (!committed.ok) {
+            this.publish({
+                ...this.view,
+                refreshing: false,
+                error: refreshFailureMessage(this.view.messages, committed.error),
+            });
+            return;
+        }
+        if (!pageBelongsToConversation(conversationId, committed.value.items)) {
+            this.failSelectedConversation(generation, selectionRevision, conversationId, 'AWiki 本地消息归属不一致，请重新打开会话。');
+            return;
+        }
+        const existingIds = new Set(this.view.messages.map(message => message.id));
+        const incoming = committed.value.items.filter(message => !existingIds.has(message.id));
+        const existingError = this.view.error;
+        this.publish({
+            ...this.view,
+            messages: mergeLatestMessages(this.view.messages, committed.value.items),
+            historyHasMore: remote.value.hasMore && remote.value.nextCursor !== undefined,
+            refreshing: false,
+            error: existingError?.startsWith('群聊已创建，但以下成员未加入：') ? existingError : null,
+            summaries: this.staleSummaries(conversationId, incoming),
+        });
+    }
+    async readRemoteHistoryWithGroupReadiness(conversation, conversationId, generation, selectionRevision) {
+        if (conversation?.kind !== 'group') {
+            return call(() => this.remote.getHistory({ conversationId }));
+        }
+        for (const retryDelay of GROUP_HISTORY_RETRY_DELAYS_MS) {
+            const remote = await call(() => this.remote.getHistory({ conversationId }), groupReadFailureMessage);
+            if (remote.ok || !this.currentSelection(generation, selectionRevision, conversationId))
+                return remote;
+            await delay(retryDelay);
+            if (!this.currentSelection(generation, selectionRevision, conversationId))
+                return remote;
+        }
+        return call(() => this.remote.getHistory({ conversationId }), groupReadFailureMessage);
+    }
+    async refreshSelectedDirectProfile(selected, generation, selectionRevision) {
+        if (selected?.kind !== 'direct')
+            return;
+        const refreshed = await call(() => this.remote.resolvePeer({ peer: selected.peerDid }));
+        if (!refreshed.ok
+            || !this.currentSelection(generation, selectionRevision, selected.id)
+            || refreshed.value.did !== selected.peerDid
+            || refreshed.value.conversationId !== selected.id)
+            return;
+        this.publish({
+            ...this.view,
+            conversations: this.view.conversations.map((conversation) => {
+                if (conversation.id !== selected.id || conversation.kind !== 'direct')
+                    return conversation;
+                const displayName = refreshed.value.displayName ?? conversation.displayName;
+                const peerHandle = refreshed.value.handle ?? conversation.peerHandle;
+                this.directProfiles.set(conversation.peerDid, {
+                    ...(peerHandle === undefined ? {} : { peerHandle }),
+                    ...(displayName === undefined ? {} : { displayName, title: displayName }),
+                });
+                return this.cacheConversation({
+                    ...conversation,
+                    title: displayName ?? peerHandle ?? conversation.title,
+                    ...(peerHandle === undefined ? {} : { peerHandle }),
+                    ...(displayName === undefined ? {} : { displayName }),
+                });
+            }),
+        });
+    }
+    failSelectedConversation(generation, selectionRevision, conversationId, error) {
+        if (this.currentSelection(generation, selectionRevision, conversationId)) {
+            this.publish({
+                ...this.view,
+                localPending: false,
+                refreshing: false,
+                error,
+            });
+        }
+        return { ok: false, error };
+    }
     /**
      * Mark the selected conversation read after the UI proves its newest message is visible.
      * Repeated scroll and layout notifications share one Host request, while a failed
@@ -518,16 +1230,20 @@ export class AwikiController {
     /**
      * Send one text message to the selected direct or group conversation.
      * @param text - non-empty text prepared by the composer.
+     * @param clientMessageId - optional logical identity shared with the optimistic row.
      * @returns successful delivery or one display-safe failure.
      */
-    async sendText(text) {
+    async sendText(text, clientMessageId, mentions) {
         const conversation = this.selectedConversation();
         if (conversation === undefined)
             return this.fail('请先选择会话');
         const conversationId = conversation.id;
         const generation = this.generation;
         const result = await this.withPending('发送消息', () => call(() => this.remote.sendText({
-            target: targetOf(conversation), text, idempotencyKey: crypto.randomUUID(),
+            target: targetOf(conversation),
+            text,
+            idempotencyKey: clientMessageId ?? crypto.randomUUID(),
+            ...mentions === undefined || mentions.length === 0 ? {} : { mentions },
         })));
         if (!result.ok)
             return result;
@@ -554,7 +1270,7 @@ export class AwikiController {
             mimeType: file.mimeType,
             bytesBase64: file.bytesBase64,
             ...(file.caption === undefined ? {} : { caption: file.caption }),
-            idempotencyKey: crypto.randomUUID(),
+            idempotencyKey: file.clientMessageId ?? crypto.randomUUID(),
         };
         const result = await this.withPending('发送附件', () => call(() => this.remote.sendAttachment(request)));
         if (!result.ok)
@@ -574,9 +1290,34 @@ export class AwikiController {
     async downloadAttachment(messageId, attachmentId) {
         if (this.disposed)
             return { ok: false, error: 'AWiki 插件已卸载' };
+        const cacheKey = `${String(messageId)}\u0000${String(attachmentId)}`;
+        const cached = this.imageAttachments.get(cacheKey);
+        if (cached !== undefined) {
+            this.imageAttachments.delete(cacheKey);
+            this.imageAttachments.set(cacheKey, cached);
+            return { ok: true, value: cached };
+        }
         const generation = this.generation;
+        const ownerDid = this.presentationCacheOwnerDid;
+        if (ownerDid !== null) {
+            const persisted = await this.persistentImageCache.read(ownerDid, messageId, attachmentId).catch(() => undefined);
+            if (!this.current(generation))
+                return { ok: false, error: 'AWiki 已关闭' };
+            if (persisted !== undefined) {
+                this.cacheImageAttachment(cacheKey, persisted);
+                return { ok: true, value: persisted };
+            }
+        }
         const result = await call(() => this.remote.downloadAttachment({ attachmentId, messageId }));
-        return this.current(generation) ? result : { ok: false, error: 'AWiki 已关闭' };
+        if (!this.current(generation))
+            return { ok: false, error: 'AWiki 已关闭' };
+        if (result.ok && result.value.attachment.mimeType.startsWith('image/')) {
+            this.cacheImageAttachment(cacheKey, result.value);
+            if (ownerDid !== null) {
+                void this.persistentImageCache.write(ownerDid, messageId, result.value).catch(() => undefined);
+            }
+        }
+        return result;
     }
     /** Clear Host-owned local data and immediately remove every cached browser projection. */
     async clearLocalData(request) {
@@ -585,12 +1326,15 @@ export class AwikiController {
         const result = await call(() => this.remote.clearLocalData(request));
         if (!result.ok)
             return result;
+        await this.persistentImageCache.clear().catch(() => undefined);
         this.close();
         this.config = null;
         this.conversationsCursor = undefined;
         this.historyCursor = undefined;
         this.unreadAtOpen.clear();
         this.summaryBaselines.clear();
+        this.clearPresentationCache();
+        storeRecoveryOperation(null);
         this.publish({ ...INITIAL_VIEW, status: 'ready' });
         return result;
     }
@@ -600,16 +1344,19 @@ export class AwikiController {
         this.close();
         this.listeners.clear();
     }
-    async refreshConversations(generation) {
+    async refreshConversations(generation, background = false) {
         const result = await call(() => this.remote.listConversations({}));
         if (!this.current(generation))
             return { ok: true, value: undefined };
         if (!result.ok)
-            return this.fail(result.error);
+            return background ? result : this.fail(result.error);
         const firstPage = this.view.conversations.length === 0;
         if (firstPage)
             this.conversationsCursor = result.value.nextCursor;
-        const refreshed = result.value.items.map(incoming => preserveDirectProfile(incoming, this.view.conversations.find(current => current.id === incoming.id)));
+        const refreshed = result.value.items.map((incoming) => {
+            const current = this.view.conversations.find(value => value.id === incoming.id);
+            return this.cacheConversation(incoming, current);
+        });
         this.publish({
             ...this.view,
             conversations: firstPage
@@ -618,10 +1365,40 @@ export class AwikiController {
             conversationsHasMore: firstPage
                 ? result.value.hasMore && result.value.nextCursor !== undefined
                 : this.view.conversationsHasMore,
-            error: null,
+            error: background ? this.view.error : null,
         });
         return { ok: true, value: undefined };
     }
+    /** Hydrate account-projected groups before asking Core to resume their durable rebind jobs. */
+    async refreshConversationsAndRecoverGroups(generation, background = false) {
+        const listed = await this.refreshConversations(generation, background);
+        if (!listed.ok || !this.current(generation))
+            return listed;
+        await this.resumeGroupRebindRecovery(generation);
+        return listed;
+    }
+    resumeGroupRebindRecovery(generation) {
+        const active = this.groupRecoveryOperation;
+        if (active !== undefined && active.generation === generation)
+            return active.operation;
+        let operation;
+        operation = call(() => this.remote.resumeGroupRebindRecovery(), groupRecoveryFailureMessage).then((result) => {
+            if (!this.current(generation))
+                return result;
+            this.publish({
+                ...this.view,
+                groupRecovery: result.ok
+                    ? groupRecoveryView(result.value)
+                    : { status: 'unavailable', pending: 0, blocked: 0 },
+            });
+            return result;
+        }).finally(() => {
+            if (this.groupRecoveryOperation?.operation === operation)
+                this.groupRecoveryOperation = undefined;
+        });
+        this.groupRecoveryOperation = { generation, operation };
+        return operation;
+    }
     async loadHistory(older) {
         const conversationId = this.view.selectedConversationId;
         if (conversationId === null)
@@ -631,17 +1408,21 @@ export class AwikiController {
             conversationId,
             ...(older && this.historyCursor !== undefined ? { cursor: this.historyCursor } : {}),
         };
-        const result = await this.withPending(older ? '加载更早消息' : '加载消息', () => call(() => this.remote.getHistory(request)));
+        const selected = this.view.conversations.find(value => value.id === conversationId);
+        const result = await this.withPending(older ? '加载更早消息' : '加载消息', () => call(() => this.remote.getHistory(request), selected?.kind === 'group' ? groupReadFailureMessage : undefined));
         if (!result.ok)
             return result;
         if (!this.current(generation))
             return { ok: true, value: undefined };
         if (this.view.selectedConversationId !== conversationId)
             return { ok: true, value: undefined };
+        if (!pageBelongsToConversation(conversationId, result.value.items)) {
+            return this.fail('AWiki 远端消息归属不一致，请重新打开会话。');
+        }
         this.historyCursor = result.value.nextCursor;
         const messages = older
-            ? prependUnique(this.view.messages, result.value.items, value => value.id)
-            : result.value.items;
+            ? mergeOlderMessages(this.view.messages, result.value.items)
+            : mergeLatestMessages(this.view.messages, result.value.items);
         this.publish({
             ...this.view,
             // SDK pages are chronological. A continuation page contains older
@@ -657,16 +1438,26 @@ export class AwikiController {
             return;
         this.polling = true;
         try {
-            await this.refreshConversations(generation);
+            const knownGroups = new Set(this.view.conversations
+                .filter(conversation => conversation.kind === 'group')
+                .map(conversation => conversation.groupDid));
+            const listed = await this.refreshConversations(generation, true);
+            if (listed.ok && this.view.conversations.some(conversation => conversation.kind === 'group' && !knownGroups.has(conversation.groupDid))) {
+                await this.resumeGroupRebindRecovery(generation);
+            }
             const selected = this.view.selectedConversationId;
             if (selected === null || !this.current(generation))
                 return;
             const result = await call(() => this.remote.getHistory({ conversationId: selected }));
             if (!this.current(generation) || !result.ok || this.view.selectedConversationId !== selected)
                 return;
+            if (!pageBelongsToConversation(selected, result.value.items)) {
+                this.publish({ ...this.view, error: 'AWiki 远端消息归属不一致，请重新打开会话。' });
+                return;
+            }
             const existingIds = new Set(this.view.messages.map(message => message.id));
             const incoming = result.value.items.filter(message => !existingIds.has(message.id));
-            const messages = appendUnique(this.view.messages, result.value.items, value => value.id);
+            const messages = mergeLatestMessages(this.view.messages, result.value.items);
             const added = messages.length - this.view.messages.length;
             if (added > 0 && (this.unreadAtOpen.get(selected) ?? 0) > 0) {
                 this.unreadAtOpen.set(selected, (this.unreadAtOpen.get(selected) ?? 0) + added);
@@ -693,8 +1484,10 @@ export class AwikiController {
         return result;
     }
     appendMessage(message) {
+        if (this.view.selectedConversationId !== message.conversationId)
+            return;
         const isNew = !this.view.messages.some(current => current.id === message.id);
-        const messages = appendUnique(this.view.messages, [message], value => value.id);
+        const messages = appendMessageById(this.view.messages, message);
         if ((this.unreadAtOpen.get(message.conversationId) ?? 0) > 0 && messages.length > this.view.messages.length) {
             this.unreadAtOpen.set(message.conversationId, (this.unreadAtOpen.get(message.conversationId) ?? 0) + 1);
         }
@@ -738,6 +1531,104 @@ export class AwikiController {
         const selected = this.view.selectedConversationId;
         return selected === null ? undefined : this.view.conversations.find(value => value.id === selected);
     }
+    /** Keep presentation-only cache entries isolated to one authenticated identity. */
+    activatePresentationCache(identity) {
+        const ownerDid = identity?.did ?? null;
+        if (ownerDid === this.presentationCacheOwnerDid)
+            return;
+        this.directProfiles.clear();
+        this.groupTitles.clear();
+        this.clearImageAttachments();
+        this.presentationCacheOwnerDid = ownerDid;
+    }
+    /** Drop every browser projection without touching the Core-owned SQLite cache. */
+    clearPresentationCache() {
+        this.directProfiles.clear();
+        this.groupTitles.clear();
+        this.clearImageAttachments();
+        this.presentationCacheOwnerDid = null;
+    }
+    /** Retain recently used verified image bytes without exposing them in AwikiView. */
+    cacheImageAttachment(key, value) {
+        if (value.attachment.size > BROWSER_IMAGE_ATTACHMENT_CACHE_MAX_BYTES)
+            return;
+        const previous = this.imageAttachments.get(key);
+        if (previous !== undefined)
+            this.imageAttachmentCacheBytes -= previous.attachment.size;
+        this.imageAttachments.delete(key);
+        this.imageAttachments.set(key, Object.freeze({
+            attachment: Object.freeze({ ...value.attachment }),
+            bytesBase64: value.bytesBase64,
+        }));
+        this.imageAttachmentCacheBytes += value.attachment.size;
+        while (this.imageAttachmentCacheBytes > BROWSER_IMAGE_ATTACHMENT_CACHE_MAX_BYTES) {
+            const oldestKey = this.imageAttachments.keys().next().value;
+            if (oldestKey === undefined)
+                break;
+            const oldest = this.imageAttachments.get(oldestKey);
+            this.imageAttachments.delete(oldestKey);
+            if (oldest !== undefined)
+                this.imageAttachmentCacheBytes -= oldest.attachment.size;
+        }
+    }
+    clearImageAttachments() {
+        this.imageAttachments.clear();
+        this.imageAttachmentCacheBytes = 0;
+    }
+    /**
+     * Reconcile direct identity and group title projections with their last trustworthy values.
+     * Core remains authoritative; this browser cache only prevents sparse refreshes from
+     * replacing already resolved presentation data with protocol identifiers.
+     */
+    cacheConversation(incoming, current) {
+        if (incoming.kind === 'direct') {
+            const active = current?.kind === 'direct' && current.peerDid === incoming.peerDid ? current : undefined;
+            const cached = this.directProfiles.get(incoming.peerDid);
+            const incomingDisplayName = incoming.displayName?.trim();
+            const displayName = active?.displayName
+                ?? cached?.displayName
+                ?? (incomingDisplayName === undefined || incomingDisplayName === '' ? undefined : incomingDisplayName);
+            const peerHandle = active?.peerHandle ?? cached?.peerHandle ?? incoming.peerHandle;
+            const title = displayName
+                ?? (active !== undefined && hasDisplayableDirectTitle(active) ? active.title : undefined)
+                ?? cached?.title
+                ?? (hasDisplayableDirectTitle(incoming) ? incoming.title : undefined)
+                ?? peerHandle
+                ?? incoming.title;
+            if (displayName !== undefined || peerHandle !== undefined || hasDisplayableDirectTitle(incoming)) {
+                this.directProfiles.set(incoming.peerDid, {
+                    ...(peerHandle === undefined ? {} : { peerHandle }),
+                    ...(displayName === undefined ? {} : { displayName }),
+                    ...hasDisplayableDirectTitle({ ...incoming, title }) ? { title } : {},
+                });
+            }
+            return {
+                ...incoming,
+                title,
+                ...(peerHandle === undefined ? {} : { peerHandle }),
+                ...(displayName === undefined ? {} : { displayName }),
+            };
+        }
+        return this.cacheGroupTitle(incoming, current);
+    }
+    /**
+     * Reconcile one group roster row with the last trustworthy local presentation.
+     * A real remote/Core title may update the cache; a temporary Group DID fallback may not.
+     */
+    cacheGroupTitle(incoming, current) {
+        if (incoming.kind !== 'group')
+            return incoming;
+        if (hasDisplayableGroupTitle(incoming)) {
+            this.groupTitles.set(incoming.groupDid, incoming.title);
+            return incoming;
+        }
+        if (current?.kind === 'group' && current.groupDid === incoming.groupDid && hasDisplayableGroupTitle(current)) {
+            this.groupTitles.set(incoming.groupDid, current.title);
+            return { ...incoming, title: current.title };
+        }
+        const cached = this.groupTitles.get(incoming.groupDid);
+        return cached === undefined ? incoming : { ...incoming, title: cached };
+    }
     fail(error) {
         this.publish({ ...this.view, status: this.view.status === 'loading' ? 'error' : this.view.status, pending: null, error });
         return { ok: false, error };
@@ -745,6 +1636,11 @@ export class AwikiController {
     current(generation) {
         return !this.disposed && generation === this.generation;
     }
+    currentSelection(generation, selectionRevision, conversationId) {
+        return this.current(generation)
+            && selectionRevision === this.selectionRevision
+            && this.view.selectedConversationId === conversationId;
+    }
     publish(view) {
         /* v8 ignore next -- every asynchronous and public mutation path checks disposal before publishing. */
         if (this.disposed)