@arcfold/dsh-method-ui 0.0.0-stage → 0.4.0

package/src/MethodDock.mjs

@@ -0,0 +1,145 @@
+import { presentationLabel } from './locales.mjs';
+import React, { useRef, useState } from 'react';
+const h = React.createElement;
+const text = (key, value) => h('div', { className: 'text', key }, value ?? '');
+
+export function MethodDock({ useMethods, onDetails, onDecide, onAcknowledge, onRefresh, onPage, t }) {
+  const state = useMethods(value => value);
+  const [expanded, setExpanded] = useState(false);
+  const [detail, setDetail] = useState(null);
+  const [detailLoading, setDetailLoading] = useState(false);
+  const [busy, setBusy] = useState(false);
+  const [error, setError] = useState(null);
+  const [notice, setNotice] = useState(null);
+  const actionPending = useRef(false), detailGeneration = useRef(0), retryIds = useRef(new Map());
+
+  async function show(methodId, keepError = false) {
+    const generation = ++detailGeneration.current;
+    setDetailLoading(true); setExpanded(true);
+    if (!keepError) { setError(null); setNotice(null); }
+    try {
+      const value = await onDetails(methodId);
+      if (generation === detailGeneration.current) setDetail(value);
+    } catch (failure) {
+      if (generation === detailGeneration.current) { setDetail(null); setError(failure.message || t('failed')); }
+    } finally {
+      if (generation === detailGeneration.current) setDetailLoading(false);
+    }
+  }
+  function closeDetail() {
+    detailGeneration.current++; setDetail(null); setDetailLoading(false);
+  }
+  async function historyPage(offset) {
+    if (!detail) return;
+    const methodId = detail.method.id, generation = ++detailGeneration.current;
+    setDetailLoading(true); setError(null);
+    try {
+      const value = await onDetails(methodId, offset);
+      if (generation === detailGeneration.current) setDetail(current => current?.method.id === methodId
+        ? { ...current, notifications: value.notifications } : current);
+      // History reads do not silently replace the full method/version the user
+      // is deciding on. A deliberate reload or conflict refresh does that.
+    } catch (failure) {
+      if (generation === detailGeneration.current) setError(failure.message || t('failed'));
+    } finally { if (generation === detailGeneration.current) setDetailLoading(false); }
+  }
+  async function decide(action) {
+    if (actionPending.current || detailLoading || !detail) return;
+    actionPending.current = true; setBusy(true); setError(null); setNotice(null);
+    // The request comes from the displayed detail, never a newer unseen list item.
+    const request = { methodId: detail.method.id, expectedRevision: detail.method.revision,
+      contentHash: detail.contentHash, action };
+    const key = JSON.stringify(request);
+    if (!retryIds.current.has(key)) retryIds.current.set(key, globalThis.crypto.randomUUID());
+    request.requestId = retryIds.current.get(key);
+    try {
+      await onDecide(request);
+      retryIds.current.delete(key);
+      setNotice(t('saved'));
+      await show(request.methodId, true);
+    } catch (failure) {
+      if (failure.remote) retryIds.current.delete(key);
+      setError(failure.remote ? failure.message : `${failure.message || t('failed')} ${t('unknown')}`);
+      if (failure.code === 'revision_conflict' || failure.code === 'method_superseded' || failure.code === 'method_source_invalid') {
+        setError(`${failure.message || ''} ${t('conflict')}`);
+        await show(request.methodId, true);
+      }
+    } finally { actionPending.current = false; setBusy(false); }
+  }
+  async function acknowledge(id) {
+    if (actionPending.current) return;
+    actionPending.current = true; setBusy(true); setError(null);
+    try { await onAcknowledge(id); await historyPage(detail?.notifications?.offset ?? 0); }
+    catch (failure) { setError(failure.message || t('failed')); }
+    finally { actionPending.current = false; setBusy(false); }
+  }
+  const button = (label, action, disabled = false, extra = {}) => h('button', { type: 'button', disabled,
+    onClick: () => { void action(); }, ...extra }, label);
+  const method = detail?.method;
+  const history = detail?.notifications;
+  return h('section', { className: 'arcfold-methods', 'aria-label': t('title') },
+    h('header', null,
+      h('strong', null, `${t('title')} · ${t('pending')} ${state.decisionCount} · ${t('unread')} ${state.unreadCount}`),
+      button(expanded ? t('close') : t('open'), () => setExpanded(!expanded), false, { 'aria-expanded': expanded }),
+      button(t('refresh'), onRefresh)),
+    state.loading && h('p', { role: 'status' }, t('loading')),
+    state.error && h('p', { role: 'alert' }, state.error),
+    expanded && h('div', { className: 'detail' },
+      error && h('p', { role: 'alert' }, error),
+      notice && h('p', { role: 'status' }, notice),
+      !method && !detailLoading && h('ul', null, state.items.map(item => h('li', { key: item.method.id },
+        h('strong', null, item.method.title),
+        h('p', { className: 'meta' }, `${presentationLabel('method', item.method.status, t)} · ${t('version')} ${item.method.version ?? 1}`),
+        text('current-reason', item.reason),
+        item.needsDecision && h('p', null, t('decisionPrompt')),
+        item.unreadCount > 0 && h('p', { className: 'meta' }, `${t('unread')} ${item.unreadCount}`),
+        button(t(item.needsDecision ? 'reviewDecision' : 'viewDetails'), () => show(item.method.id), busy)))),
+      !method && !detailLoading && !state.loading && !state.error && !state.items.length && h('p', null, t('empty')),
+      !method && !detailLoading && (state.offset > 0 || state.nextOffset != null) && h('nav', { 'aria-label': t('title') },
+        button(t('previous'), () => onPage(Math.max(0, state.offset - 20)), state.offset === 0),
+        button(t('next'), () => onPage(state.nextOffset), state.nextOffset === null || state.nextOffset === undefined)),
+      detailLoading && h('p', { role: 'status' }, t('loading')),
+      method && h('ul', null, h('li', null, h('article', { 'aria-label': method.title },
+        button(t('backToMethods'), closeDetail, busy),
+        h('h3', null, method.title),
+        h('p', { className: 'meta' }, [`${t('version')} ${method.version ?? 1}`,
+          method.revision != null ? `${t('revision')} ${method.revision}` : null,
+          `${t('status')} ${presentationLabel('method', method.status, t)}`].filter(Boolean).join(' · ')),
+        h('h4', null, t('reason')), text('reason', detail.reason),
+        detail.needsDecision && h('p', null, t('decisionPrompt')),
+        detail.usage && h('p', null, `${t('usage')} ${detail.usage.trialUses}/${detail.usage.maxTrialUses} · ${t('remaining')} ${detail.usage.remaining}`),
+        detail.pendingAdoptionCount > 0 && h('div', null,
+          h('h4', null, `${t('pendingAdoptions')} ${detail.pendingAdoptionCount}`),
+          (detail.pendingAdoptions || []).map(adoption => h('p', { className: 'meta', key: adoption.id },
+            `${adoption.id} · ${t('conversation')} ${adoption.sessionId} · ${t('turn')} ${adoption.turn} · ${presentationLabel('adoption', adoption.state, t)}`))),
+        method.guidance !== undefined && h('div', null,
+          h('h4', null, t('guidance')), text('guidance', method.guidance),
+          h('h4', null, t('applies')), text('applies', method.appliesTo),
+          h('h4', null, t('excludes')), text('excludes', method.doesNotApplyTo)),
+        h('h4', null, t('sources')),
+        detail.sources.length ? detail.sources.map(source => h('div', { className: 'source', key: source.id },
+          h('p', { className: 'meta' }, `${t('sourceIdentity')}: ${source.id} · ${t('revision')} ${source.revision} · ${t('author')}: ${presentationLabel('role', source.role, t)} · ${t('sourceTime')}: ${source.occurredAt ?? ''}`),
+          text('content', source.content),
+          h('p', { className: 'meta' }, `${t('provenance')}: ${JSON.stringify(source.provenance ?? null)}`))) : h('p', null, t('noSources')),
+        detail.successors.length > 0 && h('div', null, h('h4', null, t('successors')),
+          detail.successors.map(next => h('p', { key: next.id },
+            `${next.title} · ${t('version')} ${next.version} · ${presentationLabel('method', next.status, t)} `,
+            button(t('open'), () => show(next.id), busy)))),
+        !detail.activation.allowed && method.status !== 'active' && h('p', { role: 'alert' }, detail.activation.message),
+        h('p', { className: 'meta' }, t('boundary')),
+        h('div', { className: 'actions' },
+          button(busy ? t('busy') : t('continue'), () => decide('continue'), busy || detailLoading || !detail.activation.allowed),
+          button(t(method.status === 'paused' ? 'keepPaused' : 'pause'), () => decide('pause'),
+            busy || detailLoading || !(['trial', 'active'].includes(method.status) || method.status === 'paused' && detail.needsDecision)),
+          button(t('retry'), () => show(method.id), busy)),
+        h('details', { key: method.id, 'aria-label': t('history') },
+          h('summary', null, `${t('history')} ${history?.total ?? 0} · ${t('unread')} ${history?.unreadCount ?? 0}`),
+          h('ul', null, (history?.items || []).map(item => h('li', { key: item.id },
+            h('strong', null, item.title), text('message', item.displayMessage ?? item.message),
+            h('p', { className: 'meta' }, `${t('version')} ${item.methodVersion} · ${item.createdAt ?? ''}`),
+            item.status === 'unread' ? button(t('acknowledge'), () => acknowledge(item.id), busy || detailLoading) : h('span', null, t('read'))))),
+          !history?.total && h('p', null, t('noNotifications')),
+          (history?.offset > 0 || history?.nextOffset != null) && h('nav', { 'aria-label': t('history') },
+            button(t('previous'), () => historyPage(Math.max(0, history.offset - 20)), busy || detailLoading || history.offset === 0),
+            button(t('next'), () => historyPage(history.nextOffset), busy || detailLoading || history.nextOffset == null))))))));
+}

package/src/ModelSettings.mjs

@@ -0,0 +1,144 @@
+import React, { useEffect, useRef, useState } from 'react';
+import { deployedRoutes, validLearningChoice } from './model-settings-source.mjs';
+const h = React.createElement;
+const PHASE_LABELS = { ready: 'modelsPhaseReady', starting: 'modelsPhaseStarting',
+  'requires-restart': 'modelsPhaseRestart', failed: 'modelsPhaseFailed', closed: 'modelsPhaseClosed' };
+const REASON_LABELS = {
+  'main-not-configured': 'modelsReasonNoModel', 'learn-not-configured': 'modelsReasonNoModel',
+  'native-credential-not-configured': 'modelsReasonCredential',
+  'transport-not-configured': 'modelsReasonUnsupported', 'selected-route-not-supported': 'modelsReasonUnsupported',
+  'selected-model-controls-unavailable': 'modelsReasonUnsupported', 'main-output-limit-unavailable': 'modelsReasonUnsupported',
+  'selection-outside-model-policy': 'modelsReasonUnsupported', 'model-catalog-controls-invalid': 'modelsReasonUnsupported',
+  'model-catalog-has-no-common-controls': 'modelsReasonUnsupported',
+  'native-selection-changed-during-status': 'modelsReasonChanged', 'learning-selection-changed-during-status': 'modelsReasonChanged',
+  'runtime-not-ready': 'modelsReasonNotReady', 'runtime-readiness-unavailable': 'modelsReasonNotReady',
+  'guard-unavailable': 'modelsReasonNotReady', 'startup-failed': 'modelsReasonNotReady', 'runtime-closed': 'modelsReasonNotReady',
+  'runtime-restart-required': 'modelsReasonRestart', 'critical-component-changed': 'modelsReasonRestart',
+  'critical-configuration-changed': 'modelsReasonRestart', 'model-topology-changed': 'modelsReasonRestart',
+};
+const EFFORT_LABELS = { off: 'modelsEffortOff', low: 'modelsEffortLow', medium: 'modelsEffortMedium',
+  high: 'modelsEffortHigh', xhigh: 'modelsEffortXHigh', max: 'modelsEffortMax' };
+const reasonText = (reason, t) => t(REASON_LABELS[reason] || 'modelsReasonUnknown');
+const effortText = (effort, t) => t(EFFORT_LABELS[effort] || 'modelsEffortOther');
+const selectionText = (value, t) => value ? [value.provider, value.model,
+  value.reasoningEffort ? effortText(value.reasoningEffort, t) : null].filter(Boolean).join(' · ') : '';
+function outcomeText(result, t, credential = false) {
+  if (result?.status === 'saved') return t(result.refreshed ? 'modelsSaved' : 'modelsSavedUnread');
+  if (credential) return t(result?.status === 'unknown' ? 'modelsCredentialUnknown' : 'modelsCredentialFailed');
+  return t(result?.status === 'unknown' ? 'modelsUnknown' : result?.code === 'conflict' ? 'modelsConflict' : 'modelsRefused');
+}
+function CredentialCard({ route, info, disabled, readFailed, onStore, onRemove, t }) {
+  const [draft, setDraft] = useState(''), [busy, setBusy] = useState(false), [notice, setNotice] = useState('');
+  const pending = useRef(false), mounted = useRef(true);
+  useEffect(() => { mounted.current = true; return () => { mounted.current = false; }; }, []);
+  async function write(remove) {
+    if (pending.current || disabled || !info?.writable) return;
+    pending.current = true; setBusy(true); setNotice('');
+    const value = draft;
+    setDraft('');
+    try {
+      const result = remove ? await onRemove(route.provider) : await onStore(route.provider, value);
+      if (mounted.current) setNotice(outcomeText(result, t, true));
+    } catch {
+      if (mounted.current) setNotice(t('modelsCredentialUnknown'));
+    } finally {
+      pending.current = false;
+      if (mounted.current) { setDraft(''); setBusy(false); }
+    }
+  }
+  return h('article', { className: 'model-card' }, h('h3', null, route.label),
+    h('p', null, readFailed ? t('modelsCredentialReadFailed') : t(info?.configured ? 'modelsConfigured' : 'modelsNotConfigured')),
+    info?.source && h('p', { className: 'meta' }, t('modelsSource') + ': ' + info.source),
+    !readFailed && !info?.writable && h('p', null, t('modelsReadOnly')),
+    h('label', null, route.label + ' · ' + t('modelsCredential'),
+      h('input', { type: 'password', value: draft, autoComplete: 'new-password', spellCheck: false,
+        disabled: disabled || busy || !info?.writable,
+        onChange: event => setDraft(event.target.value) })),
+    h('div', { className: 'actions' },
+      h('button', { type: 'button', disabled: disabled || busy || !info?.writable || !draft.trim(), onClick: () => { void write(false); } }, t('modelsCredentialSave')),
+      h('button', { type: 'button', disabled: disabled || busy || !info?.writable || !info?.configured, onClick: () => { void write(true); } }, t('modelsCredentialRemove')),
+      h('button', { type: 'button', onClick: () => { setDraft(''); setNotice(''); } }, t('modelsCredentialCancel'))),
+    notice && h('p', { role: 'status' }, notice));
+}
+function Usage({ route, t }) {
+  const usage = route.usage;
+  const scope = { limited: 'modelsScopeLimited', 'web-unlimited': 'modelsScopeWeb', 'web-openai': 'modelsScopeOpenai' };
+  const row = (label, value) => h('div', { key: label }, h('dt', null, t(label)), h('dd', null, value));
+  return h('article', { className: 'model-card' }, h('h3', null, route.label),
+    !usage ? h('p', null, t('modelsUsageMissing')) : h(React.Fragment, null,
+      h('p', { className: 'meta' }, scope[usage.scope] ? t(scope[usage.scope]) : usage.scope),
+      h('dl', null, row('modelsRequests', usage.requests), row('modelsUnknownCount', usage.unknownCount),
+        usage.accounting === 'cny' ? [
+          row('modelsSpent', '¥ ' + usage.spentCny), row('modelsReserved', '¥ ' + usage.reservedCny),
+          row('modelsCeiling', usage.ceilingCny === null ? t('modelsNoCeiling') : '¥ ' + usage.ceilingCny),
+        ] : [
+          row('modelsPrompt', usage.promptTokens), row('modelsCompletion', usage.completionTokens),
+          row('modelsCached', usage.cachedTokens), row('modelsPending', usage.pendingCount),
+        ]),
+      usage.accounting === 'tokens_only' && h('p', null, t('modelsTokensOnly'))));
+}
+function LearningForm({ data, disabled, onSave, t }) {
+  const defaults = data.learning?.defaults;
+  const [draft, setDraft] = useState(() => ({ ...defaults }));
+  const [busy, setBusy] = useState(false), [notice, setNotice] = useState('');
+  const pending = useRef(false), mounted = useRef(true);
+  useEffect(() => { mounted.current = true; return () => { mounted.current = false; }; }, []);
+  useEffect(() => { setDraft({ ...defaults }); }, [defaults?.revision, defaults?.provider, defaults?.model, defaults?.reasoningEffort]);
+  const routes = deployedRoutes(data), route = routes.find(row => row.provider === draft.provider);
+  const model = route?.models?.find(row => row.id === draft.model);
+  const blocked = disabled || busy || data.gate?.phase !== 'ready' || !data.learning?.enabled ||
+    !defaults;
+  const select = (label, value, options, update) => h('label', { key: label }, t(label),
+    h('select', { value: options.some(item => item.id === value) ? value : '', disabled: blocked,
+      onChange: event => update(event.target.value) },
+    h('option', { value: '', disabled: true }, t('modelsChoose')),
+    options.map(item => h('option', { key: item.id, value: item.id }, item.label || item.id))));
+  async function save() {
+    if (pending.current || blocked || !validLearningChoice(data, draft)) return;
+    pending.current = true; setBusy(true); setNotice('');
+    try {
+      const result = await onSave({ expectedRevision: defaults.revision, provider: draft.provider,
+        model: draft.model, reasoningEffort: draft.reasoningEffort });
+      if (mounted.current) setNotice(outcomeText(result, t));
+    } catch { if (mounted.current) setNotice(t('modelsUnknown')); }
+    finally { pending.current = false; if (mounted.current) setBusy(false); }
+  }
+  return h('div', null,
+    !data.learning?.enabled && h('p', null, t('modelsLearnDisabled')),
+    !defaults && h('p', null, t('modelsNoDefault')),
+    !data.learning?.availability?.available && h('p', null, reasonText(data.learning?.availability?.reason, t)),
+    defaults && h('p', { className: 'meta' }, t('modelsRevision') + ': ' + defaults.revision + ' · ' + selectionText(defaults, t)),
+    h('div', { className: 'model-fields' },
+      select('modelsProvider', draft.provider, routes.map(row => ({ id: row.provider, label: row.label })),
+        provider => { setNotice(''); setDraft({ provider, model: '', reasoningEffort: '' }); }),
+      select('modelsModel', draft.model, route?.models || [],
+        model => { setNotice(''); setDraft({ ...draft, model, reasoningEffort: '' }); }),
+      select('modelsReasoning', draft.reasoningEffort, (model?.reasoningEfforts || []).map(id => ({ id, label: effortText(id, t) })),
+        reasoningEffort => { setNotice(''); setDraft({ ...draft, reasoningEffort }); })),
+    h('button', { type: 'button', disabled: blocked || !validLearningChoice(data, draft), onClick: () => { void save(); } },
+      t(busy ? 'modelsBusy' : 'modelsSave')),
+    notice && h('p', { role: 'status' }, notice));
+}
+export function ModelSettings({ useModels, onRefresh, onSaveLearning, onStoreCredential, onRemoveCredential, t }) {
+  const state = useModels(value => value), data = state.data;
+  return h('section', { className: 'arcfold-methods arcfold-model-settings', 'aria-label': t('modelsTitle') },
+    h('header', null, h('h2', null, t('modelsTitle')),
+      h('button', { type: 'button', disabled: state.loading, onClick: () => { void onRefresh(); } }, t('modelsRefresh'))),
+    state.loading && h('p', { role: 'status' }, t('modelsLoading')),
+    state.error && h('p', { role: 'alert' }, t('modelsReadFailed')),
+    data && h(React.Fragment, null,
+      h('p', { className: 'meta' }, t('modelsGate') + ': ' + t(PHASE_LABELS[data.gate.phase] || 'modelsReasonUnknown') + (data.gate.reason ? ' · ' + reasonText(data.gate.reason, t) : '')),
+      h('h3', null, t('modelsMain')), h('p', null, t('modelsMainScope')),
+      h('p', null, t('modelsDefault') + ': ' + (selectionText(data.main?.defaultSelection, t) || t('modelsUnavailable'))),
+      !data.main?.availability?.available && h('p', null, reasonText(data.main?.availability?.reason, t)),
+      h('h3', null, t('modelsLearn')), h('p', null, t('modelsLearnScope')),
+      h(LearningForm, { data,
+        disabled: Boolean(state.error || state.loading), onSave: onSaveLearning, t }),
+      h('h3', null, t('modelsCredentials')), h('p', null, t('modelsCredentialScope')),
+      !deployedRoutes(data).length && h('p', null, t('modelsNoRoutes')),
+      deployedRoutes(data).map(route => h(CredentialCard, { key: route.provider + ':' + route.apiKeyRef, route,
+        info: state.credentials[route.apiKeyRef], readFailed: state.credentialError,
+        disabled: Boolean(state.error || state.loading), onStore: onStoreCredential, onRemove: onRemoveCredential, t })),
+      h('h3', null, t('modelsUsage')), h('p', null, t('modelsUsageBoundary')),
+      deployedRoutes(data).map(route => h(Usage, { key: route.provider, route, t }))));
+}

package/src/OpportunityDock.mjs

@@ -0,0 +1,66 @@
+import React, { useEffect, useState } from 'react';
+const h = React.createElement;
+
+function status(item, t) {
+  const key = item.control?.dismissed ? 'opportunityDismissed' : item.stopped ? 'opportunityStopped'
+    : !item.run ? (item.rejection ? 'opportunityRejected' : 'opportunityPending')
+    : ({ prepared: 'opportunityPrepared', submitted: 'opportunitySubmitted', unknown: 'opportunityUncertain',
+      stopped: 'opportunityStopped', settled: 'opportunitySettled' }[item.run.state] ?? 'presentationUnknown');
+  return t(key);
+}
+
+function OpportunityCard({ item, readDetails, sessionId, t }) {
+  const [detail, setDetail] = useState(null), [error, setError] = useState(null);
+  useEffect(() => {
+    let active = true;
+    // Browsing never grants permission, marks a notice as read, starts
+    // preparation, or submits a new instruction.
+    Promise.resolve().then(() => readDetails(item.opportunity.id)).then(value => {
+      if (active) setDetail(value);
+    }, failure => { if (active) setError(failure.message); });
+    return () => { active = false; };
+  }, [item.opportunity.id, readDetails]);
+  const current = detail ?? item, row = current.opportunity;
+  return h('article', { className: 'opportunity-card', 'aria-label': row.description },
+    h('div', { className: 'opportunity-status' },
+      h('span', { className: 'status-badge' }, status(current, t)),
+      current.notice && h('span', { className: 'meta' }, t(current.notice.status === 'unread' ? 'opportunityUnread' : 'opportunityAlreadyRead'))),
+    h('h3', { className: 'text' }, row.description),
+    sessionId && row.conversationId !== sessionId && h('p', { className: 'meta' }, t('browseOtherSession')),
+    row.rationale && h('div', { className: 'opportunity-field' }, h('h4', null, t('opportunityRationale')), h('p', { className: 'text' }, row.rationale)),
+    row.suggestedPreparation && h('div', { className: 'opportunity-field' }, h('h4', null, t('opportunitySuggestion')), h('p', { className: 'text' }, row.suggestedPreparation)),
+    error && h('p', { role: 'alert' }, error),
+    current.reason && (current.run || current.control || current.rejection) && h('p', { className: 'meta' }, current.reason),
+    current.rejection && !current.run && h('p', { role: 'alert' }, current.rejection.error.message),
+    current.run?.error && h('p', { role: 'alert' }, current.run.error.message),
+    current.artifact && h('div', { className: 'opportunity-draft' }, h('h4', null, t('opportunityDraft')),
+      !current.available && h('p', { role: 'alert' }, t('opportunityStopped')),
+      h('p', { className: 'meta' }, current.artifact.evidence.path), h('pre', { className: 'text' }, current.artifact.evidence.text),
+      h('p', { className: 'meta' }, t('opportunityNotUsefulYet'))),
+    detail && h('details', { className: 'opportunity-evidence' }, h('summary', null, t('opportunityEvidence')),
+      h('pre', { className: 'text' }, JSON.stringify(detail.run?.input ?? detail.originals, null, 2))));
+}
+
+export function OpportunityDock({ useOpportunities, onOpportunityDetails, onOpportunityRefresh, onOpportunityPage, opportunitySessionId, viewScope, t }) {
+  const state = useOpportunities(value => value);
+  const [open, setOpen] = useState(false), [refreshVersion, setRefreshVersion] = useState(0);
+  const button = (label, action, disabled = false, extra = {}) => h('button', { type: 'button', disabled, onClick: action, ...extra }, label);
+  return h('section', { className: 'arcfold-methods arcfold-opportunities', 'aria-label': t('opportunityTitle') },
+    h('header', null, h('strong', null, `${t('opportunityTitle')} · ${state.total}`),
+      button(t(open ? 'opportunityHide' : 'opportunityOpen'), () => setOpen(!open), false, { 'aria-expanded': open }),
+      button(t('refresh'), () => { setRefreshVersion(value => value + 1); void onOpportunityRefresh(); })),
+    state.error && h('p', { role: 'alert' }, state.error),
+    open && h('div', { className: 'detail opportunity-content' },
+      h('div', { className: 'opportunity-overview' },
+        h('p', null, t('opportunityReadOnly')),
+        viewScope !== 'all' && h('div', { className: 'opportunity-status' }, h('span', { className: 'status-badge' }, t(state.permission?.enabled ? 'opportunityOn' : 'opportunityOff'))),
+        state.workspace && h('p', { className: 'meta' }, `${t('opportunityWorkspace')} · ${state.workspace}`)),
+      h('ul', { className: 'opportunity-list' }, state.items.map(item => h('li', {
+        // Versioned snapshots discard late reads across reconnects and refresh.
+        key: JSON.stringify([item, state.permission?.revision, state.resetVersion, refreshVersion]),
+      }, h(OpportunityCard, { item, readDetails: onOpportunityDetails, sessionId: opportunitySessionId, t })))),
+      !state.loading && !state.items.length && h('p', { className: 'meta' }, t('opportunityEmpty'))),
+    open && (state.offset > 0 || state.nextOffset != null) && h('nav', { className: 'opportunity-pagination', 'aria-label': t('opportunityTitle') },
+      button(t('previous'), () => onOpportunityPage(Math.max(0, state.offset - 20)), !state.offset),
+      button(t('next'), () => onOpportunityPage(state.nextOffset), state.nextOffset == null)));
+}

package/src/UnderstandingDock.mjs

@@ -0,0 +1,117 @@
+import { presentationLabel } from './locales.mjs';
+import React, { useEffect, useRef, useState } from 'react';
+const h = React.createElement;
+const literal = value => typeof value === 'string' ? value : JSON.stringify(value ?? '');
+export function UnderstandingDock({ useUnderstandings, onUnderstandingDetails, onUnderstandingDecide,
+  onUnderstandingCorrect, onUnderstandingRefresh, onUnderstandingPage, t }) {
+  const state = useUnderstandings(value => value);
+  const [expanded, expand] = useState(false), [detail, setDetail] = useState(null), [edit, setEdit] = useState(null);
+  const [busy, setBusy] = useState(false), [loading, setLoading] = useState(false), [notice, setNotice] = useState(''), [error, setError] = useState('');
+  const generation = useRef(0), pending = useRef(false), identities = useRef(new Map()), mounted = useRef(true);
+  useEffect(() => { mounted.current = true; return () => { mounted.current = false; generation.current++; }; }, []);
+  useEffect(() => {
+    generation.current++; setDetail(null); setEdit(null); setLoading(false); setError(''); setNotice('');
+  }, [state.readEpoch]);
+  async function show(id, retainNotice = false, retainedEdit = null) {
+    const current = ++generation.current; setLoading(true); setEdit(null); setDetail(null);
+    if (!retainNotice) { setError(''); setNotice(''); }
+    try {
+      const value = await onUnderstandingDetails(id);
+      if (mounted.current && current === generation.current) {
+        setDetail(value);
+        if (retainedEdit?.id === value.understanding.id && retainedEdit.revision === value.understanding.revision) setEdit(retainedEdit);
+      }
+    }
+    catch (failure) { if (mounted.current && current === generation.current) setError(failure.message || t('failed')); }
+    finally { if (mounted.current && current === generation.current) setLoading(false); }
+  }
+  async function refresh() {
+    const current = generation.current, id = detail?.understanding.id;
+    try {
+      await onUnderstandingRefresh();
+      if (mounted.current && current === generation.current && id) await show(id);
+    } catch (failure) { if (mounted.current && current === generation.current) setError(failure.message || t('failed')); }
+  }
+  async function act(action, source) {
+    if (pending.current || loading || !detail || detail.browse?.related === false) return;
+    const current = detail.understanding, selectedGeneration = generation.current;
+    if (action === 'correct' && (!edit || edit.id !== current.id || edit.revision !== current.revision || !edit.text.trim())) return;
+    const request = { understandingId: current.id, expectedRevision: current.revision,
+      ...(action === 'correct' ? { text: edit.text } : { action }),
+      ...(source ? { sourceRef: { id: source.id, revision: source.revision, expectedControlRevision: source.expectedControlRevision } } : {}) };
+    const key = JSON.stringify(request);
+    if (!identities.current.has(key)) identities.current.set(key, globalThis.crypto.randomUUID());
+    request.requestId = identities.current.get(key);
+    pending.current = true; setBusy(true); setNotice(''); setError('');
+    try {
+      const value = await (action === 'correct' ? onUnderstandingCorrect(request) : onUnderstandingDecide(request));
+      if (!mounted.current || selectedGeneration !== generation.current) return;
+      const command = value.command;
+      setNotice(t(command?.result?.state === 'applied' ? 'understandingApplied' : command?.result?.state === 'failed' ? 'understandingFailed'
+        : action !== 'correct' ? 'understandingSaved' : command?.admission?.state === 'accepted' ? 'understandingPending' : 'understandingUnknown'));
+      await onUnderstandingRefresh();
+      if (mounted.current && selectedGeneration === generation.current)
+        await show(current.id, true, action === 'correct' && !command?.result && command?.admission?.state !== 'accepted' ? edit : null);
+    } catch (failure) {
+      if (mounted.current && selectedGeneration === generation.current) {
+        if (failure.code === 'revision_conflict') {
+          setError(failure.message || t('failed'));
+          await show(current.id, true);
+        } else setError((failure.message || t('failed')) + ' ' + t('understandingUnknown'));
+      }
+    } finally { pending.current = false; if (mounted.current) setBusy(false); }
+  }
+  const button = (label, action, disabled = false, props = {}) => h('button', { type: 'button', disabled,
+    onClick: () => { void action(); }, ...props }, t(label));
+  const body = value => h('div', { className: 'text' }, literal(value));
+  const item = detail?.understanding;
+  const claim = value => presentationLabel('claim', value, t);
+  return h('section', { className: 'arcfold-methods arcfold-understandings', 'aria-label': t('understandingTitle') },
+    h('header', null, h('strong', null, `${t('understandingTitle')} · ${state.total}`),
+      button(expanded ? 'understandingHide' : 'understandingOpen', () => expand(!expanded), false, { 'aria-expanded': expanded }),
+      button('refresh', refresh, busy || loading)),
+    expanded && h('div', { className: 'detail' },
+      h('p', { className: 'meta' }, t('understandingBoundary')),
+      (state.loading || loading) && h('p', { role: 'status' }, t('understandingLoading')),
+      (error || state.error) && h('p', { role: 'alert' }, error || state.error), notice && h('p', { role: 'status' }, notice),
+      h('ul', null, state.items.map(row => h('li', { key: row.understanding.id },
+        body(row.understanding.content), h('p', { className: 'meta' }, claim(row.understanding.claimType)),
+        button('understandingOpen', () => show(row.understanding.id), busy || loading)))),
+      !state.loading && !state.error && !state.items.length && h('p', null, t('understandingEmpty')),
+      h('nav', null, button('previous', () => onUnderstandingPage(Math.max(0, state.offset - 20)), busy || loading || !state.offset),
+        button('next', () => onUnderstandingPage(state.nextOffset), busy || loading || state.nextOffset == null)),
+      item && h('article', { 'aria-label': t('understandingTitle') + ' ' + item.id },
+        h('h3', null, claim(item.claimType)), body(item.content),
+        detail.browse?.related === false && h('p', { className: 'meta' }, t('browseReturnToOrigin')),
+        h('p', { className: 'meta' }, `${t('revision')} ${item.revision} · ${t('understandingVersion')} ${item.version ?? '—'} · ${presentationLabel('understanding', item.status, t)} · ${t(detail.availability.allowed ? 'understandingAvailable' : 'understandingUnavailable')}`),
+        !detail.availability.allowed && h('p', null, detail.availability.message),
+        h('p', { className: 'meta' }, t('understandingWithdrawalHelp')),
+        h('div', { className: 'actions' },
+          button('understandingStop', () => act('stop-understanding'), busy || loading || !detail.controls?.stopAllowed),
+          button('understandingCorrect', () => setEdit({ id: item.id, revision: item.revision, text: item.content }), busy || loading || !detail.controls?.correctionAllowed)),
+        edit && h('div', { className: 'understanding-correction' },
+          h('p', null, t('understandingCorrectionHelp')),
+          h('label', null, t('understandingReplacement'), h('textarea', { value: edit.text, maxLength: 16000, disabled: busy || loading,
+            onChange: event => setEdit({ ...edit, text: event.target.value }) })),
+          button('understandingSubmit', () => act('correct'), busy || loading || !edit.text.trim()),
+          button('understandingCancel', () => setEdit(null), busy)),
+        h('h4', null, t('understandingSource')),
+        (detail.sources || []).map(source => h('div', { className: 'source', key: source.id },
+          h('p', { className: 'meta' }, `${source.id} · ${source.author && source.author !== source.role ? source.author : presentationLabel('role', source.role, t)} · ${source.occurredAt || ''} · ${t('revision')} ${source.revision ?? '—'} · ${t(source.available ? 'understandingAvailable' : 'understandingUnavailable')}`),
+          body(source.missing ? t('understandingMissing') : source.content),
+          h('details', null, h('summary', null, t('understandingProvenance')), body(source.provenance), source.control && body(source.control)),
+          button('understandingWithdraw', () => act('withdraw-source', source), busy || loading || detail.controls?.sourceControlAllowed === false || !source.available || !Number.isSafeInteger(source.revision)))),
+        h('h4', null, t('understandingSuccessors')),
+        (detail.successors || []).map(next => h('div', { key: next.id }, h('span', null, `${next.id} · ${t('revision')} ${next.revision} `),
+          button('understandingOpen', () => show(next.id), busy || loading))),
+        h('details', null, h('summary', null, `${t('understandingHistory')} · ${detail.history?.length || 0}/${detail.historyTotal || 0}`),
+          (detail.history || []).map(row => h('div', { className: 'source', key: row.understanding.id },
+            h('p', { className: 'meta' }, `${row.understanding.id} · ${t('revision')} ${row.understanding.revision} · ${t('understandingVersion')} ${row.understanding.version ?? '—'}`), body(row.understanding.content)))),
+        h('h4', null, `${t('understandingCommands')} · ${detail.commands?.length || 0}/${detail.commandsTotal || 0}`),
+        (detail.commands || []).map(command => h('div', { className: 'source', key: command.id },
+          h('p', null, `${presentationLabel('understandingAction', command.action, t)} · ${command.requestId} · ${t(command.result?.state === 'applied' ? 'understandingApplied' : command.result?.state === 'failed' ? 'understandingFailed' : 'understandingAwaiting')}`),
+          command.admission && h('p', null, t('understandingAdmission') + ': ' + presentationLabel('admission', command.admission.state, t)),
+          command.request?.text !== undefined && body(command.request.text), command.result?.error && body(command.result.error.message),
+          command.result?.changes?.length > 0 && h('details', null, h('summary', null, t('understandingEffects')), body(command.result.changes)),
+          command.result?.goalImpacts?.length > 0 && h('details', null, h('summary', null, t('understandingGoalEffects')), body(command.result.goalImpacts)))))));
+}

package/src/browse-scope.mjs

@@ -0,0 +1,6 @@
+// The UI host is packaged separately from core; keep its wire validation local.
+export function browseScope(value, fallback = 'current') {
+  if (value === undefined) return fallback;
+  if (value === 'all' || value === 'current') return value;
+  throw Object.assign(new Error('请选择全部积累或与当前聊天相关的内容。'), { code: 'invalid_browse_scope' });
+}

package/src/browse-source.mjs

@@ -0,0 +1,31 @@
+// Browsing changes a read projection, never a record's scope or an action's authority.
+export function viewScopeFields(viewScope) {
+  if (viewScope !== undefined && !['all', 'current'].includes(viewScope))
+    throw new TypeError('Unknown Arcfold view scope');
+  return viewScope === undefined ? {} : { viewScope };
+}
+
+export function requireViewScope(viewScope) {
+  if (viewScope === undefined) throw new TypeError('A view scope is required');
+  viewScopeFields(viewScope);
+}
+
+export function createBrowseScopeSource(sources) {
+  let snapshot = { viewScope: 'all', epoch: 0 }, disposed = false;
+  const listeners = new Set();
+  return {
+    getSnapshot: () => snapshot,
+    subscribe(listener) {
+      if (disposed) return () => {};
+      listeners.add(listener); return () => listeners.delete(listener);
+    },
+    setViewScope(viewScope) {
+      requireViewScope(viewScope);
+      if (disposed || snapshot.viewScope === viewScope) return;
+      for (const source of sources) source.setViewScope?.(viewScope);
+      snapshot = { viewScope, epoch: snapshot.epoch + 1 };
+      for (const listener of listeners) listener();
+    },
+    dispose() { disposed = true; listeners.clear(); },
+  };
+}