@lincyaw/workbench 0.0.0-stage → 0.2.0-rc.0

package/src/authoring-client.ts

@@ -0,0 +1,136 @@
+import { authoringClientResultFits } from '@lincyaw/kernel'
+import type { AuthoringClientActionResult, AuthoringClientEvent, AuthoringClientSnapshot, CanonicalSource } from '@lincyaw/kernel'
+import type { Workbench } from './workbench.ts'
+import type { AuthoringClientChannel } from './workspace-client.ts'
+
+const sameSource = (a: CanonicalSource, b: CanonicalSource) => a.documentId === b.documentId && a.version === b.version && a.fingerprint === b.fingerprint
+// Clock samples are observations, not user input revisions. Never push at animation-frame frequency.
+const signature = (value: AuthoringClientSnapshot) => JSON.stringify({ ...value, revision: 0, playback: value.playback && { ...value.playback,
+  position: value.playback.position && { ...value.playback.position, timeMs: 0, stepTimeMs: 0 } } })
+type Attachment = { directory: string, identity: string, epoch: string, channel: AuthoringClientChannel, connectionId?: string }
+
+/** One logical reader on Studio's shared authenticated socket; no extra browser SSE or polling timer. */
+export function connectAuthoringClient(workbench: Workbench): () => void {
+  const open = workbench.client.openAuthoringClient
+  if (!open) return () => {}
+  const clientId = crypto.randomUUID()
+  let closed = false, revision = 0, sequence = 0
+  let attached: Attachment | undefined
+  let lastSignature: string | undefined, lastContent: object | undefined
+  let lastDraftRevision: string | undefined
+  let active: { requestId: string, controller: AbortController } | undefined
+  let reports: Promise<void> = Promise.resolve()
+  let pendingState: { owner: Attachment, connectionId: string, value: AuthoringClientSnapshot } | undefined
+  let stateSending = false
+  const seen = new Set<string>()
+  const snapshot = (): AuthoringClientSnapshot | undefined => {
+    const value = workbench.authoringClientSnapshot(revision)
+    if (!value) return
+    const next = signature(value), content = workbench.state.authoring?.content, drafts = workbench.authoringDraftRevision()
+    if (next !== lastSignature || content !== lastContent || drafts !== lastDraftRevision) { revision++; lastSignature = next; lastContent = content; lastDraftRevision = drafts }
+    return { ...value, revision }
+  }
+  const detach = () => {
+    active?.controller.abort(); active = undefined
+    attached?.channel.close(); attached = undefined
+    pendingState = undefined
+    lastSignature = undefined; lastContent = undefined; lastDraftRevision = undefined; seen.clear()
+  }
+  const send = (owner: Attachment, connectionId: string, value: AuthoringClientSnapshot, acknowledgement?: { requestId: string, state: 'executing' | 'done' | 'refused' | 'failed', error?: { code: string }, result?: AuthoringClientActionResult }, preflight?: () => void) => {
+    const report = { sequence: ++sequence, snapshot: value, ...acknowledgement }
+    const next = reports.then(() => {
+      if (closed || attached !== owner || owner.connectionId !== connectionId) throw new Error('client-connection-changed')
+      preflight?.()
+      return acknowledgement ? owner.channel.acknowledge(connectionId, report as import('@lincyaw/kernel').AuthoringClientAcknowledgement) : owner.channel.publish(connectionId, report)
+    })
+    reports = next.catch(() => {})
+    return next
+  }
+  const publishState = (owner: Attachment, connectionId: string, value: AuthoringClientSnapshot) => {
+    pendingState = { owner, connectionId, value }
+    if (stateSending) return
+    stateSending = true
+    void (async () => {
+      try {
+        while (pendingState) {
+          const pending = pendingState; pendingState = undefined
+          if (attached !== pending.owner || attached.connectionId !== pending.connectionId) continue
+          // Coalesce rapid input while a publication is in flight; never retain an unbounded keystroke queue.
+          const latest = snapshot() ?? pending.value
+          await send(pending.owner, pending.connectionId, latest).catch(() => {})
+        }
+      } finally { stateSending = false }
+    })()
+  }
+  const received = async (owner: Attachment, event: AuthoringClientEvent) => {
+    if (closed || attached !== owner) return
+    if (event.type === 'connected') {
+      active?.controller.abort(); active = undefined
+      owner.connectionId = event.connectionId
+      const value = snapshot()
+      if (value) publishState(owner, event.connectionId, value)
+      return
+    }
+    if (event.type === 'cancel') { if (event.connectionId === owner.connectionId && event.requestId === active?.requestId) active.controller.abort(); return }
+    const request = event.request, connectionId = owner.connectionId
+    if (!connectionId || request.clientId !== clientId || request.epoch !== owner.epoch || request.expectedClientState.connectionId !== connectionId || seen.has(request.requestId)) return
+    seen.add(request.requestId)
+    if (seen.size > 64) seen.delete(seen.values().next().value!)
+    const value = snapshot()
+    if (!value) return
+    const controller = new AbortController(), task = { requestId: request.requestId, controller }
+    const owned = () => {
+      controller.signal.throwIfAborted()
+      if (closed || attached !== owner || owner.connectionId !== connectionId || active !== task || Date.now() >= Date.parse(event.expiresAt)) throw new Error('client-request-expired')
+    }
+    if (active || value.revision !== request.expectedClientState.revision || !sameSource(value.source, request.source) || !value.actions.includes(request.action.type) || Date.now() >= Date.parse(event.expiresAt)) {
+      await send(owner, connectionId, value, { requestId: request.requestId, state: 'refused', error: { code: 'client-state-changed' } }).catch(() => {})
+      return
+    }
+    active = task
+    const expiresAt = Date.parse(event.expiresAt)
+    const timeout = setTimeout(() => controller.abort(new Error('client-request-expired')), Math.max(0, expiresAt - Date.now()))
+    try {
+      // Only a confirmed executing acknowledgement grants this epoch permission to invoke a control.
+      await send(owner, connectionId, value, { requestId: request.requestId, state: 'executing' })
+      owned()
+      const latest = snapshot()
+      if (!latest || latest.revision !== request.expectedClientState.revision || !sameSource(latest.source, request.source)) throw new Error('client-state-changed')
+      const fits = (result: AuthoringClientActionResult) => authoringClientResultFits({ request, connection: { clientId, epoch: owner.epoch, connectionId }, document: owner.directory, snapshot: snapshot() ?? value }, result)
+      const actionResult = await workbench.executeAuthoringClientAction(request.action, request.source, controller.signal, expiresAt, fits)
+      owned()
+      const result = snapshot()
+      if (!result) throw new Error('client-document-changed')
+      await send(owner, connectionId, result, { requestId: request.requestId, state: 'done', ...actionResult ? { result: actionResult } : {} }, actionResult ? () => {
+        owned()
+        const latest = snapshot()
+        if (!latest || latest.revision !== result.revision || !['component-drafts.restore', 'component-drafts.discard', 'comment-drafts.restore', 'comment-drafts.discard'].includes(actionResult.type) && latest.revision !== request.expectedClientState.revision) throw new Error(actionResult.family === 'component' ? 'client-component-drafts-changed' : 'client-comment-drafts-changed')
+        if (!fits(actionResult)) throw new Error(actionResult.family === 'component' ? 'client-component-result-too-large' : 'client-comment-result-too-large')
+      } : undefined)
+    } catch (error) {
+      const result = snapshot()
+      const code = error instanceof Error && /^(client|production)-[a-z-]{1,100}$/.test(error.message) ? error.message : 'client-action-not-verified'
+      if (!controller.signal.aborted && attached === owner && owner.connectionId === connectionId && result) await send(owner, connectionId, result, { requestId: request.requestId, state: 'failed', error: { code } }).catch(() => {})
+    } finally { clearTimeout(timeout); if (active === task) active = undefined }
+  }
+  const changed = () => {
+    const state = workbench.state, source = state.authoring
+    if (closed || state.document === undefined || !source?.identity || source.loading) { detach(); return }
+    const before = revision, value = snapshot()
+    if (!value) { detach(); return }
+    if (attached && (attached.directory !== state.document || attached.identity !== source.identity)) detach()
+    if (!attached) {
+      const epoch = crypto.randomUUID()
+      // Callbacks run after the channel has been installed; the socket implementation is asynchronous.
+      const owner = { directory: state.document, identity: source.identity, epoch } as Attachment
+      owner.channel = open(state.document, { clientId, epoch, snapshot: value }, event => { void received(owner, event) }, () => {
+        if (attached === owner) { owner.connectionId = undefined; active?.controller.abort(); active = undefined }
+      })
+      attached = owner
+    } else if (before !== revision && attached.connectionId) publishState(attached, attached.connectionId, value)
+  }
+  const stop = workbench.subscribe(changed)
+  const stopDrafts = workbench.subscribeAuthoringDraftChanges(changed)
+  changed()
+  return () => { closed = true; stop(); stopDrafts(); detach() }
+}

package/src/authoring-draft-fragment.ts

@@ -0,0 +1,28 @@
+import type { AuthoringClientActionResult } from '@lincyaw/kernel'
+
+type Fragment = Extract<AuthoringClientActionResult, { jsonText: string }>
+type Fields = 'offset' | 'endOffset' | 'totalUtf16' | 'totalUtf8' | 'sha256' | 'jsonText'
+type FragmentBase = Fragment extends infer Value ? Value extends Fragment ? Omit<Value, Fields> : never : never
+export const draftContentHash = async (text: string): Promise<string> => [...new Uint8Array(await crypto.subtle.digest('SHA-256', new TextEncoder().encode(text)))].map(value => value.toString(16).padStart(2, '0')).join('')
+const boundary = (text: string, offset: number) => !(offset > 0 && offset < text.length && /[\uD800-\uDBFF]/.test(text[offset - 1]!) && /[\uDC00-\uDFFF]/.test(text[offset]!))
+
+/** Budget the complete client receipt and WS frame, preserving exact JSON text and Unicode progress. */
+export async function authoringDraftFragment(options: { text: string, base: FragmentBase, offset: number, maxChars?: number }, current: () => void, fits: (value: AuthoringClientActionResult) => boolean): Promise<Fragment> {
+  const { text, base, offset } = options, maxChars = options.maxChars ?? 2048
+  const sha256 = await draftContentHash(text)
+  current()
+  if (!Number.isSafeInteger(offset) || offset < 0 || offset > text.length || !boundary(text, offset)) throw new Error(`client-${base.family}-offset-invalid`)
+  if (!Number.isSafeInteger(maxChars) || maxChars < 2 || maxChars > 2048) throw new Error(`client-${base.family}-fragment-limit`)
+  const lengths = { offset, totalUtf16: text.length, totalUtf8: new TextEncoder().encode(text).byteLength, sha256 }
+  let low = offset, high = Math.min(text.length, offset + maxChars), best: Fragment | undefined
+  while (low <= high) {
+    const middle = Math.floor((low + high) / 2)
+    const end = boundary(text, middle) ? middle : middle - 1
+    const result: Fragment = { ...base, ...lengths, endOffset: end, jsonText: text.slice(offset, end) }
+    if (fits(result)) { if (end > offset || end === text.length) best = result; low = middle + 1 }
+    else high = middle - 1
+  }
+  if (!best) throw new Error(`client-${base.family}-fragment-too-large`)
+  current()
+  return best
+}

package/src/base-controls.tsx

@@ -0,0 +1,47 @@
+import { ICONS } from '@lincyaw/design'
+import type { IconName } from '@lincyaw/design'
+import * as Tooltip from '@radix-ui/react-tooltip'
+import { createElement, forwardRef } from 'react'
+import type { ButtonHTMLAttributes, ReactNode } from 'react'
+
+const cls = (...names: (string | false | undefined | null)[]) => names.filter(Boolean).join(' ')
+
+export function PmIcon({ name, size: _size, strokeWidth = 1.7 }: { name: IconName, size?: number | string, strokeWidth?: number }) {
+  return (
+    <svg className="pm-ui-icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth={strokeWidth} strokeLinecap="round" strokeLinejoin="round" aria-hidden="true" focusable="false">
+      {ICONS[name].map(([tag, attrs], i) => createElement(tag, { key: i, ...attrs }))}
+    </svg>
+  )
+}
+
+export type ButtonVariant = 'default' | 'primary' | 'accent' | 'ghost' | 'danger'
+
+export type ButtonProps = Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'type'> & { type?: 'button' | 'submit' | 'reset' }
+export type ControlDensity = 'compact' | 'regular' | 'touch'
+export type ControlProps = { density?: ControlDensity, loading?: boolean }
+
+export const PmButton = forwardRef<HTMLButtonElement, ButtonProps & ControlProps & { variant?: ButtonVariant, small?: boolean, icon?: IconName }>(function PmButton({ variant = 'default', small, density = small ? 'compact' : 'regular', loading, icon, type = 'button', className, children, disabled, ...rest }, ref) {
+  return (
+    <button {...rest} ref={ref} type={type} data-density={density} aria-busy={loading || undefined} disabled={disabled || loading || rest['aria-disabled'] === true || rest['aria-disabled'] === 'true'} className={cls('pm-ui-button', variant !== 'default' && `pm-ui-button--${variant}`, className)}>
+      <span className={cls('pm-ui-button__content', !icon && loading !== undefined && 'pm-ui-button__content--loading-text')}>{(icon || loading !== undefined) && <span aria-hidden="true" className={cls('pm-ui-button__icon', loading && 'pm-ui-loading')}>{loading ? <PmIcon name="loading" /> : icon && <PmIcon name={icon} />}</span>}{children}</span>
+    </button>
+  )
+})
+
+/** Radix opens on keyboard focus immediately; pointer hover uses the I11 delay. */
+export function PmTooltip({ label, shortcut, children }: { label: string, shortcut?: string, children: ReactNode }) {
+  return (
+    <Tooltip.Provider delayDuration={300} skipDelayDuration={0}>
+      <Tooltip.Root><Tooltip.Trigger asChild>{children}</Tooltip.Trigger><Tooltip.Portal><div className="pm-ui-tooltip-layer"><Tooltip.Content className="pm-ui-tooltip pm-ui" side="bottom" sideOffset={6} collisionPadding={8}>
+        {label}{shortcut && <kbd className="pm-ui-shortcut">{shortcut}</kbd>}
+      </Tooltip.Content></div></Tooltip.Portal></Tooltip.Root>
+    </Tooltip.Provider>
+  )
+}
+
+export const PmIconButton = forwardRef<HTMLButtonElement, ButtonProps & ControlProps & { icon: IconName, label: string, hint?: string, shortcut?: string, small?: boolean, tooltip?: boolean }>(function PmIconButton({ icon, label, hint, shortcut, small, tooltip = true, density = small ? 'compact' : 'regular', loading, className, disabled, ...rest }, ref) {
+  const button = <button {...rest} ref={ref} type="button" data-density={density} aria-label={label} aria-busy={loading || undefined} disabled={disabled || loading || rest['aria-disabled'] === true || rest['aria-disabled'] === 'true'} className={cls('pm-ui-icon-button', className)}>
+      <span className={cls('pm-ui-button__content', loading && 'pm-ui-loading')}><PmIcon name={loading ? 'loading' : icon} /></span>
+    </button>
+  return tooltip ? <PmTooltip label={hint ?? label} shortcut={shortcut}>{button}</PmTooltip> : button
+})

package/src/caption-timing-drafts.ts

@@ -0,0 +1,61 @@
+import type { CaptionTimingSource, TeachingDocument } from '@lincyaw/kernel'
+
+export interface CaptionTimingRow { id: string, from: number, to: number, start: string, end: string }
+export interface CaptionTimingDraft { version: string, text: string, basis: CaptionTimingSource, rows: CaptionTimingRow[] }
+type Scope = { identity: string, memberId: string }
+interface Entry { values: Map<string, CaptionTimingDraft>, failed: boolean, unreadable: boolean }
+const MAX_CHARS = 1 << 20
+const MAX_TARGETS = 512
+const valid = (value: unknown): value is CaptionTimingDraft => {
+  if (!value || typeof value !== 'object') return false
+  const d = value as CaptionTimingDraft, b = d.basis
+  if (typeof d.version !== 'string' || !d.version || d.version.length > 256 || typeof d.text !== 'string' || d.text.length > MAX_CHARS
+    || !b || typeof b !== 'object' || typeof b.available !== 'boolean' || typeof b.sourceFingerprint !== 'string'
+    || b.sourceFingerprint.length > 256 || b.playbackFingerprint !== undefined && (typeof b.playbackFingerprint !== 'string' || b.playbackFingerprint.length > 256)
+    || b.durationMs !== undefined && (!Number.isSafeInteger(b.durationMs) || b.durationMs < 0)
+    || b.reason !== undefined && (typeof b.reason !== 'string' || b.reason.length > 256)
+    || !Array.isArray(b.narrationIds) || b.narrationIds.length > MAX_TARGETS || b.narrationIds.some(id => typeof id !== 'string' || id.length > 256)
+    || !Array.isArray(d.rows) || d.rows.length > MAX_TARGETS) return false
+  return d.rows.every(r => r && typeof r.id === 'string' && r.id.length <= 256 && Number.isSafeInteger(r.from) && r.from >= 0
+    && Number.isSafeInteger(r.to) && r.to >= r.from && r.to <= d.text.length && typeof r.start === 'string' && r.start.length <= 32 && typeof r.end === 'string' && r.end.length <= 32)
+}
+
+/** Unapplied author inputs are per-tab recovery data, never the canonical production timing. */
+export class CaptionTimingDrafts {
+  readonly #entries = new Map<string, Entry>()
+  readonly #leave = (event: BeforeUnloadEvent) => { if ([...this.#entries.values()].some(entry => entry.values.size || entry.failed)) event.preventDefault() }
+  constructor() { if (typeof window !== 'undefined') window.addEventListener('beforeunload', this.#leave) }
+  #key(scope: Scope): string { return `presmium.caption-timing.v1:${JSON.stringify([scope.identity, scope.memberId])}` }
+  #entry(scope: Scope): Entry {
+    const key = this.#key(scope), existing = this.#entries.get(key)
+    if (existing) return existing
+    const result: Entry = { values: new Map(), failed: false, unreadable: false }; this.#entries.set(key, result)
+    try {
+      const raw = sessionStorage.getItem(key)
+      if (raw === null) return result
+      if (raw.length > MAX_CHARS) throw new Error('caption-draft-limit')
+      const data: unknown = JSON.parse(raw)
+      if (!Array.isArray(data) || data.length > MAX_TARGETS) throw new Error('caption-draft-data')
+      for (const pair of data) {
+        if (!Array.isArray(pair) || pair.length !== 2 || typeof pair[0] !== 'string' || !pair[0] || pair[0].length > 256 || !valid(pair[1]) || result.values.has(pair[0])) throw new Error('caption-draft-data')
+        result.values.set(pair[0], pair[1])
+      }
+    } catch { result.values.clear(); result.failed = true; result.unreadable = true }
+    return result
+  }
+  get(scope: Scope, stepId: string): CaptionTimingDraft | undefined { return this.#entry(scope).values.get(stepId) }
+  steps(scope: Scope, document: TeachingDocument): string[] { return [...this.#entry(scope).values.keys()].filter(id => Object.hasOwn(document.steps, id)) }
+  failed(scope: Scope): boolean { return this.#entry(scope).failed }
+  set(scope: Scope, stepId: string, value: CaptionTimingDraft | undefined): void {
+    const entry = this.#entry(scope)
+    if (value) entry.values.set(stepId, value); else entry.values.delete(stepId)
+    if (entry.unreadable) { entry.failed = true; return }
+    try {
+      const key = this.#key(scope), raw = JSON.stringify([...entry.values])
+      if (raw.length > MAX_CHARS || entry.values.size > MAX_TARGETS || [...entry.values.values()].some(draft => !valid(draft))) throw new Error('caption-draft-limit')
+      if (entry.values.size) sessionStorage.setItem(key, raw); else sessionStorage.removeItem(key)
+      entry.failed = false
+    } catch { entry.failed = true }
+  }
+  close(): void { if (typeof window !== 'undefined') window.removeEventListener('beforeunload', this.#leave) }
+}

package/src/caption-timing-messages.ts

@@ -0,0 +1,14 @@
+export const CAPTION_TIMING_MESSAGES = {
+  'zh-CN': {
+    title: '手动字幕时间', open: '设置字幕时间', cancel: '取消', done: '完成', apply: '应用', automatic: '使用自动时间', split: '按换行分段',
+    start: '开始（秒）', end: '结束（秒）', step: '本步骤 · 时间从步骤起点计算', invalid: '时间须递增且不超出本步骤。',
+    loading: '正在加载字幕时间…', prepare: '请先准备当前步骤。', unavailable: '当前步骤的字幕时间不可用。', changed: '讲稿或音频已变化。', recheck: '再次检查', saved: '字幕时间已保存到当前步骤。',
+    failed: '无法确认字幕时间已保存。输入已保留，请重试。', storageFailed: '无法备份字幕时间，请保持此页面打开。', discard: '放弃修改', limit: '本次最多设置 32 段。', segment: (n: number) => `字幕 ${n}`,
+  },
+  en: {
+    title: 'Manual Caption Timing', open: 'Set Caption Times', cancel: 'Cancel', done: 'Done', apply: 'Apply', automatic: 'Use Automatic Times', split: 'Split at Line Breaks',
+    start: 'Start (seconds)', end: 'End (seconds)', step: 'Current step · Times start at the step boundary', invalid: 'Times must increase and fit inside this step.',
+    loading: 'Loading caption times…', prepare: 'Prepare the current step first.', unavailable: 'Caption timing is unavailable for this step.', changed: 'The script or audio has changed.', recheck: 'Check Again', saved: 'Caption times saved to this step.',
+    failed: 'Couldn’t confirm that caption times were saved. Your input is kept; try again.', storageFailed: 'Couldn’t back up caption times. Keep this page open.', discard: 'Discard Changes', limit: 'Set no more than 32 segments at once.', segment: (n: number) => `Caption ${n}`,
+  },
+}

package/src/caption-timing.css

@@ -0,0 +1,20 @@
+.pmw-caption-times {
+  display: grid;
+  gap: var(--pm-space-3);
+  min-width: 0;
+}
+.pmw-caption-times__text {
+  margin: 0;
+  white-space: pre-wrap;
+  overflow-wrap: anywhere;
+}
+.pmw-caption-times__range {
+  display: grid;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  gap: var(--pm-space-2);
+}
+.pmw-caption-times__actions {
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--pm-space-2);
+}

package/src/caption-timing.ts

@@ -0,0 +1,14 @@
+import { applyDocumentCaptionTiming, captionSourceFingerprint } from '@lincyaw/kernel'
+import type { DocumentAnswer, DocumentCaptionTimingAction, TeachingDocument } from '@lincyaw/kernel'
+
+const same = (a: unknown, b: unknown) => JSON.stringify(a) === JSON.stringify(b)
+/** The source actor adopts only this caption slot; later native body input remains owned by the editor. */
+export function reconcileCaptionTiming(action: DocumentCaptionTimingAction, before: TeachingDocument, answer: DocumentAnswer, current: TeachingDocument): TeachingDocument | undefined {
+  try {
+    if (before.id !== answer.content.id || before.id !== current.id || !same(applyDocumentCaptionTiming(before, action).content, answer.content)) return
+    if (!current.steps[action.stepId]) return current
+    if (!same(before.production.captionTimings?.[action.stepId], current.production.captionTimings?.[action.stepId])
+      || captionSourceFingerprint(before, action.stepId) !== captionSourceFingerprint(current, action.stepId)) return
+    return applyDocumentCaptionTiming(current, action).content
+  } catch { return }
+}

package/src/component-draft-actions.ts

@@ -0,0 +1,54 @@
+import type { AuthoringClientAction, AuthoringClientActionResult, CanonicalSource, ClientComponentDraftReference } from '@lincyaw/kernel'
+import { draftContentHash } from './authoring-draft-fragment.ts'
+import { componentDraftMetadata, componentDraftReference } from './component-draft-inspection.ts'
+import type { ComponentPropertyDraft, ComponentPropertyDrafts } from './component-property-drafts.ts'
+
+export const sameComponentDraftReference = (a: ClientComponentDraftReference | null, b: ClientComponentDraftReference | null): boolean => a === null || b === null ? a === b
+  : a.id === b.id && a.revision === b.revision && a.token === b.token && a.blockId === b.blockId && a.stepId === b.stepId
+
+/** Explicit form actions reuse the human bank; they never apply parameters to lecture.json. */
+export async function mutateComponentDrafts(bank: ComponentPropertyDrafts, context: { identity: string, memberId: string, source: CanonicalSource }, action: Extract<AuthoringClientAction, { type: 'component-drafts.restore' | 'component-drafts.discard' }>, signal: AbortSignal, owned: (draft?: ComponentPropertyDraft) => void, fits: (result: AuthoringClientActionResult) => boolean): Promise<AuthoringClientActionResult> {
+  const read = await bank.readForAgent(context, signal, action.draft)
+  owned()
+  const candidate = read.candidates[0]!, target = candidate.record.target, previous = bank.get(target)
+  owned(candidate.record)
+  const unchanged = () => { signal.throwIfAborted(); owned(candidate.record); if (bank.get(target) !== previous) throw new Error('client-component-drafts-changed') }
+  if (action.type === 'component-drafts.discard') {
+    if (candidate.current && (!previous || previous.id !== candidate.record.id || previous.revision !== candidate.record.revision)) throw new Error('client-component-drafts-changed')
+    if (candidate.current !== action.current) throw new Error('client-component-drafts-changed')
+    if (candidate.current && (candidate.storage !== 'durable' || candidate.status !== 'available' || candidate.record.composing || bank.status(target) !== 'available')) throw new Error('client-component-draft-needs-human')
+    const result: AuthoringClientActionResult = { type: action.type, family: 'component', draft: action.draft, current: action.current, discarded: true }
+    if (!fits(result)) throw new Error('client-component-result-too-large')
+    unchanged()
+    const discarded = candidate.current ? await bank.clear(previous!, { preserveOrigins: true }) : await bank.discard(candidate, signal, unchanged)
+    signal.throwIfAborted(); owned()
+    if (!discarded) throw new Error('client-component-drafts-changed')
+    return result
+  }
+  if (candidate.current || candidate.record.composing) throw new Error('client-component-draft-needs-human')
+  if (previous) {
+    if (!action.expectedCurrent || action.expectedCurrent.blockId !== target.blockId || action.expectedCurrent.stepId !== target.stepId) throw new Error('client-component-drafts-changed')
+    const current = await bank.readForAgent(context, signal, action.expectedCurrent)
+    unchanged()
+    const value = current.candidates[0]!
+    if (!value.current || !sameComponentDraftReference(componentDraftReference(value), action.expectedCurrent)) throw new Error('client-component-drafts-changed')
+    if (value.storage !== 'durable' || value.status !== 'available' || value.record.composing || bank.status(target) !== 'available') throw new Error('client-component-draft-needs-human')
+  } else if (action.expectedCurrent !== null) throw new Error('client-component-drafts-changed')
+  unchanged()
+  if (!bank.canKeep(target)) throw new Error('client-component-drafts-limit')
+  const projected = { ...candidate.record, id: '0'.repeat(36), revision: 1, composing: false, updatedAt: new Date().toISOString() }
+  if (!fits({ type: action.type, family: 'component', draft: action.draft,
+    restored: componentDraftMetadata({ ...candidate, record: projected, token: '0'.repeat(64), current: true, storage: 'durable', status: 'available' }, context.source), preservedCurrent: action.expectedCurrent })) throw new Error('client-component-result-too-large')
+  const restored = await bank.recover(candidate, previous, signal, unchanged)
+  signal.throwIfAborted(); owned()
+  if (!restored) throw new Error('client-component-drafts-changed')
+  const record = bank.get(target)
+  if (!record || record.id === candidate.record.id || record.id === previous?.id || record.composing || bank.status(target) !== 'available') throw new Error('client-component-drafts-changed')
+  const token = await draftContentHash(JSON.stringify(record))
+  signal.throwIfAborted(); owned()
+  if (bank.get(target) !== record) throw new Error('client-component-drafts-changed')
+  const result: AuthoringClientActionResult = { type: action.type, family: 'component', draft: action.draft,
+    restored: componentDraftMetadata({ record, token, key: candidate.key, current: true, storage: 'durable', status: 'available' }, context.source), preservedCurrent: action.expectedCurrent }
+  if (!fits(result)) throw new Error('client-component-result-too-large')
+  return result
+}

package/src/component-draft-inspection.ts

@@ -0,0 +1,35 @@
+import type { AuthoringClientAction, AuthoringClientActionResult, CanonicalSource, ClientComponentDraftMetadata } from '@lincyaw/kernel'
+import { authoringDraftFragment, draftContentHash } from './authoring-draft-fragment.ts'
+import type { ComponentPropertyAgentCandidate, ComponentPropertyDrafts } from './component-property-drafts.ts'
+
+export const componentDraftReference = ({ record, token }: ComponentPropertyAgentCandidate) => ({ id: record.id, revision: record.revision, token, blockId: record.target.blockId, ...record.target.stepId !== undefined ? { stepId: record.target.stepId } : {} })
+/** Metadata is an explicit whitelist: neither baseline/value nor trusted scope identities are spread. */
+export function componentDraftMetadata(value: ComponentPropertyAgentCandidate, source: CanonicalSource): ClientComponentDraftMetadata {
+  const { record } = value
+  return { draft: componentDraftReference(value), current: value.current, definitionId: record.definitionId, storage: value.storage, status: value.status, updatedAt: Date.parse(record.updatedAt), baseVersion: record.source.version,
+    sourceCurrent: record.source.documentId === source.documentId && record.source.version === source.version && record.source.fingerprint === source.fingerprint, composing: record.composing, reset: record.reset }
+}
+
+export async function inspectComponentDrafts(drafts: ComponentPropertyDrafts, context: { identity: string, memberId: string, source: CanonicalSource }, action: Extract<AuthoringClientAction, { type: 'component-drafts.inspect' | 'component-drafts.read' }>, signal: AbortSignal, fits: (result: AuthoringClientActionResult) => boolean): Promise<AuthoringClientActionResult> {
+  const read = await drafts.readForAgent(context, signal, action.type === 'component-drafts.read' ? action.draft : undefined)
+  const current = () => { signal.throwIfAborted(); if (!drafts.readable(context.identity, context.memberId) || drafts.revision(context.identity, context.memberId) !== read.revision) throw new Error('client-component-drafts-changed') }
+  if (action.type === 'component-drafts.inspect') {
+    const values = read.candidates.map(value => componentDraftMetadata(value, context.source)), token = await draftContentHash(JSON.stringify({ values, coverage: read.coverage, skippedInvalid: read.skippedInvalid }))
+    current()
+    if (action.cursor && action.cursor.token !== token) throw new Error('client-component-drafts-changed')
+    const start = action.cursor ? values.findIndex(value => value.draft.token === action.cursor!.after) + 1 : 0
+    if (action.cursor && start === 0) throw new Error('client-component-drafts-changed')
+    const result: Extract<AuthoringClientActionResult, { type: 'component-drafts.inspect' }> = { type: action.type, family: 'component', coverage: read.coverage, skippedInvalid: read.skippedInvalid, token, drafts: [] }
+    for (const value of values.slice(start, start + (action.limit ?? 10))) {
+      const next = { ...result, drafts: [...result.drafts, value], ...start + result.drafts.length + 1 < values.length ? { next: { after: value.draft.token, token } } : {} }
+      if (!fits(next)) break
+      result.drafts.push(value)
+    }
+    if (start < values.length && !result.drafts.length) throw new Error('client-component-metadata-too-large')
+    if (start + result.drafts.length < values.length) result.next = { after: result.drafts.at(-1)!.draft.token, token }
+    if (!fits(result)) throw new Error('client-component-metadata-too-large')
+    return result
+  }
+  const value = read.candidates[0]!
+  return authoringDraftFragment({ text: JSON.stringify(value.record.value), base: { type: action.type, family: 'component', draft: componentDraftReference(value), storage: value.storage, format: 'presmium-component-parameters-json-v1' }, offset: action.offset, maxChars: action.maxChars }, current, fits)
+}

package/src/component-properties.css

@@ -0,0 +1,24 @@
+.component-properties__content,
+.component-properties__backups,
+.component-properties__references {
+  display: grid;
+  gap: var(--pm-space-3);
+  min-width: 0;
+}
+.component-properties__actions {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: var(--pm-space-2);
+}
+.component-properties__reference {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--pm-space-2);
+  min-width: 0;
+}
+.component-properties__reference > span {
+  min-width: 0;
+  overflow-wrap: anywhere;
+}

package/src/component-properties.ts

@@ -0,0 +1,45 @@
+import { applyDocumentComponentAction, createDocumentParameterChanges, effectiveComponentParameters } from '@lincyaw/kernel'
+import type { CanonicalSource, DocumentAnswer, DocumentComponentAction, JsonObject, TeachingDocument } from '@lincyaw/kernel'
+import type { ComponentPropertyDraft } from './component-property-drafts.ts'
+
+export const sameComponentSource = (a: CanonicalSource, b: CanonicalSource) => a.documentId === b.documentId && a.version === b.version && a.fingerprint === b.fingerprint
+export const componentSource = (answer: Pick<DocumentAnswer, 'content' | 'version' | 'fingerprint'>): CanonicalSource => ({ documentId: answer.content.id, version: answer.version, fingerprint: answer.fingerprint })
+const same = (a: unknown, b: unknown) => JSON.stringify(a) === JSON.stringify(b)
+
+export function componentPropertyAction(draft: ComponentPropertyDraft): DocumentComponentAction | undefined {
+  const { blockId, stepId } = draft.target
+  if (stepId && draft.reset) return { type: 'component.step-parameters.reset', blockId, stepId }
+  const changes = createDocumentParameterChanges(draft.baseline, draft.value)
+  if (!changes.length) return
+  return stepId ? { type: 'component.step-parameters.patch', blockId, stepId, changes } : { type: 'component.parameters.patch', blockId, changes }
+}
+
+/** A checked rebase borrows the same reducer as the service, preserving unrelated current data. */
+export function rebaseComponentPropertyDraft(document: TeachingDocument, draft: ComponentPropertyDraft): JsonObject {
+  const block = document.blocks[draft.target.blockId]
+  if (block?.type !== 'component' || block.definitionId !== draft.definitionId) throw new Error('component-definition-changed')
+  const action = componentPropertyAction(draft)
+  const content = action ? applyDocumentComponentAction(document, action).content : document
+  return effectiveComponentParameters(content, block.id, draft.target.stepId).parameters
+}
+
+/** An external acknowledgement owns its parameter paths, never a later body tree or sibling form. */
+export function reconcileComponentAction(action: DocumentComponentAction, before: TeachingDocument, answer: DocumentAnswer, current: TeachingDocument): TeachingDocument | undefined {
+  try {
+    if (answer.content.id !== before.id || current.id !== before.id) return
+    const expected = applyDocumentComponentAction(before, action).content
+    if (!same(expected, answer.content)) return
+    const original = before.blocks[action.blockId], actual = current.blocks[action.blockId]
+    if (original?.type !== 'component') return
+    // A later native deletion stays deleted. Its history is updated separately from the verified canonical reply.
+    if (!actual) return current
+    if (actual.type !== 'component' || actual.definitionId !== original.definitionId || !same(actual.parameters, original.parameters)
+      || !same(before.definitions[original.definitionId], current.definitions[actual.definitionId])) return
+    if ('stepId' in action) {
+      const oldStep = before.steps[action.stepId], newStep = current.steps[action.stepId]
+      if (!oldStep || !newStep || oldStep.sectionId !== newStep.sectionId || oldStep.inherits !== newStep.inherits
+        || !same(effectiveComponentParameters(before, action.blockId, action.stepId), effectiveComponentParameters(current, action.blockId, action.stepId))) return
+    }
+    return applyDocumentComponentAction(current, action).content
+  } catch { return }
+}