@lincyaw/workbench 0.1.0 → 0.2.0-rc.0

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 }
+}

package/src/component-property-drafts.ts

@@ -0,0 +1,273 @@
+import { isRecord } from '@lincyaw/kernel'
+import type { CanonicalSource, ClientComponentDraftReference, JsonObject } from '@lincyaw/kernel'
+import { DocumentDraftStore } from './document-draft-store.ts'
+import type { DraftStoreCommit } from './document-draft-store.ts'
+
+export interface ComponentPropertyTarget { identity: string, memberId: string, blockId: string, stepId?: string }
+export interface ComponentPropertyDraft {
+  format: 1
+  id: string
+  revision: number
+  target: ComponentPropertyTarget
+  source: CanonicalSource
+  definitionId: string
+  baseline: JsonObject
+  value: JsonObject
+  reset: boolean
+  composing: boolean
+  updatedAt: string
+}
+export interface ComponentPropertyBackup { record: ComponentPropertyDraft, token: string, key: string }
+export interface ComponentPropertyBackupRead { candidates: ComponentPropertyBackup[], unreadable: number }
+export interface ComponentPropertyAgentCandidate extends ComponentPropertyBackup { current: boolean, storage: 'durable' | 'session', status: 'available' | 'pending' | 'session-only' }
+interface Entry { record: ComponentPropertyDraft, store: DocumentDraftStore, operation?: DraftStoreCommit, failed: boolean, origins: ComponentPropertyBackup[] }
+const PREFIX = 'presmium.component-properties.v1:'
+const SETTLED = 'presmium.component-properties-settled.v1:'
+const MAX_CHARS = 1 << 20
+const scope = (target: Pick<ComponentPropertyTarget, 'identity' | 'memberId'>) => JSON.stringify([target.identity, target.memberId])
+const targetKey = (target: ComponentPropertyTarget) => JSON.stringify([target.identity, target.memberId, target.blockId, target.stepId ?? null])
+const prefix = (target: ComponentPropertyTarget) => `${PREFIX}${targetKey(target)}:`
+const markerPrefix = (target: ComponentPropertyTarget) => `${SETTLED}${targetKey(target)}:`
+const scopedPrefix = (kind: string, identity: string, memberId: string) => `${kind}${JSON.stringify([identity, memberId]).slice(0, -1)},`
+const markerOf = (target: ComponentPropertyTarget, reference: { id: string, revision: number, token: string }) => `${markerPrefix(target)}${JSON.stringify([reference.id, reference.revision, reference.token])}`
+const marker = (backup: ComponentPropertyBackup) => markerOf(backup.record.target, { id: backup.record.id, revision: backup.record.revision, token: backup.token })
+const keyOf = (record: ComponentPropertyDraft) => `${prefix(record.target)}${record.id}`
+const tokenOf = async (raw: string) => [...new Uint8Array(await crypto.subtle.digest('SHA-256', new TextEncoder().encode(raw)))].map(byte => byte.toString(16).padStart(2, '0')).join('')
+
+function valid(value: unknown, target: ComponentPropertyTarget): value is ComponentPropertyDraft {
+  return isRecord(value) && value.format === 1 && typeof value.id === 'string' && value.id.length > 0
+    && Number.isSafeInteger(value.revision) && (value.revision as number) > 0 && isRecord(value.target)
+    && value.target.identity === target.identity && value.target.memberId === target.memberId && value.target.blockId === target.blockId && value.target.stepId === target.stepId
+    && isRecord(value.source) && typeof value.source.documentId === 'string' && typeof value.source.version === 'string' && typeof value.source.fingerprint === 'string'
+    && typeof value.definitionId === 'string' && isRecord(value.baseline) && isRecord(value.value)
+    && typeof value.reset === 'boolean' && typeof value.composing === 'boolean' && typeof value.updatedAt === 'string' && Number.isFinite(Date.parse(value.updatedAt))
+}
+
+/** Unapplied form input borrows the existing strict backup actor; only lecture.json is authoring content. */
+export class ComponentPropertyDrafts {
+  readonly #entries = new Map<string, Entry>()
+  readonly #listeners = new Set<() => void>()
+  readonly #revisions = new Map<string, number>()
+  readonly #settling = new Map<string, number>()
+  #agentReader?: { identity: string, memberId: string, store: DocumentDraftStore }
+  readonly #writerOwner = crypto.randomUUID()
+  #revision = 0
+  #closed = false
+  readonly #leave = (event: BeforeUnloadEvent) => {
+    if ([...this.#entries.values()].some(entry => entry.failed || entry.operation || entry.record.composing)) event.preventDefault()
+  }
+  constructor() { if (typeof window !== 'undefined') window.addEventListener('beforeunload', this.#leave) }
+  subscribe = (listener: () => void): (() => void) => { this.#listeners.add(listener); return () => this.#listeners.delete(listener) }
+  snapshot = (): number => this.#revision
+  revision(identity: string, memberId: string): number { return this.#revisions.get(JSON.stringify([identity, memberId])) ?? 0 }
+  readable(identity: string, memberId: string): boolean { return !this.#closed && !this.#settling.get(JSON.stringify([identity, memberId])) }
+  #settle(target: ComponentPropertyTarget): () => void {
+    const key = scope(target)
+    this.#settling.set(key, (this.#settling.get(key) ?? 0) + 1); this.#touch(target)
+    return () => {
+      const remaining = (this.#settling.get(key) ?? 1) - 1
+      if (remaining) this.#settling.set(key, remaining); else this.#settling.delete(key)
+      this.#touch(target)
+    }
+  }
+  #touch(target: Pick<ComponentPropertyTarget, 'identity' | 'memberId'>): void {
+    if (this.#closed) return
+    this.#revision++
+    this.#revisions.set(scope(target), (this.#revisions.get(scope(target)) ?? 0) + 1)
+    for (const listener of this.#listeners) listener()
+  }
+  get(target: ComponentPropertyTarget): ComponentPropertyDraft | undefined { return this.#entries.get(targetKey(target))?.record }
+  canKeep(target: ComponentPropertyTarget): boolean { return !this.#closed && (this.#entries.has(targetKey(target)) || this.#entries.size < 512) }
+  status(target: ComponentPropertyTarget): 'available' | 'pending' | 'session-only' {
+    const entry = this.#entries.get(targetKey(target))
+    return entry?.failed ? 'session-only' : entry?.operation ? 'pending' : 'available'
+  }
+  has(identity: string, memberId: string): boolean { return [...this.#entries.values()].some(entry => entry.record.target.identity === identity && entry.record.target.memberId === memberId) }
+  stopAgentRead(): void {
+    const reader = this.#agentReader
+    this.#agentReader = undefined
+    reader?.store.close()
+    if (reader) this.#touch(reader)
+  }
+
+  /** Explicit reads never settle backups; current input shadows older disk bytes even after admission failure. */
+  async readForAgent(context: { identity: string, memberId: string, source: CanonicalSource }, signal: AbortSignal, reference?: ClientComponentDraftReference): Promise<{ revision: number, candidates: ComponentPropertyAgentCandidate[], coverage: 'stored-and-session' | 'session-only', skippedInvalid: number }> {
+    const { identity, memberId, source } = context
+    signal.throwIfAborted()
+    if (!this.readable(identity, memberId)) throw new Error('client-component-drafts-unavailable')
+    if (this.#agentReader && (this.#agentReader.identity !== identity || this.#agentReader.memberId !== memberId)) this.stopAgentRead()
+    if (!this.#agentReader) {
+      const store = new DocumentDraftStore(JSON.stringify([identity, memberId]), () => { if (this.#agentReader?.store === store) this.#touch({ identity, memberId }) }, { owner: this.#writerOwner, family: 'component' })
+      this.#agentReader = { identity, memberId, store }
+    }
+    const reader = this.#agentReader, revision = this.revision(identity, memberId), writing = [...this.#entries.values()].filter(entry => entry.record.target.identity === identity && entry.record.target.memberId === memberId)
+    const target = reference ? { identity, memberId, blockId: reference.blockId, ...reference.stepId !== undefined ? { stepId: reference.stepId } : {} } : undefined
+    const key = target && reference ? `${prefix(target)}${reference.id}` : undefined
+    const known = reference && writing.find(entry => keyOf(entry.record) === key)
+    if (known && known.record.revision !== reference!.revision) throw new Error('client-component-draft-changed')
+    const current = () => { signal.throwIfAborted(); if (this.#agentReader !== reader || !this.readable(identity, memberId) || revision !== this.revision(identity, memberId)) throw new Error('client-component-drafts-changed') }
+    let stored: Map<string, unknown>, coverage: 'stored-and-session' | 'session-only' = 'stored-and-session'
+    try { stored = await reader.store.read(key && target && reference ? [key, markerOf(target, reference)] : [scopedPrefix(PREFIX, identity, memberId), scopedPrefix(SETTLED, identity, memberId)], signal, 2048) }
+    catch (error) {
+      current()
+      if (error instanceof Error && error.message === 'document-draft-read-limit') throw new Error('client-component-drafts-limit')
+      if (reference ? !known : !writing.length) throw new Error('client-component-drafts-unavailable')
+      stored = new Map(); coverage = 'session-only'
+    }
+    current()
+    const entries = new Map<string, { raw: unknown, storage: 'durable' | 'session', status: ComponentPropertyAgentCandidate['status'], current: boolean }>()
+    for (const [name, raw] of stored) if (name.startsWith(scopedPrefix(PREFIX, identity, memberId)) && (!key || name === key)) entries.set(name, { raw, storage: 'durable', status: 'available', current: false })
+    for (const entry of writing) if (!key || keyOf(entry.record) === key) {
+      const raw = JSON.stringify(entry.record), name = keyOf(entry.record)
+      entries.set(name, { raw, storage: stored.get(name) === raw ? 'durable' : 'session', status: entry.failed ? 'session-only' : entry.operation ? 'pending' : 'available', current: true })
+    }
+    const candidates: ComponentPropertyAgentCandidate[] = []; let skippedInvalid = 0
+    for (const [name, entry] of entries) {
+      try {
+        if (typeof entry.raw !== 'string' || entry.storage === 'durable' && entry.raw.length > MAX_CHARS) throw new Error('component-draft-data')
+        const value: unknown = JSON.parse(entry.raw)
+        if (!isRecord(value) || !isRecord(value.target) || typeof value.target.blockId !== 'string' || !value.target.blockId || value.target.blockId.length > 200
+          || value.target.stepId !== undefined && (typeof value.target.stepId !== 'string' || !value.target.stepId || value.target.stepId.length > 200)) throw new Error('component-draft-data')
+        const owned = { identity, memberId, blockId: value.target.blockId, ...value.target.stepId !== undefined ? { stepId: value.target.stepId as string } : {} }
+        if (!valid(value, owned) || name !== keyOf(value) || value.id.length > 200 || value.definitionId.length > 200 || !value.definitionId
+          || value.source.documentId !== source.documentId || !value.source.version || value.source.version.length > 200 || !value.source.fingerprint || value.source.fingerprint.length > 200) throw new Error('component-draft-data')
+        const token = await tokenOf(entry.raw); current()
+        const marked = stored.get(marker({ key: name, token, record: value })) === token
+        if (marked && !entry.current) continue
+        // Discarding a backup in another tab does not discard this tab's visible input.
+        const candidate: ComponentPropertyAgentCandidate = { key: name, token, record: value, current: entry.current, storage: marked ? 'session' : entry.storage, status: marked ? 'session-only' : entry.status }
+        if (reference && (value.id !== reference.id || value.revision !== reference.revision || token !== reference.token)) throw new Error('client-component-draft-changed')
+        candidates.push(candidate)
+      } catch { current(); if (reference) throw new Error('client-component-draft-changed'); skippedInvalid++ }
+    }
+    current()
+    if (reference && candidates.length !== 1) throw new Error('client-component-draft-changed')
+    return { revision, candidates: candidates.sort((a, b) => a.record.id.localeCompare(b.record.id)), coverage, skippedInvalid }
+  }
+
+  keep(target: ComponentPropertyTarget, value: { source: CanonicalSource, definitionId: string, baseline: JsonObject, value: JsonObject, reset?: boolean, composing?: boolean }, origins: ComponentPropertyBackup[] = []): ComponentPropertyDraft {
+    if (this.#closed) throw new Error('component-draft-closed')
+    const key = targetKey(target), previous = this.#entries.get(key)
+    if (!previous && this.#entries.size >= 512) throw new Error('component-draft-limit')
+    const record: ComponentPropertyDraft = { format: 1, id: previous?.record.id ?? crypto.randomUUID(), revision: (previous?.record.revision ?? 0) + 1,
+      target: structuredClone(target), source: structuredClone(value.source), definitionId: value.definitionId, baseline: structuredClone(value.baseline), value: structuredClone(value.value),
+      reset: Boolean(value.reset), composing: Boolean(value.composing), updatedAt: new Date().toISOString() }
+    const entry: Entry = previous ?? { record, store: new DocumentDraftStore(scope(target), undefined, { owner: this.#writerOwner, family: 'component' }), failed: false, origins: [] }
+    entry.record = record
+    for (const origin of origins) if (!entry.origins.some(candidate => candidate.key === origin.key && candidate.token === origin.token)) entry.origins.push(origin)
+    this.#entries.set(key, entry)
+    const raw = JSON.stringify(record)
+    const operation = raw.length <= MAX_CHARS ? entry.store.put(keyOf(record), raw) : undefined
+    entry.operation = operation
+    entry.failed = !operation
+    this.#touch(target)
+    if (operation) void operation.done.then(result => {
+      if (this.#closed || this.#entries.get(key) !== entry || entry.operation !== operation) return
+      entry.operation = undefined; entry.failed = result !== 'committed'; this.#touch(target)
+    })
+    return record
+  }
+
+  /** Reads never settle a foreign backup or replace current input. Recovery is an explicit caller action. */
+  async read(target: ComponentPropertyTarget, signal?: AbortSignal): Promise<ComponentPropertyBackupRead> {
+    if (this.#closed) throw new Error('component-draft-closed')
+    const reader = new DocumentDraftStore(scope(target), undefined, { owner: this.#writerOwner, family: 'component' })
+    try {
+      const stored = await reader.read([prefix(target), markerPrefix(target)], signal), result: ComponentPropertyBackup[] = []
+      if (stored.size > 1024) throw new Error('component-draft-limit')
+      let unreadable = 0
+      for (const [key, raw] of stored) {
+        signal?.throwIfAborted()
+        if (!key.startsWith(prefix(target))) continue
+        if (typeof raw !== 'string' || raw.length > MAX_CHARS) { unreadable++; continue }
+        let record: unknown
+        try { record = JSON.parse(raw) } catch { unreadable++; continue }
+        if (!valid(record, target) || key !== keyOf(record)) { unreadable++; continue }
+        const token = await tokenOf(raw), candidate = { record, token, key }
+        signal?.throwIfAborted()
+        if (stored.get(marker(candidate)) === token) continue
+        const current = this.#entries.get(targetKey(target))
+        if (current?.record.id === record.id || current?.origins.some(origin => origin.key === key && origin.token === token)) continue
+        result.push(candidate)
+      }
+      return { candidates: result.sort((a, b) => b.record.updatedAt.localeCompare(a.record.updatedAt)), unreadable }
+    } finally { reader.close() }
+  }
+
+  /** Recovery creates a confirmed branch before replacing the current in-memory draft. */
+  async recover(backup: ComponentPropertyBackup, expected: ComponentPropertyDraft | undefined, signal?: AbortSignal, guard?: () => void): Promise<boolean> {
+    const target = backup.record.target, key = targetKey(target), previous = this.#entries.get(key)
+    const owns = () => !this.#closed && this.#entries.get(key) === previous && previous?.record === expected
+      && this.status(target) === 'available' && this.canKeep(target)
+    signal?.throwIfAborted(); guard?.()
+    if (!owns()) return false
+    const settled = this.#settle(target)
+    const store = new DocumentDraftStore(scope(target), undefined, { owner: this.#writerOwner, family: 'component' })
+    let adopted = false
+    try {
+      const values = await store.read([backup.key, marker(backup)], signal), raw = values.get(backup.key)
+      if (typeof raw !== 'string' || raw.length > MAX_CHARS || await tokenOf(raw) !== backup.token || values.get(marker(backup)) === backup.token) return false
+      signal?.throwIfAborted()
+      if (!owns()) return false
+      let value: unknown
+      try { value = JSON.parse(raw) } catch { return false }
+      if (!valid(value, target) || backup.key !== keyOf(value)) return false
+      guard?.()
+      const record: ComponentPropertyDraft = { ...structuredClone(value), id: crypto.randomUUID(), revision: 1, composing: false, updatedAt: new Date().toISOString() }
+      const fork = JSON.stringify(record)
+      if (fork.length > MAX_CHARS) return false
+      const operation = store.put(keyOf(record), fork)
+      if (!operation || await operation.done !== 'committed') return false
+      signal?.throwIfAborted()
+      // A later keystroke retains ownership; the committed branch remains recoverable.
+      guard?.()
+      if (!owns()) return false
+      this.#entries.set(key, { record, store, failed: false, origins: [backup] })
+      previous?.store.close()
+      adopted = true; this.#touch(target)
+      return true
+    } finally { if (!adopted) store.close(); settled() }
+  }
+
+  /** Both the in-memory revision and strict storage owner must still match the acknowledged input. */
+  async clear(expected: ComponentPropertyDraft, options?: { preserveOrigins?: boolean }): Promise<boolean> {
+    const key = targetKey(expected.target), entry = this.#entries.get(key)
+    if (this.#closed || !entry || entry.record !== expected) return false
+    const settled = this.#settle(expected.target)
+    try {
+      const operation = entry.store.remove(keyOf(expected), options?.preserveOrigins ? [] : entry.origins.map(origin => [marker(origin), origin.token] as [string, string]))
+      if (!operation) { entry.failed = true; this.#touch(expected.target); return false }
+      entry.operation = operation; this.#touch(expected.target)
+      const result = await operation.done
+      if (this.#closed || this.#entries.get(key) !== entry) return false
+      if (entry.operation === operation) { entry.operation = undefined; entry.failed = result !== 'committed' }
+      if (result === 'committed' && entry.record === expected) { this.#entries.delete(key); entry.store.close(); this.#touch(expected.target); return true }
+      this.#touch(expected.target)
+      return false
+    } finally { settled() }
+  }
+
+  /** A discarded foreign revision is marked exactly; newer input under that key remains recoverable. */
+  async discard(backup: ComponentPropertyBackup, signal?: AbortSignal, guard?: () => void): Promise<boolean> {
+    signal?.throwIfAborted(); guard?.()
+    if (this.#closed) return false
+    const settled = this.#settle(backup.record.target)
+    const reader = new DocumentDraftStore(scope(backup.record.target), undefined, { owner: this.#writerOwner, family: 'component' })
+    try {
+      const values = await reader.read([backup.key], signal), raw = values.get(backup.key)
+      if (typeof raw !== 'string' || await tokenOf(raw) !== backup.token) return false
+      signal?.throwIfAborted(); guard?.()
+      const result = await reader.mark([[marker(backup), backup.token]])
+      this.#touch(backup.record.target)
+      return result
+    } finally { reader.close(); settled() }
+  }
+  close(): void {
+    if (this.#closed) return
+    this.#closed = true
+    this.stopAgentRead()
+    if (typeof window !== 'undefined') window.removeEventListener('beforeunload', this.#leave)
+    for (const entry of this.#entries.values()) entry.store.close()
+    this.#listeners.clear()
+  }
+}

package/src/component-property-messages.ts

@@ -0,0 +1,31 @@
+export const COMPONENT_PROPERTY_MESSAGES = {
+  'zh-CN': {
+    properties: '属性', scope: '参数范围', base: '基础参数', step: '当前步骤', materials: '素材与引用', back: '返回参数',
+    apply: '应用', adopt: '采用', cancel: '取消', done: '完成', undo: '撤消', reset: '使用继承参数', resetPending: '将使用继承参数', edit: '继续编辑',
+    loading: '正在加载参数…', empty: '此内容没有公开参数。', changed: '文稿已更新，请重新检查。', recheck: '再次检查',
+    invalid: '请检查参数。', failed: '无法应用参数。输入已保留，请重试。', denied: '没有修改权限。', missing: '此内容已移除。',
+    storage: '输入仅在本次会话中保留。', storagePending: '正在备份输入…', storageRead: '无法读取备份。', limit: '无法再保留参数草稿。',
+    retry: '重试', backup: '参数备份', recover: '恢复草稿', discard: '放弃', discardChanges: '放弃更改', unreadable: '部分备份无法读取。',
+    backupChanged: '备份或输入已变化，请重新加载。', definitionChanged: '素材已改变，请核对保留的输入。',
+    preserved: '保留已有步骤覆盖', impact: (count: number) => `影响 ${count} 个步骤`,
+    search: '搜索素材', definitions: '已有素材', noDefinitions: '没有兼容素材。', results: (count: number) => `${count} 项`,
+    current: '当前素材', incompatible: '不适用于当前内容', module: '暂不支持此素材', references: '引用位置', locate: '定位',
+    actions: '素材操作', copy: '创建独立副本', remove: '删除', unavailable: '尚未提供独立副本或删除能力。', copyUnavailable: '尚未提供独立副本。', inUse: '此素材正在被引用。',
+    saved: '参数已应用到此内容。', resetReason: '之后将使用继承的参数。',
+  },
+  en: {
+    properties: 'Properties', scope: 'Parameter scope', base: 'Base parameters', step: 'Current step', materials: 'Assets and References', back: 'Back to Parameters',
+    apply: 'Apply', adopt: 'Use', cancel: 'Cancel', done: 'Done', undo: 'Undo', reset: 'Use Inherited Parameters', resetPending: 'Inherited parameters will be used', edit: 'Keep Editing',
+    loading: 'Loading parameters…', empty: 'No public parameters.', changed: 'The document changed. Review again.', recheck: 'Check Again',
+    invalid: 'Check the parameters.', failed: 'Couldn’t apply the parameters. Your input is kept; try again.', denied: 'Editing is not permitted.', missing: 'This content was removed.',
+    storage: 'Input is kept only in this session.', storagePending: 'Backing up input…', storageRead: 'Couldn’t read the backups.', limit: 'No more parameter drafts can be kept.',
+    retry: 'Retry', backup: 'Parameter backup', recover: 'Recover Draft', discard: 'Discard', discardChanges: 'Discard Changes', unreadable: 'Some backups could not be read.',
+    backupChanged: 'The backup or input changed. Reload it.', definitionChanged: 'The asset changed. Review the input that was kept.',
+    preserved: 'Keep existing step overrides', impact: (count: number) => `Affects ${count} ${count === 1 ? 'step' : 'steps'}`,
+    search: 'Search assets', definitions: 'Existing assets', noDefinitions: 'No compatible assets.', results: (count: number) => `${count} ${count === 1 ? 'item' : 'items'}`,
+    current: 'Current asset', incompatible: 'Not compatible with this content', module: 'This asset is not supported yet', references: 'References', locate: 'Locate',
+    actions: 'Asset Actions', copy: 'Make an Independent Copy', remove: 'Delete', unavailable: 'Independent copies and deletion are not available yet.', copyUnavailable: 'Independent copies are not available yet.', inUse: 'This asset is in use.',
+    saved: 'Parameters applied to this content.', resetReason: 'The inherited parameters will be used.',
+  },
+}
+export type ComponentPropertyMessages = typeof COMPONENT_PROPERTY_MESSAGES['en']