refactor(gui): slot system standard — single register, four props shares, framework store seat

The definitive slot model for the web client, replacing the first-generation
define/register two-step, ScopedSlots whitelist faces, and binding handles:

- 'root' is the only a-priori slot (SlotsService built-in); the shell renders
  exactly ctx.slots.renderSlot('root', {}).
- register is the single API: children = slot declaration + render
  authorization + runtime spec in one options object; misconfiguration fails
  loud at load (duplicate declaration, undeclared contribution, one store
  handle under two scopes).
- Component props arrive in four auto-derived shares: PropsRuntime<K>
  (owner params + session/global standard kits via declare-merge),
  PropsRenderSlots<S>, PropsStore<H>, and the inject business face.
  sessionId is framework-supplied; hooks are framework-made only.
- Framework store seat: defineStore factories declare schema/actions/persist;
  read = useStore, write = baked actions only; store scope derives from the
  mounting entry; per-session persist keys and clearPersisted lifecycle.
- inject factories read the apply closure's own ctx (binding handles retired;
  root-ctx back door closed); SessionProvider is self-wired render-prop.
- Rendering sits behind the SlotRenderer install seam; runtime stays
  React-free; ownership ledger keyed to the single entry axis closes the
  stale-authority window (StaleAuthorizationError probes).

Docs: the slot type-chain note is refreshed in place as the slot system
standard RFC (bilingual pair re-recorded); the web client architecture RFC
defers its slot sections there; packages/client/AGENTS.md gains the slot and
props discipline; gui-testing/web-styling notes drop missions/ references.

Tests: suites rewritten to the standard (props fed directly, real store
engines via createXXXStore().create(), no render machinery); load-time
negative samples for declaration/authorization/store conflicts; verified by
real-host playwright run (three columns, empty state, collapse, keyed session
remount, cross-slot selection sharing).

docs(ui-sidebar): point contract reference at the committed slot standard RFC

missions/ is workspace-local and never committed; the README must not cite it.
This commit is contained in:
imccyu
2026-07-23 01:40:30 +08:00
parent efa4326ff4
commit 1b0ea07bce
95 changed files with 5024 additions and 3322 deletions

View File

@@ -1,70 +1,121 @@
// @vitest-environment jsdom
/**
* Integration against the real ui-slots SlotCore (T1): the outlet's uSES
* pairing rides the real subscribe/getVersion/entries surfaces, and the
* whitelist narrows at compile time (expect-error negative samples).
* Integration against the real ui-slots SlotCore through a passthrough host:
* registrations go through the real register() (options form, children
* declaration), and the outlets ride the real subscribe/getVersion/entries/
* isLive surfaces — microtask-batched notifications, mutation-stable entry
* references (the cache axis), and ledger-fed stale bindings are the
* real-core semantics the fake-host suite cannot vouch for.
*/
import { describe, expect, it, vi } from 'vitest'
import { act, render } from '@testing-library/react'
import { SlotCore } from '@deepseek-ai/dsh-client-ui-slots'
import { scopedSlots } from '@deepseek-ai/dsh-client-web-react'
import { SlotCore, type PropsRenderSlots, type SlotRendererHost } from '@deepseek-ai/dsh-client-ui-slots'
import { createSlotRenderer, StaleAuthorizationError } from '@deepseek-ai/dsh-client-web-react'
declare module '@deepseek-ai/dsh-client-ui-slots' {
interface SlotMap {
'spec.single': { kind: 'single'; scope: 'root'; props: { label?: string } }
'spec.list': { kind: 'list'; scope: 'root'; props: object }
'spec.off-limits': { kind: 'single'; scope: 'root'; props: object }
// No 'root' merge: the aggregate client program already carries runtime's
// authoritative 'root' declaration (a private merge would TS2717-collide);
// only this suite's own test keys merge here.
'spec.single': { kind: 'single'; scope: 'root'; owner: { label?: string } }
'spec.list': { kind: 'list'; scope: 'root' }
}
}
describe('scopedSlots over the real SlotCore', () => {
it('renders registrations live: define, register, dispose back to fallback', async () => {
type FrameSlots = PropsRenderSlots<'spec.single' | 'spec.list'>
/** Passthrough host over the real core (store/session seats unused here). */
function hostOver(core: SlotCore): SlotRendererHost {
return {
subscribe: (key, fn) => core.subscribe(key, fn),
getVersion: (key) => core.getVersion(key),
entriesOf: (key) => core.entries(key),
specOf: (key) => core.specDynamic(key),
isLive: (entry) => core.isLive(entry),
storeOf: () => undefined,
sessions: {
list: { getSnapshot: () => ({}), subscribe: () => () => {} },
current: { getSnapshot: () => undefined, subscribe: () => () => {} },
cell: () => undefined,
},
}
}
/** Register the root frame (declaring both child keys) and mount the renderer. */
function mountFrame(core: SlotCore, body: (renderSlot: FrameSlots['renderSlot']) => React.ReactNode) {
const dispose = core.register({
name: 'root',
children: {
'spec.single': { kind: 'single', scope: 'root' },
'spec.list': { kind: 'list', scope: 'root' },
},
}, (props: FrameSlots) => <>{body(props.renderSlot)}</>)
const view = render(<>{createSlotRenderer().renderRoot(hostOver(core), {})}</>)
return { view, dispose }
}
describe('createSlotRenderer over the real SlotCore', () => {
it('renders registrations live through real microtask batching: register, dispose back to fallback', async () => {
const core = new SlotCore()
core.define('spec.single', { kind: 'single', scope: 'root' })
const slots = scopedSlots(core, 'spec.single')
const view = render(<>{slots.renderSlot('spec.single', {}, { fallback: <i>none</i> })}</>)
const { view } = mountFrame(core, (renderSlot) =>
renderSlot('spec.single', {}, { fallback: <i>none</i> }))
expect(view.container.textContent).toBe('none')
let dispose = () => {}
// The real core batches subscriber notification per microtask: async act.
await act(async () => { dispose = core.register('spec.single', ({ label }) => <b>{label ?? 'on'}</b>) })
await act(async () => {
dispose = core.register({ name: 'spec.single' }, ({ label }: { label?: string }) => <b>{label ?? 'on'}</b>)
})
expect(view.container.textContent).toBe('on')
await act(async () => { dispose(); dispose() }) // disposer is idempotent in the real core
expect(view.container.textContent).toBe('none')
})
it('passes owner props through and orders list entries', () => {
it('coalesces same-tick mutations into one notification (uSES pairing stays consistent)', async () => {
const core = new SlotCore()
core.define('spec.single', { kind: 'single', scope: 'root' })
core.define('spec.list', { kind: 'list', scope: 'root' })
core.register('spec.single', ({ label }) => <b>{label}</b>)
core.register('spec.list', () => <span>2</span>, { id: 'two', order: 2 })
core.register('spec.list', () => <span>1</span>, { id: 'one', order: 1 })
const slots = scopedSlots(core, 'spec.single', 'spec.list')
const view = render(
<>
{slots.renderSlot('spec.single', { label: 'owner' })}
{slots.renderSlot('spec.list', {})}
</>,
)
expect(view.container.textContent).toBe('owner12')
const notified = vi.fn()
core.subscribe('spec.list', notified)
const { view } = mountFrame(core, (renderSlot) => renderSlot('spec.list', {}))
await act(async () => {
core.register({ name: 'spec.list', id: 'two', order: 2 }, () => <span>2</span>)
core.register({ name: 'spec.list', id: 'one', order: 1 }, () => <span>1</span>)
})
expect(notified).toHaveBeenCalledTimes(1) // two same-tick mutations, one batch
expect(view.container.textContent).toBe('12')
})
it('fails loud when rendering a key that was never defined', () => {
it('passes owner props through and keeps sibling entries() references stable across mutations', async () => {
const core = new SlotCore()
const slots = scopedSlots(core, 'spec.single')
const spy = vi.spyOn(console, 'error').mockImplementation(() => {})
expect(() => render(<>{slots.renderSlot('spec.single', {})}</>)).toThrow(/before define/)
spy.mockRestore()
core.register({ name: 'root', children: {
'spec.single': { kind: 'single', scope: 'root' },
'spec.list': { kind: 'list', scope: 'root' },
} }, (props: FrameSlots) => <>
{props.renderSlot('spec.single', { label: 'owner' })}
{props.renderSlot('spec.list', {})}
</>)
core.register({ name: 'spec.single' }, ({ label }: { label?: string }) => <b>{label}</b>)
const view = render(<>{createSlotRenderer().renderRoot(hostOver(core), {})}</>)
expect(view.container.textContent).toBe('owner')
// A mutation on the sibling key leaves this key's entries() reference
// untouched (real-core stability the inject/renderSlot caches key on).
const before = core.entries('spec.single')
await act(async () => { core.register({ name: 'spec.list', id: 'l' }, () => <span>L</span>) })
expect(core.entries('spec.single')).toBe(before)
expect(view.container.textContent).toBe('ownerL')
})
it('narrows the whitelist at compile time and backstops at runtime', () => {
it('feeds stale bindings from the real ledger: a disposed registration throws off isLive', () => {
const core = new SlotCore()
core.define('spec.single', { kind: 'single', scope: 'root' })
core.define('spec.off-limits', { kind: 'single', scope: 'root' })
const slots = scopedSlots(core, 'spec.single')
// @ts-expect-error spec.off-limits is outside this ScopedSlots whitelist
expect(() => slots.renderSlot('spec.off-limits', {})).toThrow(/whitelist/)
// @ts-expect-error unknown keys are rejected even before whitelist narrowing
expect(() => slots.renderSlot('spec.nonexistent', {})).toThrow(/whitelist/)
let captured: FrameSlots['renderSlot'] | undefined
const { view, dispose } = mountFrame(core, (renderSlot) => {
captured = renderSlot
return null
})
expect(captured!('spec.single', {})).not.toBeUndefined() // live binding renders
// Unmount before disposing: an empty 'root' makes a LIVE root outlet
// rethrow boot-order (covered in the fake-host suite); the scenario here
// is a retained closure outliving both tree and registration.
view.unmount()
dispose()
expect(() => captured!('spec.single', {})).toThrow(StaleAuthorizationError)
})
})

View File

@@ -1,142 +1,415 @@
// @vitest-environment jsdom
/**
* createSlotRenderer machinery account over a behavioral fake host: root
* outlet + per-kind child outlets, standard-kit synthesis (renderSlot
* binding, session pair, global useSessions, store pair), inject execution
* point (inside component bodies, contained per entry) and parameter
* derivation, and cache granularity (entry x scope key). Ledger semantics
* (declaration conflicts, store instance accounting) belong to the runtime
* SlotsService suite, not here.
*/
import { describe, expect, it, vi } from 'vitest'
import { act, render } from '@testing-library/react'
import type {
FC } from 'react'
import type {
InjectFactory, RootBinding, SlotCore, SlotEntry, SlotEntryDef, SlotSpec,
} from '@deepseek-ai/dsh-client-ui-slots'
import type { ReactNode } from 'react'
import type { SlotEntryDef, SlotSpec, StoredEntry } from '@deepseek-ai/dsh-client-ui-slots'
import {
createSessionProvider, createSnapshotStore, RootBindingProvider, scopedSlots,
type SessionBinding, type SessionProviderDeps,
createSlotRenderer, defineStore, SessionProvider, SlotOwnershipError,
type RenderOpts, type SessionCell,
type SlotRendererHost, type StoreInstanceLike,
} from '@deepseek-ai/dsh-client-web-react'
type AnyProps = Record<string, unknown>
type RenderSlotFn = (key: string, owner: object, opts?: RenderOpts) => ReactNode
type DeclaredSpec = SlotSpec<SlotEntryDef>
/** Entry literal helper: fake entries default the mandatory options bag. */
const entryOf = (partial: Omit<StoredEntry, 'options'> & { options?: StoredEntry['options'] }): StoredEntry =>
({ options: {}, ...partial })
function observable<T>(initial: T) {
let value = initial
const subs = new Set<() => void>()
return {
getSnapshot: () => value,
subscribe: (fn: () => void) => { subs.add(fn); return () => { subs.delete(fn) } },
set: (next: T) => { value = next; for (const fn of [...subs]) fn() },
}
}
/**
* Behavioral SlotCore fake (the real ui-slots is still a T0 stub): registration
* mutates entries, bumps the key version, and notifies subscribers synchronously
* (batching semantics belong to fw-slots' core, not this package's outlet).
* Behavioral SlotRendererHost fake: registration mutates entries, bumps the
* key version, and notifies synchronously (batching semantics belong to the
* runtime host, not this package's outlets). Store instances resolve through
* the entry's real handle, cached per (entry x scope key) like the real
* ledger; session cells are identity-stable per id.
*/
function makeFakeCore() {
const specs = new Map<string, SlotSpec<SlotEntryDef>>()
const entries = new Map<string, SlotEntry<SlotEntryDef>[]>()
function makeHost() {
const entries = new Map<string, StoredEntry[]>()
const specs = new Map<string, DeclaredSpec>()
const versions = new Map<string, number>()
const subs = new Map<string, Set<() => void>>()
const live = new Set<StoredEntry>()
const storeCache = new Map<StoredEntry, Map<string, StoreInstanceLike>>()
const list = observable<{ ids: string[] }>({ ids: [] })
const current = observable<string | undefined>(undefined)
const cells = new Map<string, SessionCell>()
const bump = (key: string) => {
versions.set(key, (versions.get(key) ?? 0) + 1)
for (const fn of [...(subs.get(key) ?? [])]) fn()
}
const core = {
define: (key: string, spec: SlotSpec<SlotEntryDef>) => {
specs.set(key, spec)
bump(key)
return () => { specs.delete(key); bump(key) }
},
// Options widened beyond SlotOptions<SlotEntryDef>: fake keys ('fake.list')
// are not in SlotMap, so calls resolve against this signature and need the
// list/keyed fields the conditional type would otherwise narrow away.
register: (
key: string, component: FC<object>,
options: { key?: string; id?: string; order?: number; label?: string; inject?: InjectFactory<SlotEntryDef> } = {},
) => {
const list = entries.get(key) ?? []
const entry: SlotEntry<SlotEntryDef> = { component, options }
entries.set(key, [...list, entry])
bump(key)
return () => {
entries.set(key, (entries.get(key) ?? []).filter((e) => e !== entry))
bump(key)
}
},
entries: (key: string) => entries.get(key) ?? [],
spec: (key: string) => specs.get(key),
subscribe: (key: string, fn: () => void) => {
const host: SlotRendererHost = {
subscribe: (key, fn) => {
const set = subs.get(key) ?? new Set()
set.add(fn)
subs.set(key, set)
return () => { set.delete(fn) }
},
getVersion: (key: string) => versions.get(key) ?? 0,
onMutate: () => () => {},
getVersion: (key) => versions.get(key) ?? 0,
entriesOf: (key) => entries.get(key) ?? [],
specOf: (key) => specs.get(key),
isLive: (entry) => live.has(entry),
storeOf: (entry, scopeKey) => {
if (entry.store === undefined) return undefined
let perScope = storeCache.get(entry)
if (!perScope) {
perScope = new Map()
storeCache.set(entry, perScope)
}
const cacheKey = scopeKey ?? ''
let instance = perScope.get(cacheKey)
if (!instance) {
// Fake entries always carry engine handles (never factories), and the
// engine create() takes the scope key (persist suffixing).
const handle = entry.store as { create(scopeKey?: string): StoreInstanceLike }
instance = handle.create(scopeKey)
perScope.set(cacheKey, instance)
}
return instance
},
sessions: {
list,
current,
cell: (id) => cells.get(id),
},
}
return {
host,
list,
current,
declare: (key: string, spec: DeclaredSpec) => { specs.set(key, spec); bump(key) },
add: (key: string, partial: Omit<StoredEntry, 'options'> & { options?: StoredEntry['options'] }) => {
const entry = entryOf(partial)
entries.set(key, [...(entries.get(key) ?? []), entry])
live.add(entry)
bump(key)
return () => {
entries.set(key, (entries.get(key) ?? []).filter((e) => e !== entry))
live.delete(entry)
bump(key)
}
},
addSession: (id: string): SessionCell => {
const cell: SessionCell = { sessionId: id, useSession: { hookTag: id } }
cells.set(id, cell)
return cell
},
}
return core as unknown as SlotCore & typeof core
}
const useSelectorStub = (() => { throw new Error('unused in these specs') }) as never
type Fake = ReturnType<typeof makeHost>
const makeBinding = (sessionId: string): SessionBinding => ({
sessionId, session: { useSelector: useSelectorStub }, ctx: { tag: sessionId },
})
/** Mount ui under a SessionProvider bound to one switchable session. */
function sessionHarness(body: (id: string) => React.ReactNode, bindings: Record<string, SessionBinding>) {
const current = createSnapshotStore<{ id: string | undefined }>({ id: undefined })
const deps: SessionProviderDeps = {
useCurrent: () => current.useSelector((s) => s.id),
resolveBinding: (id) => bindings[id],
renderBody: body,
}
const Provider = createSessionProvider(deps)
return { current, Provider }
/** Mount a root entry whose component renders `body` with its kit renderSlot. */
function mountRoot(h: Fake, children: Record<string, DeclaredSpec>, body: (renderSlot: RenderSlotFn) => ReactNode) {
const dispose = h.add('root', {
component: (props: { renderSlot: RenderSlotFn }) => <>{body(props.renderSlot)}</>,
children,
})
const renderer = createSlotRenderer()
const view = render(<>{renderer.renderRoot(h.host, {})}</>)
return { view, dispose }
}
describe('scopedSlots basics', () => {
it('throws on renderSlot before define and on non-whitelisted keys', () => {
const core = makeFakeCore()
const slots = scopedSlots(core, 'fake.root' as never)
expect(() => slots.renderSlot('fake.session' as never, {})).toThrow(/whitelist/)
const SINGLE_ROOT: DeclaredSpec = { kind: 'single', scope: 'root' }
const SINGLE_SESSION: DeclaredSpec = { kind: 'single', scope: 'session' }
describe('root outlet', () => {
it('renders the root registration and fails loud when root is unregistered (boot order)', () => {
const h = makeHost()
h.add('root', { component: () => <b>shell</b> })
const renderer = createSlotRenderer()
const view = render(<>{renderer.renderRoot(h.host, {})}</>)
expect(view.container.textContent).toBe('shell')
const empty = makeHost()
const spy = vi.spyOn(console, 'error').mockImplementation(() => {})
expect(() => render(<>{slots.renderSlot('fake.root' as never, {})}</>)).toThrow(/before define/)
expect(() => render(<>{createSlotRenderer().renderRoot(empty.host, {})}</>))
.toThrow(/boot order/)
spy.mockRestore()
})
it('renders single-kind root slots, falls back when empty, live-updates on register/dispose', () => {
const core = makeFakeCore()
core.define('fake.root', { kind: 'single', scope: 'root' })
const slots = scopedSlots(core, 'fake.root' as never)
const view = render(<>{slots.renderSlot('fake.root' as never, {}, { fallback: <i>none</i> })}</>)
it('passes renderRoot owner props into the root component', () => {
const h = makeHost()
h.add('root', { component: ({ tag }: { tag?: string }) => <b>{tag}</b> })
const view = render(<>{createSlotRenderer().renderRoot(h.host, { tag: 'OWNER' })}</>)
expect(view.container.textContent).toBe('OWNER')
})
})
describe('child outlets and the renderSlot binding', () => {
it('renders declared single slots live: fallback when empty, register, dispose back', () => {
const h = makeHost()
h.declare('k.single', SINGLE_ROOT)
const { view } = mountRoot(h, { 'k.single': SINGLE_ROOT },
(renderSlot) => renderSlot('k.single', {}, { fallback: <i>none</i> }))
expect(view.container.textContent).toBe('none')
let dispose = () => {}
act(() => { dispose = core.register('fake.root', () => <b>SB</b>) })
act(() => { dispose = h.add('k.single', { component: () => <b>SB</b> }) })
expect(view.container.textContent).toBe('SB')
act(() => { dispose() })
expect(view.container.textContent).toBe('none')
})
it('renders list slots in order, honors only-filter, keyed slots dispatch by entryKey', () => {
const core = makeFakeCore()
core.define('fake.list', { kind: 'list', scope: 'root' })
core.define('fake.keyed', { kind: 'keyed', scope: 'root' })
core.register('fake.list', () => <span>b</span>, { id: 'b', order: 2 })
core.register('fake.list', () => <span>a</span>, { id: 'a', order: 1 })
core.register('fake.keyed', () => <span>goal</span>, { key: 'goal' })
const slots = scopedSlots(core, 'fake.list' as never, 'fake.keyed' as never)
const list = render(<>{slots.renderSlot('fake.list' as never, {})}</>)
expect(list.container.textContent).toBe('ab')
const only = render(<>{slots.renderSlot('fake.list' as never, {}, { only: 'b' })}</>)
expect(only.container.textContent).toBe('b')
const hit = render(<>{slots.renderSlot('fake.keyed' as never, {}, { entryKey: 'goal' })}</>)
expect(hit.container.textContent).toBe('goal')
const miss = render(
<>{slots.renderSlot('fake.keyed' as never, {}, { entryKey: 'nope', fallback: <i>fb</i> })}</>)
expect(miss.container.textContent).toBe('fb')
it('renders an undeclared key as empty (declaring entry unloaded = natural blank, not a crash)', () => {
const h = makeHost()
const { view } = mountRoot(h, { 'k.single': SINGLE_ROOT },
(renderSlot) => <main>{renderSlot('k.single', {}, { fallback: <i>fb</i> })}</main>)
// Declared by children (authorization) but absent from the ledger (specOf
// undefined): the outlet renders nothing, not even the fallback path's spec dispatch.
expect(view.container.querySelector('main')!.textContent).toBe('')
})
it('contains a throwing root inject factory to its own entry (P1 whiteout regression)', () => {
const core = makeFakeCore()
core.define('fake.list', { kind: 'list', scope: 'root' })
core.register('fake.list', () => <span>never</span>, {
id: 'bad', order: 1,
inject: (() => { throw new Error('inject boom') }) as unknown as InjectFactory<SlotEntryDef>,
it('orders list entries, honors only-filter, dispatches keyed entries by entryKey', () => {
const h = makeHost()
h.declare('k.list', { kind: 'list', scope: 'root' })
h.declare('k.keyed', { kind: 'keyed', scope: 'root' })
h.add('k.list', { component: () => <span>b</span>, options: { id: 'b', order: 2 } })
h.add('k.list', { component: () => <span>a</span>, options: { id: 'a', order: 1 } })
h.add('k.keyed', { component: () => <span>goal</span>, options: { key: 'goal' } })
const children = { 'k.list': { kind: 'list', scope: 'root' } as DeclaredSpec, 'k.keyed': { kind: 'keyed', scope: 'root' } as DeclaredSpec }
const { view } = mountRoot(h, children, (renderSlot) => <>
<main>{renderSlot('k.list', {})}</main>
<aside>{renderSlot('k.list', {}, { only: 'b' })}</aside>
<nav>{renderSlot('k.keyed', {}, { entryKey: 'goal' })}</nav>
<footer>{renderSlot('k.keyed', {}, { entryKey: 'nope', fallback: <i>fb</i> })}</footer>
</>)
expect(view.container.querySelector('main')!.textContent).toBe('ab')
expect(view.container.querySelector('aside')!.textContent).toBe('b')
expect(view.container.querySelector('nav')!.textContent).toBe('goal')
expect(view.container.querySelector('footer')!.textContent).toBe('fb')
})
it('keeps the binding identity-stable across re-renders and throws SlotOwnershipError off-declaration', () => {
const h = makeHost()
h.declare('k.single', SINGLE_ROOT)
const seen: RenderSlotFn[] = []
mountRoot(h, { 'k.single': SINGLE_ROOT }, (renderSlot) => {
seen.push(renderSlot)
return renderSlot('k.single', {})
})
core.register('fake.list', () => <span>alive</span>, { id: 'ok', order: 2 })
const slots = scopedSlots(core, 'fake.list' as never)
const root: RootBinding = { ctx: {} }
// Bump the 'root' key to force a root-entry re-render (the single-kind
// outlet only reads entries[0], so the extra entry is inert).
act(() => { h.add('root', { component: () => null }) })
expect(seen.length).toBeGreaterThan(1)
expect(seen.at(-1)).toBe(seen[0])
expect(() => seen[0]!('k.undeclared', {})).toThrow(SlotOwnershipError)
})
it('isolates a crashing entry without collapsing siblings', () => {
const h = makeHost()
h.declare('k.list', { kind: 'list', scope: 'root' })
h.add('k.list', { component: () => { throw new Error('entry boom') }, options: { id: 'bad', order: 1 } })
h.add('k.list', { component: () => <span>alive</span>, options: { id: 'ok', order: 2 } })
const spy = vi.spyOn(console, 'error').mockImplementation(() => {})
const view = render(
<RootBindingProvider value={root}>
<main>{slots.renderSlot('fake.list' as never, {})}</main>
</RootBindingProvider>,
)
const { view } = mountRoot(h, { 'k.list': { kind: 'list', scope: 'root' } },
(renderSlot) => renderSlot('k.list', {}))
spy.mockRestore()
expect(view.container.textContent).toBe('alive')
expect(view.container.querySelector('[data-slot-error]')).not.toBeNull()
})
})
describe('standard-kit synthesis', () => {
it('delivers a live useSessions hook to every slot component', () => {
const h = makeHost()
h.declare('k.single', SINGLE_ROOT)
h.add('k.single', {
component: ({ useSessions }: { useSessions: <S>(sel: (s: { ids: string[] }) => S) => S }) =>
<b>{useSessions((s) => s.ids.length)}</b>,
})
const { view } = mountRoot(h, { 'k.single': SINGLE_ROOT }, (renderSlot) => renderSlot('k.single', {}))
expect(view.container.textContent).toBe('0')
act(() => { h.list.set({ ids: ['a', 'b'] }) })
expect(view.container.textContent).toBe('2')
})
it('delivers the session pair (useSession identity + sessionId) under SessionProvider', () => {
const h = makeHost()
h.declare('k.session', SINGLE_SESSION)
const cell = h.addSession('s1')
const seen: AnyProps[] = []
h.add('k.session', { component: (props: object) => { seen.push(props as AnyProps); return null } })
mountRoot(h, { 'k.session': SINGLE_SESSION }, (renderSlot) => (
<SessionProvider empty={() => <i>empty</i>}>
{() => renderSlot('k.session', {})}
</SessionProvider>
))
act(() => { h.current.set('s1') })
const props = seen.at(-1)!
expect(props['useSession']).toBe(cell.useSession)
expect(props['sessionId']).toBe('s1')
})
it('fails loud when a session slot renders outside SessionProvider', () => {
const h = makeHost()
h.declare('k.session', SINGLE_SESSION)
h.add('k.session', { component: () => <b>x</b> })
const spy = vi.spyOn(console, 'error').mockImplementation(() => {})
expect(() => mountRoot(h, { 'k.session': SINGLE_SESSION },
(renderSlot) => renderSlot('k.session', {}))).toThrow(/outside SessionProvider/)
spy.mockRestore()
})
it('delivers the store pair for store-declaring entries and writes through baked actions', () => {
const h = makeHost()
h.declare('k.single', SINGLE_ROOT)
const handle = defineStore({
init: () => ({ n: 0 }),
actions: { inc: (d) => { d.n += 1 } },
})
let bump = () => {}
h.add('k.single', {
component: ({ useStore, actions }: {
useStore: <S>(sel: (s: { n: number }) => S) => S
actions: { inc: () => void }
}) => {
bump = actions.inc
return <b>{useStore((s) => s.n)}</b>
},
store: handle,
})
const { view } = mountRoot(h, { 'k.single': SINGLE_ROOT }, (renderSlot) => renderSlot('k.single', {}))
expect(view.container.textContent).toBe('0')
act(() => { bump() })
expect(view.container.textContent).toBe('1')
})
it('resolves session-slot stores per scope key: values survive a switch-away and back', () => {
const h = makeHost()
h.declare('k.session', SINGLE_SESSION)
h.addSession('s1')
h.addSession('s2')
const handle = defineStore({
init: () => ({ draft: '' }),
actions: { setDraft: (d, text: string) => { d.draft = text } },
})
let setDraft: (text: string) => void = () => {}
h.add('k.session', {
component: ({ useStore, actions }: {
useStore: <S>(sel: (s: { draft: string }) => S) => S
actions: { setDraft: (text: string) => void }
}) => {
setDraft = actions.setDraft
return <b>{useStore((s) => s.draft) || '(blank)'}</b>
},
store: handle,
})
const { view } = mountRoot(h, { 'k.session': SINGLE_SESSION }, (renderSlot) => (
<SessionProvider>{() => renderSlot('k.session', {})}</SessionProvider>
))
act(() => { h.current.set('s1') })
act(() => { setDraft('draft-one') })
expect(view.container.textContent).toBe('draft-one')
act(() => { h.current.set('s2') })
expect(view.container.textContent).toBe('(blank)') // distinct instance per session
act(() => { h.current.set('s1') })
expect(view.container.textContent).toBe('draft-one') // same scope key = same instance
})
})
describe('inject: execution point, parameter derivation, cache granularity', () => {
it('root inject runs once per entry with no arguments (no store declared)', () => {
const h = makeHost()
h.declare('k.single', SINGLE_ROOT)
const inject = vi.fn(() => ({ tag: 'FROM-INJECT' }))
h.add('k.single', { component: ({ tag }: { tag?: string }) => <b>{tag}</b>, inject })
const { view } = mountRoot(h, { 'k.single': SINGLE_ROOT }, (renderSlot) => renderSlot('k.single', {}))
expect(view.container.textContent).toBe('FROM-INJECT')
act(() => { h.add('k.single', { component: () => null }) }) // sibling bump re-renders the outlet
expect(inject).toHaveBeenCalledTimes(1)
expect(inject).toHaveBeenCalledWith()
})
it('session inject receives sessionId and caches per (entry x session): switch-back reuses', () => {
const h = makeHost()
h.declare('k.session', SINGLE_SESSION)
h.addSession('s1')
h.addSession('s2')
const inject = vi.fn((sessionId: string) => ({ sid: sessionId }))
h.add('k.session', {
component: ({ sid }: { sid?: string }) => <b>{sid}</b>,
inject: inject as unknown as StoredEntry['inject'],
})
const { view } = mountRoot(h, { 'k.session': SINGLE_SESSION }, (renderSlot) => (
<SessionProvider>{() => renderSlot('k.session', {})}</SessionProvider>
))
act(() => { h.current.set('s1') })
expect(view.container.textContent).toBe('s1')
expect(inject).toHaveBeenCalledTimes(1)
expect(inject).toHaveBeenLastCalledWith('s1')
act(() => { h.current.set('s2') })
expect(view.container.textContent).toBe('s2')
expect(inject).toHaveBeenCalledTimes(2)
act(() => { h.current.set('s1') }) // back: (entry x cell) cache hit
expect(view.container.textContent).toBe('s1')
expect(inject).toHaveBeenCalledTimes(2)
})
it('store-declaring entries get baked actions appended to the inject parameters', () => {
const h = makeHost()
h.declare('k.single', SINGLE_ROOT)
h.declare('k.session', SINGLE_SESSION)
h.addSession('s1')
const handle = defineStore({ init: () => ({ n: 0 }), actions: { inc: (d) => { d.n += 1 } } })
const rootInject = vi.fn((actions: { inc: () => void }) => ({ viaRoot: actions }))
const sessionInject = vi.fn((sessionId: string, actions: { inc: () => void }) => ({ sid: sessionId, viaSession: actions }))
const seenRoot: AnyProps[] = []
const seenSession: AnyProps[] = []
h.add('k.single', {
component: (props: object) => { seenRoot.push(props as AnyProps); return null },
inject: rootInject as unknown as StoredEntry['inject'],
store: handle,
})
h.add('k.session', {
component: (props: object) => { seenSession.push(props as AnyProps); return null },
inject: sessionInject as unknown as StoredEntry['inject'],
store: handle,
})
mountRoot(h, { 'k.single': SINGLE_ROOT, 'k.session': SINGLE_SESSION }, (renderSlot) => <>
{renderSlot('k.single', {})}
<SessionProvider>{() => renderSlot('k.session', {})}</SessionProvider>
</>)
act(() => { h.current.set('s1') })
// The inject-received actions are the same baked callbacks the component
// gets as props.actions (one instance per entry x scope key).
expect(rootInject).toHaveBeenCalledTimes(1)
expect(seenRoot.at(-1)!['viaRoot']).toBe(seenRoot.at(-1)!['actions'])
expect(sessionInject).toHaveBeenCalledTimes(1)
expect(sessionInject.mock.calls[0]![0]).toBe('s1')
expect(seenSession.at(-1)!['viaSession']).toBe(seenSession.at(-1)!['actions'])
})
it('contains a throwing inject factory to its own entry (runs inside the component body)', () => {
const h = makeHost()
h.declare('k.list', { kind: 'list', scope: 'root' })
h.add('k.list', {
component: () => <span>never</span>,
options: { id: 'bad', order: 1 },
inject: () => { throw new Error('inject boom') },
})
h.add('k.list', { component: () => <span>alive</span>, options: { id: 'ok', order: 2 } })
const spy = vi.spyOn(console, 'error').mockImplementation(() => {})
const { view } = mountRoot(h, { 'k.list': { kind: 'list', scope: 'root' } },
(renderSlot) => <main>{renderSlot('k.list', {})}</main>)
spy.mockRestore()
// The failing entry blacks out alone; the sibling and the tree above survive.
expect(view.container.querySelector('main')).not.toBeNull()
@@ -144,131 +417,20 @@ describe('scopedSlots basics', () => {
expect(view.container.querySelector('[data-slot-error]')).not.toBeNull()
})
it('contains a throwing session inject factory to its own entry', () => {
const core = makeFakeCore()
core.define('fake.session', { kind: 'single', scope: 'session' })
core.register('fake.session', () => <span>never</span>, {
inject: (() => { throw new Error('session inject boom') }) as unknown as InjectFactory<SlotEntryDef>,
it('merges kit, inject, and owner props with owner winning', () => {
const h = makeHost()
h.declare('k.single', SINGLE_ROOT)
const seen: AnyProps[] = []
h.add('k.single', {
component: (props: object) => { seen.push(props as AnyProps); return null },
inject: () => ({ fromInject: 'inject', shared: 'inject' }),
})
const slots = scopedSlots(core, 'fake.session' as never)
const bindings = { s1: makeBinding('s1') }
const { current, Provider } = sessionHarness(
(id) => <main data-shell={id}>{slots.renderSlot('fake.session' as never, {})}</main>, bindings)
const spy = vi.spyOn(console, 'error').mockImplementation(() => {})
const view = render(<Provider />)
act(() => { current.update((d) => { d.id = 's1' }) })
spy.mockRestore()
expect(view.container.querySelector('[data-shell]')).not.toBeNull()
expect(view.container.querySelector('[data-slot-error]')).not.toBeNull()
})
it('isolates a crashing entry without collapsing siblings', () => {
const core = makeFakeCore()
core.define('fake.list', { kind: 'list', scope: 'root' })
core.register('fake.list', () => { throw new Error('entry boom') }, { id: 'bad', order: 1 })
core.register('fake.list', () => <span>alive</span>, { id: 'ok', order: 2 })
const slots = scopedSlots(core, 'fake.list' as never)
const spy = vi.spyOn(console, 'error').mockImplementation(() => {})
const view = render(<>{slots.renderSlot('fake.list' as never, {})}</>)
spy.mockRestore()
expect(view.container.textContent).toBe('alive')
expect(view.container.querySelector('[data-slot-error]')).not.toBeNull()
})
})
describe('inject caching and props merge', () => {
it('root inject runs once per entry and receives the root binding ctx', () => {
const core = makeFakeCore()
core.define('fake.root', { kind: 'single', scope: 'root' })
const inject = vi.fn((b: RootBinding) => ({ tag: (b.ctx as { tag: string }).tag }))
core.register('fake.root', ({ tag }: { tag?: string }) => <b>{tag}</b>,
{ inject: inject as unknown as InjectFactory<SlotEntryDef> })
const slots = scopedSlots(core, 'fake.root' as never)
const root: RootBinding = { ctx: { tag: 'ROOT' } }
const view = render(
<RootBindingProvider value={root}>
{slots.renderSlot('fake.root' as never, {})}
</RootBindingProvider>,
)
expect(view.container.textContent).toBe('ROOT')
view.rerender(
<RootBindingProvider value={root}>
{slots.renderSlot('fake.root' as never, {})}
</RootBindingProvider>,
)
expect(inject).toHaveBeenCalledTimes(1)
})
it('root slots with inject throw without RootBindingProvider; plain entries do not need it', () => {
const core = makeFakeCore()
core.define('fake.root', { kind: 'single', scope: 'root' })
core.register('fake.root', () => <b>plain</b>)
const slots = scopedSlots(core, 'fake.root' as never)
const view = render(<>{slots.renderSlot('fake.root' as never, {})}</>)
expect(view.container.textContent).toBe('plain')
const core2 = makeFakeCore()
core2.define('fake.root', { kind: 'single', scope: 'root' })
core2.register('fake.root', () => <b>x</b>,
{ inject: (() => ({})) as unknown as InjectFactory<SlotEntryDef> })
const slots2 = scopedSlots(core2, 'fake.root' as never)
const spy = vi.spyOn(console, 'error').mockImplementation(() => {})
expect(() => render(<>{slots2.renderSlot('fake.root' as never, {})}</>))
.toThrow(/RootBindingProvider/)
spy.mockRestore()
})
it('session inject caches per (entry x binding): session switch re-invokes, switch-back reuses', () => {
const core = makeFakeCore()
core.define('fake.session', { kind: 'single', scope: 'session' })
const inject = vi.fn((b: { sessionId: string }) => ({ sid: b.sessionId }))
core.register('fake.session', ({ sid }: { sid?: string }) => <b>{sid}</b>,
{ inject: inject as unknown as InjectFactory<SlotEntryDef> })
const slots = scopedSlots(core, 'fake.session' as never)
const bindings = { s1: makeBinding('s1'), s2: makeBinding('s2') }
const { current, Provider } = sessionHarness(
() => slots.renderSlot('fake.session' as never, {}), bindings)
const view = render(<Provider />)
act(() => { current.update((d) => { d.id = 's1' }) })
expect(view.container.textContent).toBe('s1')
expect(inject).toHaveBeenCalledTimes(1)
act(() => { current.update((d) => { d.id = 's2' }) })
expect(view.container.textContent).toBe('s2')
expect(inject).toHaveBeenCalledTimes(2)
act(() => { current.update((d) => { d.id = 's1' }) }) // back: cache hit
expect(view.container.textContent).toBe('s1')
expect(inject).toHaveBeenCalledTimes(2)
})
it('session slots receive standard useSession injection and owner props win the merge', () => {
const core = makeFakeCore()
core.define('fake.session', { kind: 'single', scope: 'session' })
const seen: Record<string, unknown>[] = []
core.register('fake.session', (props: object) => {
seen.push(props as Record<string, unknown>)
return null
}, { inject: (() => ({ fromInject: 'inject', shared: 'inject' })) as unknown as InjectFactory<SlotEntryDef> })
const slots = scopedSlots(core, 'fake.session' as never)
const bindings = { s1: makeBinding('s1') }
const { current, Provider } = sessionHarness(
() => slots.renderSlot('fake.session' as never, { owner: 'owner', shared: 'owner' } as never), bindings)
render(<Provider />)
act(() => { current.update((d) => { d.id = 's1' }) })
mountRoot(h, { 'k.single': SINGLE_ROOT },
(renderSlot) => renderSlot('k.single', { owner: 'owner', shared: 'owner' }))
const props = seen.at(-1)!
expect(props.useSession).toBe(bindings.s1.session.useSelector)
expect(props.fromInject).toBe('inject')
expect(props.owner).toBe('owner')
expect(props.shared).toBe('owner') // three-source merge: owner overrides inject
})
it('session slots outside a SessionProvider fail loud', () => {
const core = makeFakeCore()
core.define('fake.session', { kind: 'single', scope: 'session' })
core.register('fake.session', () => <b>x</b>)
const slots = scopedSlots(core, 'fake.session' as never)
const spy = vi.spyOn(console, 'error').mockImplementation(() => {})
expect(() => render(<>{slots.renderSlot('fake.session' as never, {})}</>))
.toThrow(/outside SessionProvider/)
spy.mockRestore()
expect(typeof props['useSessions']).toBe('function') // kit always present
expect(props['fromInject']).toBe('inject')
expect(props['owner']).toBe('owner')
expect(props['shared']).toBe('owner') // owner overrides inject
})
})

View File

@@ -1,106 +1,143 @@
// @vitest-environment jsdom
/**
* SessionProvider behavior account (render-prop form, framework-wired):
* empty/body branching off the host's current-session source, key={sessionId}
* remount semantics, and cell delivery observed through a session slot's
* standard kit — never through the internal context objects (BindingContext
* does not leave the package).
*/
import { useEffect, useRef } from 'react'
import { describe, expect, it, vi } from 'vitest'
import { act, render } from '@testing-library/react'
import type { RootBinding } from '@deepseek-ai/dsh-client-ui-slots'
import type { StoredEntry } from '@deepseek-ai/dsh-client-ui-slots'
import {
createSessionProvider, createSnapshotStore, RootBindingProvider,
useRootBinding, useSessionBinding,
type SessionBinding, type SessionProviderDeps,
createSlotRenderer, SessionProvider,
type SessionCell, type SlotRendererHost,
} from '@deepseek-ai/dsh-client-web-react'
const makeBinding = (sessionId: string): SessionBinding => ({
sessionId,
session: { useSelector: (() => { throw new Error('unused') }) as never },
ctx: { tag: sessionId },
})
function setup(bindings: Record<string, SessionBinding>) {
const current = createSnapshotStore<{ id: string | undefined }>({ id: undefined })
const resolveBinding = vi.fn((id: string) => bindings[id])
const seen: { id: string; binding: SessionBinding; mountCount: number }[] = []
let mounts = 0
function Body({ id }: { id: string }) {
const binding = useSessionBinding()
const mountRef = useRef(0)
useEffect(() => { mounts += 1; mountRef.current = mounts }, [])
seen.push({ id, binding, mountCount: mountRef.current })
return <div data-testid="body">{id}</div>
function observable<T>(initial: T) {
let value = initial
const subs = new Set<() => void>()
return {
getSnapshot: () => value,
subscribe: (fn: () => void) => { subs.add(fn); return () => { subs.delete(fn) } },
set: (next: T) => { value = next; for (const fn of [...subs]) fn() },
}
const deps: SessionProviderDeps = {
useCurrent: () => current.useSelector((s) => s.id),
resolveBinding,
renderBody: (id) => <Body id={id} />,
}
const SessionProvider = createSessionProvider(deps)
return { current, resolveBinding, SessionProvider, seen, mountCount: () => mounts }
}
describe('createSessionProvider', () => {
it('renders empty without a current session and switches to the body on select', () => {
const { current, SessionProvider } = setup({ s1: makeBinding('s1') })
const view = render(<SessionProvider renderEmpty={() => <span>empty</span>} />)
/**
* Minimal host: SessionProvider only reads sessions.current/cell, but it must
* render inside the renderer tree (HostContext), so the harness mounts a real
* root entry whose body is the test's render-prop provider.
*/
function makeHost(bodies: { root: (rp: (key: string, owner: object) => React.ReactNode) => React.ReactNode }) {
const current = observable<string | undefined>(undefined)
const cells = new Map<string, SessionCell>()
const sessionEntries: StoredEntry[] = []
const rootEntry: StoredEntry = {
component: (props: { renderSlot: (key: string, owner: object) => React.ReactNode }) =>
<>{bodies.root(props.renderSlot)}</>,
options: {},
children: { 'k.session': { kind: 'single', scope: 'session' } },
}
const host: SlotRendererHost = {
subscribe: () => () => {},
getVersion: () => 0,
entriesOf: (key) => key === 'root' ? [rootEntry] : sessionEntries,
specOf: (key) => key === 'k.session' ? { kind: 'single', scope: 'session' } : undefined,
isLive: () => true,
storeOf: () => undefined,
sessions: {
list: observable<unknown>({ ids: [] }),
current,
cell: (id) => cells.get(id),
},
}
return {
host,
current,
addSession: (id: string) => {
const cell: SessionCell = { sessionId: id, useSession: { hookTag: id } }
cells.set(id, cell)
return cell
},
registerSession: (entry: StoredEntry) => { sessionEntries.push(entry) },
}
}
describe('SessionProvider', () => {
it('renders empty without a current session, switches to the body on select, falls back on an unresolvable id', () => {
const h = makeHost({
root: () => (
<SessionProvider empty={() => <span>empty</span>}>
{(id) => <div data-testid="body">{id}</div>}
</SessionProvider>
),
})
h.addSession('s1')
const view = render(<>{createSlotRenderer().renderRoot(h.host, {})}</>)
expect(view.container.textContent).toBe('empty')
act(() => { current.update((d) => { d.id = 's1' }) })
act(() => { h.current.set('s1') })
expect(view.container.textContent).toBe('s1')
act(() => { h.current.set('ghost') }) // listed nowhere: cell() misses
expect(view.container.textContent).toBe('empty')
})
it('renders null empty state when renderEmpty is omitted', () => {
const { SessionProvider } = setup({})
const view = render(<SessionProvider />)
it('renders null empty state when the empty prop is omitted', () => {
const h = makeHost({
root: () => <SessionProvider>{(id) => <b>{id}</b>}</SessionProvider>,
})
const view = render(<>{createSlotRenderer().renderRoot(h.host, {})}</>)
expect(view.container.textContent).toBe('')
})
it('falls back to empty when the binding does not resolve', () => {
const { current, SessionProvider } = setup({})
const view = render(<SessionProvider renderEmpty={() => <span>empty</span>} />)
act(() => { current.update((d) => { d.id = 'ghost' }) })
expect(view.container.textContent).toBe('empty')
it('remounts the body on session switch (key semantics) but not on unrelated re-renders', () => {
let mounts = 0
function Body({ id }: { id: string }) {
const mounted = useRef(false)
useEffect(() => {
/* v8 ignore next -- strict-mode double-invoke guard, not a branch under test */
if (!mounted.current) { mounted.current = true; mounts += 1 }
}, [])
return <div>{id}</div>
}
const h = makeHost({
root: () => <SessionProvider>{(id) => <Body id={id} />}</SessionProvider>,
})
h.addSession('s1')
h.addSession('s2')
const view = render(<>{createSlotRenderer().renderRoot(h.host, {})}</>)
act(() => { h.current.set('s1') })
const afterS1 = mounts
act(() => { h.current.set('s2') })
expect(mounts).toBe(afterS1 + 1)
const afterS2 = mounts
view.rerender(<>{createSlotRenderer().renderRoot(h.host, {})}</>)
expect(mounts).toBe(afterS2)
})
it('passes the resolved binding through context and remounts on session switch', () => {
const bindings = { s1: makeBinding('s1'), s2: makeBinding('s2') }
const { current, SessionProvider, seen, mountCount } = setup(bindings)
render(<SessionProvider />)
act(() => { current.update((d) => { d.id = 's1' }) })
expect(seen.at(-1)!.binding).toBe(bindings.s1)
const mountsAfterS1 = mountCount()
act(() => { current.update((d) => { d.id = 's2' }) })
expect(seen.at(-1)!.binding).toBe(bindings.s2)
// key={id} semantics: switching sessions remounts the body subtree.
expect(mountCount()).toBe(mountsAfterS1 + 1)
it('delivers the resolved cell to session slots under it (observable behavior, not context internals)', () => {
const seen: Record<string, unknown>[] = []
const h = makeHost({
root: (renderSlot) => <SessionProvider>{() => renderSlot('k.session', {})}</SessionProvider>,
})
const s1 = h.addSession('s1')
const s2 = h.addSession('s2')
h.registerSession({ component: (props: object) => { seen.push(props as Record<string, unknown>); return null }, options: {} })
render(<>{createSlotRenderer().renderRoot(h.host, {})}</>)
act(() => { h.current.set('s1') })
expect(seen.at(-1)!['useSession']).toBe(s1.useSession)
expect(seen.at(-1)!['sessionId']).toBe('s1')
act(() => { h.current.set('s2') })
expect(seen.at(-1)!['useSession']).toBe(s2.useSession)
expect(seen.at(-1)!['sessionId']).toBe('s2')
})
it('does not remount the body when unrelated renders happen on the same session', () => {
const bindings = { s1: makeBinding('s1') }
const { current, SessionProvider, mountCount } = setup(bindings)
const view = render(<SessionProvider />)
act(() => { current.update((d) => { d.id = 's1' }) })
const mounts = mountCount()
view.rerender(<SessionProvider />)
expect(mountCount()).toBe(mounts)
})
})
describe('binding contexts', () => {
it('useSessionBinding throws outside a SessionProvider subtree', () => {
it('fails loud when mounted outside the renderer tree (no host channel)', () => {
const spy = vi.spyOn(console, 'error').mockImplementation(() => {})
function Naked() { useSessionBinding(); return null }
expect(() => render(<Naked />)).toThrow(/outside SessionProvider/)
spy.mockRestore()
})
it('RootBindingProvider supplies the root binding; absence throws', () => {
const root: RootBinding = { ctx: { tag: 'root' } }
let got: RootBinding | undefined
function Probe() { got = useRootBinding(); return null }
render(<RootBindingProvider value={root}><Probe /></RootBindingProvider>)
expect(got).toBe(root)
const spy = vi.spyOn(console, 'error').mockImplementation(() => {})
expect(() => render(<Probe />)).toThrow(/RootBindingProvider/)
expect(() => render(
<SessionProvider>{(id) => <b>{id}</b>}</SessionProvider>,
)).toThrow(/outside the installed renderer tree/)
spy.mockRestore()
})
})

View File

@@ -0,0 +1,136 @@
// @vitest-environment jsdom
/**
* Stale renderSlot bindings (slot terminal design §9): a binding dies with
* its entry — a retained closure invoked after the entry's disposal throws
* StaleAuthorizationError off the ledger check, and an HMR-style reload (new
* entry, same key) mints a NEW binding rather than reviving the old one.
*/
import { describe, expect, it } from 'vitest'
import { act, render } from '@testing-library/react'
import type { ReactNode } from 'react'
import type { SlotEntryDef, SlotSpec, StoredEntry } from '@deepseek-ai/dsh-client-ui-slots'
import {
createSlotRenderer, StaleAuthorizationError,
type RenderOpts, type SlotRendererHost,
} from '@deepseek-ai/dsh-client-web-react'
type RenderSlotFn = (key: string, owner: object, opts?: RenderOpts) => ReactNode
type DeclaredSpec = SlotSpec<SlotEntryDef>
/** Ledger-shaped fake: add/dispose maintain the live set the way the runtime ledger does. */
function makeHost() {
const entries = new Map<string, StoredEntry[]>()
const versions = new Map<string, number>()
const subs = new Map<string, Set<() => void>>()
const live = new Set<StoredEntry>()
const bump = (key: string) => {
versions.set(key, (versions.get(key) ?? 0) + 1)
for (const fn of [...(subs.get(key) ?? [])]) fn()
}
const host: SlotRendererHost = {
subscribe: (key, fn) => {
const set = subs.get(key) ?? new Set()
set.add(fn)
subs.set(key, set)
return () => { set.delete(fn) }
},
getVersion: (key) => versions.get(key) ?? 0,
entriesOf: (key) => entries.get(key) ?? [],
specOf: () => ({ kind: 'single', scope: 'root' }),
isLive: (entry) => live.has(entry),
storeOf: () => undefined,
sessions: {
list: { getSnapshot: () => ({}), subscribe: () => () => {} },
current: { getSnapshot: () => undefined, subscribe: () => () => {} },
cell: () => undefined,
},
}
return {
host,
add: (key: string, entry: StoredEntry) => {
entries.set(key, [...(entries.get(key) ?? []), entry])
live.add(entry)
bump(key)
return () => {
entries.set(key, (entries.get(key) ?? []).filter((e) => e !== entry))
live.delete(entry)
bump(key)
}
},
}
}
const CHILD: DeclaredSpec = { kind: 'single', scope: 'root' }
/**
* Mount a root entry that leaks its binding to the test, then render. The
* returned dispose unmounts the view FIRST: an empty 'root' makes the live
* root outlet rethrow its boot-order failure (fail-loud, covered in the
* scoped-slots suite); the retained-closure scenario under test here is a
* dead entry whose binding outlives the tree.
*/
function mountCapturing(h: ReturnType<typeof makeHost>) {
let captured: RenderSlotFn | undefined
const entry: StoredEntry = {
component: (props: { renderSlot: RenderSlotFn }) => {
captured = props.renderSlot
return null
},
options: {},
children: { 'k.child': CHILD },
}
const disposeEntry = h.add('root', entry)
const view = render(<>{createSlotRenderer().renderRoot(h.host, {})}</>)
return {
binding: captured!,
entry,
dispose: () => {
view.unmount()
disposeEntry()
},
}
}
describe('stale authorization', () => {
it('a live binding renders; the same closure throws after its entry is disposed', () => {
const h = makeHost()
const { binding, dispose } = mountCapturing(h)
expect(binding('k.child', {})).not.toBeUndefined() // live: returns an element
act(() => { dispose() })
expect(() => binding('k.child', {})).toThrow(StaleAuthorizationError)
expect(() => binding('k.child', {})).toThrow(/disposed registration/)
})
it('stale check precedes the ownership check: a dead binding throws stale even for undeclared keys', () => {
const h = makeHost()
const { binding, dispose } = mountCapturing(h)
act(() => { dispose() })
// Were ownership checked first this would be SlotOwnershipError; the dead
// entry must fail on liveness regardless of the key asked for.
expect(() => binding('k.undeclared', {})).toThrow(StaleAuthorizationError)
})
it('HMR reload (same key, new entry) mints a fresh binding; the old one stays dead', () => {
const h = makeHost()
const first = mountCapturing(h)
act(() => { first.dispose() })
// Reload: a new entry object for the same slot key (new registration identity).
let secondBinding: RenderSlotFn | undefined
const secondEntry: StoredEntry = {
component: (props: { renderSlot: RenderSlotFn }) => {
secondBinding = props.renderSlot
return null
},
options: {},
children: { 'k.child': CHILD },
}
h.add('root', secondEntry)
render(<>{createSlotRenderer().renderRoot(h.host, {})}</>)
expect(secondBinding).toBeDefined()
expect(secondBinding).not.toBe(first.binding) // new identity, no revival
expect(secondBinding!('k.child', {})).not.toBeUndefined() // new binding is live
expect(() => first.binding('k.child', {})).toThrow(StaleAuthorizationError) // old stays dead
})
})

View File

@@ -1,5 +1,5 @@
import { afterEach, describe, expect, it, vi } from 'vitest'
import { createSnapshotStore, shallowEqual } from '@deepseek-ai/dsh-client-web-react/store'
import { createSnapshotStore, defineStore, shallowEqual } from '@deepseek-ai/dsh-client-web-react/store'
interface State {
a: { n: number }
@@ -124,6 +124,98 @@ describe('createSnapshotStore', () => {
})
})
describe('defineStore', () => {
const declare = () => defineStore({
init: () => ({ selection: null as string | null, draft: '' }),
actions: {
select: (d, target: string) => { d.selection = target },
setDraft: (d, text: string) => { d.draft = text },
clearDraft: (d) => { d.draft = '' },
},
})
it('create() yields a live instance: fresh init state, selector-visible action writes', () => {
const inst = declare().create()
expect(inst.store.getSnapshot()).toEqual({ selection: null, draft: '' })
inst.actions.setDraft('hello')
inst.actions.select('m1')
expect(inst.store.getSnapshot()).toEqual({ selection: 'm1', draft: 'hello' })
inst.actions.clearDraft()
expect(inst.store.getSnapshot().draft).toBe('')
})
it('bakes draft-stripped actions that write through update (draft mutation, not replacement)', () => {
const inst = declare().create()
const before = inst.store.getSnapshot()
inst.actions.setDraft('x')
const after = inst.store.getSnapshot()
expect(after).not.toBe(before)
expect(after.selection).toBe(before.selection) // untouched branch preserved (immer path)
})
it('creates independent instances per create() call (the handle is a spec, not a singleton)', () => {
const handle = declare()
const a = handle.create()
const b = handle.create()
a.actions.setDraft('only-a')
expect(b.store.getSnapshot().draft).toBe('')
})
it('suffixes the persist key with the scope key: per-session persistence plus clearPersisted cleanup', () => {
const backing = new Map<string, string>()
vi.stubGlobal('localStorage', {
getItem: (k: string) => backing.get(k) ?? null,
setItem: (k: string, v: string) => { backing.set(k, v) },
removeItem: (k: string) => { backing.delete(k) },
})
const handle = defineStore({
init: () => ({ draft: '' }),
persist: 'spec.chat',
actions: { setDraft: (d, text: string) => { d.draft = text } },
})
handle.create('s1').actions.setDraft('one')
handle.create('s2').actions.setDraft('two')
handle.create().actions.setDraft('root')
expect(JSON.parse(backing.get('spec.chat.s1')!)).toEqual({ draft: 'one' })
expect(JSON.parse(backing.get('spec.chat.s2')!)).toEqual({ draft: 'two' })
expect(JSON.parse(backing.get('spec.chat')!)).toEqual({ draft: 'root' })
// Rehydration honors the same suffixed key.
expect(handle.create('s1').store.getSnapshot().draft).toBe('one')
// Scope-death cleanup removes exactly the suffixed key.
handle.create('s1').clearPersisted()
expect(backing.has('spec.chat.s1')).toBe(false)
expect(backing.has('spec.chat.s2')).toBe(true)
expect(backing.has('spec.chat')).toBe(true)
})
it('clearPersisted is a no-op without a persist declaration or without storage', () => {
const inst = declare().create('s1') // no persist key declared
expect(() => { inst.clearPersisted() }).not.toThrow()
const persisting = defineStore({
init: () => ({ n: 0 }),
persist: 'spec.nostorage',
actions: { inc: (d) => { d.n += 1 } },
}).create()
// jsdom-less lane: localStorage may exist here, so simulate its absence.
vi.stubGlobal('localStorage', undefined)
expect(() => { persisting.clearPersisted() }).not.toThrow()
})
it('swallows storage failures in clearPersisted (same non-fatal contract as persistence)', () => {
vi.stubGlobal('localStorage', {
getItem: () => null,
setItem: () => {},
removeItem: () => { throw new Error('quota / private mode') },
})
const inst = defineStore({
init: () => ({ n: 0 }),
persist: 'spec.throwing',
actions: { inc: (d) => { d.n += 1 } },
}).create()
expect(() => { inst.clearPersisted() }).not.toThrow()
})
})
describe('shallowEqual', () => {
it('matches one-level-equal objects and rejects deeper drift', () => {
const leaf = { deep: 1 }