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

package/src/document-timing-drafts.ts

@@ -0,0 +1,61 @@
+import type { TeachingDocument } from '@lincyaw/kernel'
+import { stepTimingValue } from './step-production.ts'
+import type { ProductionSource, StepDurationDraft, StepDurationKey } from './step-production.ts'
+
+interface StoredDraft extends StepDurationDraft { baseValue?: number, baseSource: ProductionSource }
+const KEYS = ['minimumHoldMs', 'trailingPauseMs'] as const
+
+/** Only unaccepted form strings live here. Accepted timing remains in the document actor. */
+export class DocumentTimingDrafts {
+  readonly #documents = new Map<string, Map<string, StoredDraft>>()
+  failed = false
+  #storage(identity: string): string { return `presmium.document-timing.v1:${identity}` }
+  #load(identity: string): Map<string, StoredDraft> {
+    const existing = this.#documents.get(identity)
+    if (existing) return existing
+    const values = new Map<string, StoredDraft>()
+    this.#documents.set(identity, values)
+    let raw: string | null = null
+    try {
+      raw = sessionStorage.getItem(this.#storage(identity))
+      const entries: unknown = JSON.parse(raw ?? '[]')
+      if (!Array.isArray(entries) || entries.length > 512) throw new Error('document-timing-draft-data')
+      for (const entry of entries) {
+        if (!Array.isArray(entry) || entry.length !== 2 || typeof entry[0] !== 'string' || !entry[1] || typeof entry[1] !== 'object') throw new Error('document-timing-draft-data')
+        const target: unknown = JSON.parse(entry[0]), value = entry[1] as StoredDraft
+        if (!Array.isArray(target) || typeof target[0] !== 'string' || !KEYS.includes(target[1]) || typeof value.text !== 'string' || value.text.length > 256 || !['step', 'section', 'document', 'unset'].includes(value.baseSource) || value.baseValue !== undefined && (typeof value.baseValue !== 'number' || !Number.isFinite(value.baseValue) || value.baseValue < 0)) throw new Error('document-timing-draft-data')
+        values.set(entry[0], { text: value.text, error: true, review: true, baseValue: value.baseValue, baseSource: value.baseSource })
+      }
+    } catch {
+      this.failed = true
+      if (raw !== null) try { sessionStorage.setItem(`${this.#storage(identity)}:unreadable`, raw) } catch { /* Keep the original slot untouched when storage is unavailable. */ }
+    }
+    if (!this.failed) for (const key of this.#documents.keys()) {
+      if (this.#documents.size <= 8) break
+      if (key !== identity) this.#documents.delete(key)
+    }
+    return values
+  }
+  get(identity: string, document: TeachingDocument, stepId: string, key: StepDurationKey): StepDurationDraft | undefined {
+    const draft = this.#load(identity).get(JSON.stringify([stepId, key]))
+    if (!draft) return undefined
+    const actual = stepTimingValue(document, stepId, key)
+    return { text: draft.text, error: draft.error, review: draft.review || draft.baseValue !== actual.value || draft.baseSource !== actual.source }
+  }
+  has(identity: string, document: TeachingDocument): boolean {
+    return [...this.#load(identity).keys()].some(target => Object.hasOwn(document.steps, JSON.parse(target)[0]))
+  }
+  set(identity: string, document: TeachingDocument, stepId: string, key: StepDurationKey, draft: StepDurationDraft | undefined): boolean {
+    const values = this.#load(identity), target = JSON.stringify([stepId, key]), previous = values.get(target), actual = stepTimingValue(document, stepId, key)
+    if (draft && draft.text.length > 256 || draft && !previous && values.size >= 512) { this.failed = true; return true }
+    if (previous?.text === draft?.text && previous?.error === draft?.error && !previous?.review && (!previous || previous.baseValue === actual.value && previous.baseSource === actual.source)) return false
+    if (draft) values.set(target, { ...draft, baseValue: actual.value, baseSource: actual.source })
+    else values.delete(target)
+    try {
+      if (values.size) sessionStorage.setItem(this.#storage(identity), JSON.stringify([...values]))
+      else sessionStorage.removeItem(this.#storage(identity))
+      this.failed = false
+    } catch { this.failed = true }
+    return true
+  }
+}

package/src/document-voices.ts

@@ -0,0 +1,2 @@
+export { changeDocumentVoice, documentVoiceStepIds, previewDocumentVoiceChange, resolveDocumentStepVoice } from '@lincyaw/kernel'
+export type { DocumentStepVoice, DocumentVoiceImpact, DocumentVoiceOptions, DocumentVoiceScope } from '@lincyaw/kernel'

package/src/history.ts

@@ -0,0 +1,167 @@
+import { errorMessage } from '@lincyaw/kernel'
+import type { RevertResult, ReviewChange, ReviewSnapshot, ReviewUpdate } from '@lincyaw/kernel'
+import type { WorkbenchStore } from './workbench.ts'
+import { WorkspaceServerError } from './workspace-client.ts'
+import type { WorkspaceClient } from './workspace-client.ts'
+
+/**
+ * The open document's version history: its revisions with the next undo and redo, the files changed elsewhere and not
+ * yet in the history, and the AI's change in progress (followed while the document is open). Each action reads the
+ * history again. `changed` hears the AI's changes once each of its turns has made them: when the review waits for the
+ * author, or was accepted.
+ */
+export class DocumentHistory {
+  readonly #client: WorkspaceClient
+  readonly #store: WorkbenchStore
+  readonly #changed: (changes: ReviewChange[]) => void
+  #reads = 0
+  #offsets = [0]
+  #page = 0
+  #readFailure?: string
+  #scope = 0
+  #unsubscribeReview?: () => void
+  #review?: ReviewSnapshot
+  #told?: string
+
+  constructor(client: WorkspaceClient, store: WorkbenchStore, changed: (changes: ReviewChange[]) => void = () => {}) {
+    this.#client = client
+    this.#store = store
+    this.#changed = changed
+  }
+
+  subscribeReview(dir: string): void {
+    const scope = this.#scope
+    this.#unsubscribeReview = this.#client.subscribeReview(dir, event => { if (scope === this.#scope) this.#handleReviewUpdate(dir, event) })
+  }
+
+  stop(): void {
+    this.#scope++
+    this.#readFailure = undefined
+    this.#unsubscribeReview?.()
+    this.#unsubscribeReview = undefined
+    this.#review = undefined
+  }
+
+  async read(dir: string): Promise<void> {
+    this.#offsets = [0]
+    this.#page = 0
+    const read = ++this.#reads, scope = this.#scope
+    const current = () => this.#store.state.document === dir && read === this.#reads && scope === this.#scope
+    try {
+      const [history, { files }] = await Promise.all([this.#client.readRevisions(dir), this.#client.readChanges(dir)])
+      if (current()) {
+        const historyFailure = this.#store.state.historyFailure
+        this.#store.set({ history, outside: files, ...this.#readFailure === historyFailure ? { historyFailure: undefined } : {} })
+        this.#readFailure = undefined
+      }
+    } catch (error) {
+      if (current()) {
+        this.#readFailure = errorMessage(error)
+        const history = this.#store.state.history
+        this.#store.set({ ...history ? { history: { ...history, loading: false } } : {}, historyFailure: this.#readFailure })
+      }
+    }
+  }
+
+  async page(offset: number): Promise<void> {
+    const dir = this.#store.state.document, before = this.#store.state.history
+    if (dir === undefined || !before?.historyBinding || before.loading || this.#store.state.isHistoryBusy || ![before.nextOffset, before.previousOffset].includes(offset)) return
+    const read = ++this.#reads, scope = this.#scope
+    const current = () => read === this.#reads && scope === this.#scope && this.#store.state.document === dir
+    this.#store.set({ history: { ...before, loading: true } })
+    try {
+      const history = await this.#client.readRevisions(dir, { snapshot: before.historyBinding.snapshot, offset })
+      if (!current()) return
+      let index = this.#offsets.indexOf(offset)
+      if (index < 0) { this.#offsets = [...this.#offsets.slice(0, this.#page + 1), offset]; index = this.#offsets.length - 1 }
+      this.#page = index
+      this.#readFailure = undefined
+      this.#store.set({ history: { ...history, ...index > 0 ? { previousOffset: this.#offsets[index - 1] } : {} }, historyFailure: undefined })
+    } catch (error) {
+      if (!current()) return
+      if (error instanceof WorkspaceServerError && error.status === 409) { await this.read(dir); return }
+      this.#readFailure = errorMessage(error)
+      this.#store.set({ history: { ...before, loading: false }, historyFailure: this.#readFailure })
+    }
+  }
+
+  #handleReviewUpdate(dir: string, event: ReviewUpdate): void {
+    if (this.#store.state.document !== dir) return
+    this.#store.set({ review: event.review })
+    if (event.review) this.#review = event.review
+    const settled = event.review && !event.review.running ? event.review : event.ended?.outcome === 'accepted' ? this.#review : undefined
+    // One review spans the turns until it is accepted; each turn's changes are told once.
+    const turn = settled && `${settled.id}:${settled.turns.to}`
+    if (settled && turn !== this.#told && settled.changes.length > 0) {
+      this.#told = turn
+      this.#changed(settled.changes)
+    }
+    if (event.ended) {
+      this.#review = undefined
+      void this.read(dir)
+    }
+  }
+
+  async #run(work: (dir: string) => Promise<RevertResult | unknown>): Promise<boolean> {
+    const dir = this.#store.state.document
+    if (dir === undefined || this.#store.state.isHistoryBusy) return false
+    const scope = this.#scope
+    const current = () => scope === this.#scope && dir === this.#store.state.document
+    this.#readFailure = undefined
+    this.#store.set({ isHistoryBusy: true })
+    try {
+      const answer = await work(dir)
+      if (!current()) return false
+      if (isFailedRevert(answer)) throw new Error(answer.conflicts.join(', '))
+      this.#store.set({ historyFailure: undefined })
+      return true
+    } catch (error) {
+      if (current()) this.#store.set({ historyFailure: errorMessage(error) })
+      return false
+    } finally {
+      if (current()) {
+        this.#store.set({ isHistoryBusy: false })
+        await this.read(dir)
+      }
+    }
+  }
+
+  #change(which: 'undo' | 'redo' | 'revertRevision', expect: string | undefined): Promise<boolean> {
+    const binding = this.#store.state.history?.historyBinding
+    if (!binding || !expect) return Promise.resolve(false)
+    const request = { id: crypto.randomUUID(), ...binding, expect }
+    return this.#run(dir => this.#client[which](dir, request))
+  }
+
+  undo(): Promise<boolean> {
+    const expect = this.#store.state.history?.undo
+    return this.#change('undo', expect)
+  }
+
+  redo(): Promise<boolean> {
+    const expect = this.#store.state.history?.redo
+    return this.#change('redo', expect)
+  }
+
+  /** Takes back one revision of the history, whether or not it is the latest. */
+  revert(id: string): Promise<boolean> {
+    return this.#change('revertRevision', id)
+  }
+
+  acceptReview(): Promise<boolean> {
+    return this.#run(dir => this.#client.acceptReview(dir, {}))
+  }
+
+  rejectReview(): Promise<boolean> {
+    return this.#run(dir => this.#client.rejectReview(dir))
+  }
+
+  /** Makes the files changed elsewhere one revision of the history. */
+  recordOutside(message: string): Promise<boolean> {
+    return this.#run(dir => this.#client.commitChanges(dir, message))
+  }
+}
+
+function isFailedRevert(answer: unknown): answer is Extract<RevertResult, { ok: false }> {
+  return typeof answer === 'object' && answer !== null && (answer as { ok?: unknown }).ok === false
+}

package/src/index.ts

@@ -0,0 +1,36 @@
+export * from './components.tsx'
+export { PmSchemaForm, schemaFormPropertyNames } from './schema-form/PmSchemaForm.tsx'
+export type { PmSchemaFormProps } from './schema-form/PmSchemaForm.tsx'
+export { StepProductionEditor } from './StepProductionEditor.tsx'
+export type { StepProductionEditorProps } from './StepProductionEditor.tsx'
+export { MediaClipEditor } from './MediaClipEditor.tsx'
+export type { MediaClipAssetChoice, MediaClipDraft, MediaClipEditorProps } from './MediaClipEditor.tsx'
+export type { StepDurationDraft, StepDurationKey, StepTimingKey, StepTimingPatch } from './step-production.ts'
+export { useMessages, useWorkbench, useWorkbenchState, WorkbenchProvider } from './context.tsx'
+export type { DocumentComment } from '@lincyaw/kernel'
+export { localeOf, MESSAGES, timeAgo } from './messages.ts'
+export type { Locale, WorkbenchMessages } from './messages.ts'
+export { findPlaceAtLine, findPlaceSource } from './places.ts'
+export type { PlaceWithSource } from './places.ts'
+export { connectPreview } from './preview.ts'
+export type { PreviewConnection, PreviewHandlers } from './preview.ts'
+export { documentDirFor, hasSlides, isAgentChanging, selectedDocument, Workbench } from './workbench.ts'
+export type { AgentAnswer, AgentRequest, Pointer, PreviewSink, SaveState, WebView, WorkbenchMode, WorkbenchState } from './workbench.ts'
+export { OperationLog } from './telemetry.ts'
+export type { OperationBatch, OperationValue } from './telemetry.ts'
+export { isObservedWorkspaceFailure, workspaceClient, WorkspaceServerError } from './workspace-client.ts'
+export type { ApprovalEvent, WorkspaceCapabilities, WorkspaceClient, WorkspaceRequestEvent, WorkspaceSubscription, WorkspaceTransport, AuthoringClientChannel, AuthoringClientSubscription } from './workspace-client.ts'
+export { DocumentView } from './panels/DocumentView.tsx'
+export type { DocumentAside } from './panels/DocumentView.tsx'
+export { HistoryPanel } from './panels/HistoryPanel.tsx'
+export type { HistoryPanelProps, HistoryRevisionAction } from './panels/HistoryPanel.tsx'
+export { HomePanel } from './panels/HomePanel.tsx'
+export { WorkbenchApprovals } from './approvals.tsx'
+export { assistantMascotAction, useAssistantMascot } from './assistant-mascot.ts'
+export type { AssistantActivity } from './assistant-mascot.ts'
+export { mascotEnabled, setMascotEnabled, useMascotEnabled } from './mascot-preference.ts'
+export { PreviewPanel } from './panels/PreviewPanel.tsx'
+export { SpeechSettingsPanel } from './panels/SpeechSettingsPanel.tsx'
+export { SPEECH_SETTINGS_MESSAGES } from './speech-settings-messages.ts'
+export { connectAuthoringClient } from './authoring-client.ts'
+export { SHORTCUTS } from './shortcuts.ts'

package/src/jobs.ts

@@ -0,0 +1,111 @@
+import { errorMessage } from '@lincyaw/kernel'
+import type { CompileJob, JobSource } from '@lincyaw/kernel'
+import type { WorkbenchStore } from './workbench.ts'
+import type { WorkspaceClient } from './workspace-client.ts'
+
+/** Of two copies of a job (an event and an answer cross on the way), the one of the later change. */
+function newer(known: CompileJob | undefined, job: CompileJob): CompileJob {
+  return known && known.sequence > job.sequence ? known : job
+}
+
+/**
+ * The open document's builds and exports: what it can be made into, and its jobs as the workspace server runs them,
+ * whoever started them (the author here, or the AI), followed as they change.
+ */
+export class DocumentJobs {
+  readonly #client: WorkspaceClient
+  readonly #store: WorkbenchStore
+  #unsubscribe?: () => void
+  #scope = 0
+  #readTicket = 0
+  #baselineChanged = false
+
+  constructor(client: WorkspaceClient, store: WorkbenchStore) {
+    this.#client = client
+    this.#store = store
+  }
+
+  subscribe(dir: string): void {
+    this.#unsubscribe?.()
+    const scope = ++this.#scope
+    this.#baselineChanged = false
+    const current = () => scope === this.#scope && this.#store.state.document === dir
+    this.#unsubscribe = this.#client.subscribeJobs(dir, (job) => {
+      if (current()) {
+        if (!this.#store.state.jobs) this.#baselineChanged = true
+        this.#merge(job)
+      }
+    }, () => {
+      // A failed carrier may have missed changes.
+      if (current()) void this.#read(dir, current)
+    }, () => {
+      // Subscribe before reading: the first list and a reconnect can race a job.
+      if (current()) void this.#read(dir, current)
+    })
+    void this.#read(dir, current)
+  }
+
+  async #read(dir: string, current: () => boolean): Promise<void> {
+    const ticket = ++this.#readTicket
+    const startedWith = new Map((this.#store.state.jobs?.jobs ?? []).map(job => [job.id, job.sequence]))
+    const owns = () => current() && ticket === this.#readTicket
+    try {
+      const answer = await this.#client.readJobs(dir)
+      if (!owns()) return
+      // The events that arrived meanwhile may be newer than the list read.
+      const known = new Map((this.#store.state.jobs?.jobs ?? []).map(job => [job.id, job]))
+      const read = new Set(answer.jobs.map(job => job.id))
+      // Keep only observations made after this read began, including a job that already finished.
+      const observed = [...known.values()].filter(job => !read.has(job.id) && (!startedWith.has(job.id) || job.sequence > startedWith.get(job.id)!))
+      const jobs = [...observed, ...answer.jobs.map(job => newer(known.get(job.id), job))]
+      this.#store.set({ jobs: { ...answer, jobs }, jobsFailure: undefined })
+      if (this.#baselineChanged && owns()) {
+        this.#baselineChanged = false
+        void this.#read(dir, current)
+      }
+    } catch (error) {
+      if (owns()) this.#store.set({ jobsFailure: errorMessage(error) })
+    }
+  }
+
+  /** A job as it is now, in its place among the document's (newest first): a copy older than the one known is left. */
+  #merge(job: CompileJob): void {
+    const known = this.#store.state.jobs
+    if (!known) return
+    const jobs = known.jobs.some(own => own.id === job.id) ? known.jobs.map(own => (own.id === job.id ? newer(own, job) : own)) : [job, ...known.jobs]
+    this.#store.set({ jobs: { ...known, jobs } })
+  }
+
+  async start(dir: string, target: string, source: JobSource): Promise<void> {
+    const scope = this.#scope
+    const current = () => scope === this.#scope && this.#store.state.document === dir
+    try {
+      const job = await this.#client.startJob(dir, target, source)
+      if (!current()) return
+      this.#merge(job)
+      this.#store.set({ jobsFailure: undefined })
+    } catch (error) {
+      if (current()) this.#store.set({ jobsFailure: errorMessage(error) })
+    }
+  }
+
+  async cancel(id: string): Promise<void> {
+    const dir = this.#store.state.document
+    if (dir === undefined) return
+    const scope = this.#scope
+    const current = () => scope === this.#scope && this.#store.state.document === dir
+    try {
+      const job = await this.#client.cancelJob(dir, id)
+      if (current()) this.#merge(job)
+    } catch (error) {
+      if (current()) this.#store.set({ jobsFailure: errorMessage(error) })
+    }
+  }
+
+  stop(): void {
+    this.#scope++
+    this.#baselineChanged = false
+    this.#unsubscribe?.()
+    this.#unsubscribe = undefined
+  }
+}

package/src/mascot-preference.ts

@@ -0,0 +1,37 @@
+// Whether the author wants the kitten: one choice for every place it shows, kept in this browser and followed by
+// every open tab. It is on until the author turns it off.
+import { useSyncExternalStore } from 'react'
+
+const KEY = 'presmium.mascot'
+const listeners = new Set<() => void>()
+
+function read(): boolean {
+  try { return localStorage.getItem(KEY) !== 'off' } catch { return true }
+}
+
+let enabled = typeof localStorage === 'undefined' ? true : read()
+
+function subscribe(listener: () => void): () => void {
+  listeners.add(listener)
+  const storage = (event: StorageEvent) => {
+    if (event.key !== KEY) return
+    enabled = read()
+    for (const each of listeners) each()
+  }
+  window.addEventListener('storage', storage)
+  return () => { listeners.delete(listener); window.removeEventListener('storage', storage) }
+}
+
+export function mascotEnabled(): boolean {
+  return enabled
+}
+
+export function setMascotEnabled(on: boolean): void {
+  enabled = on
+  try { localStorage.setItem(KEY, on ? 'on' : 'off') } catch { /* The choice holds for this page only. */ }
+  for (const listener of listeners) listener()
+}
+
+export function useMascotEnabled(): boolean {
+  return useSyncExternalStore(subscribe, mascotEnabled, () => true)
+}

package/src/media-drafts.ts

@@ -0,0 +1,83 @@
+import { isRecord } from '@lincyaw/kernel'
+import type { MediaClip } from '@lincyaw/kernel'
+import type { MediaClipDraft } from './MediaClipEditor.tsx'
+import type { WorkspaceClient } from './workspace-client.ts'
+
+export interface MediaDrafts { selectedClipId?: string, entries: Record<string, MediaClipDraft> }
+interface Entry { value: MediaDrafts, failed: boolean, volatile: boolean, unreadable?: string }
+const memory = new WeakMap<WorkspaceClient, Map<string, Entry>>()
+const prefix = 'presmium.media-drafts.v1:', limit = 64
+const keyOf = (identity: string, stepId: string) => prefix + JSON.stringify([identity, stepId])
+const string = (value: unknown): value is string => typeof value === 'string'
+const number = (value: unknown): value is number => typeof value === 'number' && Number.isFinite(value) && value >= 0
+
+function validClip(value: unknown): value is MediaClip {
+  return isRecord(value) && string(value.id) && string(value.assetId) && isRecord(value.sourceRange) && number(value.sourceRange.startMs) && number(value.sourceRange.endMs)
+    && isRecord(value.attachment) && string(value.attachment.stepId) && number(value.attachment.offsetMs) && number(value.volume) && value.volume <= 1 && (value.muted === undefined || typeof value.muted === 'boolean')
+}
+function valid(value: unknown): value is MediaDrafts {
+  return isRecord(value) && (value.selectedClipId === undefined || string(value.selectedClipId)) && isRecord(value.entries)
+    && Object.entries(value.entries).every(([key, draft]) => string(key) && isRecord(draft) && string(draft.version) && validClip(draft.clip) && (draft.baseClip === undefined || validClip(draft.baseClip))
+      && [draft.startText, draft.endText, draft.offsetText].every(text => text === undefined || string(text)))
+}
+function store(client: WorkspaceClient): Map<string, Entry> {
+  let known = memory.get(client)
+  if (!known) memory.set(client, known = new Map())
+  return known
+}
+function trim(known: Map<string, Entry>): void {
+  // Persisted forms can be reloaded; failed writes must keep their only current copy.
+  for (const [key, value] of known) {
+    if (known.size <= limit) break
+    if (!value.volatile) known.delete(key)
+  }
+}
+function load(client: WorkspaceClient, key: string): Entry {
+  const known = store(client), previous = known.get(key)
+  if (previous) { known.delete(key); known.set(key, previous); return previous }
+  const entry: Entry = { value: { entries: {} }, failed: false, volatile: false }
+  try {
+    const raw = sessionStorage.getItem(key)
+    if (raw !== null) {
+      entry.unreadable = raw
+      if (raw.length > 131072) throw new Error('media-drafts-size')
+      const value: unknown = JSON.parse(raw)
+      if (!valid(value)) throw new Error('media-drafts-shape')
+      entry.value = value; delete entry.unreadable
+    }
+  } catch { entry.failed = true }
+  known.set(key, entry)
+  trim(known)
+  return entry
+}
+
+/** Only form input is cached. Current canonical IDs, versions, media and step limits are checked on apply. */
+export function readMediaDrafts(client: WorkspaceClient, identity: string, stepId: string): MediaDrafts {
+  return structuredClone(load(client, keyOf(identity, stepId)).value)
+}
+export function mediaDraftStorageFailed(client: WorkspaceClient, identity: string, stepId: string): boolean {
+  return load(client, keyOf(identity, stepId)).failed
+}
+export function keepMediaDrafts(client: WorkspaceClient, identity: string, stepId: string, value: MediaDrafts): boolean {
+  if (!valid(value)) return false
+  const key = keyOf(identity, stepId), entry = load(client, key)
+  entry.value = structuredClone(value); entry.volatile = true
+  const known = store(client); known.set(key, entry)
+  try {
+    const raw = JSON.stringify(value)
+    if (raw.length > 131072) throw new Error('media-drafts-size')
+    if (entry.unreadable !== undefined) sessionStorage.setItem(`${key}:unreadable`, entry.unreadable)
+    sessionStorage.setItem(key, raw)
+    const keys = Array.from({ length: sessionStorage.length }, (_, index) => sessionStorage.key(index)!).filter(name => name.startsWith(prefix) && !name.endsWith(':unreadable') && name !== key)
+    let excess = keys.length - limit + 1
+    for (const old of keys) {
+      if (excess <= 0) break
+      let previous: unknown
+      try { previous = JSON.parse(sessionStorage.getItem(old) ?? 'null') } catch { continue }
+      if (valid(previous) && !Object.keys(previous.entries).length && sessionStorage.getItem(`${old}:unreadable`) === null) { sessionStorage.removeItem(old); excess-- }
+    }
+    entry.failed = false; entry.volatile = false; delete entry.unreadable
+    trim(known)
+    return true
+  } catch { entry.failed = true; trim(known); return false }
+}

package/src/media-messages.ts

@@ -0,0 +1,53 @@
+import type { Locale } from './messages.ts'
+
+export const MEDIA_MESSAGES = {
+  'zh-CN': {
+    title: '音频片段', import: '导入音频', retryImport: '重试导入', asset: '音频素材', chooseAsset: '选择音频素材', clip: '当前步骤片段', newClip: '新片段',
+    in: '入点', out: '出点', timeFormat: 'mm:ss.mmm', offset: '步骤内延后（秒）', volume: '音量', mute: '静音', unmute: '取消静音',
+    add: '采用到本步', apply: '应用', restore: '使用完整音频', remove: '删除片段', check: '核对当前版本', retry: '重新加载',
+    loading: '正在加载音频…', pending: '尚未采用', saved: '片段已应用到当前步骤', imported: '音频已导入',
+    original: (duration: string, used?: string) => `原始 00:00.000 – ${duration}${used ? ` · 使用 ${used}` : ''}`,
+    clipLabel: (index: number, name: string) => `片段 ${index + 1} · ${name}`,
+    invalidTime: '请输入 mm:ss.mmm 格式的时间。', invalidRange: '出点须晚于入点，且不超出原始时长。', invalidOffset: '请输入不小于 0 的秒数。',
+    exceedsStep: '片段超出本步。请裁剪片段、减少延后，或另行调整本步的停留。',
+    unavailable: '先准备当前版本并确认本步时段，再采用片段。',
+    review: '文稿已变化，输入仍保留；请核对当前版本后采用。', removed: '原片段已移除，输入仍保留；请选择新片段。',
+    storageFailed: '无法在本机保留草稿，请保持页面打开。', failed: '无法完成音频操作。输入已保留，请重试。',
+    sourceChanged: '文稿已变化，输入仍保留。请准备当前版本后重试。',
+    size: '请选择非空且不超过 16 MiB 的音频。', format: '此文件不是受支持的单音轨音频，或数据已损坏。',
+    duration: '无法确认音频时长，或时长超过 10 分钟。', missing: '找不到音频素材或原始文件，请检查或重新导入。',
+    changed: '原始音频已变化，请重新加载并准备当前版本。', serviceUnavailable: '当前工作区未提供音频导入服务。',
+  },
+  en: {
+    title: 'Audio Clip', import: 'Import Audio', retryImport: 'Retry Import', asset: 'Audio asset', chooseAsset: 'Choose Audio', clip: 'Clips in this step', newClip: 'New Clip',
+    in: 'In', out: 'Out', timeFormat: 'mm:ss.mmm', offset: 'Step offset (seconds)', volume: 'Volume', mute: 'Mute', unmute: 'Unmute',
+    add: 'Add to Step', apply: 'Apply', restore: 'Use Full Audio', remove: 'Delete Clip', check: 'Review Current Version', retry: 'Reload',
+    loading: 'Loading audio…', pending: 'Not applied', saved: 'Clip applied to this step', imported: 'Audio imported',
+    original: (duration: string, used?: string) => `Original 00:00.000 – ${duration}${used ? ` · Used ${used}` : ''}`,
+    clipLabel: (index: number, name: string) => `Clip ${index + 1} · ${name}`,
+    invalidTime: 'Enter a time in mm:ss.mmm format.', invalidRange: 'The out point must follow the in point and stay within the original duration.', invalidOffset: 'Enter an offset of 0 seconds or more.',
+    exceedsStep: 'The clip exceeds this step. Trim it, reduce its offset, or change the step hold separately.',
+    unavailable: 'Prepare the current version and confirm this step’s timing before applying.',
+    review: 'The document changed. Your input is kept; review the current version before applying.', removed: 'The original clip was removed. Your input is kept; choose New Clip.',
+    storageFailed: 'Couldn’t keep the draft on this device. Keep this page open.', failed: 'Couldn’t finish the audio operation. Your input is kept; try again.',
+    sourceChanged: 'The document changed. Your input is kept; prepare the current version and retry.',
+    size: 'Choose nonempty audio of at most 16 MiB.', format: 'The file is not supported single-track audio, or its data is damaged.',
+    duration: 'The audio duration is unconfirmed or exceeds ten minutes.', missing: 'The audio asset or original file is missing. Check it or import again.',
+    changed: 'The original audio changed. Reload it and prepare the current version.', serviceUnavailable: 'This workspace does not provide audio import.',
+  },
+}
+
+export function mediaFailure(error: unknown, locale: Locale): string {
+  const code = error instanceof Error ? error.message : String(error), t = MEDIA_MESSAGES[locale]
+  if (['document-version-changed', 'production-revision-changed', 'production-binding-changed', 'production-plan-changed', 'production-source-changed', 'document-context-changed'].includes(code)) return t.sourceChanged
+  if (code === 'production.asset-size') return t.size
+  if (code === 'production.asset-duration') return t.duration
+  if (code === 'production.asset-changed' || code === 'production.asset-fingerprint') return t.changed
+  if (['production.asset-missing', 'production.asset-path', 'production.asset-file', 'workspace-file-missing'].includes(code)) return t.missing
+  if (code === 'production.asset-format' || code === 'production.asset-kind') return t.format
+  if (code === 'production.media-range') return t.invalidRange
+  if (code === 'production.media-step-range') return t.exceedsStep
+  if (code === 'production.media-step-unknown') return t.unavailable
+  if (code === 'production-audio-unavailable') return t.serviceUnavailable
+  return t.failed
+}

package/src/media-time.ts

@@ -0,0 +1,12 @@
+/** Untouched values keep their original numeric precision; edited values use the shared media grammar. */
+export function mediaTime(value: number): string {
+  const ms = Math.max(0, Math.round(value))
+  return `${String(Math.floor(ms / 60000)).padStart(2, '0')}:${(ms % 60000 / 1000).toFixed(3).padStart(6, '0')}`
+}
+export function mediaTimeValue(raw: string | undefined, original: number): number | undefined {
+  if (raw === undefined || raw === mediaTime(original)) return original
+  const match = /^(\d+):([0-5]\d)(?:\.(\d{1,6}))?$/.exec(raw.normalize('NFKC').trim())
+  if (!match) return undefined
+  const value = Number(match[1]) * 60000 + Number(match[2]) * 1000 + Number(`0.${match[3] ?? '0'}`) * 1000
+  return Number.isFinite(value) ? value : undefined
+}