@musnows/scriverse 1.1.1 → 1.1.3

package/dist/public/mobile-offline-api.js

@@ -0,0 +1,196 @@
+export class MobileOfflineApiError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.name = "MobileOfflineApiError";
+    this.code = code;
+  }
+}
+
+function page(items, url) {
+  const requestedPage = Math.max(1, Number(url.searchParams.get("page")) || 1);
+  const limit = Math.max(1, Math.min(100, Number(url.searchParams.get("limit")) || 30));
+  const start = (requestedPage - 1) * limit;
+  const selected = items.slice(start, start + limit);
+  return {
+    items: selected,
+    page: requestedPage,
+    limit,
+    total: items.length,
+    hasMore: start + selected.length < items.length,
+    nextPage: start + selected.length < items.length ? requestedPage + 1 : null
+  };
+}
+
+function sortDirectory(items) {
+  return [...items].sort((left, right) => (
+    Number(left.sortOrder ?? 0) - Number(right.sortOrder ?? 0)
+    || String(left.title ?? left.name ?? left.id).localeCompare(String(right.title ?? right.name ?? right.id), "zh-CN")
+  ));
+}
+
+function snapshotRecord(entity) {
+  const snapshot = structuredClone(entity.snapshot);
+  return {
+    ...snapshot,
+    ...(typeof snapshot?.content === "string" ? { wordCount: textCount(snapshot.content) } : {}),
+    versionNo: Number(entity.snapshot?.versionNo ?? entity.serverVersionNo),
+    mobileLocalRevisionNo: Number(entity.localRevisionNo ?? 0),
+    mobileSyncConflict: entity.conflict === true,
+    mobileReadOnly: entity.locked === true
+  };
+}
+
+function workAccess(work) {
+  const saved = work.permissionsSnapshot && typeof work.permissionsSnapshot === "object" && !Array.isArray(work.permissionsSnapshot)
+    ? work.permissionsSnapshot
+    : {};
+  const modulePermissions = saved.modulePermissions && typeof saved.modulePermissions === "object" && !Array.isArray(saved.modulePermissions)
+    ? saved.modulePermissions
+    : saved;
+  const permissionValues = Object.values(modulePermissions);
+  const fallbackRole = permissionValues.length > 0 && permissionValues.every((access) => access === "write")
+    ? "editor"
+    : permissionValues.some((access) => access === "write") ? "custom" : "viewer";
+  return {
+    accessRole: typeof saved.accessRole === "string" ? saved.accessRole : fallbackRole,
+    modulePermissions: structuredClone(modulePermissions)
+  };
+}
+
+function textCount(value) {
+  return Array.from(String(value ?? "").replace(/\s/gu, "")).length;
+}
+
+export class MobileOfflineApi {
+  constructor({ store, client }) {
+    this.store = store;
+    this.client = client;
+  }
+
+  async work(workId, { includeVolumes = false } = {}) {
+    const cached = await this.store.getWork(workId);
+    if (!cached) throw new MobileOfflineApiError("SYNC_WORK_NOT_FOUND", "离线副本中不存在该作品");
+    const volumeEntities = sortDirectory((await this.store.listEntities(workId, "volume")).map(snapshotRecord));
+    const chapterEntities = await this.store.listEntities(workId, "chapter");
+    const chaptersByVolume = new Map();
+    for (const entity of chapterEntities) {
+      const chapter = snapshotRecord(entity);
+      const volumeId = String(chapter.volumeId ?? "");
+      const records = chaptersByVolume.get(volumeId) ?? [];
+      records.push(chapter);
+      chaptersByVolume.set(volumeId, records);
+    }
+    const volumes = volumeEntities.map((volume) => {
+      const chapters = sortDirectory(chaptersByVolume.get(String(volume.id)) ?? []);
+      return { ...volume, chapterCount: chapters.length, chapters: includeVolumes ? chapters : [] };
+    });
+    const summary = structuredClone(cached.summary ?? {});
+    return {
+      ...summary,
+      id: String(summary.id ?? cached.workId),
+      title: String(summary.title ?? cached.title ?? "未命名作品"),
+      coverUrl: typeof summary.coverUrl === "string" ? summary.coverUrl : null,
+      ...workAccess(cached),
+      offlineAccessEnabled: true,
+      wordCount: chapterEntities.reduce((total, entity) => total + textCount(entity.snapshot?.content), 0),
+      chapterCount: chapterEntities.length,
+      volumes
+    };
+  }
+
+  async works(url) {
+    const cached = await this.store.listWorks();
+    const works = [];
+    for (const work of cached) works.push(await this.work(work.workId));
+    return page(works, url);
+  }
+
+  async volumeChapters(volumeId, url) {
+    const works = await this.store.listWorks();
+    for (const work of works) {
+      const chapters = sortDirectory((await this.store.listEntities(work.workId, "chapter")).map(snapshotRecord))
+        .filter((chapter) => String(chapter.volumeId) === volumeId);
+      if (chapters.length > 0 || (await this.store.listEntities(work.workId, "volume")).some((entity) => String(entity.entityId) === volumeId)) {
+        return page(chapters, url);
+      }
+    }
+    throw new MobileOfflineApiError("SYNC_VOLUME_NOT_FOUND", "离线副本中不存在该分卷");
+  }
+
+  async entity(entityType, entityId) {
+    for (const work of await this.store.listWorks()) {
+      const entity = await this.store.getEntity(work.workId, entityType, entityId);
+      if (entity) return { workId: work.workId, entity, snapshot: snapshotRecord(entity) };
+    }
+    throw new MobileOfflineApiError("SYNC_ENTITY_NOT_FOUND", "离线副本中不存在该记录");
+  }
+
+  async settings(workId, url, contextOnly = false) {
+    const records = sortDirectory(await this.store.listEntities(workId, "setting")).map(snapshotRecord);
+    if (contextOnly) return records.filter((setting) => setting.locked === true);
+    return page(records, url);
+  }
+
+  async saveEntity(entityType, entityId, body) {
+    const current = await this.entity(entityType, entityId);
+    if (current.entity.locked || current.entity.conflict) {
+      throw new MobileOfflineApiError("SYNC_ENTITY_READ_ONLY", "该记录存在冲突或已锁定为只读，请先在同步中心处理");
+    }
+    const allowed = entityType === "chapter"
+      ? ["title", "content", "chapterType"]
+      : ["title", "category", "content", "tags", "status", "locked", "evidence", "scope", "authorNote"];
+    const snapshot = { ...current.snapshot };
+    for (const key of allowed) {
+      if (body && Object.hasOwn(body, key)) snapshot[key] = structuredClone(body[key]);
+    }
+    const saved = await this.store.saveLocalEntity(current.workId, entityType, entityId, snapshot);
+    await this.client?.emitStatus("saved", current.workId);
+    return {
+      ...snapshot,
+      versionNo: Number(current.entity.serverVersionNo),
+      mobileLocalRevisionNo: Number(saved.localRevisionNo),
+      updatedAt: saved.savedAt
+    };
+  }
+
+  unsupported() {
+    throw new MobileOfflineApiError(
+      "MOBILE_OFFLINE_OPERATION_UNSUPPORTED",
+      "当前离线副本仅支持修改已下载的正文和设定；其他操作需恢复连接后完成"
+    );
+  }
+
+  async request(path, options = {}) {
+    const method = String(options.method ?? "GET").toUpperCase();
+    const url = new URL(path, globalThis.location?.origin ?? "https://mobile.invalid");
+    const pathname = url.pathname;
+    if (method === "GET" && pathname === "/api/works") return this.works(url);
+    const workMatch = pathname.match(/^\/api\/works\/([^/]+)$/u);
+    if (method === "GET" && workMatch) return this.work(decodeURIComponent(workMatch[1]), { includeVolumes: url.searchParams.get("directory") !== "volumes" });
+    const volumeChaptersMatch = pathname.match(/^\/api\/volumes\/([^/]+)\/chapters$/u);
+    if (method === "GET" && volumeChaptersMatch) return this.volumeChapters(decodeURIComponent(volumeChaptersMatch[1]), url);
+    const chapterMatch = pathname.match(/^\/api\/chapters\/([^/]+)$/u);
+    if (chapterMatch && method === "GET") return (await this.entity("chapter", decodeURIComponent(chapterMatch[1]))).snapshot;
+    if (chapterMatch && method === "PATCH") return this.saveEntity("chapter", decodeURIComponent(chapterMatch[1]), options.body);
+    const settingMatch = pathname.match(/^\/api\/settings\/([^/]+)$/u);
+    if (settingMatch && method === "GET") return (await this.entity("setting", decodeURIComponent(settingMatch[1]))).snapshot;
+    if (settingMatch && method === "PATCH") return this.saveEntity("setting", decodeURIComponent(settingMatch[1]), options.body);
+    const workSettingsMatch = pathname.match(/^\/api\/works\/([^/]+)\/settings(?:\/context)?$/u);
+    if (method === "GET" && workSettingsMatch) {
+      return this.settings(
+        decodeURIComponent(workSettingsMatch[1]),
+        url,
+        pathname.endsWith("/context")
+      );
+    }
+    if (method === "GET" && /^\/api\/chapters\/[^/]+\/(?:annotation-counts|annotations)$/u.test(pathname)) return [];
+    if (method === "GET" && /^\/api\/works\/[^/]+\/chapters\/[^/]+\/foreshadow-reminders$/u.test(pathname)) return [];
+    if (method === "GET" && /^\/api\/(?:chapters\/[^/]+\/versions|entity-versions\/[^/]+\/[^/]+)$/u.test(pathname)) return [];
+    if (method === "POST" && /^\/api\/works\/[^/]+\/presence$/u.test(pathname)) return { participants: [], recentChanges: [] };
+    return this.unsupported();
+  }
+}
+
+export function createMobileOfflineApi(options) {
+  return new MobileOfflineApi(options);
+}

package/dist/public/mobile-service-worker.js

@@ -0,0 +1,82 @@
+const CACHE_NAME = "scriverse-mobile-shell-v2";
+const STATIC_REQUEST = /\.(?:css|js|mjs|svg|png|webp|woff2?|ttf)(?:\?.*)?$/iu;
+const MOBILE_SHELL_URL = new URL("/?scriverseMobile=1", self.location.origin);
+
+async function cacheMobileShell() {
+  const response = await fetch(MOBILE_SHELL_URL, { cache: "reload" });
+  if (!response.ok || response.type === "opaque") return;
+  const cache = await caches.open(CACHE_NAME);
+  await cache.put(new Request(MOBILE_SHELL_URL), response.clone());
+  await cache.put(new Request(new URL("/index.html", self.location.origin)), response);
+}
+
+self.addEventListener("install", (event) => {
+  event.waitUntil((async () => {
+    await self.skipWaiting();
+    await cacheMobileShell().catch(() => undefined);
+  })());
+});
+
+self.addEventListener("activate", (event) => {
+  event.waitUntil(self.clients.claim());
+});
+
+self.addEventListener("message", (event) => {
+  if (event.data?.type !== "CACHE_ASSETS" || !Array.isArray(event.data.urls)) return;
+  const urls = [...new Set(event.data.urls)].filter((value) => {
+    if (typeof value !== "string") return false;
+    try {
+      const url = new URL(value, self.location.origin);
+      return url.origin === self.location.origin
+        && !url.pathname.startsWith("/api/")
+        && STATIC_REQUEST.test(url.pathname + url.search);
+    } catch {
+      return false;
+    }
+  }).slice(0, 500);
+  event.waitUntil((async () => {
+    const cache = await caches.open(CACHE_NAME);
+    await Promise.all(urls.map(async (value) => {
+      try {
+        const request = new Request(new URL(value, self.location.origin), {
+          cache: "force-cache",
+          credentials: "same-origin"
+        });
+        const response = await fetch(request);
+        if (response.ok && response.type !== "opaque") await cache.put(request, response);
+      } catch {
+        // 单个资源缓存失败时继续处理其余资源。
+      }
+    }));
+  })());
+});
+
+async function cacheShellResponse(request, response) {
+  if (!response || !response.ok || response.type === "opaque") return response;
+  const cache = await caches.open(CACHE_NAME);
+  await cache.put(request, response.clone());
+  return response;
+}
+
+self.addEventListener("fetch", (event) => {
+  const request = event.request;
+  if (request.method !== "GET" || new URL(request.url).origin !== self.location.origin) return;
+  const url = new URL(request.url);
+  if (url.pathname.startsWith("/api/")) return;
+  if (request.mode === "navigate") {
+    event.respondWith((async () => {
+      try {
+        return await cacheShellResponse(request, await fetch(request));
+      } catch {
+        return await caches.match(request) ?? await caches.match("/index.html") ?? Response.error();
+      }
+    })());
+    return;
+  }
+  if (!STATIC_REQUEST.test(url.pathname + url.search)) return;
+  event.respondWith((async () => {
+    const cached = await caches.match(request);
+    const network = fetch(request).then((response) => cacheShellResponse(request, response)).catch(() => null);
+    return cached ?? await network ?? Response.error();
+  })());
+});

package/dist/public/mobile-sync-client.js

@@ -0,0 +1,292 @@
+const SYNC_PROTOCOL = 1;
+const SYNC_POLL_INTERVAL_MS = 30_000;
+const RETRYABLE_STATUS = new Set([429, 500, 502, 503, 504]);
+const READ_ONLY_ERROR_CODES = new Set([
+  "OFFLINE_ACCESS_DISABLED",
+  "WORK_ACCESS_DENIED",
+  "WORK_EDIT_DENIED",
+  "WORK_MODULE_READ_DENIED",
+  "WORK_MODULE_WRITE_DENIED",
+  "WORK_OWNER_REQUIRED"
+]);
+
+export class MobileSyncClientError extends Error {
+  constructor(code, message, options = {}) {
+    super(message);
+    this.name = "MobileSyncClientError";
+    this.code = code;
+    this.status = options.status ?? 0;
+    this.retryable = options.retryable === true;
+    this.retryAfterSeconds = options.retryAfterSeconds ?? null;
+  }
+}
+
+function responseError(payload, response) {
+  const code = typeof payload?.error?.code === "string" ? payload.error.code : `SYNC_HTTP_${response.status}`;
+  const message = typeof payload?.error?.message === "string" ? payload.error.message : "同步请求失败，请稍后重试";
+  const retryAfter = Number(response.headers.get("retry-after"));
+  return new MobileSyncClientError(code, message, {
+    status: response.status,
+    retryable: RETRYABLE_STATUS.has(response.status),
+    retryAfterSeconds: Number.isInteger(retryAfter) && retryAfter > 0 ? retryAfter : null
+  });
+}
+
+async function jsonResponse(response) {
+  let payload = null;
+  try {
+    payload = await response.json();
+  } catch {
+    if (response.ok) throw new MobileSyncClientError("SYNC_RESPONSE_INVALID", "Server 返回的内容无法识别");
+  }
+  if (!response.ok) throw responseError(payload, response);
+  if (!payload || typeof payload !== "object" || !("data" in payload)) {
+    throw new MobileSyncClientError("SYNC_RESPONSE_INVALID", "Server 返回的内容无法识别");
+  }
+  return payload.data;
+}
+
+function retryDelay(attempts, retryAfterSeconds = null) {
+  if (retryAfterSeconds) return retryAfterSeconds * 1_000;
+  return Math.min(5 * 60_000, 1_000 * (2 ** Math.max(0, Math.min(8, attempts - 1))));
+}
+
+function rangesOverlap(range, version) {
+  return range && Number(range.min) <= version && Number(range.max) >= version;
+}
+
+export function syncMutationSnapshot(entityType, snapshot) {
+  if (entityType === "chapter") {
+    return {
+      title: String(snapshot?.title ?? ""),
+      content: String(snapshot?.content ?? ""),
+      chapterType: ["正文", "设定", "作者的话", "其他"].includes(snapshot?.chapterType) ? snapshot.chapterType : "正文"
+    };
+  }
+  if (entityType === "setting") {
+    return {
+      title: String(snapshot?.title ?? ""),
+      category: String(snapshot?.category ?? ""),
+      content: String(snapshot?.content ?? ""),
+      tags: Array.isArray(snapshot?.tags) ? snapshot.tags : [],
+      status: ["draft", "pending", "confirmed", "deprecated"].includes(snapshot?.status) ? snapshot.status : "draft",
+      locked: snapshot?.locked === true,
+      evidence: Array.isArray(snapshot?.evidence) ? snapshot.evidence : [],
+      scope: snapshot?.scope && typeof snapshot.scope === "object" && !Array.isArray(snapshot.scope) ? snapshot.scope : {},
+      authorNote: String(snapshot?.authorNote ?? "")
+    };
+  }
+  throw new MobileSyncClientError("SYNC_ENTITY_TYPE_UNSUPPORTED", "该类型暂不支持离线同步");
+}
+
+export class MobileSyncClient {
+  constructor({
+    profile = null,
+    user,
+    store,
+    csrfToken = null,
+    fetchImpl = globalThis.fetch,
+    online = () => globalThis.navigator?.onLine !== false,
+    pollIntervalMs = SYNC_POLL_INTERVAL_MS
+  }) {
+    this.profile = profile;
+    this.user = user;
+    this.store = store;
+    this.getCsrfToken = typeof csrfToken === "function" ? csrfToken : () => csrfToken;
+    this.fetch = (input, init) => fetchImpl(input, init);
+    this.online = online;
+    this.syncing = new Set();
+    this.disposed = false;
+    this.handleOnline = () => { void this.syncAll(); };
+    globalThis.addEventListener?.("online", this.handleOnline);
+    this.pollTimer = Number(pollIntervalMs) > 0
+      ? globalThis.setInterval?.(() => { void this.syncAll(); }, Number(pollIntervalMs)) ?? null
+      : null;
+  }
+
+  async request(path, options = {}) {
+    const method = String(options.method ?? "GET").toUpperCase();
+    let response;
+    try {
+      response = await this.fetch(path, {
+        method,
+        headers: {
+          Accept: "application/json",
+          ...(method === "GET" || method === "HEAD" || method === "OPTIONS" || !this.getCsrfToken()
+            ? {}
+            : { "X-CSRF-Token": this.getCsrfToken() }),
+          ...(options.body === undefined ? {} : { "Content-Type": "application/json" })
+        },
+        ...(options.body === undefined ? {} : { body: JSON.stringify(options.body) }),
+        redirect: "error",
+        cache: "no-store"
+      });
+    } catch (error) {
+      throw new MobileSyncClientError("SYNC_NETWORK_ERROR", "无法连接 Server，本地变更已保留", { retryable: true, cause: error });
+    }
+    return jsonResponse(response);
+  }
+
+  async downloadWork(work, { scheduleRequest = null } = {}) {
+    if (!work?.id) throw new MobileSyncClientError("SYNC_WORK_INVALID", "请先选择要下载的作品");
+    if (work.offlineAccessEnabled !== true) {
+      throw new MobileSyncClientError("OFFLINE_ACCESS_DISABLED", "作品所有者尚未允许 手机端离线访问");
+    }
+    const request = (path, options = {}) => typeof scheduleRequest === "function"
+      ? scheduleRequest(() => this.request(path, options))
+      : this.request(path, options);
+    const descriptor = await request(`/api/sync/works/${encodeURIComponent(work.id)}/snapshots`, { method: "POST", body: {} });
+    const items = [];
+    let after = 0;
+    try {
+      while (true) {
+        const page = await request(`/api/sync/snapshots/${encodeURIComponent(descriptor.snapshotId)}/items?after=${after}&limit=100`);
+        items.push(...page.items);
+        if (!page.hasMore) break;
+        if (!Number.isInteger(page.nextAfter) || page.nextAfter <= after) {
+          throw new MobileSyncClientError("SYNC_SNAPSHOT_INVALID", "Server 返回的离线数据不完整");
+        }
+        after = page.nextAfter;
+      }
+      const stored = await this.store.replaceSnapshot({
+        workId: work.id,
+        cutoffCursor: descriptor.cutoffCursor,
+        items,
+        permissionsSnapshot: {
+          accessRole: work.accessRole ?? "viewer",
+          modulePermissions: work.modulePermissions ?? null
+        }
+      });
+      await this.emitStatus("downloaded", work.id);
+      return stored;
+    } finally {
+      await request(`/api/sync/snapshots/${encodeURIComponent(descriptor.snapshotId)}`, { method: "DELETE" }).catch(() => undefined);
+    }
+  }
+
+  async syncAll() {
+    if (this.disposed || !this.online()) return [];
+    const works = await this.store.listWorks();
+    const results = [];
+    for (const work of works) results.push(await this.syncWork(work.workId).catch((error) => ({ status: "failed", error })));
+    return results;
+  }
+
+  async syncWork(workId) {
+    if (this.disposed) return { status: "disposed" };
+    if (!this.online()) {
+      await this.store.setWorkStatus(workId, "offline");
+      await this.emitStatus("offline", workId);
+      return { status: "offline" };
+    }
+    if (this.syncing.has(workId)) return { status: "already-syncing" };
+    const lease = await this.store.acquireSyncLease(workId);
+    if (!lease) return { status: "leased-elsewhere" };
+    this.syncing.add(workId);
+    await this.store.setWorkStatus(workId, "syncing");
+    await this.emitStatus("syncing", workId);
+    try {
+      const session = await this.request("/api/auth/session");
+      if (session.authenticated !== true || session.user?.userId !== this.user.userId) {
+        throw new MobileSyncClientError("REMOTE_LOGIN_REQUIRED", "手机端登录已失效，同步队列已暂停");
+      }
+      const health = await this.request("/api/health");
+      if (!rangesOverlap(health.syncProtocol, SYNC_PROTOCOL)) {
+        throw new MobileSyncClientError("SYNC_PROTOCOL_INCOMPATIBLE", "当前 Server 版本不支持离线同步，请升级后重试");
+      }
+      const work = await this.request(`/api/works/${encodeURIComponent(workId)}`);
+      if (work.offlineAccessEnabled !== true) throw new MobileSyncClientError("OFFLINE_ACCESS_DISABLED", "作品已关闭离线访问");
+      await this.pullWork(workId);
+      await this.pushWork(workId);
+      const summary = await this.store.statusSummary(workId);
+      const finalStatus = summary.rejected > 0 ? "read-only" : summary.conflicts > 0 ? "conflict" : "ready";
+      await this.store.setWorkStatus(workId, finalStatus === "conflict" ? "ready" : finalStatus);
+      await this.emitStatus(finalStatus, workId);
+      return { status: finalStatus, summary };
+    } catch (error) {
+      const code = error?.code ?? "SYNC_FAILED";
+      if (READ_ONLY_ERROR_CODES.has(code)) await this.store.setWorkStatus(workId, "read-only", code);
+      else if (code === "REMOTE_LOGIN_REQUIRED" || code === "SYNC_NETWORK_ERROR") await this.store.setWorkStatus(workId, "offline", code);
+      else await this.store.setWorkStatus(workId, "error", code);
+      await this.emitStatus(READ_ONLY_ERROR_CODES.has(code) ? "read-only" : "failed", workId, error);
+      throw error;
+    } finally {
+      this.syncing.delete(workId);
+      await this.store.releaseSyncLease(workId, lease.leaseId);
+    }
+  }
+
+  async pullWork(workId) {
+    const work = await this.store.getWork(workId);
+    if (!work) throw new MobileSyncClientError("SYNC_WORK_NOT_FOUND", "离线作品不存在");
+    let cursor = Number(work.cursor);
+    while (true) {
+      const page = await this.request(`/api/sync/works/${encodeURIComponent(workId)}/changes?after=${cursor}&limit=200`);
+      await this.store.applyRemoteChanges(workId, page.items, Number(page.nextCursor));
+      cursor = Number(page.nextCursor);
+      if (!page.hasMore) return cursor;
+    }
+  }
+
+  async pushWork(workId) {
+    const results = [];
+    while (true) {
+      const batch = await this.store.preparePushBatch(workId, 20);
+      if (batch.mutations.length === 0) return results;
+      const body = {
+        clientId: batch.clientId,
+        mutations: batch.mutations.map((mutation) => ({
+          ...mutation,
+          localSnapshot: syncMutationSnapshot(mutation.entityType, mutation.localSnapshot)
+        }))
+      };
+      try {
+        const pushed = await this.request(`/api/sync/works/${encodeURIComponent(workId)}/push`, { method: "POST", body });
+        await this.store.applyPushResults(workId, pushed.results);
+        results.push(...pushed.results);
+      } catch (error) {
+        const attempts = Math.max(...batch.mutations.map((mutation) => Number(mutation.attempts ?? 1)), 1);
+        if (error?.retryable) {
+          const delay = retryDelay(attempts, error.retryAfterSeconds);
+          await this.store.returnSyncingToPending(batch.mutationIds, new Date(Date.now() + delay).toISOString());
+        } else {
+          await this.store.returnSyncingToPending(batch.mutationIds, null);
+        }
+        throw error;
+      }
+    }
+  }
+
+  async emitStatus(status, workId, error = null) {
+    const works = await this.store.listWorks();
+    const summaries = await Promise.all(works.map((work) => this.store.statusSummary(work.workId)));
+    const aggregate = summaries.reduce((total, summary) => ({
+      pendingMutations: total.pendingMutations + summary.pending + summary.syncing,
+      conflicts: total.conflicts + summary.conflicts,
+      rejected: total.rejected + summary.rejected
+    }), { pendingMutations: 0, conflicts: 0, rejected: 0 });
+    const detail = { status, workId, ...aggregate, errorCode: error?.code ?? null };
+    globalThis.dispatchEvent?.(new CustomEvent("scriverse-mobile-sync-state", { detail }));
+    return detail;
+  }
+
+  dispose() {
+    this.disposed = true;
+    globalThis.removeEventListener?.("online", this.handleOnline);
+    if (this.pollTimer !== null) globalThis.clearInterval?.(this.pollTimer);
+    this.store.close();
+  }
+}
+
+export async function createMobileSyncClient({
+  user,
+  profile = null,
+  store,
+  csrfToken = null,
+  fetchImpl = globalThis.fetch
+} = {}) {
+  if (!user?.userId || !store) return null;
+  await store.open();
+  await store.recoverSyncing();
+  return new MobileSyncClient({ profile, user, store, csrfToken, fetchImpl });
+}