@prettier-ai/dsh-client-ui-renderer 0.1.2-alpha.1

package/lib/index.js

@@ -0,0 +1,6 @@
+//#region lib/types/index.js
+/** Host loader entry for the browser-only UI renderer. */
+/** Provides no host-side behavior. */
+function apply() {}
+//#endregion
+export { apply };

package/lib/invariant.js

@@ -0,0 +1,34 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@prettier-ai/dsh-client-ui-renderer`.
+* @module @prettier-ai/dsh-client-ui-renderer/invariant
+*/
+const PACKAGE_NAME = "@prettier-ai/dsh-client-ui-renderer";
+/** Cordis companion plugin name. */
+const name = "client-ui-renderer-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* Verify that each `slots/changed` dispatch observes its mutation already
+* applied to the renderer-owned slot registry.
+*/
+const install = (ctx, fail) => {
+	ctx.on("internal/dispatch", (_mode, eventName, args) => {
+		if (eventName !== "slots/changed") return;
+		const key = args[0];
+		if (typeof key !== "string" || key === "") {
+			fail("'slots/changed' dispatched without a slot key argument");
+			return;
+		}
+		const slots = ctx.get("slots");
+		if (slots !== void 0 && slots.getVersion(key) === 0) fail(`'slots/changed' fired for "${key}" before any mutation bumped its version — emission must follow the applied mutation`);
+	}, { global: true });
+};
+/**
+* Register this package's invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/types/client/app.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Real-UI assembly closure. The whole layout tree hangs from the built-in
+ * `root` slot, which is the only ctx-level slot render in the application.
+ */
+import type { ReactNode } from 'react';
+import type { Context } from '@prettier-ai/cordis';
+/** Inputs available after the UI renderer's inject set activates. */
+export interface AssemblyDeps {
+    /** Client context carrying the renderer-owned Slot registry. */
+    ctx: Context;
+}
+/**
+ * Build the assembled application factory.
+ * @param deps - Active UI-renderer dependencies.
+ * @returns Factory producing the application React tree.
+ */
+export declare function buildRenderApp(deps: AssemblyDeps): () => ReactNode;
+//# sourceMappingURL=app.d.ts.map

package/lib/types/client/bind.d.ts

@@ -0,0 +1,11 @@
+import type { HostObservable, SnapshotSelectorHook } from '@prettier-ai/dsh-client-ui-slots';
+/**
+ * Bind a bare observable source to a typed uSES selector hook.
+ * subscribe/getSnapshot are captured once per source into stable closures
+ * (also re-binds `this` for method-based sources), so components never
+ * resubscribe across renders. Equality defaults to Object.is.
+ * @param w - snapshot source (engine store, Session object, store instance).
+ * @returns the selector hook.
+ */
+export declare function bindSnapshotSelector<T>(w: HostObservable<T>): SnapshotSelectorHook<T>;
+//# sourceMappingURL=bind.d.ts.map

package/lib/types/client/bindings.d.ts

@@ -0,0 +1,53 @@
+/** Internal React bindings for renderer hosts and standard-source scopes. */
+import { type ReactNode } from 'react';
+import type { HostObservable, KeyedStandardSource, MaybeSnapshotSelectorHook, SlotRendererHost, SnapshotSelectorHook, StandardSourceBinding } from '@prettier-ai/dsh-client-ui-slots';
+/** Missing renderer assembly dependency. */
+export declare class SlotAssemblyError extends Error {
+}
+/** In-package renderer host context. */
+export declare const HostContext: import("react").Context<SlotRendererHost | null>;
+/**
+ * Read the installed renderer host.
+ * @returns the host API.
+ */
+export declare function useHost(): SlotRendererHost;
+/**
+ * Read the root standard-source binding.
+ * @returns the current root binding.
+ */
+export declare function useRootBinding(): StandardSourceBinding;
+/**
+ * Read the current-session-optional binding.
+ * @returns a binding whose key is absent when no Session is selected.
+ */
+export declare function useScopeBinding(): StandardSourceBinding;
+/**
+ * Bind one observable source to an identity-stable selector Hook.
+ * @param source - observable source.
+ * @returns cached selector Hook.
+ */
+export declare function observableHook<T>(source: HostObservable<T>): SnapshotSelectorHook<T>;
+/**
+ * Bind an optional source without changing Hook call order.
+ * @param source - current source, or absence.
+ * @returns selector Hook returning `undefined` while absent.
+ */
+export declare function maybeObservableHook<T>(source: HostObservable<T> | undefined): MaybeSnapshotSelectorHook<T>;
+/** Erased open-key selector Hook synthesized from one keyed source family. */
+export type KeyedSnapshotHook = (key: string, selector?: (value: unknown) => unknown, equal?: (left: unknown, right: unknown) => boolean) => unknown;
+/**
+ * Bind an open-key source family.
+ * @param source - keyed resolver, or absence for an optional scope.
+ * @returns cached keyed selector Hook.
+ */
+export declare function keyedObservableHook(source: KeyedStandardSource | undefined): KeyedSnapshotHook;
+/** Subscribe the tree to the atomically assembled root standard-source roster. */
+export declare function RootStandardProvider({ children }: {
+    children: ReactNode;
+}): import("react").JSX.Element;
+/** Subscribe to the scope roster before resolving and binding its current adapter. */
+export declare function ScopeProvider({ scope, children, }: {
+    scope: 'session' | 'session-maybe';
+    children: ReactNode;
+}): import("react").JSX.Element;
+//# sourceMappingURL=bindings.d.ts.map

package/lib/types/client/index.d.ts

@@ -0,0 +1,38 @@
+import type { Context } from '@prettier-ai/cordis';
+import { SlotRegistry } from './registry.ts';
+export { SlotRegistry } from './registry.ts';
+export type { RootOwnerProps } from './registry.ts';
+export type { ChainRenderOpts, HostObservable, RenderOpts, SnapshotSelectorHook, SlotRenderer, ScopedStandardSourceBinding, SlotRendererHost, SlotScopeAdapter, StandardSourceBinding, StoreInstanceLike, } from '@prettier-ai/dsh-client-ui-slots';
+/** Mount operation exposed to the framework-free boot kernel. */
+export interface UiRendererService {
+    /**
+     * Mount the assembled application into the supplied element.
+     * @param container - Application mount point.
+     * @returns Disposer that unmounts the React root.
+     */
+    mount: (container: HTMLElement) => () => void;
+}
+declare module '@prettier-ai/cordis' {
+    interface Events {
+        /**
+         * A slot declaration or registration set changed.
+         * @mode emit
+         * @param key - mutated SlotMap key.
+         */
+        'slots/changed'(key: string): void;
+    }
+    interface Context {
+        /** Renderer-owned UI composition registry. */
+        slots: SlotRegistry;
+        /** Mount face provided after the UI renderer activates. */
+        uiRenderer: UiRendererService;
+    }
+}
+/** Services required before application assembly. */
+export declare const inject: string[];
+/**
+ * Install the slot renderer and provide the application mount face.
+ * @param ctx - Plugin context.
+ */
+export declare function apply(ctx: Context): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/client/registry.d.ts

@@ -0,0 +1,222 @@
+/**
+ * SlotRegistry: the renderer-owned Cordis service over the pure
+ * SlotCore (ui-slots owns registration semantics, the declaration ledger,
+ * the load-time validations, and the unload cascade). This layer owns what
+ * needs a live application: the 'slots/changed' event bridge, register and
+ * declaration injection through the caller's ctx.effect (fiber unload
+ * collects both), the renderer installation contract (install()/renderSlot('root') +
+ * the SlotRendererHost face), and the store INSTANCE axis — handle x scope
+ * key -> create/cache, dropped with the last holding entry, session instances
+ * cleared (with persisted state) on scope death.
+ */
+import { Service } from '@prettier-ai/cordis';
+import type { Context } from '@prettier-ai/cordis';
+import { SlotCore } from '@prettier-ai/dsh-client-ui-slots';
+import type { LiveSlotNode, LocaleFace, OwnerOf, SlotMap, SlotRenderer, RootStandardSourceContribution, ScopedStandardSourceBinding, SlotScope, SlotScopeAdapter, SlotSpec, StoredEntry } from '@prettier-ai/dsh-client-ui-slots';
+declare module '@prettier-ai/dsh-client-ui-slots' {
+    interface SlotMap {
+        /**
+         * The built-in render-tree root hole (seeded by SlotCore): the one slot the
+         * shell itself renders, and the ancestor of every other seat. OCCUPIED by
+         * ui-layout's AppFrame, which declares the sidebar, conversation, details,
+         * and shell.overlay seats inside it.
+         *
+         * DO NOT register here. This is a single slot, so a second entry does not
+         * sit beside the frame — it shadows it, and a dynamically registered entry
+         * is assigned a lower priority than the shipped one, which makes it the
+         * winner: the page would render your component alone, with every seat the
+         * frame declares gone. For a surface of your own that floats over the whole
+         * app, register into `shell.overlay` instead (a list slot: additive, and
+         * click-through until your entry opts into pointer events).
+         */
+        'root': {
+            kind: 'single';
+            scope: 'root';
+            owner: RootOwnerProps;
+        };
+    }
+}
+/** Root owner share: the shell supplies nothing — the frame is inject-assembled. */
+export interface RootOwnerProps {
+    children?: never;
+}
+/** One synchronous effect installed while an injected slot declaration is live. */
+type SlotInjectionEffect = (() => void) | Iterable<() => void, void, void>;
+/** cordis Service layer of the slot system; see the module doc for the split with SlotCore. */
+export declare class SlotRegistry extends Service {
+    private readonly _core;
+    /** Store-instance axis: handle -> mounted scope, refcount, resolved instances. */
+    private readonly _stores;
+    /** Latest live Context generation for each scoped store key. */
+    private readonly _storeScopeOwners;
+    private _renderer;
+    private _locale;
+    private _host;
+    private readonly _rootContributions;
+    private readonly _rootListeners;
+    private _rootBinding;
+    private readonly _rootSource;
+    private readonly _scopes;
+    private _scopeRevision;
+    private readonly _scopeListeners;
+    private readonly _scopeRevisionSource;
+    /**
+     * @param ctx - owning root context.
+     */
+    constructor(ctx: Context);
+    /**
+     * The single registration API. The typed face IS the core's register
+     * (both overloads reused verbatim — one authority, no structural copy;
+     * see SlotCore.register for children declaration, store seat, inject
+     * face, load-time validation, and the unload cascade). This layer adds:
+     * disposal through the caller's ctx.effect (fiber unload = cascade),
+     * exclusive-factory minting (`store: createXxxStore` becomes a per-entry
+     * handle), the registrant diagnostics stamp, and store-instance lifecycle
+     * on the entry axis.
+     *
+     * Declared here, implemented by prototype assignment below the class: it
+     * MUST stay a prototype method (never an instance arrow) — the cordis
+     * service proxy binds `this.ctx` to the CALLER's context at call time,
+     * which is what routes the effect (and the unload cascade) into the
+     * caller's fiber. An arrow property would freeze `this` to the service's
+     * own root ctx and silently break per-plugin disposal.
+     */
+    readonly register: SlotCore['register'];
+    /**
+     * Install an effect for each declaration lifetime of a slot. The callback
+     * runs synchronously when the declaration already exists; otherwise it runs
+     * inside the declaring `register()` call after the declaration is committed.
+     * Collapse disposes the effect and a later declaration runs it again.
+     * Callback effects are synchronous disposers; iterable effects install
+     * transactionally and dispose in reverse order. The controller belongs to
+     * the caller's fiber, so plugin unload cancels a pending wait and removes any
+     * active contribution.
+     *
+     * @param key - declared SlotMap key to depend on.
+     * @param callback - creates one disposer or an iterable of disposers.
+     * @returns idempotent disposer for the wait and active effect.
+     * @throws callback setup failures synchronously when the slot is already declared.
+     */
+    inject(key: keyof SlotMap & string, callback: () => SlotInjectionEffect): () => void;
+    /**
+     * Install the shell's renderer (ui-renderer's createSlotRenderer product).
+     * Boot-once: a second install throws. Runs through the caller's ctx.effect,
+     * so shell fiber unload uninstalls the renderer.
+     * @param renderer - the outlet machinery implementing SlotRenderer.
+     */
+    install(renderer: SlotRenderer): void;
+    /**
+     * Install the locale face backing the `t` standard seat (the locale
+     * plugin's product; same boot-once discipline as the renderer install).
+     * Runs through the caller's ctx.effect, so the installing fiber's unload
+     * uninstalls the face.
+     * @param face - namespace binder + revision observable.
+     */
+    installLocale(face: LocaleFace): void;
+    /**
+     * Contribute domain-owned root data. Hook names must be globally unique;
+     * registration and disposal republish one atomic root binding.
+     * @param contribution - bare sources and stable props.
+     * @returns disposer owned by the caller's Cordis fiber.
+     */
+    provideRoot(contribution: RootStandardSourceContribution): () => void;
+    /**
+     * Install the owner adapter for one strict scope. Its optional counterpart
+     * resolves through the same adapter.
+     * @param scope - strict scope name.
+     * @param adapter - current/resolved binding source and release notifications.
+     */
+    installScope(scope: Exclude<SlotScope, 'root' | 'session-maybe'>, adapter: SlotScopeAdapter): void;
+    /**
+     * Bind all scoped Store handles to one owner Context lifetime. The cleanup
+     * materializes an otherwise-unused handle before clearing it, because a
+     * previous application run may have persisted state for a Slot that this
+     * scope never rendered. Rebinding the same key transfers cleanup ownership
+     * to the newest Context generation.
+     *
+     * @param binding - materialized scope identity and its owning Context.
+     */
+    bindStoreScope(binding: Pick<ScopedStandardSourceBinding, 'key' | 'ctx'>): void;
+    /**
+     * The single ctx-level render entry: the shell renders 'root'; every other
+     * key renders inside components through the props renderSlot face. All
+     * three guards are fail-loud boot-order checks, no fallback.
+     * @param key - must be 'root' (runtime-enforced for dynamically composed callers).
+     * @param owner - owner share for the root entry (the shell supplies {}).
+     * @returns the rendered root tree.
+     */
+    renderSlot<K extends keyof SlotMap & string>(key: K, owner: OwnerOf<K>): ReturnType<SlotRenderer['renderRoot']>;
+    /**
+     * Snapshot entries for a key (render-erased view; stable reference between mutations).
+     * @param key - SlotMap key.
+     * @returns registered entries.
+     */
+    entries(key: keyof SlotMap & string): readonly StoredEntry[];
+    /**
+     * Shadowing winners per cell for a key: the first live (non-abdicated)
+     * entry of each cell in priority order — what outlets render; chain keys
+     * pass through unchanged (election consumes every entry). The raw
+     * {@link SlotsService.entries} view stays the inspection surface. Fresh
+     * array per call, not a uSES getSnapshot source.
+     * @param key - SlotMap key.
+     * @returns the winning entry per occupied cell.
+     */
+    entriesOfSlot(key: keyof SlotMap & string): readonly StoredEntry[];
+    /**
+     * Export the current JSON-safe Slot declaration tree for read-only inspection.
+     * @param root - exact live Slot root; omitted returns all roots.
+     * @returns selected Slot trees.
+     */
+    snapshot(root?: string): LiveSlotNode[];
+    /**
+     * Observe entry boundary crashes (every render-time entry failure the
+     * boundaries contain, abdicating or not) — the supervision seam for
+     * plugins mirroring contribution health. Fires synchronously per report,
+     * after the registry mutated for abdicating crashes. Callers own the
+     * disposer (wire it through ctx.effect for fiber-lifetime cleanup, as with
+     * {@link SlotsService.subscribe}).
+     * @param fn - called with the slot key, the crashed entry, the crash
+     * cause, and `abdicated`: whether the crash retired the entry from its cell.
+     * @returns unsubscribe.
+     */
+    onEntryError(fn: (key: string, entry: StoredEntry, error: unknown, info: {
+        abdicated: boolean;
+    }) => void): () => void;
+    /**
+     * Look up a declared spec (register-declared or the built-in 'root').
+     * @param key - SlotMap key.
+     * @returns spec or undefined.
+     */
+    spec<K extends keyof SlotMap & string>(key: K): SlotSpec<SlotMap[K]> | undefined;
+    /**
+     * Subscribe to a key's registration changes (microtask-batched).
+     * @param key - SlotMap key.
+     * @param fn - change callback.
+     * @returns unsubscribe.
+     */
+    subscribe(key: keyof SlotMap & string, fn: () => void): () => void;
+    /**
+     * Version counter for uSES pairing.
+     * @param key - SlotMap key.
+     * @returns current version.
+     */
+    getVersion(key: keyof SlotMap & string): number;
+    /** Delegating registration path: factory minting + registrant stamp + core write + instance-axis bookkeeping. */
+    private _register;
+    /** Build the domain-neutral host face once; installed adapters remain live through getters. */
+    private hostFace;
+    /** Validate and atomically publish the current root contribution roster. */
+    private rebuildRootBinding;
+    /** Publish one installed-scope roster transition after the map is authoritative. */
+    private publishScopeRevision;
+    /** Resolve (create or reuse) the store instance for a registered handle under a scope key. */
+    private resolveStore;
+    /** Clear every live non-root Store handle for one dead scope key. */
+    private clearStoreScope;
+    /** Bind (or re-reference) a handle on the axis; cross-scope conflicts already threw in the core. */
+    private _acquire;
+    /** Drop one reference; the last holder's unload drops the record (instances go with it — engine stores need no explicit dispose). */
+    private _release;
+}
+export {};
+//# sourceMappingURL=registry.d.ts.map

package/lib/types/client/scoped-slots.d.ts

@@ -0,0 +1,9 @@
+import { type SlotRenderer } from '@prettier-ai/dsh-client-ui-slots';
+/**
+ * Build the renderer installed into the `ui-renderer` SlotRegistry
+ * (ctx.slots.install(createSlotRenderer()) at boot; the service owns the
+ * install/renderSlot contract and the double-install/not-installed throws).
+ * @returns the renderer.
+ */
+export declare function createSlotRenderer(): SlotRenderer;
+//# sourceMappingURL=scoped-slots.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,4 @@
+/** Host loader entry for the browser-only UI renderer. */
+/** Provides no host-side behavior. */
+export declare function apply(): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@prettier-ai/dsh-client-ui-renderer`.
+ * @module @prettier-ai/dsh-client-ui-renderer/invariant
+ */
+import type { Context } from '@prettier-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "client-ui-renderer-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@prettier-ai/dsh-client-ui-renderer",
+  "description": "Browser UI renderer: React slot bindings, ctx.uiRenderer, and the assembled application root",
+  "version": "0.1.2-alpha.1",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/client/ui-renderer"
+  },
+  "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"
+    },
+    "./client": {
+      "types": "./lib/types/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "dsh": {
+    "client": {
+      "platform": "web",
+      "immediately": true
+    }
+  },
+  "license": "MIT",
+  "dependencies": {
+    "use-sync-external-store": "1.2.0"
+  },
+  "peerDependencies": {
+    "@prettier-ai/dsh-invariants": "^0.1.2-alpha.1",
+    "@prettier-ai/cordis": "^4.0.1"
+  },
+  "devDependencies": {
+    "@types/react": "~18.3.1",
+    "@types/react-dom": "~18.3.0",
+    "@types/use-sync-external-store": "^1.5.0",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "@prettier-ai/dsh-client-ui-slots": "^0.1.2-alpha.1",
+    "@prettier-ai/cordis": "^4.0.1",
+    "@prettier-ai/dsh-invariants": "^0.1.2-alpha.1",
+    "@prettier-ai/dsh-client-test-runtime": "^0.1.2-alpha.1"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/client.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "scripts": {
+    "bundle": "tsdown",
+    "watch": "tsdown --watch"
+  }
+}