refactor(gui): move the snapshot-store engine into the client runtime

The data layer no longer depends on the React glue package, and business plugins no longer depend on web-react at all: - The store engine (zustand vanilla + immer + persist + dev freeze), defineStore, and shallowEqual move to @deepseek-ai/dsh-client-runtime, exported from the ./client main entry — no ./store subpath survives on either package (the web-react one is deleted, none is opened on runtime). - Store products are bare snapshot sources: useSelector leaves SnapshotStore/StoreInstance and Session; every hook is composed at the binding site in web-react's renderer (per-source cached uSES binding). The SlotRendererHost sessions face carries bare observables only. - SessionProvider becomes a standard-kit seat: an entry whose children declare a session-scope slot receives the framework component as a prop, retiring the last value import of web-react from plugin packages. UseSession and the session-area types now live in ui-slots. - web-react shrinks to the shell-only React glue (renderer, providers, uSES bridge); zustand/immer belong to runtime alone; the module-table seed and tsdown externals drop the web-react/store seat. - NODE_ENV replacement is defined once in the shared tsdown client preset (browser bundles inline the engine and lost vite's define); the 3-line process.env typecheck shim moves to runtime with the engine. - Stray tsc artifacts (.js/.d.ts/.d.ts.map beside sources under src/) swept repo-wide; they shadow real sources under vitest resolution. Verified: both aggregate typecheck programs at zero; 604 client tests green; repo-wide grep for web-react/store at zero; real-host playwright run 7/7 including persist round-trip. ci: fix test/docs
2026-07-23 02:56:16 +08:00
parent 004a988168
commit 8b3d1ac943
77 changed files with 484 additions and 317 deletions
@@ -12,7 +12,7 @@
 import type { Context } from 'cordis'
 import type { ConnectionHandle, SessionId } from '@deepseek-ai/dsh-client-connection/client'
 import type { SnapshotSelectorHook } from '@deepseek-ai/dsh-client-ui-slots'
-import type { SnapshotStore, UseSession } from '@deepseek-ai/dsh-client-web-react'
+import type { SnapshotStore } from './store/index.ts'
 import { SlotsService } from './slots.ts'
 import { SessionsService } from './sessions/service.ts'
 import type { SessionListState } from './sessions/service.ts'
@@ -25,6 +25,13 @@ export type { RootOwnerProps } from './slots.ts'
 export { SessionsService, scopeOf } from './sessions/service.ts'
 export type { Session } from './sessions/session.ts'
 export type { SessionBinding, SessionListState, SessionSummary } from './sessions/service.ts'
+// The snapshot-store engine lives here since the store migration (the data
+// layer owns its substrate; web-react is React glue only). The './client'
+// main export is the single serving door — no store subpath.
+export { createSnapshotStore, defineStore, shallowEqual } from './store/index.ts'
+export type {
+  EngineStoreHandle, EngineStoreInstance, ObservableSnapshot, SnapshotStore,
+} from './store/index.ts'
 export type {
  AssistantBlock, AssistantMessageNode, ContextMessageNode, ConversationNode, ConversationSnapshot,
  PendingInteraction, RunningToolCall, SteeringMessageNode,
@@ -45,7 +52,7 @@ export type { SessionId } from '@deepseek-ai/dsh-client-connection/client'
 export type ClientContext = Context

 /** The conversation-snapshot selector hook (ConvViewProps/ToolViewProps take this). */
-export type UseConversationSession = UseSession<ConversationSnapshot>
+export type UseConversationSession = SnapshotSelectorHook<ConversationSnapshot>

 /**
 * One tool call as the chat flow renders it: still-running (spinner card) or
@@ -17,7 +17,7 @@
 * load one by one in inject topology.
 */
 import type { Context } from 'cordis'
-import { createSnapshotStore } from '@deepseek-ai/dsh-client-web-react/store'
+import { createSnapshotStore } from '../store/index.ts'
 import type { BootPluginEntry, ClientLoader, LoaderStatus } from '../index.ts'

 export type { BootPluginEntry, ClientLoader, LoaderStatus } from '../index.ts'
@@ -15,11 +15,9 @@
 */
 import type { Context, Fiber } from 'cordis'
 import type { IApiClient, SessionId } from '@deepseek-ai/dsh-client-connection/client'
-// Engine reach-through: the store subpath is the framework-internal channel
-// (the public web-react face carries defineStore only).
-import type { SnapshotStore } from '@deepseek-ai/dsh-client-web-react/store'
-import { createSnapshotStore } from '@deepseek-ai/dsh-client-web-react/store'
-import type { SessionCell } from '@deepseek-ai/dsh-client-web-react'
+import type { SessionCell } from '@deepseek-ai/dsh-client-ui-slots'
+import type { SnapshotStore } from '../store/index.ts'
+import { createSnapshotStore } from '../store/index.ts'
 import { SessionManager } from './manager.ts'
 import type { Session } from './session.ts'

@@ -216,7 +214,9 @@ export class SessionsService {
      fiber,
      ctx,
      binding: { sessionId: id, session, ctx },
-      cell: { sessionId: id, useSession: session.useSelector },
+      // Bare source form (store migration): the Session object IS the
+      // observable; the React side binds the useSession hook per cell.
+      cell: { sessionId: id, session },
    }
    this.scopes.set(id, record)
    return record
@@ -7,8 +7,7 @@ import type { ContentBlock } from '@deepseek-ai/dsh-llm/types'
 import type { SessionEvent } from '@deepseek-ai/dsh-session/types'
 import type { HistoryEntry, IApiClient, MuxFrame, RpcError, RpcId, RpcResult, SessionId, ToolEventView } from '@deepseek-ai/dsh-client-connection/client'
 import { transportError } from '@deepseek-ai/dsh-client-connection/client'
-import type { ObservableSnapshot, SnapshotSelectorHook } from '@deepseek-ai/dsh-client-web-react'
-import { bindSnapshotSelector } from '@deepseek-ai/dsh-client-web-react'
+import type { ObservableSnapshot } from '../store/index.ts'
 import type {
  ConversationNode, ConversationSnapshot, OpenState, PendingInteraction, PromptError, RunningToolCall,
 } from './conversation.ts'
@@ -19,11 +18,13 @@ import { PartialAccumulator } from './partial.ts'
 /** Messages per page (F.4 ledger: promote to Config at graduation; every call site references this constant). */
 export const PAGE_MESSAGES = 50

-/** Per-session state owner: event window + fold + partial, snapshot out via uSES (see the web client architecture RFC). */
+/**
+ * Per-session state owner: event window + fold + partial, snapshot out via
+ * subscribe/getSnapshot (see the web client architecture RFC). Bare source
+ * only (store migration): the React machinery binds the per-cell useSession
+ * hook at its own seam — no selector hook member lives on the data layer.
+ */
 export class Session implements ObservableSnapshot<ConversationSnapshot> {
-  /** Typed selector hook bound to this instance (the SessionBinding `useSession` source). */
-  readonly useSelector: SnapshotSelectorHook<ConversationSnapshot> = bindSnapshotSelector(this)
-
  // ---- Window and derived state (all private; the snapshot is the only read surface) ----
  private events: SessionEvent[] = []
  /** Wire views aligned with `events` by index (envelope-level annotations; undefined = no view).
@@ -0,0 +1,244 @@
+/**
+ * Snapshot store engine (zustand vanilla + immer + subscribeWithSelector +
+ * rafFlush middleware + opt-in persist + dev freeze) plus the declarative
+ * shell over it: {@link defineStore} bakes an init/persist/actions literal
+ * into a {@link StoreHandle}, the registration-side store seat of the slot
+ * terminal design (§4). Lives in the React-free runtime (store-migration
+ * ruling: the data layer owns its engine; web-react is shell-only React
+ * glue): engine products are bare observables — subscribe/getSnapshot/
+ * update/set, NO selector hook. Hook synthesis is web-react's (the one
+ * uSES bridge, cached per source at the binding site).
+ */
+import { createStore, type StoreApi } from 'zustand/vanilla'
+import { subscribeWithSelector } from 'zustand/middleware'
+import { shallow } from 'zustand/shallow'
+import { produce } from 'immer'
+import type {
+  ActionsDecl, BakedActions, StoreHandle, StoreInstance, StoreSpec,
+} from '@deepseek-ai/dsh-client-ui-slots'
+
+// Store contract types are ui-slots authority; re-exported beside the engine
+// so store consumers get one import surface.
+export type {
+  ActionsDecl, BakedActions, BoundActions, StoreFactory, StoreHandle, StoreInstance, StoreSpec,
+} from '@deepseek-ai/dsh-client-ui-slots'
+
+/** Minimal observable snapshot source: Session objects and snapshot stores both satisfy it. */
+export interface ObservableSnapshot<T> { getSnapshot(): T; subscribe(fn: () => void): () => void }
+
+/** Writable snapshot store (bare data face; React selector hooks are synthesized in web-react). */
+export interface SnapshotStore<T> extends ObservableSnapshot<T> {
+  /**
+   * Mutate the state through an immer draft.
+   * @param mutator - draft mutator.
+   */
+  update(mutator: (draft: T) => void): void
+  /**
+   * Replace the state wholesale.
+   * @param next - next state.
+   */
+  set(next: T): void
+}
+
+/**
+ * Shallow equality for selector slices (zustand/shallow semantics; travels
+ * with the engine so hook consumers need no zustand dependency).
+ * @param a - left value.
+ * @param b - right value.
+ * @returns whether the values are shallowly equal.
+ */
+export function shallowEqual(a: unknown, b: unknown): boolean {
+  return shallow(a, b)
+}
+
+/** Batches subscriber notification into one flush per animation frame. */
+function rafBatch(notify: () => void): () => void {
+  // Fall back to microtask batching where rAF is absent (node unit tests);
+  // both preserve the N-changes=1-notification contract within a tick.
+  const schedule: (fn: () => void) => void =
+    typeof requestAnimationFrame === 'function'
+      ? (fn) => { requestAnimationFrame(() => { fn() }) }
+      : (fn) => { queueMicrotask(fn) }
+  let scheduled = false
+  return () => {
+    if (scheduled) return
+    scheduled = true
+    schedule(() => {
+      scheduled = false
+      notify()
+    })
+  }
+}
+
+/**
+ * Create a snapshot store.
+ *
+ * Flush default is 'sync' (controlled inputs need same-tick echo); frame-driven
+ * stores opt into 'raf', where a frame's worth of updates coalesces into one
+ * notification. Known raf-mode tradeoff: a component mounting mid-frame reads
+ * fresh state while existing subscribers hear it next flush — transient
+ * frame-level skew, same nature as the object layer's microtask batching.
+ *
+ * @param init - initial state.
+ * @param opts - flush mode and opt-in persistence (localStorage, keyed by name).
+ * @returns the store.
+ */
+export function createSnapshotStore<T>(
+  init: T, opts?: { flush?: 'raf' | 'sync'; persist?: { name: string } }): SnapshotStore<T> {
+  // Immer enters through produce() in update() below (identical semantics to
+  // the immer middleware without its setState-signature mutator generics).
+  const withSelector = subscribeWithSelector(() => init)
+  const api: StoreApi<T> = createStore<T>()(withSelector)
+  if (opts?.persist) attachPersistence(api, opts.persist.name)
+
+  let subscribe = (fn: () => void) => api.subscribe(fn)
+  if (opts?.flush === 'raf') {
+    const listeners = new Set<() => void>()
+    const flush = rafBatch(() => { for (const fn of [...listeners]) fn() })
+    api.subscribe(flush)
+    subscribe = (fn: () => void) => {
+      listeners.add(fn)
+      return () => { listeners.delete(fn) }
+    }
+  }
+
+  return {
+    getSnapshot: () => api.getState(),
+    subscribe: fn => subscribe(fn),
+    update: (mutator) => {
+      // Immer's produce (not setState's partial-merge path) so scalar and
+      // array roots replace correctly; produce also freezes in dev.
+      api.setState(produce(api.getState(), (draft) => { mutator(draft as T) }), true)
+    },
+    set: (next) => {
+      api.setState(devFreeze(next), true)
+    },
+  }
+}
+
+/**
+ * Whole-value JSON persistence to localStorage. Hand-rolled instead of the
+ * zustand persist middleware: its write path spreads state into an object
+ * (`partialize({ ...get() })`), exploding primitive state (a persisted string
+ * draft becomes {0:'h',1:'e',...}) — not fixable via merge/deserialize options
+ * because the corruption happens before serialization. Storage failures
+ * (quota, private mode) only disable persistence, never break the store.
+ */
+function attachPersistence<T>(api: StoreApi<T>, name: string): void {
+  // Non-browser runs (node e2e booting the client tree) have no localStorage:
+  // persistence silently disables — same contract as a storage failure, minus
+  // the per-store console noise a ReferenceError would produce.
+  if (typeof localStorage === 'undefined') return
+  try {
+    const raw = localStorage.getItem(name)
+    if (raw !== null) {
+      api.setState(devFreeze(JSON.parse(raw) as T), true)
+    }
+  } catch (error) {
+    console.error(`snapshot store '${name}' rehydration failed:`, error)
+  }
+  api.subscribe((state) => {
+    try {
+      localStorage.setItem(name, JSON.stringify(state))
+    } catch (error) {
+      console.error(`snapshot store '${name}' persistence failed:`, error)
+    }
+  })
+}
+
+/** Deep-freeze wholesale-set state outside production: set() bypasses immer's freeze. */
+function devFreeze<T>(value: T): T {
+  if (process.env.NODE_ENV === 'production') return value
+  deepFreeze(value)
+  return value
+}
+
+function deepFreeze(value: unknown): void {
+  if (typeof value !== 'object' || value === null || Object.isFrozen(value)) return
+  Object.freeze(value)
+  for (const key of Reflect.ownKeys(value)) {
+    deepFreeze((value as Record<PropertyKey, unknown>)[key])
+  }
+}
+
+// ---- defineStore shell (slot terminal design §4) ----
+// The type authority is ui-slots' store family (create(scopeKey?) and
+// clearPersisted() included); this module houses only the engine-backed
+// implementation. The one engine-side widening left: instances expose the
+// raw engine store for framework/test surfaces.
+
+/** A live engine instance: the contract instance plus the raw engine store. */
+export interface EngineStoreInstance<T, A extends ActionsDecl<T>> extends StoreInstance<T, A> {
+  /** The underlying engine store (framework/test surface; components never see it). */
+  readonly store: SnapshotStore<T>
+}
+
+/** The engine-backed handle: create() narrowed to the engine instance. */
+export interface EngineStoreHandle<T, A extends ActionsDecl<T>> extends StoreHandle<T, A> {
+  /**
+   * Construct a live engine instance (see the contract JSDoc on
+   * {@link StoreHandle.create} for scopeKey/persist semantics).
+   *
+   * Known boundary: the persist key is the storage identity, so multiple live
+   * instances created under the same resolved key share (and cross-pollute)
+   * one localStorage entry. Instance uniqueness per key is the caller's
+   * responsibility — production is safe because the framework caches one
+   * instance per handle x scope key; tests wanting isolation use distinct
+   * scope keys or persist-free declarations (multi-create freedom is a
+   * feature there, so create() deliberately does not dedupe or throw).
+   * @param scopeKey - session id for session-scope instances; omitted for root scope.
+   * @returns the engine instance.
+   */
+  create(scopeKey?: string): EngineStoreInstance<T, A>
+}
+
+/**
+ * Declare a store: initial state, optional persistence, and the full write
+ * set as pure draft mutators. The returned handle is the registration
+ * currency of the store seat — its identity keys instance sharing. Satisfies
+ * ui-slots' DefineStore contract (the handle/instance are the engine-extended
+ * subtypes).
+ *
+ * The `A & ActionsDecl<T>` actions position is load-bearing: T resolves from
+ * `init` in the first inference round, and the intersection then contextually
+ * types each mutator's draft parameter (context-sensitive functions defer),
+ * so call sites write `(d, x: X) => { ... }` with no draft annotation. If a
+ * future TS version breaks this single-literal inference, the design's
+ * documented fallback is currying (`defineStore(init).actions({...})`).
+ * @param decl - init lambda (fresh state per instance), optional persist key, actions table.
+ * @returns the store handle.
+ */
+export function defineStore<T, A extends ActionsDecl<T>>(
+  decl: StoreSpec<T, A> & { actions: A & ActionsDecl<T> }): EngineStoreHandle<T, A> {
+  return {
+    spec: decl,
+    create(scopeKey?: string): EngineStoreInstance<T, A> {
+      const persistKey = decl.persist === undefined
+        ? undefined
+        : scopeKey === undefined ? decl.persist : `${decl.persist}.${scopeKey}`
+      const store = createSnapshotStore<T>(
+        decl.init(),
+        persistKey !== undefined ? { persist: { name: persistKey } } : undefined)
+      const actions = {} as Record<string, (...params: unknown[]) => void>
+      for (const key of Object.keys(decl.actions)) {
+        const mutate = decl.actions[key] as (draft: T, ...params: unknown[]) => void
+        actions[key] = (...params: unknown[]) => { store.update((draft) => { mutate(draft, ...params) }) }
+      }
+      return {
+        actions: actions as BakedActions<T, A>,
+        getSnapshot: () => store.getSnapshot(),
+        subscribe: fn => store.subscribe(fn),
+        store,
+        clearPersisted: () => {
+          if (persistKey === undefined || typeof localStorage === 'undefined') return
+          try {
+            localStorage.removeItem(persistKey)
+          } catch {
+            // Storage failures (private mode, quota teardown races) only skip
+            // cleanup — the same non-fatal contract as attachPersistence.
+          }
+        },
+      }
+    },
+  }
+}
@@ -0,0 +1,5 @@
+/**
+ * Bundler-replaced NODE_ENV: vite/tsdown substitute the literal, so browsers
+ * never evaluate a bare `process`. tsconfig carries no node types on purpose.
+ */
+declare const process: { env: { NODE_ENV?: string } }