dsh-ptc-plus 0.3.1 → 0.4.1

package/src/client-copy.js

@@ -0,0 +1,370 @@
+import { CONFIG_FIELDS, CONFIG_GROUPS } from '../internal/config-spec.js'
+
+/** Locale namespace owning every settings-card string (field copy plus chrome). */
+const LOCALE_NS = 'settings.ptcPlus'
+
+/** Card chrome copy; field labels and hints ride the shared config spec. */
+const CHROME_COPY = Object.freeze({
+  zh: Object.freeze({
+    'console.session': '会话绑定',
+    'console.global': '全局绑定',
+    'console.definition': '定义',
+    'console.name': '名称',
+    'console.kind': '类型',
+    'console.reuse': '复用',
+    'console.search': '搜索绑定名称',
+    'console.allKinds': '全部类型',
+    'console.noMatches': '没有匹配的绑定',
+    'bindings.search': '搜索全局条目',
+    'console.value': '值预览',
+    'console.observed': '结算后观察：{time}',
+    'console.unobserved': '尚无值观察记录',
+    'console.unobservedValue': '尚未观察',
+    'console.unreadable': '不可读取',
+    'console.bounded': '已截断',
+    'bindings.manage': '管理全局绑定',
+    'settings.menuEntry': 'PTC Plus 设置',
+    'settings.dialogTitle': 'PTC Plus 设置',
+    'settings.close': '关闭 PTC Plus 设置',
+    'settings.pathSettings': '设置 → 插件配置 → PTC Plus',
+    'settings.pathPlugins': '侧栏 Plugins → dsh-ptc-plus → 行 ptc-plus → Configure',
+    'bindings.entry': '条目配置',
+    'bindings.close': '关闭全局绑定工作台',
+    'card.description': 'PTC 模式的会话级 TypeScript REPL。',
+    'status.enabled': '已启用',
+    'status.disabled': '已停用',
+    'action.expand': '展开 PTC Plus 设置',
+    'action.collapse': '收起 PTC Plus 设置',
+    'state.syncing': '正在同步设置...',
+    'bindingPolicy.legacy': '沿用旧版设置（尚未迁移）',
+    'bindingPolicy.stateful': '允许重声明和覆盖',
+    'bindingPolicy.protected': '启用名称保护',
+    'bindingPolicy.migrationDescription': '当前按下方旧版开关执行。选择统一策略后停用旧版开关，并对后续代码生效。',
+    'state.unavailable': '当前 DSH 实例未提供设置服务',
+    'footer.live': '设置会在修改后立即生效',
+    'footer.readOnly': '当前设置为只读',
+    'status.applied': '设置已立即生效',
+    'status.conflict': '设置未生效，请检查设置冲突',
+    'status.failed': '设置失败：{error}',
+    'bindings.title': '全局用户绑定',
+    'bindings.reload': '重新加载',
+    'bindings.new': '新建条目',
+    'bindings.empty': '尚无全局条目',
+    'bindings.loading': '正在加载全局用户绑定...',
+    'bindings.name': '名称',
+    'bindings.id': '稳定 ID',
+    'bindings.scope': '作用域',
+    'bindings.symbols': '导出符号',
+    'bindings.symbolsPlaceholder': '逗号分隔；留空则从源码推导',
+    'bindings.purpose': '用途',
+    'bindings.source': 'TypeScript 源码',
+    'bindings.sourcePreview': '实现源码',
+    'bindings.declaration': '接口声明',
+    'bindings.modelContext': '模型上下文',
+    'bindings.includeDeclaration': '将接口声明提供给模型',
+    'bindings.declarationIncluded': '向模型提供',
+    'bindings.declarationExcluded': '不向模型提供',
+    'bindings.instructions': '给模型的提示词',
+    'bindings.noInstructions': '未设置提示词',
+    'bindings.debug': '代码控制台',
+    'bindings.edit': '编辑',
+    'bindings.cancel': '取消',
+    'bindings.unvalidated': '尚未验证当前草稿',
+    'bindings.working': '正在处理...',
+    'bindings.enabled': '启用',
+    'bindings.disabledEntry': '停用',
+    'bindings.enableAction': '启用',
+    'bindings.disableAction': '停用',
+    'bindings.validate': '验证',
+    'bindings.save': '保存',
+    'bindings.remove': '删除',
+    'bindings.importPath': '本地 .ts 路径',
+    'bindings.import': '导入',
+    'bindings.run': '运行',
+    'execution.ready': '就绪',
+    'execution.running': '运行中',
+    'execution.released': '环境已释放',
+    'execution.stopped': '已停止，环境已释放',
+    'execution.stop': '停止',
+    'execution.reset': '重置环境',
+    'execution.clear': '清空记录',
+    'execution.history': '执行记录',
+    'execution.output': '输出',
+    'execution.input': 'TypeScript 命令',
+    'execution.restarted': '已从当前草稿重新开始',
+    'execution.truncated': '记录已截断',
+    'bindings.saved': '条目已保存；从下一次 run_code 请求生效。',
+    'bindings.valid': '源码与派生声明有效。',
+    'bindings.removed': '条目已删除。',
+    'bindings.imported': '源码已导入为停用条目。',
+    'bindings.reloaded': '已从磁盘重新加载。',
+    'bindings.reloadedDraft': '目录已重新加载，未保存的编辑已保留。',
+    'bindings.reloadConflict': '读取期间目录再次发生变化，请重新加载。',
+    'bindings.failed': '全局用户绑定操作失败：{error}',
+    'bindings.authorEdit': '修改绑定',
+    'bindings.open': '全局绑定',
+    'bindings.openHint': 'PTC Plus 插件 · 打开全局用户绑定菜单，可编写、启停或管理',
+    'bindings.draftHint': 'PTC Plus 插件 · 绑定草稿待处理，点击查看',
+    'bindings.quickHeading': '全局用户绑定 · 对所有会话生效',
+    'bindings.quickDrafts': '待处理草稿',
+    'bindings.quickLoading': '正在读取绑定…',
+    'bindings.quickSaving': '正在保存…',
+    'bindings.authorNewDraft': '编写新绑定',
+    'bindings.quickEditHeading': '选择要修改的绑定',
+    'bindings.back': '返回',
+    'bindings.composerBusy': '输入框已有内容，未覆盖现有草稿。',
+    'bindings.reviewTitle': '绑定草稿',
+    'bindings.reviewExpand': '展开绑定草稿',
+    'bindings.reviewCollapse': '折叠绑定草稿',
+    'bindings.reviewClose': '关闭绑定草稿面板',
+    'bindings.reviewOpen': '打开草稿',
+    'bindings.reviewMenuLabel': '绑定草稿（{count}）',
+    'bindings.reviewLoading': '正在确认草稿操作资格…',
+    'bindings.reviewSaving': '正在处理草稿…',
+    'bindings.reviewAttention': '有待查看的操作状态',
+    'bindings.reviewUnconfirmed': '操作结果尚未确认，请刷新状态后查看。',
+    'bindings.reviewReadOnly': '只读草稿，当前没有可确认的操作资格',
+    'bindings.reviewUnavailable': '草稿审阅面板暂不可用',
+    'bindings.reviewRetry': '刷新操作状态',
+    'bindings.commandAccepted': '请求已受理，编写结果未知',
+    'bindings.commandAdmitting': '正在处理编写请求…',
+    'bindings.commandGenerated': '草稿已生成',
+    'bindings.draftSave': '保存为停用',
+    'bindings.draftSaveEnable': '保存并启用',
+    'bindings.draftDiscard': '丢弃草稿',
+    'bindings.commandTitle': '绑定编写',
+    'bindings.commandPending': 'Agent 正在编写草稿...',
+    'bindings.commandReady': '草稿已生成，可保存或丢弃',
+    'bindings.commandFailed': '未生成可保存的草稿',
+    'bindings.commandSaved': '草稿已保存为停用条目',
+    'bindings.commandSavedEnabled': '草稿已保存并启用',
+    'bindings.commandDiscarded': '草稿已丢弃',
+    'indicator.title': 'PTC Plus 已启用；查看当前可复用的 REPL 绑定',
+    'memory.title': 'REPL 可复用绑定',
+    'memory.count': '{count} 个可复用绑定',
+    'memory.globalCount': '{count} 个全局条目',
+    'memory.empty': '当前没有可复用绑定',
+    'memory.unavailable': '当前绑定状态尚不可确认',
+    'memory.more': '另有 {count} 个绑定未显示',
+    'memory.reuseCount': '复用 {count} 次',
+    'memory.reuseTotal': '共复用 {count} 次',
+    'memory.reuseHint': '被后续 cell 复用的次数',
+    'memory.kind.variable': '变量',
+    'memory.kind.function': '函数',
+    'memory.kind.class': '类',
+    'memory.kind.import': '导入',
+    'memory.location': '第 {line} 行，第 {column} 列',
+    'memory.sessionTab': '可复用绑定',
+    'memory.globalTab': '全局默认绑定',
+    'memory.globalEmpty': '没有全局默认绑定',
+    'memory.globalUnavailable': '无法读取全局默认绑定',
+    'tool.code': '执行',
+    'tool.codeEdit': '修正执行',
+    'tool.running': '正在运行',
+    'tool.completed': '执行完成',
+    'tool.failed': '执行失败',
+    'tool.stopped': '执行已中断',
+    'tool.source': '源码',
+    'tool.result': '结果',
+    'tool.copy': '复制代码',
+    'tool.copied': '已复制',
+    'tool.inspect': '检查调用',
+    'feature.safeEdit': '安全编辑执行',
+    'feature.codeRun': '隔离执行 code.run',
+    'feature.stateSaved': '保存 REPL 状态',
+    'feature.stateRestored': '恢复 REPL 状态',
+    'feature.stateDeleted': '删除 REPL 状态',
+  }),
+  en: Object.freeze({
+    'console.session': 'Session bindings',
+    'console.global': 'Global bindings',
+    'console.definition': 'Definition',
+    'console.name': 'Name',
+    'console.kind': 'Kind',
+    'console.reuse': 'Reuses',
+    'console.search': 'Search binding names',
+    'console.allKinds': 'All kinds',
+    'console.noMatches': 'No matching bindings',
+    'bindings.search': 'Search global entries',
+    'console.value': 'Value preview',
+    'console.observed': 'Observed after settlement: {time}',
+    'console.unobserved': 'No value observation yet',
+    'console.unobservedValue': 'Not observed yet',
+    'console.unreadable': 'Unreadable',
+    'console.bounded': 'Truncated',
+    'bindings.manage': 'Manage global bindings',
+    'settings.menuEntry': 'PTC Plus settings',
+    'settings.dialogTitle': 'PTC Plus settings',
+    'settings.close': 'Close PTC Plus settings',
+    'settings.pathSettings': 'Settings → Plugin configuration → PTC Plus',
+    'settings.pathPlugins': 'Side bar Plugins → dsh-ptc-plus → row ptc-plus → Configure',
+    'bindings.entry': 'Entry configuration',
+    'bindings.close': 'Close global bindings workbench',
+    'card.description': 'The session-bound TypeScript REPL for PTC mode.',
+    'status.enabled': 'Enabled',
+    'status.disabled': 'Disabled',
+    'action.expand': 'Expand PTC Plus settings',
+    'action.collapse': 'Collapse PTC Plus settings',
+    'state.syncing': 'Syncing settings...',
+    'bindingPolicy.legacy': 'Legacy settings (not migrated)',
+    'bindingPolicy.stateful': 'Allow redeclarations and overrides',
+    'bindingPolicy.protected': 'Protect names',
+    'bindingPolicy.migrationDescription': 'The legacy switches below currently apply. Choosing a unified policy replaces those switches for subsequent code.',
+    'state.unavailable': 'This DSH instance does not provide a settings service',
+    'footer.live': 'Changes take effect immediately.',
+    'footer.readOnly': 'These settings are read-only.',
+    'status.applied': 'Setting applied immediately.',
+    'status.conflict': 'The setting did not take effect; check for conflicting settings.',
+    'status.failed': 'Could not save: {error}',
+    'bindings.title': 'Global User Bindings',
+    'bindings.reload': 'Reload',
+    'bindings.new': 'New entry',
+    'bindings.empty': 'No global entries yet',
+    'bindings.loading': 'Loading Global User Bindings...',
+    'bindings.name': 'Name',
+    'bindings.id': 'Stable ID',
+    'bindings.scope': 'Scope',
+    'bindings.symbols': 'Selected exports',
+    'bindings.symbolsPlaceholder': 'Comma-separated; blank derives from source',
+    'bindings.purpose': 'Purpose',
+    'bindings.source': 'TypeScript source',
+    'bindings.sourcePreview': 'Implementation source',
+    'bindings.declaration': 'Interface declaration',
+    'bindings.modelContext': 'Model context',
+    'bindings.includeDeclaration': 'Include API declaration in model context',
+    'bindings.declarationIncluded': 'Include in model context',
+    'bindings.declarationExcluded': 'Exclude from model context',
+    'bindings.instructions': 'Prompt for the model',
+    'bindings.noInstructions': 'No prompt configured',
+    'bindings.debug': 'Code console',
+    'bindings.edit': 'Edit',
+    'bindings.cancel': 'Cancel',
+    'bindings.unvalidated': 'Current draft has not been validated',
+    'bindings.working': 'Working...',
+    'bindings.enabled': 'Enabled',
+    'bindings.disabledEntry': 'Disabled',
+    'bindings.enableAction': 'Enable',
+    'bindings.disableAction': 'Disable',
+    'bindings.validate': 'Validate',
+    'bindings.save': 'Save',
+    'bindings.remove': 'Remove',
+    'bindings.importPath': 'Local .ts path',
+    'bindings.import': 'Import',
+    'bindings.run': 'Run',
+    'execution.ready': 'Ready',
+    'execution.running': 'Running',
+    'execution.released': 'Environment released',
+    'execution.stopped': 'Stopped; environment released',
+    'execution.stop': 'Stop',
+    'execution.reset': 'Reset environment',
+    'execution.clear': 'Clear history',
+    'execution.history': 'Execution history',
+    'execution.output': 'Output',
+    'execution.input': 'TypeScript command',
+    'execution.restarted': 'Started again from the current draft',
+    'execution.truncated': 'Record truncated',
+    'bindings.saved': 'Entry saved; it takes effect from the next run_code request.',
+    'bindings.valid': 'Source and derived declaration are valid.',
+    'bindings.removed': 'Entry removed.',
+    'bindings.imported': 'Source imported as a disabled entry.',
+    'bindings.reloaded': 'Reloaded from disk.',
+    'bindings.reloadedDraft': 'Catalog reloaded; unsaved edits retained.',
+    'bindings.reloadConflict': 'The catalog changed during reload. Reload again.',
+    'bindings.failed': 'Global User Binding operation failed: {error}',
+    'bindings.authorEdit': 'Revise a binding',
+    'bindings.open': 'Global bindings',
+    'bindings.openHint': 'PTC Plus plugin · Open the Global User Binding menu to author, toggle, or manage',
+    'bindings.draftHint': 'PTC Plus plugin · Binding draft pending; click to review',
+    'bindings.quickHeading': 'Global bindings · Applies to all sessions',
+    'bindings.quickDrafts': 'Pending drafts',
+    'bindings.quickLoading': 'Loading bindings…',
+    'bindings.quickSaving': 'Saving…',
+    'bindings.authorNewDraft': 'Write a new binding',
+    'bindings.quickEditHeading': 'Choose a binding to revise',
+    'bindings.back': 'Back',
+    'bindings.composerBusy': 'The composer already has text, so its draft was not replaced.',
+    'bindings.reviewTitle': 'Binding draft',
+    'bindings.reviewExpand': 'Expand binding draft',
+    'bindings.reviewCollapse': 'Collapse binding draft',
+    'bindings.reviewClose': 'Close binding draft panel',
+    'bindings.reviewOpen': 'Open draft',
+    'bindings.reviewMenuLabel': 'Binding drafts ({count})',
+    'bindings.reviewLoading': 'Confirming draft actions…',
+    'bindings.reviewSaving': 'Processing draft…',
+    'bindings.reviewAttention': 'Action status needs attention',
+    'bindings.reviewUnconfirmed': 'The action result is unconfirmed. Refresh its status to check.',
+    'bindings.reviewReadOnly': 'Read-only draft; current action eligibility is unconfirmed',
+    'bindings.reviewUnavailable': 'Draft review panel is temporarily unavailable',
+    'bindings.reviewRetry': 'Refresh action status',
+    'bindings.commandAccepted': 'Request admitted; authoring result unknown',
+    'bindings.commandAdmitting': 'Processing authoring request…',
+    'bindings.commandGenerated': 'Draft generated',
+    'bindings.draftSave': 'Save as disabled',
+    'bindings.draftSaveEnable': 'Save and enable',
+    'bindings.draftDiscard': 'Discard draft',
+    'bindings.commandTitle': 'Binding authoring',
+    'bindings.commandPending': 'Agent is writing a draft...',
+    'bindings.commandReady': 'Draft ready to save or discard',
+    'bindings.commandFailed': 'No saveable draft was produced',
+    'bindings.commandSaved': 'Draft saved as a disabled entry',
+    'bindings.commandSavedEnabled': 'Draft saved and enabled',
+    'bindings.commandDiscarded': 'Draft discarded',
+    'indicator.title': 'PTC Plus is active; view reusable REPL bindings',
+    'memory.title': 'Reusable REPL bindings',
+    'memory.count': '{count} reusable bindings',
+    'memory.globalCount': '{count} global entries',
+    'memory.empty': 'No reusable bindings',
+    'memory.unavailable': 'Current binding state cannot be confirmed',
+    'memory.more': '{count} more bindings not shown',
+    // Number-neutral so a single reuse stays grammatical without a plural rule.
+    'memory.reuseCount': 'reused {count}\u00d7',
+    'memory.reuseTotal': 'reused {count}\u00d7 total',
+    'memory.reuseHint': 'Times later cells referenced this binding in their source',
+    'memory.kind.variable': 'Variable',
+    'memory.kind.function': 'Function',
+    'memory.kind.class': 'Class',
+    'memory.kind.import': 'Import',
+    'memory.location': 'Line {line}, column {column}',
+    'memory.sessionTab': 'Reusable bindings',
+    'memory.globalTab': 'Global defaults',
+    'memory.globalEmpty': 'No global default bindings',
+    'memory.globalUnavailable': 'Global default bindings are unavailable',
+    'tool.code': 'Code',
+    'tool.codeEdit': 'Code edit',
+    'tool.running': 'Running',
+    'tool.completed': 'Completed',
+    'tool.failed': 'Failed',
+    'tool.stopped': 'Stopped',
+    'tool.source': 'Source',
+    'tool.result': 'Result',
+    'tool.inspect': 'Inspect call',
+    'feature.safeEdit': 'Safe edit execution',
+    'feature.codeRun': 'Isolated code.run execution',
+    'feature.stateSaved': 'Saved REPL state',
+    'feature.stateRestored': 'Restored REPL state',
+    'feature.stateDeleted': 'Deleted REPL state',
+    'tool.copy': 'Copy code',
+    'tool.copied': 'Copied',
+  }),
+})
+
+/** Project one field's copy into locale dictionary keys; an empty hint has no key. */
+function fieldCopy(field, locale) {
+  const copy = { [`${field.key}.label`]: locale === 'en' ? field.labelEn : field.label }
+  const description = locale === 'en' ? field.descriptionEn : field.description
+  if (description !== '') copy[`${field.key}.description`] = description
+  return copy
+}
+
+/** Complete dictionaries for both shipped locales, derived once from the spec. */
+const SETTINGS_COPY = Object.freeze(Object.fromEntries(
+  ['zh', 'en'].map(locale => [locale, Object.freeze({
+    ...CHROME_COPY[locale],
+    ...Object.assign({}, ...CONFIG_GROUPS.map(group => ({
+      [`group.${group.key}`]: locale === 'en' ? group.labelEn : group.label,
+    }))),
+    ...Object.assign({}, ...CONFIG_FIELDS.map(field => fieldCopy(field, locale))),
+  })]),
+))
+
+export { LOCALE_NS, SETTINGS_COPY }

package/src/client-feature-gates.js

@@ -0,0 +1,62 @@
+/**
+ * Settings snapshot to feature eligibility. Each feature names the settings that
+ * gate exactly one contribution, so a new gated surface reads one table instead
+ * of copying a predicate. Session facts (preset, projections) and public
+ * capabilities stay with their own owners and are combined at the call site.
+ */
+const FEATURE_SETTINGS = Object.freeze({
+  // The plugin master switch plus every contribution that only needs it.
+  plugin: { required: [], defaultOn: [] },
+  // Global User Bindings: the workbench, its command renderer and the author menu.
+  bindings: { required: ['userBindingsEnabled'], defaultOn: [] },
+  // Enhanced run_code tool rows.
+  toolView: { required: [], defaultOn: ['enhancedToolView'] },
+  // The REPL view tab; the session preset condition is added by its registration.
+  replView: { required: [], defaultOn: ['replViewEnabled'] },
+  // The composer authoring menu.
+  authorButton: { required: ['userBindingsEnabled'], defaultOn: ['bindingAuthorButtonVisible'] },
+})
+
+/**
+ * Pure settings projection: a feature is eligible only from a ready snapshot
+ * with the master switch on and every feature-specific setting met. Required
+ * settings must be explicitly true; default-on settings are on unless the user
+ * turned them off. Writability gates setting writes, not contribution presence.
+ */
+export function featureEnabled(snapshot, feature) {
+  const rule = FEATURE_SETTINGS[feature]
+  if (rule === undefined) throw new Error(`Unknown client feature: ${feature}`)
+  if (snapshot?.status !== 'ready' || snapshot.value?.enabled !== true) return false
+  const value = snapshot.value
+  return rule.required.every(key => value[key] === true)
+    && rule.defaultOn.every(key => value[key] !== false)
+}
+
+/**
+ * Keep one slot registration in sync with an eligibility predicate: subscribe
+ * once, register on the first eligible evaluation, unregister on the next
+ * ineligible one, and dispose the registration when the owning effect is
+ * released. `register` returns its own disposer and must roll back internally
+ * when it fails part way; a throw leaves nothing registered.
+ */
+export function registerGated(scope, { subscribe, isEnabled, register }) {
+  return scope.effect(() => {
+    let dispose
+    const sync = () => {
+      const enabled = isEnabled()
+      if (enabled === (dispose !== undefined)) return
+      if (!enabled) {
+        dispose?.()
+        dispose = undefined
+        return
+      }
+      dispose = register()
+    }
+    sync()
+    const unsubscribe = subscribe(sync)
+    return () => {
+      unsubscribe?.()
+      dispose?.()
+    }
+  })
+}

package/src/client-host-compat.js

@@ -0,0 +1,150 @@
+import { SETTINGS_NAMESPACE } from '../internal/config-spec.js'
+
+/** The preset a session publishes, preferring the projection reader's evidence. */
+function sessionPresetValue(projected, summary) {
+  if (projected !== undefined) return projected
+  const values = summary?.projectionValues
+  // A published key is authoritative even when its value is undefined: it says
+  // the projection exists, so the legacy summary field must not stand in.
+  return values !== undefined && Object.hasOwn(values, 'agentPreset') ? values.agentPreset : summary?.agentPreset
+}
+
+/**
+ * The session the main view holds.
+ *
+ * The preceding DSH projects the current selection on the session list snapshot.
+ * The current one keeps view selection outside the controller and retains the
+ * session its main view shows instead, so `retainedBy.mainView` is that layer's
+ * own selection evidence. A switch retains the new session before releasing the
+ * old one, so the remembered selection wins while it is still held: that is the
+ * same rule the view layer applies to decide which session it shows.
+ */
+function currentSessionId(snapshot, remembered) {
+  if (snapshot?.current !== undefined) return snapshot.current
+  const held = id => id !== undefined && (snapshot?.byId?.[id]?.retainedBy?.mainView ?? 0) > 0
+  if (held(remembered)) return remembered
+  for (const row of Object.values(snapshot?.byId ?? {})) {
+    if ((row?.retainedBy?.mainView ?? 0) > 0) return row.id
+  }
+  return undefined
+}
+
+export function sessionUsesPtcPreset(preset) {
+  return preset === 'ptc' || preset === 'code'
+}
+
+/** Consume the renderer's public hooks; only preset selection has a summary fallback. */
+export function useSessionPreset({ sessionId, useProjection, useSessions }) {
+  const projected = useProjection('agentPreset')
+  return typeof useSessions === 'function'
+    ? useSessions(state => sessionPresetValue(projected, state.byId?.[sessionId]))
+    : projected
+}
+
+/** Publish the current preset immediately and follow its public list/projection sources. */
+export function watchCurrentSessionPreset(sessions, listener) {
+  let source
+  let unsubscribeProjection
+  let selected
+  const sync = () => {
+    const snapshot = sessions.list.getSnapshot()
+    const current = currentSessionId(snapshot, selected)
+    selected = current
+    const summary = current === undefined ? undefined : snapshot.byId?.[current]
+    const next = current === undefined
+      ? undefined : sessions.binding?.(current)?.session?.projections?.faceOf?.('agentPreset')
+    if (source !== next) {
+      unsubscribeProjection?.()
+      source = next
+      unsubscribeProjection = source?.subscribe(sync)
+    }
+    listener(sessionPresetValue(source?.getSnapshot(), summary))
+  }
+  const unsubscribeList = sessions.list.subscribe(sync)
+  const dispose = () => {
+    unsubscribeList()
+    unsubscribeProjection?.()
+  }
+  try {
+    sync()
+  } catch (error) {
+    dispose()
+    throw error
+  }
+  return dispose
+}
+
+/** Missing legacy interaction evidence never proves that the composer is idle. */
+export function isIdleSessionComposer(owner, sessionId) {
+  return Object.hasOwn(owner, 'sessionId')
+    ? owner.sessionId === sessionId && owner.pendingInteraction === undefined
+    : owner.session?.sessionId === sessionId && Array.isArray(owner.interactions) && owner.interactions.length === 0
+}
+
+/**
+ * The row this bundle's own patch declares for its Cordis entry in
+ * `cordis.patch.yml`; it is the row-id half of the row-configuration key below,
+ * so renaming one means renaming the other.
+ */
+const BUNDLE_PATCH_ROW_ID = 'ptc-plus'
+
+/**
+ * The slot seats one generation of DSH offers for a plugin's own settings card,
+ * oldest generation first:
+ *
+ * - DSH 0.1.5 and earlier: the Settings panel's Plugins section declares
+ *   `settings.plugin.item` (keyed, root) as the child slot of its configurable
+ *   tab and renders one card per settings namespace the Host serves, so this
+ *   plugin's key is its namespace.
+ * - DSH 0.1.6-alpha.2 and later: that section is a read-only inventory, and a
+ *   bundle's own configuration belongs to the side bar Plugins page, which
+ *   declares `plugins.row.config` (keyed, root) and renders the entry's summary
+ *   on the row's page with the entry's form below it. The key is
+ *   `<bundle package name>#<row id>`. The same page's `plugins.item` list is its
+ *   Official group, occupied by the host-plane configuration pages DSH itself
+ *   ships, so it is not a seat for a third-party bundle.
+ *
+ * No generation declares both keys, and `ctx.slots.inject` waits rather than
+ * failing while a key is undeclared: the callback runs only after the declaring
+ * entry mounts, and nothing is registered until then. One publication therefore
+ * serves every generation without probing a version, and no card renders twice
+ * on a generation that exists.
+ *
+ * @param bundleName - this bundle's package name, as the profile installs it.
+ * @returns one `{ slot, identity }` per generation.
+ */
+export function settingsCardSeats(bundleName) {
+  return [
+    { slot: 'settings.plugin.item', identity: { key: SETTINGS_NAMESPACE } },
+    { slot: 'plugins.row.config', identity: { key: `${bundleName}#${BUNDLE_PATCH_ROW_ID}` } },
+  ]
+}
+
+/**
+ * Publish one settings card to every seat above and report which seat the
+ * installed generation declared.
+ *
+ * Only the declaring generation runs a seat's callback, so the card's location
+ * is observed rather than inferred: the seat that registered is where a user
+ * finds the card now, and that is what any copy pointing at it must say.
+ *
+ * @param ctx - browser plugin context carrying `slots`.
+ * @param options.bundleName - this bundle's package name, as the profile installs it.
+ * @param options.locale - locale namespace owning the card's copy.
+ * @param options.injectProps - inject face producing the card's props.
+ * @param options.component - the card component; it renders the summary view as
+ *   one line and the card's other views as the full settings form.
+ * @returns `seat` reports the live seat's slot name, and `releases` holds one
+ *   disposer per seat for callers that release them explicitly.
+ */
+export function publishSettingsCard(ctx, { bundleName, locale, injectProps, component }) {
+  let live
+  const releases = settingsCardSeats(bundleName).map(({ slot, identity }) => ctx.slots.inject(
+    slot,
+    () => {
+      live = slot
+      return ctx.slots.register({ name: slot, ...identity, locale, inject: injectProps }, component)
+    },
+  ))
+  return { seat: () => live, releases }
+}