@peanut-admin/admin 0.1.0-alpha.3 → 0.1.0-alpha.5

package/client-core/src/index.ts

@@ -7,11 +7,27 @@ export type ClientRequestMethod =
   | 'POST'
   | 'PUT'
 
+export interface ClientHeaderSource {
+  forEach: (callback: (value: string, key: string) => void) => void
+}
+
+export type ClientRequestHeaders =
+  | Readonly<Record<string, string>>
+  | ReadonlyArray<readonly [string, string]>
+  | ClientHeaderSource
+
+export interface ClientHeaders extends ClientHeaderSource {
+  delete: (name: string) => void
+  get: (name: string) => string | null
+  has: (name: string) => boolean
+  set: (name: string, value: string) => void
+}
+
 export interface ClientRequest<TData = unknown> {
   readonly path: string
   readonly method?: ClientRequestMethod
   readonly data?: TData
-  readonly headers?: HeadersInit
+  readonly headers?: ClientRequestHeaders
   readonly auth?: boolean
 }
 
@@ -19,7 +35,7 @@ export interface ClientTransportRequest<TData = unknown> {
   readonly path: string
   readonly method: ClientRequestMethod
   readonly data?: TData
-  readonly headers: Headers
+  readonly headers: ClientHeaders
 }
 
 export type ClientTransport = (request: ClientTransportRequest) => Promise<unknown>
@@ -96,6 +112,9 @@ const pathControlCharacters = /[\u0000-\u001f\u007f]/
 const controlCharacters = /[\u0000-\u001f\u007f]/g
 const encodedUnsafePathSegment = /%(?:2e|2f|5c)/i
 const absolutePath = /^[A-Za-z][A-Za-z0-9+.-]*:/
+const httpBaseUrl = /^(https?):\/\/([^/?#]+)(\/[^?#]*)?$/i
+const validHeaderName = /^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/
+const invalidHeaderValue = /[\u0000\r\n]/
 const safeCode = /^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$/
 const defaultUnauthorizedCode = 'CLIENT_UNAUTHORIZED'
 const defaultBusinessCode = 'CLIENT_BUSINESS_ERROR'
@@ -130,34 +149,49 @@ const assertClientPath = (path: string): void => {
   }
 }
 
-const validBaseUrl = (baseUrl: string): URL => {
-  let url: URL
-  try {
-    url = new URL(baseUrl)
-  } catch {
-    throw new ClientRequestError('path', 'CLIENT_BASE_URL_INVALID', 'The client base URL is invalid.')
+const invalidBaseUrl = (): ClientRequestError => (
+  new ClientRequestError('path', 'CLIENT_BASE_URL_INVALID', 'The client base URL is invalid.')
+)
+
+const validBaseUrl = (baseUrl: string): { origin: string; pathname: string } => {
+  if (
+    typeof baseUrl !== 'string'
+    || baseUrl.trim() !== baseUrl
+    || pathControlCharacters.test(baseUrl)
+    || baseUrl.includes('\\')
+  ) {
+    throw invalidBaseUrl()
   }
 
+  const match = httpBaseUrl.exec(baseUrl)
+  const protocol = match?.[1]
+  const authority = match?.[2]
+  const pathname = match?.[3] ?? '/'
   if (
-    !['http:', 'https:'].includes(url.protocol)
-    || url.username !== ''
-    || url.password !== ''
-    || url.search !== ''
-    || url.hash !== ''
+    protocol === undefined
+    || authority === undefined
+    || authority === ''
+    || authority.includes('@')
+    || /\s/.test(authority)
+    || encodedUnsafePathSegment.test(pathname)
+    || pathname.split('/').some(segment => segment === '.' || segment === '..')
   ) {
-    throw new ClientRequestError('path', 'CLIENT_BASE_URL_INVALID', 'The client base URL is invalid.')
+    throw invalidBaseUrl()
   }
 
-  return url
+  return {
+    origin: `${protocol.toLowerCase()}://${authority}`,
+    pathname,
+  }
 }
 
 export const resolveClientUrl = (baseUrl: string, path: string): string => {
   assertClientPath(path)
   const base = validBaseUrl(baseUrl)
   const basePath = base.pathname.endsWith('/') ? base.pathname : `${base.pathname}/`
-  const root = new URL(base.origin)
-  root.pathname = basePath
-  return new URL(path, root).toString()
+  return path.startsWith('/')
+    ? `${base.origin}${path}`
+    : `${base.origin}${basePath}${path}`
 }
 
 const safeMessage = (value: unknown, fallback: string): string => {
@@ -203,9 +237,66 @@ const normalizedDecodedResult = (value: ClientDecodeResult): ClientDecodeResult
   }
 }
 
-const requestHeaders = (headers: HeadersInit | undefined): Headers => {
-  const result = new Headers(headers)
-  // Headers is case-insensitive and delete removes all values for this name.
+const isHeaderSource = (value: unknown): value is ClientHeaderSource => (
+  typeof value === 'object'
+  && value !== null
+  && typeof (value as { forEach?: unknown }).forEach === 'function'
+)
+
+class PortableClientHeaders implements ClientHeaders {
+  private readonly values = new Map<string, string>()
+
+  constructor(headers?: ClientRequestHeaders) {
+    if (headers === undefined) return
+
+    if (Array.isArray(headers)) {
+      for (const entry of headers) {
+        if (!Array.isArray(entry) || entry.length !== 2) throw new TypeError('invalid header entry')
+        this.set(entry[0], entry[1])
+      }
+      return
+    }
+
+    if (isHeaderSource(headers)) {
+      headers.forEach((value, key) => this.set(key, value))
+      return
+    }
+
+    if (typeof headers === 'object' && headers !== null) {
+      for (const [key, value] of Object.entries(headers)) this.set(key, value)
+      return
+    }
+
+    throw new TypeError('invalid headers')
+  }
+
+  delete(name: string): void {
+    this.values.delete(name.toLowerCase())
+  }
+
+  get(name: string): string | null {
+    return this.values.get(name.toLowerCase()) ?? null
+  }
+
+  has(name: string): boolean {
+    return this.values.has(name.toLowerCase())
+  }
+
+  set(name: string, value: string): void {
+    if (!validHeaderName.test(name) || typeof value !== 'string' || invalidHeaderValue.test(value)) {
+      throw new TypeError('invalid header')
+    }
+    this.values.set(name.toLowerCase(), value.trim())
+  }
+
+  forEach(callback: (value: string, key: string) => void): void {
+    this.values.forEach((value, key) => callback(value, key))
+  }
+}
+
+const requestHeaders = (headers: ClientRequestHeaders | undefined): ClientHeaders => {
+  const result = new PortableClientHeaders(headers)
+  // Header names are normalized, so delete removes every caller spelling.
   result.delete('Authorization')
   return result
 }
@@ -251,7 +342,7 @@ export const createClient = (options: ClientOptions): Client => {
     }
 
     const method = methodOf(input.method)
-    let headers: Headers
+    let headers: ClientHeaders
     try {
       headers = requestHeaders(input.headers)
     } catch {
@@ -322,4 +413,3 @@ export const createClient = (options: ClientOptions): Client => {
 export type ClientResult<TData = unknown> = ClientDecodeResult<TData>
 export type ClientRequestResult<TData = unknown> = Promise<TData>
 export type ClientHook = (error: ClientRequestError) => void | Promise<void>
-export type ClientRequestHeaders = HeadersInit

package/client-nuxt/src/index.ts

@@ -1,11 +1,11 @@
 import { resolveClientUrl } from '@peanut-admin/admin/client'
-import type { ClientTransport, ClientTransportRequest } from '@peanut-admin/admin/client'
+import type { ClientHeaders, ClientTransport, ClientTransportRequest } from '@peanut-admin/admin/client'
 
 export interface NuxtClientFetchOptions {
   readonly method?: string
   readonly query?: unknown
   readonly body?: unknown
-  readonly headers?: HeadersInit
+  readonly headers?: Record<string, string>
 }
 
 export type NuxtClientFetch = (
@@ -20,6 +20,14 @@ export interface NuxtClientTransportOptions {
 
 const isQueryMethod = (method: string): boolean => method === 'GET' || method === 'DELETE'
 
+const headersRecord = (headers: ClientHeaders): Record<string, string> => {
+  const result: Record<string, string> = {}
+  headers.forEach((value, key) => {
+    result[key] = value
+  })
+  return result
+}
+
 export const createNuxtClientTransport = (
   options: NuxtClientTransportOptions,
 ): ClientTransport => {
@@ -28,7 +36,7 @@ export const createNuxtClientTransport = (
     const url = resolveClientUrl(options.baseUrl, request.path)
     const fetchOptions: NuxtClientFetchOptions = {
       method,
-      headers: request.headers,
+      headers: headersRecord(request.headers),
       ...(request.data !== undefined
         ? isQueryMethod(method)
           ? { query: request.data }

package/client-uniapp/src/index.ts

@@ -1,5 +1,5 @@
 import { resolveClientUrl } from '@peanut-admin/admin/client'
-import type { ClientTransport, ClientTransportRequest } from '@peanut-admin/admin/client'
+import type { ClientHeaders, ClientTransport, ClientTransportRequest } from '@peanut-admin/admin/client'
 
 export interface UniAppClientResponse {
   readonly data: unknown
@@ -23,7 +23,7 @@ export interface UniAppClientTransportOptions {
   readonly request: UniAppClientRequest
 }
 
-const headersRecord = (headers: Headers): Record<string, string> => {
+const headersRecord = (headers: ClientHeaders): Record<string, string> => {
   const result: Record<string, string> = {}
   headers.forEach((value, key) => {
     result[key] = value

package/collaboration/src/contracts.ts

@@ -0,0 +1,207 @@
+export const COLLABORATION_ENGINE_NAME = 'yjs' as const
+export const COLLABORATION_ENGINE_VERSION = '13.6.32' as const
+
+export type CollaborationCapability = 'read' | 'write'
+export type CollaborationSessionState = 'active' | 'published' | 'closed' | 'expired'
+export type CollaborationConnectionStatus = 'idle' | 'admitting' | 'hydrating' | 'connecting' | 'connected' | 'disconnected' | 'error' | 'disposed'
+export type CollaborationUpdateOrigin = 'local' | 'remote' | 'replay'
+export type CollaborationTransportStatus = 'connecting' | 'connected' | 'disconnected'
+export type CollaborationErrorCode =
+  | 'COLLABORATION_INVALID'
+  | 'COLLABORATION_NOT_FOUND'
+  | 'COLLABORATION_DENIED'
+  | 'COLLABORATION_CONFLICT'
+  | 'COLLABORATION_LEASE_EXPIRED'
+  | 'COLLABORATION_PAYLOAD_TOO_LARGE'
+  | 'COLLABORATION_BACKPRESSURE'
+  | 'COLLABORATION_PROVIDER_UNAVAILABLE'
+  | 'COLLABORATION_INTEGRITY_FAILURE'
+  | 'COLLABORATION_INTERNAL_ERROR'
+
+export interface CollaborationSession {
+  readonly sessionKey: string
+  readonly artifactType: string
+  readonly artifactKey: string
+  readonly engineName: typeof COLLABORATION_ENGINE_NAME
+  readonly engineVersion: typeof COLLABORATION_ENGINE_VERSION
+  readonly baseRevisionKey: string
+  readonly baseRevisionDigest: string
+  readonly latestSequence: number
+  readonly state: CollaborationSessionState
+  readonly expiresAt: string
+}
+
+export interface CollaborationLease {
+  readonly leaseKey: string
+  readonly clientKey: string
+  readonly capability: CollaborationCapability
+  readonly expiresAt: string
+}
+
+export interface CollaborationTransportAdmission {
+  readonly websocketUrl: string
+  readonly roomName: string
+}
+
+export interface CollaborationAdmission {
+  readonly session: CollaborationSession
+  readonly lease: CollaborationLease
+  readonly transport: CollaborationTransportAdmission
+}
+
+export interface CollaborationUpdateEnvelope {
+  readonly updateKey: string
+  readonly sequence: number
+  readonly engineName: typeof COLLABORATION_ENGINE_NAME
+  readonly engineVersion: typeof COLLABORATION_ENGINE_VERSION
+  readonly digest: string
+  readonly payload: Uint8Array
+}
+
+export interface CollaborationSnapshotEnvelope {
+  readonly snapshotKey: string
+  readonly coveredSequence: number
+  readonly engineName: typeof COLLABORATION_ENGINE_NAME
+  readonly engineVersion: typeof COLLABORATION_ENGINE_VERSION
+  readonly snapshotDigest: string
+  readonly stateVectorDigest: string
+  readonly snapshot: Uint8Array
+  readonly stateVector: Uint8Array
+}
+
+export interface CollaborationStatePage {
+  readonly snapshot: CollaborationSnapshotEnvelope | null
+  readonly updates: readonly CollaborationUpdateEnvelope[]
+  readonly latestSequence: number
+  readonly nextAfterSequence: number | null
+}
+
+export interface CollaborationSafeError {
+  readonly code: CollaborationErrorCode
+  readonly message: string
+  readonly requestId: string | null
+  readonly status: number
+}
+
+export interface CollaborationEngine<TDocument = unknown> {
+  readonly document: TDocument
+  applyUpdate: (update: Uint8Array, origin?: Exclude<CollaborationUpdateOrigin, 'local'>) => void
+  encodeStateVector: () => Uint8Array
+  encodeSnapshot: () => Uint8Array
+  onUpdate: (listener: (update: Uint8Array, origin: CollaborationUpdateOrigin) => void) => () => void
+  dispose: () => void
+}
+
+export interface CollaborationTransport {
+  connect: (admission: CollaborationTransportAdmission, initialSnapshot: Uint8Array) => void
+  disconnect: () => void
+  sendUpdate: (update: Uint8Array) => void
+  onStatus: (listener: (status: CollaborationTransportStatus) => void) => () => void
+  onUpdate: (listener: (update: Uint8Array) => void) => () => void
+  dispose: () => void
+}
+
+export interface CollaborationHostApi {
+  admit: (signal: AbortSignal) => Promise<CollaborationAdmission>
+  state: (sessionKey: string, afterSequence: number, signal: AbortSignal) => Promise<CollaborationStatePage>
+}
+
+export interface CollaborationRuntimeState {
+  readonly status: CollaborationConnectionStatus
+  readonly session: CollaborationSession | null
+  readonly lease: CollaborationLease | null
+  readonly latestSequence: number
+  readonly error: CollaborationSafeError | null
+}
+
+const stableKey = /^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)*$/
+const opaqueKey = /^[a-z][a-z0-9]*_[0-9a-f]{32}$/
+const sha256 = /^[0-9a-f]{64}$/
+const instant = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/
+
+const printable = (value: string, maximum: number): boolean => value.length >= 1 && value.length <= maximum && /^[\x20-\x7e]+$/.test(value)
+const validInstant = (value: string): boolean => instant.test(value) && Number.isFinite(Date.parse(value))
+const sequence = (value: number): boolean => Number.isSafeInteger(value) && value >= 0
+const bytes = (value: Uint8Array, maximum: number): boolean => value.byteLength >= 1 && value.byteLength <= maximum
+
+export const assertCollaborationAdmission = (admission: CollaborationAdmission): void => {
+  const { session, lease, transport } = admission
+  if (!opaqueKey.test(session.sessionKey) || !stableKey.test(session.artifactType) || session.artifactType.length > 64
+    || !printable(session.artifactKey, 128) || session.engineName !== COLLABORATION_ENGINE_NAME
+    || session.engineVersion !== COLLABORATION_ENGINE_VERSION || !printable(session.baseRevisionKey, 128)
+    || !sha256.test(session.baseRevisionDigest) || !sequence(session.latestSequence) || session.state !== 'active'
+    || !validInstant(session.expiresAt) || !opaqueKey.test(lease.leaseKey) || !printable(lease.clientKey, 128)
+    || (lease.capability !== 'read' && lease.capability !== 'write') || !validInstant(lease.expiresAt)
+    || typeof transport.websocketUrl !== 'string' || !printable(transport.roomName, 128)) {
+    throw new Error('COLLABORATION_RESPONSE_INVALID')
+  }
+}
+
+export const assertCollaborationStatePage = (page: CollaborationStatePage, afterSequence: number): void => {
+  if (!sequence(page.latestSequence) || page.latestSequence < afterSequence
+    || (page.nextAfterSequence !== null && (!sequence(page.nextAfterSequence) || page.nextAfterSequence <= afterSequence || page.nextAfterSequence > page.latestSequence))) {
+    throw new Error('COLLABORATION_RESPONSE_INVALID')
+  }
+  let cursor = afterSequence
+  if (page.snapshot !== null) {
+    const snapshot = page.snapshot
+    if (!opaqueKey.test(snapshot.snapshotKey) || !sequence(snapshot.coveredSequence) || snapshot.coveredSequence < afterSequence
+      || snapshot.coveredSequence > page.latestSequence || snapshot.engineName !== COLLABORATION_ENGINE_NAME
+      || snapshot.engineVersion !== COLLABORATION_ENGINE_VERSION || !sha256.test(snapshot.snapshotDigest)
+      || !sha256.test(snapshot.stateVectorDigest) || !bytes(snapshot.snapshot, 8_388_608) || !bytes(snapshot.stateVector, 8_388_608)) {
+      throw new Error('COLLABORATION_RESPONSE_INVALID')
+    }
+    cursor = snapshot.coveredSequence
+  }
+  for (const update of page.updates) {
+    if (!opaqueKey.test(update.updateKey) || update.sequence !== cursor + 1 || update.sequence > page.latestSequence
+      || update.engineName !== COLLABORATION_ENGINE_NAME || update.engineVersion !== COLLABORATION_ENGINE_VERSION
+      || !sha256.test(update.digest) || !bytes(update.payload, 262_144)) {
+      throw new Error('COLLABORATION_RESPONSE_INVALID')
+    }
+    cursor = update.sequence
+  }
+  if (page.nextAfterSequence !== null && page.nextAfterSequence !== cursor) throw new Error('COLLABORATION_RESPONSE_INVALID')
+  if (page.nextAfterSequence === null && cursor !== page.latestSequence) throw new Error('COLLABORATION_RESPONSE_INVALID')
+}
+
+const messages: Readonly<Record<CollaborationErrorCode, string>> = {
+  COLLABORATION_INVALID: 'The collaboration request was rejected.',
+  COLLABORATION_NOT_FOUND: 'The collaboration session was not found.',
+  COLLABORATION_DENIED: 'You do not have access to this collaboration session.',
+  COLLABORATION_CONFLICT: 'The collaboration session changed. Reopen it and try again.',
+  COLLABORATION_LEASE_EXPIRED: 'The collaboration lease expired. Reconnect to continue.',
+  COLLABORATION_PAYLOAD_TOO_LARGE: 'The collaboration update is too large.',
+  COLLABORATION_BACKPRESSURE: 'The collaboration session must be saved before more updates can be accepted.',
+  COLLABORATION_PROVIDER_UNAVAILABLE: 'The collaboration service is temporarily unavailable.',
+  COLLABORATION_INTEGRITY_FAILURE: 'The collaboration update could not be verified.',
+  COLLABORATION_INTERNAL_ERROR: 'The collaboration request could not be completed.',
+}
+
+const statuses: Readonly<Record<CollaborationErrorCode, number>> = {
+  COLLABORATION_INVALID: 422,
+  COLLABORATION_NOT_FOUND: 404,
+  COLLABORATION_DENIED: 403,
+  COLLABORATION_CONFLICT: 409,
+  COLLABORATION_LEASE_EXPIRED: 409,
+  COLLABORATION_PAYLOAD_TOO_LARGE: 413,
+  COLLABORATION_BACKPRESSURE: 429,
+  COLLABORATION_PROVIDER_UNAVAILABLE: 503,
+  COLLABORATION_INTEGRITY_FAILURE: 500,
+  COLLABORATION_INTERNAL_ERROR: 500,
+}
+
+export class CollaborationRequestError extends Error {
+  readonly safe: CollaborationSafeError
+
+  constructor(code: CollaborationErrorCode, requestId: string | null = null) {
+    super(messages[code])
+    this.name = 'CollaborationRequestError'
+    const safeRequestId = requestId !== null && /^[A-Za-z0-9._-]{1,128}$/.test(requestId) ? requestId : null
+    this.safe = { code, message: messages[code], requestId: safeRequestId, status: statuses[code] }
+  }
+}
+
+export const safeCollaborationError = (error: unknown): CollaborationSafeError => error instanceof CollaborationRequestError
+  ? error.safe
+  : new CollaborationRequestError('COLLABORATION_INTERNAL_ERROR').safe

package/collaboration/src/engine.ts

@@ -0,0 +1,46 @@
+import * as Y from 'yjs'
+import type { CollaborationEngine, CollaborationUpdateOrigin } from './contracts'
+
+const remoteOrigin = Symbol('peanut.collaboration.remote')
+const replayOrigin = Symbol('peanut.collaboration.replay')
+
+export type YjsCollaborationEngine = CollaborationEngine<Y.Doc>
+
+export const createYjsCollaborationEngine = (options: { readonly gc?: boolean; readonly guid?: string } = {}): YjsCollaborationEngine => {
+  const document = new Y.Doc(options)
+  const listeners = new Set<(update: Uint8Array, origin: CollaborationUpdateOrigin) => void>()
+  let disposed = false
+  const updated = (update: Uint8Array, origin: unknown): void => {
+    if (disposed) return
+    const kind: CollaborationUpdateOrigin = origin === remoteOrigin ? 'remote' : origin === replayOrigin ? 'replay' : 'local'
+    for (const listener of listeners) listener(update.slice(), kind)
+  }
+  document.on('update', updated)
+  return {
+    document,
+    applyUpdate(update, origin = 'remote') {
+      if (disposed) throw new Error('COLLABORATION_ENGINE_DISPOSED')
+      Y.applyUpdate(document, update, origin === 'replay' ? replayOrigin : remoteOrigin)
+    },
+    encodeStateVector() {
+      if (disposed) throw new Error('COLLABORATION_ENGINE_DISPOSED')
+      return Y.encodeStateVector(document)
+    },
+    encodeSnapshot() {
+      if (disposed) throw new Error('COLLABORATION_ENGINE_DISPOSED')
+      return Y.encodeStateAsUpdate(document)
+    },
+    onUpdate(listener) {
+      if (disposed) throw new Error('COLLABORATION_ENGINE_DISPOSED')
+      listeners.add(listener)
+      return () => { listeners.delete(listener) }
+    },
+    dispose() {
+      if (disposed) return
+      disposed = true
+      listeners.clear()
+      document.off('update', updated)
+      document.destroy()
+    },
+  }
+}

package/collaboration/src/index.ts

@@ -0,0 +1,4 @@
+export * from './contracts'
+export * from './engine'
+export * from './runtime'
+export * from './transport'

package/collaboration/src/runtime.ts

@@ -0,0 +1,157 @@
+import {
+  CollaborationRequestError,
+  assertCollaborationAdmission,
+  assertCollaborationStatePage,
+  safeCollaborationError,
+} from './contracts'
+import type {
+  CollaborationEngine,
+  CollaborationHostApi,
+  CollaborationRuntimeState,
+  CollaborationTransport,
+} from './contracts'
+
+export interface CollaborationRuntime {
+  readonly state: CollaborationRuntimeState
+  connect: () => Promise<void>
+  reconnect: () => Promise<void>
+  disconnect: () => void
+  onState: (listener: (state: CollaborationRuntimeState) => void) => () => void
+  encodeSnapshot: () => Uint8Array
+  encodeStateVector: () => Uint8Array
+  dispose: () => void
+}
+
+export interface CollaborationRuntimeOptions<TDocument = unknown> {
+  readonly host: CollaborationHostApi
+  readonly engine: CollaborationEngine<TDocument>
+  readonly transport: CollaborationTransport
+}
+
+const aborted = (error: unknown): boolean => error instanceof DOMException && error.name === 'AbortError'
+
+export const createCollaborationRuntime = <TDocument>(options: CollaborationRuntimeOptions<TDocument>): CollaborationRuntime => {
+  const listeners = new Set<(state: CollaborationRuntimeState) => void>()
+  let current: CollaborationRuntimeState = { status: 'idle', session: null, lease: null, latestSequence: 0, error: null }
+  let controller: AbortController | null = null
+  let generation = 0
+  let disposed = false
+  let establishedSessionKey: string | null = null
+
+  const publish = (patch: Partial<CollaborationRuntimeState>): void => {
+    current = { ...current, ...patch }
+    for (const listener of listeners) listener(current)
+  }
+  const disconnect = (): void => {
+    if (disposed) return
+    generation += 1
+    controller?.abort()
+    controller = null
+    options.transport.disconnect()
+    publish({ status: 'disconnected', lease: null, error: null })
+  }
+  const hydrate = async (sessionKey: string, firstSequence: number, signal: AbortSignal, run: number): Promise<number> => {
+    let cursor = firstSequence
+    for (let pages = 0; pages < 1000; pages += 1) {
+      const page = await options.host.state(sessionKey, cursor, signal)
+      if (run !== generation) return cursor
+      assertCollaborationStatePage(page, cursor)
+      if (page.snapshot !== null) {
+        options.engine.applyUpdate(page.snapshot.snapshot, 'replay')
+        cursor = page.snapshot.coveredSequence
+      }
+      for (const update of page.updates) {
+        options.engine.applyUpdate(update.payload, 'replay')
+        cursor = update.sequence
+      }
+      if (page.nextAfterSequence === null) return page.latestSequence
+      cursor = page.nextAfterSequence
+    }
+    throw new CollaborationRequestError('COLLABORATION_INTERNAL_ERROR')
+  }
+  const connect = async (): Promise<void> => {
+    if (disposed) throw new Error('COLLABORATION_RUNTIME_DISPOSED')
+    const run = ++generation
+    controller?.abort()
+    options.transport.disconnect()
+    const nextController = new AbortController()
+    controller = nextController
+    publish({ status: 'admitting', lease: null, error: null })
+    try {
+      const admission = await options.host.admit(nextController.signal)
+      if (run !== generation) return
+      assertCollaborationAdmission(admission)
+      if (establishedSessionKey !== null && establishedSessionKey !== admission.session.sessionKey) {
+        throw new CollaborationRequestError('COLLABORATION_CONFLICT')
+      }
+      const initialSequence = establishedSessionKey === null ? 0 : current.latestSequence
+      publish({ status: 'hydrating', session: admission.session, lease: admission.lease, latestSequence: initialSequence })
+      const latestSequence = await hydrate(admission.session.sessionKey, initialSequence, nextController.signal, run)
+      if (run !== generation) return
+      if (latestSequence !== admission.session.latestSequence) throw new CollaborationRequestError('COLLABORATION_INTEGRITY_FAILURE')
+      establishedSessionKey = admission.session.sessionKey
+      publish({ status: 'connecting', latestSequence })
+      options.transport.connect(admission.transport, options.engine.encodeSnapshot())
+    } catch (error) {
+      if (run !== generation || aborted(error)) return
+      options.transport.disconnect()
+      publish({ status: 'error', lease: null, error: safeCollaborationError(error) })
+    } finally {
+      if (controller === nextController) controller = null
+    }
+  }
+
+  const removeEngineListener = options.engine.onUpdate((update, origin) => {
+    if ((current.status === 'connecting' || current.status === 'connected') && origin === 'local') {
+      try {
+        if (update.byteLength > 262_144) throw new CollaborationRequestError('COLLABORATION_PAYLOAD_TOO_LARGE')
+        options.transport.sendUpdate(update)
+      } catch (error) {
+        options.transport.disconnect()
+        publish({ status: 'error', lease: null, error: safeCollaborationError(error) })
+      }
+    }
+  })
+  const removeTransportUpdateListener = options.transport.onUpdate(update => {
+    if (current.status !== 'connecting' && current.status !== 'connected') return
+    try { options.engine.applyUpdate(update, 'remote') } catch (error) {
+      options.transport.disconnect()
+      publish({ status: 'error', lease: null, error: safeCollaborationError(error) })
+    }
+  })
+  const removeTransportStatusListener = options.transport.onStatus(status => {
+    if (disposed || current.status === 'disposed' || current.status === 'error') return
+    if (status === 'connected') publish({ status: 'connected', error: null })
+    else if (status === 'connecting') publish({ status: 'connecting' })
+    else publish({ status: 'disconnected', lease: null })
+  })
+
+  return {
+    get state() { return current },
+    connect,
+    async reconnect() { disconnect(); await connect() },
+    disconnect,
+    onState(listener) {
+      if (disposed) throw new Error('COLLABORATION_RUNTIME_DISPOSED')
+      listeners.add(listener)
+      return () => { listeners.delete(listener) }
+    },
+    encodeSnapshot: () => options.engine.encodeSnapshot(),
+    encodeStateVector: () => options.engine.encodeStateVector(),
+    dispose() {
+      if (disposed) return
+      generation += 1
+      controller?.abort()
+      controller = null
+      removeEngineListener()
+      removeTransportUpdateListener()
+      removeTransportStatusListener()
+      options.transport.dispose()
+      options.engine.dispose()
+      disposed = true
+      current = { ...current, status: 'disposed', lease: null, error: null }
+      for (const listener of listeners) listener(current)
+      listeners.clear()
+    },
+  }
+}

package/collaboration/src/transport.ts

@@ -0,0 +1,142 @@
+import * as Y from 'yjs'
+import { WebsocketProvider } from 'y-websocket'
+import type { CollaborationTransport, CollaborationTransportAdmission, CollaborationTransportStatus } from './contracts'
+
+interface ProviderStatusEvent { readonly status: CollaborationTransportStatus }
+interface CollaborationWebsocketProvider {
+  connect: () => void
+  disconnect: () => void
+  destroy: () => void
+  on: (event: 'status', listener: (event: ProviderStatusEvent) => void) => void
+  off: (event: 'status', listener: (event: ProviderStatusEvent) => void) => void
+}
+
+export interface CollaborationWebsocketProviderOptions {
+  readonly connect: false
+  readonly disableBc: true
+}
+
+export type CollaborationWebsocketProviderFactory = (
+  websocketUrl: string,
+  roomName: string,
+  document: Y.Doc,
+  options: CollaborationWebsocketProviderOptions,
+) => CollaborationWebsocketProvider
+
+export interface YWebsocketCollaborationTransportOptions {
+  readonly hostOrigin?: string
+  readonly providerFactory?: CollaborationWebsocketProviderFactory
+}
+
+const providerFactory: CollaborationWebsocketProviderFactory = (websocketUrl, roomName, document, options) => new WebsocketProvider(
+  websocketUrl,
+  roomName,
+  document,
+  options,
+)
+
+const loopback = (hostname: string): boolean => hostname === 'localhost' || hostname === '127.0.0.1' || hostname === '[::1]'
+
+const validateAdmission = (admission: CollaborationTransportAdmission, hostOrigin: string): URL => {
+  let websocket: URL
+  let host: URL
+  try {
+    websocket = new URL(admission.websocketUrl)
+    host = new URL(hostOrigin)
+  } catch {
+    throw new Error('COLLABORATION_TRANSPORT_INVALID')
+  }
+  const expectedProtocol = host.protocol === 'https:' ? 'wss:' : host.protocol === 'http:' ? 'ws:' : ''
+  if ((websocket.protocol !== 'wss:' && websocket.protocol !== 'ws:') || websocket.protocol !== expectedProtocol
+    || websocket.hostname !== host.hostname || websocket.port !== host.port || websocket.username !== '' || websocket.password !== ''
+    || websocket.search !== '' || websocket.hash !== '' || (websocket.protocol === 'ws:' && !loopback(websocket.hostname))
+    || !/^[a-z0-9][a-z0-9._-]{0,127}$/.test(admission.roomName)) {
+    throw new Error('COLLABORATION_TRANSPORT_INVALID')
+  }
+  return websocket
+}
+
+export const createYWebsocketCollaborationTransport = (options: YWebsocketCollaborationTransportOptions = {}): CollaborationTransport => {
+  const statusListeners = new Set<(status: CollaborationTransportStatus) => void>()
+  const updateListeners = new Set<(update: Uint8Array) => void>()
+  const createProvider = options.providerFactory ?? providerFactory
+  let provider: CollaborationWebsocketProvider | null = null
+  let document: Y.Doc | null = null
+  let statusHandler: ((event: ProviderStatusEvent) => void) | null = null
+  let updateHandler: ((update: Uint8Array, origin: unknown) => void) | null = null
+  let disposed = false
+
+  const notifyStatus = (status: CollaborationTransportStatus): void => {
+    for (const listener of statusListeners) listener(status)
+  }
+  const release = (): void => {
+    if (provider !== null && statusHandler !== null) provider.off('status', statusHandler)
+    if (document !== null && updateHandler !== null) document.off('update', updateHandler)
+    provider?.disconnect()
+    provider?.destroy()
+    document?.destroy()
+    provider = null
+    document = null
+    statusHandler = null
+    updateHandler = null
+  }
+
+  return {
+    connect(admission, initialSnapshot) {
+      if (disposed) throw new Error('COLLABORATION_TRANSPORT_DISPOSED')
+      if (initialSnapshot.byteLength < 1 || initialSnapshot.byteLength > 8_388_608) throw new Error('COLLABORATION_TRANSPORT_INVALID')
+      const origin = options.hostOrigin ?? globalThis.location?.origin
+      if (origin === undefined) throw new Error('COLLABORATION_TRANSPORT_ORIGIN_REQUIRED')
+      const websocket = validateAdmission(admission, origin)
+      release()
+      const syncDocument = new Y.Doc()
+      Y.applyUpdate(syncDocument, initialSnapshot)
+      const nextProvider = createProvider(websocket.toString(), admission.roomName, syncDocument, { connect: false, disableBc: true })
+      const nextStatusHandler = (event: ProviderStatusEvent): void => {
+        if (provider !== nextProvider || !['connecting', 'connected', 'disconnected'].includes(event.status)) return
+        if (event.status === 'disconnected') nextProvider.disconnect()
+        notifyStatus(event.status)
+      }
+      const nextUpdateHandler = (update: Uint8Array, updateOrigin: unknown): void => {
+        if (provider !== nextProvider || updateOrigin !== nextProvider) return
+        for (const listener of updateListeners) listener(update.slice())
+      }
+      provider = nextProvider
+      document = syncDocument
+      statusHandler = nextStatusHandler
+      updateHandler = nextUpdateHandler
+      syncDocument.on('update', nextUpdateHandler)
+      nextProvider.on('status', nextStatusHandler)
+      notifyStatus('connecting')
+      nextProvider.connect()
+    },
+    disconnect() {
+      if (disposed) return
+      release()
+      notifyStatus('disconnected')
+    },
+    sendUpdate(update) {
+      if (disposed) throw new Error('COLLABORATION_TRANSPORT_DISPOSED')
+      if (document === null) throw new Error('COLLABORATION_TRANSPORT_DISCONNECTED')
+      if (update.byteLength < 1 || update.byteLength > 262_144) throw new Error('COLLABORATION_TRANSPORT_UPDATE_INVALID')
+      Y.applyUpdate(document, update)
+    },
+    onStatus(listener) {
+      if (disposed) throw new Error('COLLABORATION_TRANSPORT_DISPOSED')
+      statusListeners.add(listener)
+      return () => { statusListeners.delete(listener) }
+    },
+    onUpdate(listener) {
+      if (disposed) throw new Error('COLLABORATION_TRANSPORT_DISPOSED')
+      updateListeners.add(listener)
+      return () => { updateListeners.delete(listener) }
+    },
+    dispose() {
+      if (disposed) return
+      release()
+      disposed = true
+      statusListeners.clear()
+      updateListeners.clear()
+    },
+  }
+}

package/package.json

@@ -1,10 +1,17 @@
 {
   "name": "@peanut-admin/admin",
-  "version": "0.1.0-alpha.3",
+  "version": "0.1.0-alpha.5",
   "description": "Reusable Peanut Admin Web services and module contributions",
   "type": "module",
   "license": "Apache-2.0",
-  "sideEffects": ["*.vue"],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/peanut-opensource/peanut-admin.git",
+    "directory": "packages/web"
+  },
+  "sideEffects": [
+    "*.vue"
+  ],
   "files": [
     "admin-core/src",
     "admin-shell/src",
@@ -16,6 +23,7 @@
     "import-export/src",
     "ops-console/src",
     "integration-security/src",
+    "collaboration/src",
     "testing/src",
     "client-core/src",
     "client-nuxt/src",
@@ -62,6 +70,10 @@
       "types": "./integration-security/src/index.ts",
       "import": "./integration-security/src/index.ts"
     },
+    "./collaboration": {
+      "types": "./collaboration/src/index.ts",
+      "import": "./collaboration/src/index.ts"
+    },
     "./testing": {
       "development": {
         "types": "./testing/src/index.ts",
@@ -83,42 +95,85 @@
   },
   "typesVersions": {
     "*": {
-      "core": ["admin-core/src/index.ts"],
-      "shell": ["admin-shell/src/index.ts"],
-      "settings": ["settings/src/index.ts"],
-      "reference-codes": ["reference-codes/src/index.ts"],
-      "file-media": ["file-media/src/index.ts"],
-      "task-job": ["task-job/src/index.ts"],
-      "notification-sms": ["notification-sms/src/index.ts"],
-      "import-export": ["import-export/src/index.ts"],
-      "ops-console": ["ops-console/src/index.ts"],
-      "integration-security": ["integration-security/src/index.ts"],
-      "testing": ["testing/src/index.ts"],
-      "client": ["client-core/src/index.ts"],
-      "client/nuxt": ["client-nuxt/src/index.ts"],
-      "client/uniapp": ["client-uniapp/src/index.ts"]
+      "core": [
+        "admin-core/src/index.ts"
+      ],
+      "shell": [
+        "admin-shell/src/index.ts"
+      ],
+      "settings": [
+        "settings/src/index.ts"
+      ],
+      "reference-codes": [
+        "reference-codes/src/index.ts"
+      ],
+      "file-media": [
+        "file-media/src/index.ts"
+      ],
+      "task-job": [
+        "task-job/src/index.ts"
+      ],
+      "notification-sms": [
+        "notification-sms/src/index.ts"
+      ],
+      "import-export": [
+        "import-export/src/index.ts"
+      ],
+      "ops-console": [
+        "ops-console/src/index.ts"
+      ],
+      "integration-security": [
+        "integration-security/src/index.ts"
+      ],
+      "collaboration": [
+        "collaboration/src/index.ts"
+      ],
+      "testing": [
+        "testing/src/index.ts"
+      ],
+      "client": [
+        "client-core/src/index.ts"
+      ],
+      "client/nuxt": [
+        "client-nuxt/src/index.ts"
+      ],
+      "client/uniapp": [
+        "client-uniapp/src/index.ts"
+      ]
     }
   },
   "dependencies": {
-    "element-plus": "2.14.3",
     "openapi-fetch": "0.17.0",
-    "pinia": "4.0.2",
-    "vue-router": "5.2.0"
+    "y-websocket": "3.1.0",
+    "yjs": "13.6.32"
   },
   "devDependencies": {
     "@vue/test-utils": "2.4.11",
+    "element-plus": "2.14.3",
     "happy-dom": "20.10.6",
+    "pinia": "4.0.2",
     "typescript": "5.9.3",
     "vite": "8.1.4",
     "vitest": "4.1.10",
     "vue": "3.5.39",
+    "vue-router": "5.2.0",
     "vue-tsc": "3.3.7"
   },
   "peerDependencies": {
-    "vue": "^3.5.39"
+    "element-plus": "^2.14.3",
+    "pinia": ">=2.0.23 <5",
+    "vue": "^3.4.21"
+  },
+  "peerDependenciesMeta": {
+    "element-plus": {
+      "optional": true
+    },
+    "pinia": {
+      "optional": true
+    }
   },
   "scripts": {
-    "test": "vitest run admin-core/tests admin-shell/tests file-media/tests import-export/tests integration-security/tests notification-sms/tests ops-console/tests reference-codes/tests settings/tests testing/tests client-core/tests client-nuxt/tests client-uniapp/tests",
-    "typecheck": "tsc --noEmit -p admin-core/tsconfig.json && tsc --noEmit -p admin-shell/tsconfig.json && vue-tsc --noEmit -p file-media/tsconfig.json && vue-tsc --noEmit -p import-export/tsconfig.json && vue-tsc --noEmit -p integration-security/tsconfig.json && vue-tsc --noEmit -p notification-sms/tsconfig.json && vue-tsc --noEmit -p ops-console/tsconfig.json && vue-tsc --noEmit -p reference-codes/tsconfig.json && vue-tsc --noEmit -p settings/tsconfig.json && vue-tsc --noEmit -p task-job/tsconfig.json && tsc --noEmit -p testing/tsconfig.json && tsc --noEmit -p client-core/tsconfig.json && tsc --noEmit -p client-nuxt/tsconfig.json && tsc --noEmit -p client-uniapp/tsconfig.json"
+    "test": "vitest run admin-core/tests admin-shell/tests collaboration/tests file-media/tests import-export/tests integration-security/tests notification-sms/tests ops-console/tests reference-codes/tests settings/tests testing/tests client-core/tests client-nuxt/tests client-uniapp/tests",
+    "typecheck": "tsc --noEmit -p admin-core/tsconfig.json && tsc --noEmit -p admin-shell/tsconfig.json && tsc --noEmit -p collaboration/tsconfig.json && vue-tsc --noEmit -p file-media/tsconfig.json && vue-tsc --noEmit -p import-export/tsconfig.json && vue-tsc --noEmit -p integration-security/tsconfig.json && vue-tsc --noEmit -p notification-sms/tsconfig.json && vue-tsc --noEmit -p ops-console/tsconfig.json && vue-tsc --noEmit -p reference-codes/tsconfig.json && vue-tsc --noEmit -p settings/tsconfig.json && vue-tsc --noEmit -p task-job/tsconfig.json && tsc --noEmit -p testing/tsconfig.json && tsc --noEmit -p client-core/tsconfig.json && tsc --noEmit -p client-nuxt/tsconfig.json && tsc --noEmit -p client-uniapp/tsconfig.json"
   }
-}
+}