ownerProps: object
+ entryKey: string | undefined
children: ReactNode
}) {
const host = useHost()
- const version = host.getVersion(slotKey)
- // `version` keys the ledger read inside composeHocLayers; a new layer set yields new layer Components and remounts
- // the content.
- const renderLayers = useMemo(() => composeHocLayers(host, slotKey, spec), [host, slotKey, spec, version])
+ const renderLayers = hocChainFor(host, slotKey, spec, entryKey)
if (renderLayers === renderHocContent) return children
return {renderLayers(ownerProps, children)}
}
@@ -1275,7 +1368,11 @@ function renderOutletContent(
throw new SlotAssemblyError(`strict session slot '${slotKey}' rendered without a scope binding`)
}
if (spec.kind === 'hoc') {
- return {opts?.children ?? null}
+ return (
+
+ {opts?.children ?? null}
+
+ )
}
const entries = host.entriesOf(slotKey)
const slotInjected = cachedSlotInject(spec.inject)
diff --git a/packages/client/ui-renderer/tests/hoc-slots.client.spec.tsx b/packages/client/ui-renderer/tests/hoc-slots.client.spec.tsx
index c00ee22480..b8fa704e24 100644
--- a/packages/client/ui-renderer/tests/hoc-slots.client.spec.tsx
+++ b/packages/client/ui-renderer/tests/hoc-slots.client.spec.tsx
@@ -1,7 +1,7 @@
// @vitest-environment jsdom
/**
* Hoc slots over the real ui-slots SlotCore: nesting order, owner and
- * children delivery, remount semantics, crash skipping, and every scope.
+ * children delivery, remount semantics, crash containment, and every scope.
*/
import { Context } from '@deepseek-ai/cordis'
import { afterEach, describe, expect, it, vi } from 'vitest'
@@ -18,10 +18,11 @@ declare module '@deepseek-ai/dsh-client-ui-slots' {
'spec.hoc': { kind: 'hoc'; scope: 'root'; owner: { tone: string } }
'spec.hoc.maybe': { kind: 'hoc'; scope: 'session-maybe' }
'spec.hoc.session': { kind: 'hoc'; scope: 'session' }
+ 'spec.hoc.keyed': { kind: 'hoc'; scope: 'root'; owner: { tone: string } }
}
}
-type Frame = PropsRenderSlots<'spec.hoc' | 'spec.hoc.maybe' | 'spec.hoc.session'>
+type Frame = PropsRenderSlots<'spec.hoc' | 'spec.hoc.maybe' | 'spec.hoc.session' | 'spec.hoc.keyed'>
afterEach(() => {
cleanup()
@@ -87,6 +88,7 @@ function mount(core: SlotCore, body?: (renderSlot: Frame['renderSlot']) => React
'spec.hoc': { kind: 'hoc', scope: 'root' },
'spec.hoc.maybe': { kind: 'hoc', scope: 'session-maybe' },
'spec.hoc.session': { kind: 'hoc', scope: 'session' },
+ 'spec.hoc.keyed': { kind: 'hoc', scope: 'root' },
},
}, function Root(props: Frame) {
const [tone, set] = useState('calm')
@@ -136,20 +138,71 @@ describe('hoc slots', () => {
expect(view.getByTestId('content')).toBeTruthy()
})
- it('skips a crashed layer: its content still renders and the layer leaves the slot', async () => {
+ it('contains a crashed layer to its occurrence: content renders there and the layer stays for other occurrences', async () => {
const error = vi.spyOn(console, 'error').mockImplementation(() => {})
const core = new SlotCore()
- const view = mount(core)
+ const reported = vi.fn()
+ core.onEntryError(reported)
+ const view = mount(core, renderSlot => (
+ <>
+ {renderSlot('spec.hoc', { tone: 'calm' }, { children: })}
+ {renderSlot('spec.hoc', { tone: 'loud' }, { children: })}
+
+ ))
core.register({ name: 'spec.hoc', id: 'outer' }, layer('outer') as never)
- core.register({ name: 'spec.hoc', id: 'broken', order: 10 }, (() => { throw new Error('layer failed') }) as never)
+ core.register({ name: 'spec.hoc', id: 'fragile', order: 10 }, (({ tone, children }: { tone: string; children: ReactNode }) => {
+ if (tone === 'loud') throw new Error('layer failed')
+ return
+ }) as never)
await flush()
await flush()
- expect(view.container.querySelector('section[data-layer="outer"] p')?.textContent).toBe('content')
+ const loud = view.getByTestId('loud-outlet')
+ expect(loud.querySelector('section[data-layer="outer"] > p')?.textContent).toBe('loud-content')
+ expect(loud.querySelector('section[data-layer="fragile"]')).toBeNull()
+ const calm = view.getByTestId('calm-outlet')
+ expect(calm.querySelector('section[data-layer="outer"] > section[data-layer="fragile"] > p')?.textContent).toBe('calm-content')
expect(view.container.querySelector('[data-slot-error]')).toBeNull()
- expect(core.entriesOfSlot('spec.hoc').map(entry => entry.options.id)).toEqual(['outer'])
+ expect(core.entriesOfSlot('spec.hoc').map(entry => entry.options.id)).toEqual(['outer', 'fragile'])
+ expect(reported).toHaveBeenCalledWith('spec.hoc', expect.anything(), expect.objectContaining({ message: 'layer failed' }), { abdicated: false })
expect(error).toHaveBeenCalled()
})
+ it('a crashed occurrence does not retry while it stays mounted', async () => {
+ vi.spyOn(console, 'error').mockImplementation(() => {})
+ const core = new SlotCore()
+ let ownerTone = 'loud'
+ let shown = true
+ const view = mount(core, renderSlot => (shown
+ ? renderSlot('spec.hoc', { tone: ownerTone }, { children: })
+ : false))
+ const calls = vi.fn()
+ core.register({ name: 'spec.hoc', id: 'fragile' }, (({ tone, children }: { tone: string; children: ReactNode }) => {
+ calls(tone)
+ if (tone === 'loud') throw new Error('layer failed')
+ return
+ }) as never)
+ await flush()
+ expect(calls).toHaveBeenCalledWith('loud')
+ expect(view.getByTestId('retry-content')).toBeTruthy()
+ calls.mockClear()
+
+ act(() => { setTone('same-owner') })
+ expect(calls).not.toHaveBeenCalled()
+ ownerTone = 'calm'
+ act(() => { setTone('changed-owner') })
+ expect(calls).not.toHaveBeenCalled()
+ expect(view.getByTestId('retry-content')).toBeTruthy()
+ expect(view.container.querySelector('section[data-layer="fragile"]')).toBeNull()
+
+ shown = false
+ act(() => { setTone('unmounted') })
+ expect(view.queryByTestId('retry-content')).toBeNull()
+ shown = true
+ act(() => { setTone('remounted') })
+ expect(calls).toHaveBeenCalledWith('calm')
+ expect(view.container.querySelector('section[data-layer="fragile"] > p')?.textContent).toBe('retry-content')
+ })
+
it('passes content errors upward without blaming or removing any layer', async () => {
vi.spyOn(console, 'error').mockImplementation(() => {})
const core = new SlotCore()
@@ -203,3 +256,207 @@ describe('hoc slots', () => {
expect(view.container.querySelector('section[data-layer="session"] p')?.textContent).toBe('session-content')
})
})
+
+function keyedOutlet(renderSlot: Frame['renderSlot'], entryKey: string, label: string) {
+ return (
+
+ {renderSlot('spec.hoc.keyed', { tone: 'x' }, { entryKey, children: })}
+
+ )
+}
+
+describe('keyed hoc slots', () => {
+ it('applies wildcard layers to every key and exact-key layers only to their key', async () => {
+ const core = new SlotCore()
+ const view = mount(core, renderSlot => (
+ <>
+ {keyedOutlet(renderSlot, 'ts', 'ts-content')}
+ {keyedOutlet(renderSlot, 'md', 'md-content')}
+
+ ))
+ core.register({ name: 'spec.hoc.keyed', id: 'w' }, layer('w') as never)
+ core.register({ name: 'spec.hoc.keyed', id: 'ts', key: 'ts', order: 1 }, layer('ts') as never)
+ await flush()
+ const ts = view.getByTestId('ts-content-outlet')
+ expect(ts.querySelector('section[data-layer="w"] > section[data-layer="ts"] > p')?.textContent).toBe('ts-content')
+ const md = view.getByTestId('md-content-outlet')
+ expect(md.querySelector('section[data-layer="w"] > p')?.textContent).toBe('md-content')
+ expect(md.querySelector('section[data-layer="ts"]')).toBeNull()
+ })
+
+ it('omitted entryKey applies only wildcard layers', async () => {
+ const core = new SlotCore()
+ const view = mount(core, renderSlot => renderSlot('spec.hoc.keyed', { tone: 'x' }, { children: }))
+ core.register({ name: 'spec.hoc.keyed', id: 'w' }, layer('w') as never)
+ core.register({ name: 'spec.hoc.keyed', id: 'ts', key: 'ts', order: 1 }, layer('ts') as never)
+ await flush()
+ expect(view.container.querySelector('section[data-layer="w"] > p')?.textContent).toBe('wild-content')
+ expect(view.container.querySelector('section[data-layer="ts"]')).toBeNull()
+ })
+
+ it('an exact-key layer replaces the wildcard layer with the same id', async () => {
+ const core = new SlotCore()
+ const view = mount(core, renderSlot => (
+ <>
+ {keyedOutlet(renderSlot, 'ts', 'ts-content')}
+ {keyedOutlet(renderSlot, 'md', 'md-content')}
+
+ ))
+ core.register({ name: 'spec.hoc.keyed', id: 'x' }, layer('wild') as never)
+ core.register({ name: 'spec.hoc.keyed', id: 'x', key: 'ts' }, layer('exact') as never)
+ await flush()
+ const ts = view.getByTestId('ts-content-outlet')
+ expect(ts.querySelector('section[data-layer="exact"] > p')?.textContent).toBe('ts-content')
+ expect(ts.querySelector('section[data-layer="wild"]')).toBeNull()
+ const md = view.getByTestId('md-content-outlet')
+ expect(md.querySelector('section[data-layer="wild"] > p')?.textContent).toBe('md-content')
+ expect(md.querySelector('section[data-layer="exact"]')).toBeNull()
+ })
+
+ it('a layer may skip its children, so the content never mounts', async () => {
+ const core = new SlotCore()
+ mounts.mockClear()
+ let outletShown = false
+ const view = mount(core, renderSlot => (outletShown ? keyedOutlet(renderSlot, 'ts', 'skipped-content') : null))
+ core.register({ name: 'spec.hoc.keyed', id: 'replace', key: 'ts' }, (() => ) as never)
+ outletShown = true
+ act(() => { setTone('loud') })
+ await flush()
+ expect(view.getByTestId('replaced')).toBeTruthy()
+ expect(view.queryByTestId('skipped-content')).toBeNull()
+ expect(mounts).not.toHaveBeenCalledWith('skipped-content')
+ })
+
+ it('a crashed keyed layer falls back to its children', async () => {
+ vi.spyOn(console, 'error').mockImplementation(() => {})
+ const core = new SlotCore()
+ const view = mount(core, renderSlot => (
+ <>
+ {keyedOutlet(renderSlot, 'ts', 'ts-content')}
+
+ {renderSlot('spec.hoc.keyed', { tone: 'calm' }, { entryKey: 'ts', children: })}
+
+
+ ))
+ core.register({ name: 'spec.hoc.keyed', id: 'fragile', key: 'ts' }, (({ tone, children }: { tone: string; children: ReactNode }) => {
+ if (tone === 'x') throw new Error('layer failed')
+ return
+ }) as never)
+ await flush()
+ await flush()
+ expect(view.getByTestId('ts-content').textContent).toBe('ts-content')
+ expect(view.getByTestId('ts-content-outlet').querySelector('section[data-layer="fragile"]')).toBeNull()
+ expect(view.getByTestId('calm-outlet').querySelector('section[data-layer="fragile"] > p')?.textContent).toBe('calm-content')
+ expect(core.entriesOfSlot('spec.hoc.keyed').map(entry => [entry.options.key, entry.options.id])).toEqual([['ts', 'fragile']])
+ })
+
+ it('interleaves wildcard and exact-key layers by order', async () => {
+ const core = new SlotCore()
+ const view = mount(core, renderSlot => (
+ <>
+ {keyedOutlet(renderSlot, 'ts', 'ts-content')}
+ {keyedOutlet(renderSlot, 'md', 'md-content')}
+
+ ))
+ core.register({ name: 'spec.hoc.keyed', id: 'w2', order: 2 }, layer('w2') as never)
+ core.register({ name: 'spec.hoc.keyed', id: 'e1', key: 'ts', order: 1 }, layer('e1') as never)
+ core.register({ name: 'spec.hoc.keyed', id: 'w0', order: 0 }, layer('w0') as never)
+ await flush()
+ const ts = view.getByTestId('ts-content-outlet')
+ expect(ts.querySelector('section[data-layer="w0"] > section[data-layer="e1"] > section[data-layer="w2"] > p')?.textContent)
+ .toBe('ts-content')
+ const md = view.getByTestId('md-content-outlet')
+ expect(md.querySelector('section[data-layer="w0"] > section[data-layer="w2"] > p')?.textContent).toBe('md-content')
+ expect(md.querySelector('section[data-layer="e1"]')).toBeNull()
+ })
+
+ it('a lower-priority registration at the same key and id shadows the layer until disposed', async () => {
+ const core = new SlotCore()
+ const view = mount(core, renderSlot => keyedOutlet(renderSlot, 'ts', 'ts-content'))
+ core.register({ name: 'spec.hoc.keyed', id: 'w0', order: 0 }, layer('w0') as never)
+ core.register({ name: 'spec.hoc.keyed', id: 'e1', key: 'ts', order: 1 }, layer('e1') as never)
+ await flush()
+ const dispose = core.register({ name: 'spec.hoc.keyed', id: 'e1', key: 'ts', order: 1, priority: -1 }, layer('shadow') as never)
+ await flush()
+ const ts = view.getByTestId('ts-content-outlet')
+ expect(ts.querySelector('section[data-layer="w0"] > section[data-layer="shadow"] > p')?.textContent).toBe('ts-content')
+ expect(ts.querySelector('section[data-layer="e1"]')).toBeNull()
+ dispose()
+ await flush()
+ expect(ts.querySelector('section[data-layer="w0"] > section[data-layer="e1"] > p')?.textContent).toBe('ts-content')
+ expect(ts.querySelector('section[data-layer="shadow"]')).toBeNull()
+ })
+
+ it('an outer wildcard layer still wraps an exact-key layer that skips its children', async () => {
+ const core = new SlotCore()
+ const view = mount(core, renderSlot => keyedOutlet(renderSlot, 'ts', 'ts-content'))
+ mounts.mockClear()
+ core.register({ name: 'spec.hoc.keyed', id: 'w0', order: 0 }, layer('w0') as never)
+ core.register({ name: 'spec.hoc.keyed', id: 'replace', key: 'ts', order: 1 }, (() => ) as never)
+ core.register({ name: 'spec.hoc.keyed', id: 'w2', order: 2 }, layer('w2') as never)
+ await flush()
+ const ts = view.getByTestId('ts-content-outlet')
+ expect(ts.querySelector('section[data-layer="w0"] > i[data-testid="replaced"]')).not.toBeNull()
+ expect(ts.querySelector('section[data-layer="w2"]')).toBeNull()
+ expect(view.queryByTestId('ts-content')).toBeNull()
+ expect(mounts).not.toHaveBeenCalledWith('ts-content')
+ })
+
+ it('registering a layer for another key keeps this key\'s content mounted', async () => {
+ const core = new SlotCore()
+ mounts.mockClear()
+ const view = mount(core, renderSlot => keyedOutlet(renderSlot, 'ts', 'ts-content'))
+ core.register({ name: 'spec.hoc.keyed', id: 'w' }, layer('w') as never)
+ await flush()
+ const before = mounts.mock.calls.length
+ act(() => { core.register({ name: 'spec.hoc.keyed', id: 'md', key: 'md' }, layer('md') as never) })
+ await flush()
+ expect(mounts).toHaveBeenCalledTimes(before)
+ act(() => { core.register({ name: 'spec.hoc.keyed', id: 'ts2', key: 'ts' }, layer('ts2') as never) })
+ await flush()
+ expect(mounts).toHaveBeenCalledTimes(before + 1)
+ expect(view.container.querySelector('section[data-layer="ts2"] > p')?.textContent).toBe('ts-content')
+ })
+
+ it('keeps every outlet of a key mounted when another key registers', async () => {
+ const core = new SlotCore()
+ mounts.mockClear()
+ const view = mount(core, renderSlot => (
+ <>
+ {keyedOutlet(renderSlot, 'ts', 'first-content')}
+ {keyedOutlet(renderSlot, 'ts', 'second-content')}
+
+ ))
+ core.register({ name: 'spec.hoc.keyed', id: 'w' }, layer('w') as never)
+ await flush()
+ const before = mounts.mock.calls.length
+ act(() => { core.register({ name: 'spec.hoc.keyed', id: 'md', key: 'md' }, layer('md') as never) })
+ await flush()
+ expect(mounts).toHaveBeenCalledTimes(before)
+ expect(view.getByTestId('first-content-outlet').querySelector('section[data-layer="w"] > p')?.textContent).toBe('first-content')
+ expect(view.getByTestId('second-content-outlet').querySelector('section[data-layer="w"] > p')?.textContent).toBe('second-content')
+ })
+
+ it('recompiles a key\'s chain for a redeclared slot', async () => {
+ const core = new SlotCore()
+ const declare = () => core.register({
+ name: 'root',
+ children: { 'spec.hoc.keyed': { kind: 'hoc', scope: 'root' } },
+ }, function Root(props: Frame) {
+ return <>{keyedOutlet(props.renderSlot, 'ts', 'ts-content')}
+ } as never)
+ const undeclare = declare()
+ const view = render(<>{createSlotRenderer().renderRoot(hostOver(core), {})})
+ core.register({ name: 'spec.hoc.keyed', id: 'first', key: 'ts' }, layer('first') as never)
+ await flush()
+ expect(view.container.querySelector('section[data-layer="first"] > p')?.textContent).toBe('ts-content')
+ act(() => {
+ undeclare()
+ declare()
+ core.register({ name: 'spec.hoc.keyed', id: 'second', key: 'ts' }, layer('second') as never)
+ })
+ await flush()
+ expect(view.container.querySelector('section[data-layer="second"] > p')?.textContent).toBe('ts-content')
+ expect(view.container.querySelector('section[data-layer="first"]')).toBeNull()
+ })
+})
diff --git a/packages/client/ui-slots/README.i18n.yaml b/packages/client/ui-slots/README.i18n.yaml
index c305f377d5..30e91cb399 100644
--- a/packages/client/ui-slots/README.i18n.yaml
+++ b/packages/client/ui-slots/README.i18n.yaml
@@ -15,8 +15,8 @@
en: d152484eb41ac6b4
zh: 09388d293f9be9cb
/deepseek-ai-dsh-client-ui-slots/use-this-package:
- en: eb72211e6b97afbc
- zh: d959b329c2eee0c6
+ en: 293a68931770fd5e
+ zh: 5f73b171f37bf08f
/deepseek-ai-dsh-client-ui-slots/use-this-package/reusable-component-factories:
en: 71cbe7aa26f3ff80
zh: 0e35265d4d95cc36
diff --git a/packages/client/ui-slots/README.md b/packages/client/ui-slots/README.md
index e64f58be6c..376c351788 100644
--- a/packages/client/ui-slots/README.md
+++ b/packages/client/ui-slots/README.md
@@ -25,7 +25,7 @@ English | [中文](README.zh.md)
## Use this package
-Compose UI through this package whenever you write a client plugin: register a component into a slot your parent declared, or declare child slots your component renders. The five kinds cover the composition shapes — `single` (one occupant), `list` (ordered entries), `keyed` (dispatch by a key), `chain` (entries elect themselves), and `hoc` (entries nest around the owner's `children`).
+Compose UI through this package whenever you write a client plugin: register a component into a slot your parent declared, or declare child slots your component renders. The five kinds cover the composition shapes — `single` (one occupant), `list` (ordered entries), `keyed` (dispatch by a key), `chain` (entries elect themselves), and `hoc` (layers nest around the owner's `children`, each rendering it at most once; an optional `key` limits a layer to the owner's matching `entryKey`).
### Reusable Component Factories
diff --git a/packages/client/ui-slots/README.zh.md b/packages/client/ui-slots/README.zh.md
index ee59e97605..12a708b447 100644
--- a/packages/client/ui-slots/README.zh.md
+++ b/packages/client/ui-slots/README.zh.md
@@ -25,7 +25,7 @@ kind: "package-library"
## 使用本包
-编写客户端插件时都通过本包组合 UI：把组件注册进父级已声明的 slot，或声明组件将要渲染的子 slot。五种 kind 覆盖组合形态——`single`（单个占位者）、`list`（有序条目）、`keyed`（按键分派）、`chain`（条目自行提名）与 `hoc`（条目层层包裹 owner 的 `children`）。
+编写客户端插件时都通过本包组合 UI：把组件注册进父级已声明的 slot，或声明组件将要渲染的子 slot。五种 kind 覆盖组合形态——`single`（单个占位者）、`list`（有序条目）、`keyed`（按键分派）、`chain`（条目自行提名）与 `hoc`（各层包裹 owner 的 `children`，每层至多渲染它一次；可选的 `key` 让该层只作用于 owner 传入的相同 `entryKey`）。
### 可复用 Component Factory
diff --git a/packages/client/ui-slots/src/index.ts b/packages/client/ui-slots/src/index.ts
index 947f507dd5..a6f829e884 100644
--- a/packages/client/ui-slots/src/index.ts
+++ b/packages/client/ui-slots/src/index.ts
@@ -288,12 +288,18 @@ export interface ChainRenderOpts {
/**
* renderSlot options for a hoc slot. `children` is the owner's content; every
- * live entry wraps it, and the slot renders it unchanged when no entry is live.
- * Omitted content renders the layers around nothing.
+ * live layer for the dispatch wraps it, and the slot renders it unchanged when
+ * no layer applies. Omitted content renders the layers around nothing.
*/
-export interface HocRenderOpts {
- /** Innermost content wrapped by the slot's entries. */
+export interface HocRenderOpts {
+ /** Innermost content wrapped by the slot's layers. */
children?: ReactNode
+ /**
+ * Dispatch key: layers registered with exactly this `key` join the wildcard
+ * layers (registered without `key`); within one `id` the exact-key layer
+ * replaces the wildcard one. Omitted, only wildcard layers apply.
+ */
+ entryKey?: EntryKey
}
/**
@@ -331,7 +337,7 @@ type OrdinaryKeysOf = Exclude =
([HocKeysOf] extends [never] ? object : {
- >(key: K, owner: OwnerOf, opts?: HocRenderOpts): ReactNode
+ >(key: K, owner: OwnerOf, opts?: HocRenderOpts>): ReactNode
}) &
([Exclude, HocKeysOf>] extends [never] ? object : {
<
@@ -365,7 +371,8 @@ export type MatchedShare =
/**
* Hoc children share: a hoc-slot component receives the next inner layer, or
* the owner's content at the innermost layer, as the framework-injected
- * `children` prop and renders it exactly once.
+ * `children` prop and renders it at most once; a layer that omits it replaces
+ * everything inside it.
*/
export type HocShare =
E['kind'] extends 'hoc' ? { children: ReactNode } : object
@@ -789,7 +796,7 @@ export type SlotLabel = string | (() => string)
/**
* Kind shape fields carried in register options (keyed dispatch key; list
- * id/order/label; hoc id/order; chain select/priority; for every other kind
+ * id/order/label; hoc id/key/order; chain select/priority; for every other kind
* priority is the cell shadowing rank, and hoc nesting follows order).
*/
export type KindOptions<
@@ -817,9 +824,17 @@ export type KindOptions<
}
: SlotMap[K]['kind'] extends 'hoc' ? {
id: string
+ /**
+ * Dispatch key this layer serves; omitted, the layer serves every
+ * dispatch (wildcard). Within one `id`, an exact-key layer replaces
+ * the wildcard layer for that key.
+ */
+ key?: EntryKey
/** Nesting position: ascending, default 0; the lowest order is the outermost layer. */
order?: number
- /** Cell shadowing rank (ascending, default 0, lowest renders; same id + same priority throws — see {@link SlotCore.register}). */
+ /**
+ * Cell shadowing rank (ascending, default 0, lowest renders; same key + id + priority throws — see {@link SlotCore.register}).
+ */
priority?: number
}
: {
@@ -1006,6 +1021,16 @@ export interface LiveFactoryNode {
/** One root in the live Slot/Factory composition topology. */
export type LiveCompositionNode = LiveSlotNode | LiveFactoryNode
+/**
+ * A hoc layer's shadowing cell: its dispatch key and id, encoded so no key/id
+ * pair collides with another; a wildcard layer's absent key encodes as `null`.
+ * @param entry - one hoc registration.
+ * @returns the cell identity.
+ */
+function hocCell(entry: StoredEntry): string {
+ return JSON.stringify([entry.options.key, entry.options.id])
+}
+
/**
* Pure slot registry (no cordis; event emission and the renderer installation contract
* live in the runtime Service wrapper).
@@ -1170,7 +1195,7 @@ export class SlotCore {
* throws (the selector is the entry's routing seat, see {@link ChainSelect}).
*
* Shadowing (single/keyed/list/hoc): entries sharing one cell (single — the
- * slot itself; keyed — same `key`; list and hoc — same `id`) coexist at distinct
+ * slot itself; keyed — same `key`; list — same id; hoc — same key (or wildcard) and id) coexist at distinct
* priorities, sorted ascending with ties keeping registration order; the
* cell's lowest live entry renders ({@link SlotCore.entriesOfSlot}). A
* second registration at an occupied cell's exact priority (default 0)
@@ -1264,12 +1289,21 @@ export class SlotCore {
}
break
}
- case 'list':
- case 'hoc': {
- if (options.id === undefined) throw new Error(`${spec.kind} slot "${options.name}" requires options.id`)
+ case 'list': {
+ if (options.id === undefined) throw new Error(`list slot "${options.name}" requires options.id`)
const occupant = rec.entries.find(e => e.options.id === options.id && (e.options.priority ?? 0) === priority)
if (occupant) {
- throw new Error(`${spec.kind} slot "${options.name}" already has an entry with id "${options.id}" ${occupantHint(occupant)}`)
+ throw new Error(`list slot "${options.name}" already has an entry with id "${options.id}" ${occupantHint(occupant)}`)
+ }
+ break
+ }
+ case 'hoc': {
+ if (options.id === undefined) throw new Error(`hoc slot "${options.name}" requires options.id`)
+ const occupant = rec.entries.find(e => e.options.id === options.id && e.options.key === options.key
+ && (e.options.priority ?? 0) === priority)
+ if (occupant) {
+ const cell = options.key === undefined ? `id "${options.id}"` : `id "${options.id}" for key "${options.key}"`
+ throw new Error(`hoc slot "${options.name}" already has an entry with ${cell} ${occupantHint(occupant)}`)
}
break
}
@@ -1380,7 +1414,7 @@ export class SlotCore {
/**
* Project a key's entries to its shadowing winners: the first live
* (non-abdicated) entry of each cell in priority order — single: the slot
- * is one cell; keyed: one cell per `key`; list and hoc: one cell per `id`
+ * is one cell; keyed: one cell per `key`; list: one cell per id; hoc: one cell per (key or wildcard, id)
* (winners keep ledger sequence; renderers still refine list display and hoc
* nesting by `order`).
* Chain keys return the raw entries unchanged: election consumes every
@@ -1400,7 +1434,10 @@ export class SlotCore {
for (const entry of rec.entries) {
if (this.abdicated.has(entry)) continue
// Single-kind entries all share the one undefined cell.
- const cell = kind === 'keyed' ? entry.options.key : kind === 'list' || kind === 'hoc' ? entry.options.id : undefined
+ const cell = kind === 'keyed' ? entry.options.key
+ : kind === 'list' ? entry.options.id
+ : kind === 'hoc' ? hocCell(entry)
+ : undefined
if (seenCells.has(cell)) continue
seenCells.add(cell)
heads.push(entry)
@@ -1566,11 +1603,12 @@ export class SlotCore {
/**
* Renderer crash report from an entry boundary. Always notifies
* {@link SlotCore.onEntryError} listeners; with `info.abdicate` set (the
- * shadowing kinds — single/keyed/list/hoc) it first retires the entry from its
+ * shadowing kinds — single/keyed/list) it first retires the entry from its
* cell, one-shot: the record's version bumps through the ordinary mutation
* channel so outlets re-project onto the cell's next survivor, and a
- * repeat abdicating report no-ops entirely. Chain crashes report with
- * `abdicate: false` — election alternatives resolve at select time, so the
+ * repeat abdicating report no-ops entirely. Chain and hoc crashes report
+ * with `abdicate: false` — chain alternatives resolve at select time, and a
+ * hoc layer's failure stays with the occurrence that rendered it — so the
* entry keeps its cell and only the notification fires. The registration
* itself stays on the ledger either way — raw {@link SlotCore.entries}
* still lists the entry and its disposer keeps working.
diff --git a/packages/client/ui-slots/src/renderer.ts b/packages/client/ui-slots/src/renderer.ts
index e6ed27a9ef..caae9de6a9 100644
--- a/packages/client/ui-slots/src/renderer.ts
+++ b/packages/client/ui-slots/src/renderer.ts
@@ -163,9 +163,9 @@ export interface SlotRendererHost {
*/
entriesOfSlot(key: string): readonly StoredEntry[]
/**
- * Report an entry boundary crash. With `info.abdicate` (shadowing kinds)
- * the entry retires from its cell, one-shot, so the next survivor renders;
- * chain crashes report without abdicating. The registration stays on the
+ * Report an entry boundary crash. With `info.abdicate` (single, keyed, and
+ * list) the entry retires from its cell, one-shot, so the next survivor
+ * renders; chain and hoc crashes report without abdicating. The registration stays on the
* ledger either way.
* @param key - slot key the entry rendered under.
* @param entry - the crashed entry.
diff --git a/packages/client/ui-slots/tests/core.client.spec.ts b/packages/client/ui-slots/tests/core.client.spec.ts
index 604b6f3804..6eca0434dd 100644
--- a/packages/client/ui-slots/tests/core.client.spec.ts
+++ b/packages/client/ui-slots/tests/core.client.spec.ts
@@ -12,6 +12,7 @@ declare module '@deepseek-ai/dsh-client-ui-slots' {
'test.keyed': { kind: 'keyed'; scope: 'session' }
'test.chain': { kind: 'chain'; scope: 'session'; owner: { tags: string[] } }
'test.hoc': { kind: 'hoc'; scope: 'root' }
+ 'test.hoc.keyed': { kind: 'hoc'; scope: 'root' }
'test.grandchild': { kind: 'single'; scope: 'root' }
}
}
@@ -38,6 +39,7 @@ function mountFrame(core: SlotCore) {
'test.keyed': { kind: 'keyed', scope: 'session' },
'test.chain': { kind: 'chain', scope: 'session' },
'test.hoc': { kind: 'hoc', scope: 'root' },
+ 'test.hoc.keyed': { kind: 'hoc', scope: 'root' },
},
// Type-level renderSlot presence is proven by the type-chain spec; erasing
// here keeps runtime fixtures terse.
@@ -158,6 +160,19 @@ describe('kind semantics', () => {
expect(() => core.register({ name: 'test.keyed', key: 'b' }, Comp)).not.toThrow()
})
+ it('hoc: a cell is key plus id; same cell and priority throws; wildcard and keyed layers coexist', () => {
+ const core = new SlotCore()
+ mountFrame(core)
+ core.register({ name: 'test.hoc.keyed', id: 'a' }, Comp)
+ core.register({ name: 'test.hoc.keyed', id: 'a', key: 'ts' }, Comp)
+ core.register({ name: 'test.hoc.keyed', id: 'a', key: 'md' }, Comp)
+ expect(() => core.register({ name: 'test.hoc.keyed', id: 'a' }, Comp)).toThrow('with id "a"')
+ expect(() => core.register({ name: 'test.hoc.keyed', id: 'a', key: 'ts' }, Comp)).toThrow('id "a" for key "ts"')
+ expect(() => core.register({ name: 'test.hoc.keyed', id: 'a', key: 'ts', priority: -1 }, Comp)).not.toThrow()
+ expect(core.entriesOfSlot('test.hoc.keyed').map(e => [e.options.key, e.options.id, e.options.priority]))
+ .toEqual([['ts', 'a', -1], [undefined, 'a', undefined], ['md', 'a', undefined]])
+ })
+
it('list: duplicate id throws, missing id throws, entries sort by order stably', () => {
const core = new SlotCore()
mountFrame(core)
@@ -408,7 +423,7 @@ describe('subscription API', () => {
const off = core.onMutate(key => keys.push(key))
mountFrame(core)
// Contribution first, then each declared child key.
- expect(keys).toEqual(['root', 'test.single', 'test.session', 'test.list', 'test.keyed', 'test.chain', 'test.hoc'])
+ expect(keys).toEqual(['root', 'test.single', 'test.session', 'test.list', 'test.keyed', 'test.chain', 'test.hoc', 'test.hoc.keyed'])
keys.length = 0
core.register({ name: 'test.list', id: 'a' }, Comp)
expect(keys).toEqual(['test.list'])
diff --git a/packages/extensions/cordis-client-runner/src/client/slot-catalog.ts b/packages/extensions/cordis-client-runner/src/client/slot-catalog.ts
index 0dfc293fa9..6796e589a2 100644
--- a/packages/extensions/cordis-client-runner/src/client/slot-catalog.ts
+++ b/packages/extensions/cordis-client-runner/src/client/slot-catalog.ts
@@ -58,7 +58,8 @@ export interface ClientSlotEntry {
occupants: readonly string[]
/**
* `shadows-shipped-ui` when registering here replaces shipped UI; `wraps-owner-content` when your
- * component wraps the owner content and must render `children`; `none` when additive.
+ * component wraps the owner content and renders `children` at most once, omitting it to replace
+ * that content; `none` when additive.
*/
replaceRisk: string
/** A minimal browser half that registers into this slot. */
@@ -277,7 +278,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
],
replaceRisk: 'none',
example: 'return {\n inject: [\'slots\'],\n apply(ctx) {\n ctx.slots.inject(\'conversation.chat.assistant-actions\', () => ctx.slots.register(\n { name: \'conversation.chat.assistant-actions\', id: \'my-entry\', order: 100, label: \'My entry\' },\n () => React.createElement(\'div\', null, \'hello\'),\n ))\n },\n}',
- source: 'packages/client/ui-chat/src/client/contract/slots.ts:493',
+ source: 'packages/client/ui-chat/src/client/contract/slots.ts:495',
},
{
key: 'conversation.chat.commandview',
@@ -331,7 +332,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
],
replaceRisk: 'shadows-shipped-ui',
example: 'return {\n inject: [\'slots\'],\n apply(ctx) {\n ctx.slots.inject(\'conversation.chat.commandview\', () => ctx.slots.register(\n { name: \'conversation.chat.commandview\', key: \'\' },\n () => React.createElement(\'div\', null, \'hello\'),\n ))\n },\n}',
- source: 'packages/client/ui-chat/src/client/contract/slots.ts:475',
+ source: 'packages/client/ui-chat/src/client/contract/slots.ts:477',
},
{
key: 'conversation.chat.flow',
@@ -378,7 +379,73 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
],
replaceRisk: 'shadows-shipped-ui',
example: 'return {\n inject: [\'slots\'],\n apply(ctx) {\n ctx.slots.inject(\'conversation.chat.flow\', () => ctx.slots.register(\n { name: \'conversation.chat.flow\' },\n () => React.createElement(\'div\', null, \'hello\'),\n ))\n },\n}',
- source: 'packages/client/ui-chat/src/client/contract/slots.ts:431',
+ source: 'packages/client/ui-chat/src/client/contract/slots.ts:433',
+ },
+ {
+ key: 'conversation.chat.markdown.fence',
+ kind: 'hoc',
+ scope: 'session',
+ summary: 'Language-keyed layers around one Markdown fence in the Chat flow; the content is the plain code block.',
+ doc: 'Language-keyed layers around one Markdown fence in the Chat flow; the content is the plain code block.',
+ registerOptions: [
+ {
+ name: 'id',
+ requirement: 'required',
+ type: 'string',
+ doc: 'Your layer key. A fresh id adds a layer; reusing a shipped id replaces that layer. Your component may omit `children`, which replaces everything inside the layer.',
+ },
+ {
+ name: 'key',
+ requirement: 'optional',
+ type: 'string',
+ doc: 'Dispatch key this layer serves; omitted, it serves every dispatch. Within one id, an exact-key layer replaces the wildcard layer for that key.',
+ },
+ {
+ name: 'order',
+ requirement: 'optional',
+ type: 'number',
+ doc: 'Nesting position, ascending (default 0); the lowest order is the outermost layer. Render the `children` prop at most once.',
+ },
+ ],
+ ownerProps: [
+ '/** One Markdown code fence whose language is final, as {@link MarkdownDelegate.renderCode} receives it. */\nexport interface MarkdownDelegateFenceInfo {\n /**\n * The info string\'s language word, cut at its first character outside\n * letters, digits, `_`, and `-`, then lowercased (`c++` yields `c`).\n */\n readonly lang: string\n /** The fence body without its closing newline. */\n readonly code: string\n /** The surrounding document is still streaming, so `code` may still change. */\n readonly streaming: boolean\n /** The info string after the language word, as the author wrote it; absent when the fence names only a language. */\n readonly meta?: string | undefined\n}',
+ ],
+ ownerPropsReferences: [
+ 'MarkdownDelegate',
+ ],
+ standardProps: [
+ 'useRemoteAccess: (action: RemoteEndpoint) => boolean',
+ 'useResource: UseResource',
+ 'useContextMenu: UseContextMenu',
+ 'useWorkspaces: SnapshotSelectorHook',
+ 'usePanelInfo: UsePanelInfo',
+ 'useSessions: UseSessions',
+ 'useSessionStatus: UseSessionStatus',
+ 'useSessionRetainInfo: UseSessionRetainInfo',
+ 'useSessionAccess: (sessionId: SessionId, action: RemoteEndpoint) => boolean',
+ 'useWorkspaceAccess: (workspaceId: WorkspaceId, action: RemoteEndpoint) => boolean',
+ 'useChat: UseChat',
+ 'useConversation: UseConversation',
+ 'useInput: SnapshotSelectorHook',
+ 'inputActions: InputActions',
+ 'useSession: SessionSnapshotSelector',
+ 'sessionId: SessionId',
+ 'useProjection: UseProjection',
+ 'useAccess: (action: RemoteEndpoint) => boolean',
+ 'useTrajectory: UseTrajectory',
+ ],
+ keyDomain: 'open: any entryKey the owner dispatches; a layer without key serves every dispatch, already taken: diff, math, patch',
+ hookContext: '',
+ slotInject: '',
+ declaredBy: 'an entry in \'conversation.view\' (client-ui-chat), so it exists while that entry is mounted',
+ occupants: [
+ 'client-ui-chat MathFenceLayer id \'@deepseek-ai/dsh-client-ui-chat/fence/math\' key \'math\'',
+ 'client-ui-chat DiffFenceLayer id \'@deepseek-ai/dsh-client-ui-chat/fence/diff\' key \'diff\'',
+ 'client-ui-chat DiffFenceLayer id \'@deepseek-ai/dsh-client-ui-chat/fence/diff\' key \'patch\'',
+ ],
+ replaceRisk: 'wraps-owner-content',
+ example: 'return {\n inject: [\'slots\'],\n apply(ctx) {\n ctx.slots.inject(\'conversation.chat.markdown.fence\', () => ctx.slots.register(\n { name: \'conversation.chat.markdown.fence\', id: \'my-layer\', order: 100 },\n ({ children }) => React.createElement(\'div\', null, children),\n ))\n },\n}',
+ source: 'packages/client/ui-chat/src/client/contract/slots.ts:430',
},
{
key: 'conversation.chat.message.images',
@@ -425,7 +492,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
],
replaceRisk: 'shadows-shipped-ui',
example: 'return {\n inject: [\'slots\'],\n apply(ctx) {\n ctx.slots.inject(\'conversation.chat.message.images\', () => ctx.slots.register(\n { name: \'conversation.chat.message.images\' },\n () => React.createElement(\'div\', null, \'hello\'),\n ))\n },\n}',
- source: 'packages/client/ui-chat/src/client/contract/slots.ts:467',
+ source: 'packages/client/ui-chat/src/client/contract/slots.ts:469',
},
{
key: 'conversation.chat.node',
@@ -497,7 +564,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
],
replaceRisk: 'shadows-shipped-ui',
example: 'return {\n inject: [\'slots\'],\n apply(ctx) {\n ctx.slots.inject(\'conversation.chat.node\', () => ctx.slots.register(\n { name: \'conversation.chat.node\', key: \'\' },\n () => React.createElement(\'div\', null, \'hello\'),\n ))\n },\n}',
- source: 'packages/client/ui-chat/src/client/contract/slots.ts:443',
+ source: 'packages/client/ui-chat/src/client/contract/slots.ts:445',
},
{
key: 'conversation.chat.reasoning.body',
@@ -541,7 +608,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
],
replaceRisk: 'shadows-shipped-ui',
example: 'return {\n inject: [\'slots\'],\n apply(ctx) {\n ctx.slots.inject(\'conversation.chat.reasoning.body\', () => ctx.slots.register(\n { name: \'conversation.chat.reasoning.body\' },\n () => React.createElement(\'div\', null, \'hello\'),\n ))\n },\n}',
- source: 'packages/client/ui-chat/src/client/contract/slots.ts:481',
+ source: 'packages/client/ui-chat/src/client/contract/slots.ts:483',
},
{
key: 'conversation.chat.text-interaction',
@@ -660,7 +727,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
],
replaceRisk: 'none',
example: 'return {\n inject: [\'slots\'],\n apply(ctx) {\n ctx.slots.inject(\'conversation.chat.turnTail\', () => ctx.slots.register(\n { name: \'conversation.chat.turnTail\', id: \'my-entry\', order: 100, label: \'My entry\' },\n () => React.createElement(\'div\', null, \'hello\'),\n ))\n },\n}',
- source: 'packages/client/ui-chat/src/client/contract/slots.ts:487',
+ source: 'packages/client/ui-chat/src/client/contract/slots.ts:489',
},
{
key: 'conversation.chat.user.before',
@@ -710,7 +777,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
],
replaceRisk: 'none',
example: 'return {\n inject: [\'slots\'],\n apply(ctx) {\n ctx.slots.inject(\'conversation.chat.user.before\', () => ctx.slots.register(\n { name: \'conversation.chat.user.before\', select: owner => null },\n () => React.createElement(\'div\', null, \'hello\'),\n ))\n },\n}',
- source: 'packages/client/ui-chat/src/client/contract/slots.ts:457',
+ source: 'packages/client/ui-chat/src/client/contract/slots.ts:459',
},
{
key: 'conversation.chat.user.images',
@@ -757,7 +824,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
],
replaceRisk: 'shadows-shipped-ui',
example: 'return {\n inject: [\'slots\'],\n apply(ctx) {\n ctx.slots.inject(\'conversation.chat.user.images\', () => ctx.slots.register(\n { name: \'conversation.chat.user.images\' },\n () => React.createElement(\'div\', null, \'hello\'),\n ))\n },\n}',
- source: 'packages/client/ui-chat/src/client/contract/slots.ts:469',
+ source: 'packages/client/ui-chat/src/client/contract/slots.ts:471',
},
{
key: 'conversation.composer',
@@ -1075,13 +1142,19 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
name: 'id',
requirement: 'required',
type: 'string',
- doc: 'Your layer key. A fresh id adds a layer; reusing a shipped id replaces that layer. Your component must render its `children` prop: a layer that omits it hides the owner content, such as the whole conversation and its composer.',
+ doc: 'Your layer key. A fresh id adds a layer; reusing a shipped id replaces that layer. Your component may omit `children`, which replaces everything inside the layer.',
+ },
+ {
+ name: 'key',
+ requirement: 'optional',
+ type: 'string',
+ doc: 'Dispatch key this layer serves; omitted, it serves every dispatch. Within one id, an exact-key layer replaces the wildcard layer for that key.',
},
{
name: 'order',
requirement: 'optional',
type: 'number',
- doc: 'Nesting position, ascending (default 0); the lowest order is the outermost layer. Render the `children` prop exactly once.',
+ doc: 'Nesting position, ascending (default 0); the lowest order is the outermost layer. Render the `children` prop at most once.',
},
],
ownerProps: [
@@ -4006,7 +4079,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
],
replaceRisk: 'none',
example: 'return {\n inject: [\'slots\'],\n apply(ctx) {\n ctx.slots.inject(\'shell.quota-notice\', () => ctx.slots.register(\n { name: \'shell.quota-notice\', select: owner => null },\n () => React.createElement(\'div\', null, \'hello\'),\n ))\n },\n}',
- source: 'packages/client/ui-chat/src/client/contract/slots.ts:501',
+ source: 'packages/client/ui-chat/src/client/contract/slots.ts:503',
},
{
key: 'sidebar',
diff --git a/scripts/gen-client-catalog.ts b/scripts/gen-client-catalog.ts
index 534609bb04..6e992a3eda 100644
--- a/scripts/gen-client-catalog.ts
+++ b/scripts/gen-client-catalog.ts
@@ -83,8 +83,9 @@ const REGISTER_OPTIONS: Readonly unknown | null', doc: 'Pure routing selector. Entries are tried in ascending order; the first non-null result wins and arrives as the component\'s `matched` prop. All-null falls through to the owner\'s fallback.' },
],
hoc: [
- { name: 'id', requirement: 'required', type: 'string', doc: 'Your layer key. A fresh id adds a layer; reusing a shipped id replaces that layer. Your component must render its `children` prop: a layer that omits it hides the owner content, such as the whole conversation and its composer.' },
- { name: 'order', requirement: 'optional', type: 'number', doc: 'Nesting position, ascending (default 0); the lowest order is the outermost layer. Render the `children` prop exactly once.' },
+ { name: 'id', requirement: 'required', type: 'string', doc: 'Your layer key. A fresh id adds a layer; reusing a shipped id replaces that layer. Your component may omit `children`, which replaces everything inside the layer.' },
+ { name: 'key', requirement: 'optional', type: 'string', doc: 'Dispatch key this layer serves; omitted, it serves every dispatch. Within one id, an exact-key layer replaces the wildcard layer for that key.' },
+ { name: 'order', requirement: 'optional', type: 'number', doc: 'Nesting position, ascending (default 0); the lowest order is the outermost layer. Render the `children` prop at most once.' },
],
}
@@ -350,10 +351,13 @@ function ownerCompositionNames(type: ts.TypeNode): string[] {
return []
}
-/** How a keyed slot's key domain is constrained, '' for the other kinds. */
+/** How a keyed slot's key domain, or a hoc slot's layer dispatch keys, is constrained; '' for the other kinds. */
function keyDomainOf(declaration: SlotDeclaration, occupants: readonly SlotRegistration[]): string {
- if (declaration.kind !== 'keyed') return ''
const taken = [...new Set(occupants.flatMap(occupant => occupant.entryKey === undefined ? [] : [occupant.entryKey]))].sort()
+ if (declaration.kind === 'hoc') {
+ return taken.length === 0 ? '' : `open: any entryKey the owner dispatches; a layer without key serves every dispatch, already taken: ${taken.join(', ')}`
+ }
+ if (declaration.kind !== 'keyed') return ''
const shipped = taken.length === 0 ? 'none are taken yet' : `already taken: ${taken.join(', ')}`
return declaration.keyProps === undefined
? `open: any string the owner dispatches (no compile-time key set), ${shipped}`
@@ -513,7 +517,8 @@ export function renderClientCatalog(entries: readonly SlotEntry[]): string {
' occupants: readonly string[]',
' /**',
' * `shadows-shipped-ui` when registering here replaces shipped UI; `wraps-owner-content` when your',
- ' * component wraps the owner content and must render `children`; `none` when additive.',
+ ' * component wraps the owner content and renders `children` at most once, omitting it to replace',
+ ' * that content; `none` when additive.',
' */',
' replaceRisk: string',
' /** A minimal browser half that registers into this slot. */',