@deepseek-ai/dsh-client-ui-slots 0.0.1-rc.1

package/lib/types/renderer.d.ts

@@ -0,0 +1,183 @@
+/** React-free contracts between the slot host and an installed renderer. */
+import type { ReactNode } from 'react';
+import type { SlotEntryDef, SlotSpec, StoredEntry, Translate } from './index.ts';
+/**
+ * The locale face the render machinery consumes: namespace binding plus an
+ * observable revision (getSnapshot/subscribe pair — the same HostObservable
+ * currency as every other standard-kit source). The revision moves on every
+ * active-locale or registry change; the renderer re-derives each entry's `t`
+ * from (namespace, revision), so a locale switch hands out NEW function
+ * references and memoized components re-render naturally. Implemented by the
+ * locale plugin, installed through the runtime SlotsService (installLocale).
+ * Install before the first render that needs the seat: outlets bind their
+ * revision subscription at mount, and a face appearing later has no channel
+ * to notify already-mounted outlets (the locale plugin is immediately-tier
+ * infrastructure, so normal compositions install during boot).
+ */
+export interface LocaleFace extends HostObservable<{
+    revision: number;
+}> {
+    /**
+     * Bind a namespace to a translate function reading the active locale at
+     * call time. Identity may be stable per namespace — freshness of rendered
+     * text is carried by the renderer's (ns, revision) seat derivation, not by
+     * this binding.
+     * @param ns - dictionary namespace.
+     * @returns the namespace-bound translate function.
+     */
+    bind(ns: string): Translate;
+}
+/** Minimal observable surface for host-provided standard-kit data sources. */
+export interface HostObservable<T> {
+    getSnapshot(): T;
+    subscribe(fn: () => void): () => void;
+}
+/**
+ * Type-erased store instance face at the render boundary (the typed twin is
+ * {@link StoreInstance}): a bare snapshot source plus the draft-stripped
+ * action callbacks. No React hook crosses this boundary — the render machinery
+ * binds `useStore` from the source at its own side (cached per instance);
+ * typing lands at the component boundary via {@link PropsStore}.
+ */
+export interface StoreInstanceLike {
+    getSnapshot(): unknown;
+    /**
+     * Subscribe to state changes (uSES subscribe side).
+     * @param fn - change callback.
+     * @returns unsubscribe.
+     */
+    subscribe(fn: () => void): () => void;
+    readonly actions: Record<string, (...params: never[]) => void>;
+}
+/**
+ * Per-session standard props resolved per session id (identity-stable per
+ * session scope; a recreated scope yields a new info). Plugins contribute
+ * members through the runtime `sessions.provide` contract; the render side binds
+ * every `hooks` source into a `use<Name>` selector hook (hooks never appear
+ * on the host contract) and spreads `props` verbatim. The runtime itself
+ * contributes the first entry (`'session'` → `useSession`).
+ */
+export interface SessionMaybeProvideInfo {
+    /** Current session id, absent while the application is in no-session mode. */
+    sessionId: string | undefined;
+    /**
+     * Static hook roster. Each value is absent with the session; keys remain so
+     * session-maybe entries always receive the same hook-shaped standard kit.
+     */
+    hooks: Record<string, HostObservable<unknown> | undefined>;
+    /** Static plain-member roster; values are undefined with the session. */
+    props: Record<string, unknown>;
+    /**
+     * Key-addressed projection value sources (the useProjection framework seat;
+     * session-projection subsystem page: docs/subsystems/session-projection.md).
+     * Unlike `hooks`, the key space is open — values
+     * arrive from host-computed push frames — so the render side binds per
+     * resolved key instead of per static roster member. Faces are always
+     * defined per key (absence is an `undefined` snapshot); the whole member is
+     * absent with the session.
+     */
+    projections?: {
+        faceOf(key: string): HostObservable<unknown>;
+    } | undefined;
+}
+/** Definite per-session standard props resolved for strict session slots. */
+export interface SessionProvideInfo extends SessionMaybeProvideInfo {
+    sessionId: string;
+    /** Bare observable sources, keyed by hook base name ('session' → useSession). */
+    hooks: Record<string, HostObservable<unknown>>;
+}
+/** renderSlot dispatch options at the machinery level. */
+export interface RenderOpts {
+    entryKey?: string;
+    only?: string;
+    fallback?: ReactNode;
+    /** Opaque occurrence context consumed only by function-valued injected Hooks. */
+    hookContext?: unknown;
+}
+/** Host surface the runtime SlotsService presents to the installed renderer. */
+export interface SlotRendererHost {
+    /**
+     * Subscribe to a key's registration changes (microtask-batched).
+     * @param key - slot key.
+     * @param fn - change callback.
+     * @returns unsubscribe.
+     */
+    subscribe(key: string, fn: () => void): () => void;
+    /**
+     * Monotonic version for uSES pairing.
+     * @param key - slot key.
+     * @returns current version.
+     */
+    getVersion(key: string): number;
+    /**
+     * Snapshot the registered entries for a key (stable reference between mutations).
+     * @param key - slot key.
+     * @returns entries in registration (list: order) sequence.
+     */
+    entriesOf(key: string): readonly StoredEntry[];
+    /**
+     * Declared runtime spec from the declarations ledger.
+     * @param key - slot key.
+     * @returns the spec, or undefined while the key is undeclared (outlets render empty).
+     */
+    specOf(key: string): SlotSpec<SlotEntryDef> | undefined;
+    /**
+     * Stale-authorization check: whether the entry is still in the ledger.
+     * @param entry - a previously rendered entry.
+     * @returns false once the entry's registration was disposed.
+     */
+    isLive(entry: StoredEntry): boolean;
+    /**
+     * Resolve (create or return cached) the store instance for an entry's
+     * declared handle under a scope key; lifecycle rides the ledger axis.
+     * @param entry - entry whose declaration carries the handle.
+     * @param scopeKey - session id for session-scope slots, undefined for root scope.
+     * @returns the instance, or undefined when the entry declares no store.
+     */
+    storeOf(entry: StoredEntry, scopeKey: string | undefined): StoreInstanceLike | undefined;
+    /** Session-side standard-kit sources. */
+    sessions: {
+        /** Session list source backing the useSessions standard hook. */
+        list: HostObservable<unknown>;
+        /**
+         * Atomic current-session provide projection used by SessionProvider:
+         * selection changes and provider-roster changes publish through this one
+         * source, so a stable current id cannot strand mounted entries on an
+         * obsolete hook/prop schema. Carries the static roster with sessionId
+         * undefined while no current session resolves.
+         */
+        provideInfo: HostObservable<SessionMaybeProvideInfo>;
+    };
+    /** Workspace-side standard-kit sources. */
+    workspaces: {
+        /** Workspace list source backing the useWorkspaces standard hook. */
+        list: HostObservable<unknown>;
+    };
+    /**
+     * Installed locale face backing the `t` standard seat (absent until the
+     * locale plugin installs one; rendering an entry that declared `locale:`
+     * without it is an assembly failure).
+     */
+    locale?: LocaleFace | undefined;
+}
+/** The installation contract: runtime owns install()/renderSlot(); web-react implements rendering. */
+export interface SlotRenderer {
+    /**
+     * Render the root slot tree over the host surface (the only ctx-level entry).
+     * @param host - the installing service's host surface.
+     * @param ownerProps - owner props from the shell's renderSlot('root', ...) call.
+     * @returns the rendered tree.
+     */
+    renderRoot(host: SlotRendererHost, ownerProps: object): ReactNode;
+}
+/** Thrown when a retained renderSlot binding is invoked after its declaring entry was disposed. */
+export declare class StaleAuthorizationError extends Error {
+}
+/**
+ * Thrown when a renderSlot binding is invoked for a key outside its entry's
+ * children declaration (plain-JS backstop; typed callers are narrowed
+ * statically).
+ */
+export declare class SlotOwnershipError extends Error {
+}
+//# sourceMappingURL=renderer.d.ts.map

package/lib/types/store.d.ts

@@ -0,0 +1,111 @@
+/** Framework-neutral store contracts for slot registrations and the runtime engine. */
+/**
+ * Typed selector hook over a snapshot source. Canonical shape for the whole
+ * slot system (web-react's engine hook is structurally identical; the
+ * framework is the only party that ever constructs one).
+ */
+export type SnapshotSelectorHook<T> = <S>(sel: (s: T) => S, eq?: (a: S, b: S) => boolean) => S;
+/**
+ * Selector hook over a source that follows the current session. The hook is
+ * always present, while its selected value is absent whenever no session is
+ * current. This keeps hook call sites stable across no-session/session
+ * transitions without pretending that a session snapshot exists.
+ */
+export type MaybeSnapshotSelectorHook<T> = <S>(sel: (s: T) => S, eq?: (a: S, b: S) => boolean) => S | undefined;
+/**
+ * Action declaration table: pure immer-draft transforms over the store state,
+ * declared as the store's complete write set (the audit face — components can
+ * only write through these).
+ */
+export type ActionsDecl<T> = Record<string, (draft: T, ...params: any[]) => void>;
+/**
+ * Draft-stripped callback form of an actions table: what components
+ * (`props.actions`) and inject factories receive — the framework bakes the
+ * draft parameter away by binding each action to the resolved instance.
+ */
+export type BakedActions<T, A extends ActionsDecl<T>> = {
+    [K in keyof A]: A[K] extends (draft: T, ...params: infer P) => void ? (...params: P) => void : never;
+};
+/**
+ * Store declaration spec: initial-state factory (a lambda so every instance
+ * gets a fresh state), optional persistence key (mechanical, framework-run),
+ * and the actions write set.
+ */
+export interface StoreSpec<T, A extends ActionsDecl<T>> {
+    init: () => T;
+    persist?: string;
+    actions: A;
+}
+/**
+ * Live engine instance: the create() product consumed by the render machinery
+ * and by tests. A bare snapshot source plus the baked write set — no React
+ * hook rides the engine product (the engine lives in the React-free runtime);
+ * the render machinery binds the `useStore` hook from this source on its own
+ * side, cached per instance. Production components and render paths never
+ * call create() themselves — instance lifecycle is the framework's.
+ */
+export interface StoreInstance<T, A extends ActionsDecl<T>> {
+    readonly actions: BakedActions<T, A>;
+    getSnapshot(): T;
+    /**
+     * Subscribe to state changes (uSES subscribe side).
+     * @param fn - change callback.
+     * @returns unsubscribe.
+     */
+    subscribe(fn: () => void): () => void;
+    /**
+     * Drop this instance's persisted value (no-op for non-persist specs). The
+     * framework calls it when the owning scope dies for good — a pruned session
+     * must not leave orphaned storage keys behind.
+     */
+    clearPersisted(): void;
+}
+/**
+ * Store handle: spec + state/actions types + shared identity + instance
+ * factory in one value. Handles are constructed in apply world (shared across
+ * registrations of one plugin) or by the framework from a registrant's
+ * factory (exclusive). Never export a handle at module level — module-cache
+ * identity is a disguised singleton across plugin reloads.
+ */
+export interface StoreHandle<T, A extends ActionsDecl<T>> {
+    readonly spec: StoreSpec<T, A>;
+    /**
+     * Create a live engine instance (framework machinery and tests only).
+     * @param scopeKey - session id for session-scope instances; suffixes the
+     * persist key so per-session instances persist independently (root-scope
+     * instances omit it).
+     * @returns a fresh instance seeded from `spec.init()`.
+     */
+    create(scopeKey?: string): StoreInstance<T, A>;
+}
+/**
+ * Exclusive-store registration form: the registrant passes the factory itself
+ * and the framework calls it per entry x scope (no shared identity exists).
+ */
+export type StoreFactory = () => StoreHandle<any, any>;
+/** The register `store` option position: a shared handle or an exclusive factory. */
+export type StoreDecl = StoreHandle<any, any> | StoreFactory;
+/** Normalize a store declaration to its handle type (factories yield their return). */
+export type HandleOf<H> = H extends () => infer R ? R : H;
+/**
+ * Handle-keyed baked actions: the `actions` parameter of an inject factory
+ * whose registration declared a store — the same baked callback set the
+ * component receives via {@link PropsStore}.
+ */
+export type BoundActions<H> = H extends StoreHandle<infer T, infer A> ? BakedActions<T, A> : never;
+/**
+ * The store props share, derived from the declared handle: a typed selector
+ * hook plus the baked write set. Components never see the instance itself
+ * (no update/set — reads via useStore, writes via the declared actions only).
+ */
+export type PropsStore<H> = H extends StoreHandle<infer T, infer A> ? {
+    useStore: SnapshotSelectorHook<T>;
+    actions: BakedActions<T, A>;
+} : object;
+/**
+ * The defineStore contract (implementation lives in the runtime package,
+ * bound to the snapshot-store engine): spec in, handle out, with T inferred
+ * from `init` and the actions table constrained by T.
+ */
+export type DefineStore = <T, A extends ActionsDecl<T>>(spec: StoreSpec<T, A>) => StoreHandle<T, A>;
+//# sourceMappingURL=store.d.ts.map

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@deepseek-ai/dsh-client-ui-slots",
+  "description": "Slot registry pure core: SlotMap declaration merging, single register composition API, four-share props types, store-seat types, renderer install seam",
+  "version": "0.0.1-rc.1",
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/client/ui-slots"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "license": "BSD-3-Clause",
+  "devDependencies": {
+    "@types/react": "~18.3.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1",
+    "@deepseek-ai/cordis": "^4.0.1-rc.1"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "peerDependencies": {
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1",
+    "@deepseek-ai/cordis": "^4.0.1-rc.1"
+  }
+}