@linxin666/dsh-client-ui-task-board 0.4.2 → 0.4.3

package/lib/index.js

@@ -2162,6 +2162,25 @@ var HostTaskLedger = class {
 		for (const task of this.document.tasks) if (task.archivedAt === void 0 && task.schedule?.enabled === true) count += 1;
 		return count;
 	}
+	/**
+	* The earliest armed `nextRunAt` strictly after the supplied Host time, or
+	* undefined when no schedule is armed in the future. This is the instant the
+	* Host arms its native timer at, so the board wakes exactly when work is due
+	* instead of polling a fixed heartbeat.
+	* @param now - current Host time in ms epoch.
+	* @returns the nearest future trigger, or undefined when none is armed.
+	*/
+	nextArmedRunAt(now) {
+		let nearest;
+		for (const task of this.document.tasks) {
+			if (task.archivedAt !== void 0) continue;
+			const schedule = task.schedule;
+			if (schedule === void 0 || !schedule.enabled || schedule.nextRunAt === void 0) continue;
+			if (schedule.nextRunAt <= now) continue;
+			if (nearest === void 0 || schedule.nextRunAt < nearest) nearest = schedule.nextRunAt;
+		}
+		return nearest;
+	}
 	/** Return value-only references for schedules due at the supplied Host time. */
 	dueSchedules(now) {
 		const due = [];
@@ -3567,19 +3586,55 @@ var PowerInhibitor = class {
 };
 //#endregion
 //#region src/host-service.ts
+/** Session-roster poll cadence — the one recurring Host timer this service still holds. */
 const SESSION_POLL_MS = 5e3;
-const SCHEDULE_TICK_MS = 3e4;
-const RESUME_GAP_MS = 45e3;
+/**
+* How late an armed schedule fire may be before it counts as a resume rather
+* than a normal occurrence. The schedule timer is armed AT the next due
+* instant, so landing this far past its target means the Host was suspended,
+* the process throttled, or the wall clock jumped forward — the same condition
+* the old fixed 30 s heartbeat detected through its own gap threshold.
+*/
+const RECOVERY_TOLERANCE_MS = 6e4;
+/** Largest delay a Node timer represents without clamping; longer targets re-arm in segments. */
+const MAX_TIMER_DELAY_MS = 2147483647;
+/**
+* Actions that can move an armed trigger. Only these re-arm the native timer;
+* an unrelated card edit leaves the pending fire untouched.
+*/
+const SCHEDULE_WRITE_ACTIONS = /* @__PURE__ */ new Set([
+	"set-schedule",
+	"delete",
+	"archive"
+]);
+/** Process-global fallback used when the deployment serves no cordis timer service. */
+const PROCESS_TIMERS = {
+	timeout(callback, delay) {
+		const handle = setTimeout(callback, delay);
+		return () => {
+			clearTimeout(handle);
+		};
+	},
+	interval(callback, delay) {
+		const handle = setInterval(callback, delay);
+		return () => {
+			clearInterval(handle);
+		};
+	}
+};
 var TaskBoardHostService = class {
 	ledger;
 	runner;
 	power;
 	listeners = /* @__PURE__ */ new Set();
-	timers = [];
-	lastScheduleTick;
+	/** The one recurring timer: the session-roster poll. */
+	pollTimer;
+	/** The armed schedule timer, if a trigger is pending. */
+	scheduleTimer;
+	/** The instant the armed schedule timer targets (ms epoch), for resume detection. */
+	scheduleTarget;
 	disposed = false;
 	pollInFlight = false;
-	tickInFlight = false;
 	active = true;
 	/**
 	* Ids the last roster poll saw as present and idle; undefined while the
@@ -3590,6 +3645,7 @@ var TaskBoardHostService = class {
 	idleSessionIds;
 	preventIdleSleep = false;
 	team;
+	timers;
 	lastPowerJson = "";
 	now;
 	constructor(gateway, options = {}) {
@@ -3599,6 +3655,7 @@ var TaskBoardHostService = class {
 		});
 		this.runner = new HostExecutionRunner(gateway, options.commandDispatcher, options.workspaceRegistry);
 		this.team = options.team;
+		this.timers = options.timers ?? PROCESS_TIMERS;
 		this.power = options.power ?? new PowerInhibitor();
 		this.now = options.now ?? Date.now;
 		installStreamErrorGuards();
@@ -3614,16 +3671,13 @@ var TaskBoardHostService = class {
 		});
 	}
 	start() {
-		if (this.disposed || this.timers.length > 0) return;
+		if (this.disposed || this.pollTimer !== void 0) return;
 		this.syncPowerReasons();
-		this.timers.push(setInterval(() => {
+		this.pollTimer = this.timers.interval(() => {
 			this.schedulePoll();
-		}, SESSION_POLL_MS));
-		this.timers.push(setInterval(() => {
-			this.scheduleTick(false);
-		}, SCHEDULE_TICK_MS));
+		}, SESSION_POLL_MS);
 		this.schedulePoll();
-		this.scheduleTick(true);
+		this.recoverSchedule();
 	}
 	setConfiguration(active, preventIdleSleep) {
 		const resumed = !this.active && active;
@@ -3640,8 +3694,8 @@ var TaskBoardHostService = class {
 		this.power.setEnabled(active && preventIdleSleep);
 		if (resumed) {
 			this.schedulePoll();
-			this.scheduleTick(true);
-		}
+			this.recoverSchedule();
+		} else if (!active) this.clearScheduleTimer();
 		this.emit();
 	}
 	snapshot() {
@@ -3679,6 +3733,7 @@ var TaskBoardHostService = class {
 		}
 		const result = this.ledger.applyRequest(requestId, action, initiator);
 		if (result.runs !== void 0) this.dispatchRuns(result.runs);
+		if (SCHEDULE_WRITE_ACTIONS.has(action.kind)) this.refreshSchedule();
 		return {
 			schemaVersion: 3,
 			revision: result.state.revision,
@@ -3689,7 +3744,9 @@ var TaskBoardHostService = class {
 	}
 	dispose() {
 		this.disposed = true;
-		for (const timer of this.timers.splice(0)) clearInterval(timer);
+		this.clearScheduleTimer();
+		this.pollTimer?.();
+		this.pollTimer = void 0;
 		this.power.dispose();
 		this.ledger.dispose();
 		this.listeners.clear();
@@ -3785,20 +3842,67 @@ var TaskBoardHostService = class {
 			} catch {}
 		}
 	}
-	async tickSchedule(first) {
+	/** Drop the armed schedule timer and forget its target. */
+	clearScheduleTimer() {
+		this.scheduleTimer?.();
+		this.scheduleTimer = void 0;
+		this.scheduleTarget = void 0;
+	}
+	/**
+	* Boot / resume recovery: skip every occurrence that came due while the
+	* board was not running and roll each schedule to its next future target,
+	* then arm the timer for the nearest one. Rendering the occurrence is
+	* deliberately not attempted: the ACL of a card that fired hours ago is
+	* stale, and the board's own recovery contract is "missed triggers are
+	* skipped, never replayed".
+	*/
+	recoverSchedule() {
+		if (this.disposed) return;
+		this.clearScheduleTimer();
+		const now = this.now();
+		this.ledger.setScheduler({ lastTickAt: now });
+		this.ledger.skipMissed(now);
+		this.armSchedule();
+	}
+	/**
+	* Arm the native timer at the nearest armed future trigger. One timer serves
+	* every schedule: the ledger's next target is the only instant the Host has
+	* to wake for. A target beyond the platform's timer ceiling re-arms in
+	* segments, and a target already past (the wall clock jumped, or the process
+	* was suspended) is handled immediately as a recovery.
+	*/
+	armSchedule() {
+		if (this.disposed || !this.active) return;
+		this.clearScheduleTimer();
+		const target = this.ledger.nextArmedRunAt(this.now());
+		if (target === void 0) return;
+		this.scheduleTarget = target;
+		const delay = Math.max(0, Math.min(target - this.now(), MAX_TIMER_DELAY_MS));
+		this.scheduleTimer = this.timers.timeout(() => {
+			this.scheduleTimer = void 0;
+			this.onScheduleFire(target);
+		}, delay);
+	}
+	/**
+	* One armed target became due. A fire landing well past its target is a
+	* resume (suspend, throttle, forward clock jump) rather than a normal
+	* occurrence, so it takes the recovery path instead of launching a run for a
+	* long-stale instant.
+	*/
+	onScheduleFire(target) {
 		if (this.disposed || !this.active) return;
 		const now = this.now();
-		const recovered = first || this.lastScheduleTick !== void 0 && now - this.lastScheduleTick > RESUME_GAP_MS;
-		this.lastScheduleTick = now;
+		this.scheduleTarget = void 0;
 		this.ledger.setScheduler({ lastTickAt: now });
-		if (recovered) {
-			this.ledger.skipMissed(now);
+		if (now - target > RECOVERY_TOLERANCE_MS) {
+			this.recoverSchedule();
 			return;
 		}
 		for (const schedule of this.ledger.dueSchedules(now)) {
 			const next = nextRunAtMs(schedule.cron, schedule.nextRunAt);
 			this.dispatchRuns(this.ledger.openScheduled(schedule.taskId, next, now));
 		}
+		this.armSchedule();
 	}
 	armedSchedules() {
 		return this.ledger.armedScheduleCount();
@@ -3831,14 +3935,18 @@ var TaskBoardHostService = class {
 			this.pollInFlight = false;
 		});
 	}
-	scheduleTick(first) {
-		if (this.tickInFlight || this.disposed) return;
-		this.tickInFlight = true;
-		this.tickSchedule(first).catch((error) => {
-			safeConsoleError("[dsh-task-board] scheduler tick failed", error);
-		}).finally(() => {
-			this.tickInFlight = false;
-		});
+	/**
+	* Re-arm from the ledger's current targets. Callers that just changed a
+	* schedule (the host routes, the agent tools) invoke this after the write
+	* commits, so a new or edited trigger arms without waiting for the next fire.
+	*/
+	refreshSchedule() {
+		if (this.disposed) return;
+		if (!this.active) {
+			this.clearScheduleTimer();
+			return;
+		}
+		this.armSchedule();
 	}
 	syncPowerReasons() {
 		const current = this.power.snapshot();
@@ -4895,13 +5003,47 @@ function resolveAccess(access) {
 	};
 }
 /**
+* Harness browser-auth cookie prefix (dsh-client-connection): the
+* authority-bound signed cookie the Host mints in exchange for its launch
+* token. dsh-web's remote channel redeems that token before re-issuing paired
+* traffic to 127.0.0.1 (packages/dsh-remote-web-ui/src/inner-auth.ts), and the
+* official DSH Desktop shell keeps its own copy from the same exchange and
+* attaches it to every request it forwards for the dsh-app://app/ page. The
+* two constants describe one fact and move together.
+*/
+const BROWSER_AUTH_COOKIE_PREFIX = "dsh-auth-";
+/**
+* Whether a Cookie header carries the Host's browser-auth credential. Only an
+* application on this machine can hold it: the desktop shell never lets it
+* reach the page's cookie jar, and SameSite=Strict keeps a cross-site page
+* from attaching it.
+* @param header - the raw Cookie header value.
+*/
+function carriesBrowserAuthCookie(header) {
+	if (header === void 0) return false;
+	return header.split(";").some((segment) => segment.trim().startsWith(BROWSER_AUTH_COOKIE_PREFIX));
+}
+/**
 * Browser-signal tripwire, NOT an authority check: a bare curl sends neither
 * header and is refused, but a curl with a forged Origin passes this too.
 * The real boundary is the loopback socket + Host + origin-equality checks
 * in isTrustedTaskBoardRequest below; do not rely on this marker alone.
+*
+* A first-party client that presents NEITHER header must still pass. The DSH
+* Desktop shell serves the Web GUI from dsh-app://app/ and forwards that
+* page's Host requests itself, deleting origin and sec-fetch-site on the
+* way (dsh-desktop-host's forwardWebRequest), so the panel's own fetch
+* arrives marker-less and every route behind this guard answered 403 - which
+* the panel renders as its board.hostError.unauthorized message. The shell
+* does attach the Host's browser-auth cookie, redeemed from the Host's launch
+* URL at startup and deliberately withheld from the page. That credential,
+* not a header the shell strips, is the browser signal of an application on
+* this machine; a marker-less, credential-less request stays refused.
 */
 function browserSameOriginMarker(req) {
-	return req.headers["sec-fetch-site"] === "same-origin" || typeof req.headers.origin === "string";
+	if (req.headers["sec-fetch-site"] === "same-origin") return true;
+	if (typeof req.headers.origin === "string") return true;
+	return carriesBrowserAuthCookie(req.headers.cookie);
 }
 function sameAuthority(req, host) {
 	if (req.headers["sec-fetch-site"] === "cross-site") return false;
@@ -5113,38 +5255,111 @@ function makeTaskBoardRoutes(service, access = {}, options = {}) {
 * the loader accepts a standalone install of the same package side by side;
 * without this guard the second instance would still re-register the same
 * webserver routes, tools, settings namespaces, and system-prompt sections
-* and fail the boot. mountOnce makes the second host apply a no-op for the
-* lifetime of the first instance (the browser half is already deduped by
-* package name in the client module host).
+* and fail the boot. mountOnce makes a mount of an already-mounted package a
+* no-op for as long as the first instance lives (the browser half is already
+* deduped by package name in the client module host).
+*
+* A no-op is only safe while the holder is ALIVE. The holder can be disposed
+* long after the refused mount ran its course: the Host reloads a profile by
+* creating the new loader entries before the old ones are torn down (a
+* plugin-manager enable/disable/install write, a settings-driven row reload,
+* HMR), so the new aggregate shell entry mounts its family plugin while the
+* previous entry still owns the name. Dropping that refused mount lost the
+* plugin for good - the previous entry then disposed its own mount, releasing
+* the name with nobody left to take it, and the family row stayed listed as
+* active while its host routes 404ed (the task-board panel showed
+* "board.hostError.notMounted", no degraded record appeared, and only a Host
+* restart recovered it).
+*
+* The refused mount is therefore QUEUED, not dropped, and replayed the moment
+* the holder releases the name - if the waiting fiber is still alive then. The
+* single-instance guarantee is unchanged: exactly one mount is live per
+* package name, and the replay re-enters the guard so a later mount still
+* dedupes against it.
 *
 * The registry rides a global symbol so two module instances of the same
-* package (npm copy vs repository link) still share one verdict. cordis
-* `ctx.effect` runs its callback immediately and treats the callback's
+* package (npm copy vs repository link) still share one verdict. That symbol
+* is a CROSS-REPOSITORY contract, not this file's private state: the four
+* satellite packages (dsh-skins / dsh-pet / dsh-presets /
+* dsh-community-plugins) are separate repositories carrying their own copy of
+* this guard, rebuilt on their own schedule, so the value under `MOUNTED`
+* must keep the shape every published copy reads (a `Set` of package names
+* with `has`/`add`/`delete`). The wait queues this guard added therefore live
+* under their own additive key, and the registry reads back a `Set` even when
+* some other build left a different value there. Changing `MOUNTED`'s shape
+* in place broke that contract once: a satellite's legacy copy created a
+* `Set`, the family's new copy read it as a `Map`, and every family row
+* mounted after it failed with "claims.get is not a function".
+*
+* cordis `ctx.effect` runs its callback immediately and treats the callback's
 * return value as the fiber disposer, so the unmarker is returned, not run.
 */
+/** Published cross-repository contract: package names currently mounted. */
 const MOUNTED = Symbol.for("dsh-web.mounted-plugins");
+/** Additive key this guard owns: refused mounts waiting for the name. */
+const WAITERS = Symbol.for("dsh-web.mounted-plugins.waiters");
+/**
+* The shared name registry, always a `Set` whatever another build stored here:
+* a foreign value (an interim shape, a hand-written global) must not take every
+* family plugin down with it.
+* @returns the process-wide set of mounted package names.
+*/
 function mountedSet() {
 	const registry = globalThis;
-	return registry[MOUNTED] ??= /* @__PURE__ */ new Set();
+	const existing = registry[MOUNTED];
+	if (existing instanceof Set) return existing;
+	const created = /* @__PURE__ */ new Set();
+	registry[MOUNTED] = created;
+	return created;
+}
+/** Queue per package name for mounts refused while a holder was alive. */
+function mountWaiters() {
+	const registry = globalThis;
+	return registry[WAITERS] ??= /* @__PURE__ */ new Map();
 }
 /**
 * Wrap a cordis plugin apply so the package runs at most once per process.
-* The first mount registers normally and unmarks when its fiber disposes;
-* any later mount of the same package name is a no-op.
+* The first mount registers normally and releases the name when its fiber
+* disposes; a mount refused while that name is held waits for the release and
+* then runs, unless its own fiber disposes first.
 * @param packageName - npm package identity shared by every install source.
 * @param fn - the original plugin apply.
 * @returns an apply of the same shape.
 */
 function mountOnce(packageName, fn) {
-	return ((...args) => {
+	const mount = (...args) => {
 		const mounted = mountedSet();
-		if (mounted.has(packageName)) return;
+		const ctx = args[0];
+		if (mounted.has(packageName)) {
+			const waiters = mountWaiters();
+			const queue = waiters.get(packageName) ?? [];
+			let alive = true;
+			const pending = { run: () => {
+				if (alive) mount(...args);
+			} };
+			ctx?.effect?.(() => () => {
+				alive = false;
+				const index = queue.indexOf(pending);
+				if (index >= 0) queue.splice(index, 1);
+			});
+			queue.push(pending);
+			waiters.set(packageName, queue);
+			return;
+		}
 		mounted.add(packageName);
-		args[0]?.effect?.(() => () => {
+		ctx?.effect?.(() => () => {
 			mounted.delete(packageName);
+			const waiters = mountWaiters();
+			const queue = waiters.get(packageName);
+			if (queue === void 0) return;
+			waiters.delete(packageName);
+			for (const waiter of queue.splice(0)) queueMicrotask(() => {
+				waiter.run();
+			});
 		});
 		return fn(...args);
-	});
+	};
+	return mount;
 }
 //#endregion
 //#region src/index.ts
@@ -5228,6 +5443,27 @@ function resolveToolRegistry(ctx) {
 		return;
 	}
 }
+/**
+* Resolve the native cordis timer service (dsh-base's own `cordis-plugin-timer`
+* row). The board arms its schedule through it so unloading the row clears
+* every pending timer with the owning fiber, instead of the row tracking raw
+* process handles by hand. A composition that serves no timer service keeps
+* working on the process globals.
+* @param ctx - the plugin context.
+* @returns the timer face, or undefined when this deployment serves none.
+*/
+function resolveHostTimers(ctx) {
+	try {
+		const timer = ctx.get("timer");
+		if (timer === void 0) return void 0;
+		return typeof timer.timeout === "function" && typeof timer.interval === "function" ? {
+			timeout: timer.timeout.bind(timer),
+			interval: timer.interval.bind(timer)
+		} : void 0;
+	} catch {
+		return;
+	}
+}
 /** Schema default, re-read for hand-built test contexts (the loader applies them normally). */
 const DEFAULT_ANNOUNCE = false;
 /**
@@ -5331,6 +5567,7 @@ function applyImpl(ctx, config) {
 		workspaceRegistry: ctx.workspaceRegistry,
 		sessionDefaultPermission: config?.sessionDefaultPermission ?? "read-only",
 		maxSubtaskDepth: maxSubtaskDepth(),
+		timers: resolveHostTimers(ctx),
 		team: buildTeamDispatcher(ctx, config?.teamProvider ?? "spawn"),
 		commandDispatcher: { async execute(sessionId, line, signal) {
 			const agent = ctx.agents.get(sessionId);
@@ -5416,4 +5653,4 @@ function applyImpl(ctx, config) {
 	sync();
 }
 //#endregion
-export { Config, DEFAULT_PROXY_TOKEN_ENV, DEFAULT_TEAM_PROVIDER, TASK_BOARD_GUIDANCE, apply, buildTeamDispatcher, inject, readConfigField, resolveAgentTeams, resolveLlmRuntime, resolveProxyAccess, resolveToolRegistry };
+export { Config, DEFAULT_PROXY_TOKEN_ENV, DEFAULT_TEAM_PROVIDER, TASK_BOARD_GUIDANCE, apply, buildTeamDispatcher, inject, readConfigField, resolveAgentTeams, resolveHostTimers, resolveLlmRuntime, resolveProxyAccess, resolveToolRegistry };

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

@@ -9,7 +9,7 @@
  * plugin must not take the GUI down.
  */
 import type { Context as ClientContext } from '@deepseek-ai/cordis';
-import type { ConfigForm } from '@deepseek-ai/dsh-client-ui-settings/client';
+import type { ConfigForm, ConfigForms } from '@deepseek-ai/dsh-client-ui-settings/client';
 import { type TaskBoardSettings } from './TaskBoardSettingsCard.tsx';
 import { type TaskBoardKey } from './locales.ts';
 /** Domain-owned description of one settings namespace a family card binds. */
@@ -94,3 +94,17 @@ export declare function apply(ctx: ClientContext): void;
  * @returns the form the settings card reads and writes.
  */
 export declare function bindSettingsForm(ctx: ClientContext): ConfigForm<TaskBoardSettings>;
+/**
+ * The profile entry id this package's own row carries, for a page that serves
+ * no family binder.
+ *
+ * The shared describe mirror is the only local evidence of which row id this
+ * profile actually serves, but it answers asynchronously: at plugin activation
+ * it usually holds nothing yet. An unanswered mirror therefore binds the
+ * aggregate row id rather than guessing among the candidates, and the binding
+ * is re-resolved once the mirror answers — see
+ * {@link createServedEntryForm}, which owns that rebinding.
+ * @param forms - the shared configuration forms service.
+ * @returns the entry id to bind before the mirror answers.
+ */
+export declare function servedEntryId(forms: ConfigForms): string;

package/lib/types/client/native-panel.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Native panel registration for the task board.
+ *
+ * The board is an official-style center-column panel, not a DOM takeover: it
+ * contributes a row into the sidebar shell's own global panel list
+ * (`sidebar.panellist`) and its page into the layout's keyed `main` slot. The
+ * shell then owns the row box, the label, the active highlight, the collapsed
+ * rail, the panel switch and the window-chrome interplay exactly as it does for
+ * the shipped Plugins and Schedule pages, so the board renders through the same
+ * container the desktop application's Plugins page uses.
+ *
+ * Both registrations go through `ctx.slots.inject`, which fires only once the
+ * owning shell entry has declared the seat: load order between this plugin and
+ * ui-layout / ui-sidebar therefore does not matter, and neither does a shell
+ * that cannot serve the seats (the callback simply never runs).
+ *
+ * @module @linxin666/dsh-client-ui-task-board/client
+ */
+import type { Context as ClientContext } from '@deepseek-ai/cordis';
+import { TASK_BOARD_PANEL_ID, type BoardController } from '../core/controller.ts';
+/** The panel id shared by the sidebar row and the main-slot occupant. */
+export { TASK_BOARD_PANEL_ID };
+/**
+ * The sidebar row glyph the shell asks for at its own size and active state.
+ * The shell owns the button, label, tooltip and rail geometry; this component
+ * draws only the glyph, like every other panel row.
+ *
+ * The glyph carries `data-dsh-panel-entry` because it is the only DOM the
+ * panel's own code owns inside that shell-owned row: the L2 contract (skins)
+ * resolves which row belongs to which plugin through it, since the shell
+ * stamps no per-entry hook of its own (see contracts/semantic-attrs-v1.md).
+ * @param props - the shell's icon share: square edge and selection state.
+ * @returns the decorative board glyph.
+ */
+export declare function TaskBoardPanelIcon({ size }: {
+    size: number;
+    active: boolean;
+}): React.ReactElement;
+/**
+ * The main-slot page. The layout mounts it only while the board is the selected
+ * panel, so the conversation keeps the center column untouched the rest of the
+ * time; the wrapper carries the pinned `data-dsh-taskboard-view` semantic
+ * anchor (L2 contract, skins) and the container query context the board's
+ * responsive rules read.
+ * @param props - the framework main-slot share plus this entry's injected face.
+ * @returns the board page.
+ */
+export declare function TaskBoardPanel({ controller }: {
+    controller: BoardController;
+}): React.ReactElement;
+/**
+ * Register the board's sidebar row and center-column page.
+ *
+ * Both seats are declared by shell plugins this package does not depend on at
+ * runtime, so each registration is wrapped in `ctx.slots.inject`: the callback
+ * runs only after the owning entry declares the seat, and a shell that never
+ * declares it leaves the board simply absent instead of failing boot.
+ * @param ctx - client root context (services: slots).
+ * @param controller - the board controller the page and the row drive.
+ * @returns disposer releasing both registrations.
+ */
+export declare function registerTaskBoardPanel(ctx: ClientContext, controller: BoardController): () => void;

package/lib/types/client/settings-entry-form.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Family settings form bound to the profile entry id a Host actually serves.
+ *
+ * Under the 0.1.7 settings model a form is addressed by PROFILE ENTRY ID, while
+ * a family card knows only its own settings namespace. The family binder
+ * (`ctx.get('webUiSettings')`, published by dsh-web-settings) resolves one onto
+ * the other and is the preferred transport; this module is the fallback for a
+ * page that serves no binder — the group plugin is not installed, or its client
+ * half has not applied yet (the aggregate mounts its children in order, and a
+ * child still waiting on its own injects publishes nothing).
+ *
+ * The shared describe mirror is the only local evidence of which row id this
+ * profile serves, but it answers asynchronously: at plugin activation it usually
+ * holds nothing yet. A one-shot guess therefore cannot be right for every
+ * deployment, and the form is bound once per session:
+ *
+ * - binding the bare namespace made every save answer `No configurable plugin
+ *   entry "<namespace>"` on an aggregate install (the namespace is not an entry
+ *   id there), which the card reported as "the deployment did not accept these
+ *   values";
+ * - binding the aggregate row id would break a standalone install, whose row id
+ *   is the namespace or the package's own `ui-*` row.
+ *
+ * So the fallback starts on the most likely row and REBINDS the moment the
+ * mirror names one of this package's rows. Until the mirror answers, the form
+ * reports the binding it holds (usually `loading`), which the card renders as an
+ * unavailable form rather than a doomed one.
+ */
+import type { ConfigForm, ConfigForms } from '@deepseek-ai/dsh-client-ui-settings/client';
+/** Options of {@link createServedEntryForm}. */
+export interface ServedEntryFormOptions<T> {
+    /** The shared configuration forms service (`ctx.configForms`). */
+    forms: ConfigForms;
+    /**
+     * Profile entry ids this package's rows carry, most likely first: the
+     * aggregate's generated row, the package's own standalone row, then the bare
+     * namespace. The first is the fallback while the mirror has no answer; the
+     * last is the answer when the mirror serves none of them.
+     */
+    entryIds: readonly string[];
+}
+/**
+ * Create a settings form bound to the profile entry id this Host serves, and
+ * rebound whenever the shared describe mirror names a different one of this
+ * package's rows.
+ * @param options - the shared forms service and this package's candidate row ids.
+ * @returns a form delegating to the currently resolved entry's own form.
+ */
+export declare function createServedEntryForm<T>(options: ServedEntryFormOptions<T>): ConfigForm<T>;

package/lib/types/core/controller.d.ts

@@ -43,6 +43,19 @@ export interface SessionsControllerFace {
     /** Subscribe to catalog changes; selection ownership rides the same snapshot. */
     subscribe(fn: () => void): () => void;
 }
+/** Stable id shared by the board's sidebar panel row and its main-slot page. */
+export declare const TASK_BOARD_PANEL_ID = "task-board";
+/**
+ * The layout's panel-navigation face. The board no longer owns the center
+ * column at the DOM level: selecting the panel is the layout's business, and
+ * this is the one call that asks for it (null returns to the conversation).
+ * Optional, so a composition without the layout service keeps the board's
+ * pure state transitions testable.
+ */
+export interface PanelNavigationFace {
+    /** Select the board panel, or null to hand the column back to the conversation. */
+    select(panelId: string | null): void;
+}
 /** Controller dependencies (all swappable in tests). */
 export interface ControllerDeps {
     store: TaskStore;
@@ -53,6 +66,8 @@ export interface ControllerDeps {
     uuid?: () => string;
     /** Host-authoritative transport; absent keeps the legacy in-memory test path. */
     transport?: TaskBoardTransport;
+    /** Layout panel selection; absent keeps the board state-only (tests, shell-less hosts). */
+    panel?: PanelNavigationFace;
 }
 /**
  * Register one host directory as a DSH project (workspace). Wired by the
@@ -149,9 +164,33 @@ export declare class BoardController {
     isHostBacked(): boolean;
     /** Retry initial migration/state synchronization after an explicit Host error. */
     retryHostSync(): Promise<boolean>;
+    /**
+     * Show the board. The layout owns which panel the center column renders, so
+     * the state flip and the panel selection travel together here; a composition
+     * with no layout face (tests, a shell-less host) still flips the state.
+     *
+     * The selection is requested AFTER the snapshot flips so a subscriber
+     * rendering against `boardOpen` never observes "open" while the shell still
+     * shows the conversation.
+     */
     openBoard(): void;
+    /**
+     * Return the center column to the conversation. The layout's own selection is
+     * the source of truth for what the column renders, so this asks for the
+     * conversation explicitly rather than only clearing local state.
+     */
     closeBoard(): void;
     toggleBoard(): void;
+    /**
+     * Reflect a panel selection that came from OUTSIDE this controller (the user
+     * clicked another sidebar row, or the layout dropped the panel id). Keeps
+     * `boardOpen` aligned with what the column actually shows without asking the
+     * layout to select anything back.
+     * @param panelId - the layout's current panel id, or null for the conversation.
+     */
+    syncPanelSelection(panelId: string | null): void;
+    /** Ask the layout to select a panel; a shell that serves no layout face is a no-op. */
+    private selectPanel;
     /**
      * Switch between the kanban columns and the archive view. Leaving the
      * archive view with an archived task still selected closes the selection —
@@ -259,8 +298,8 @@ export declare class BoardController {
      * (background navigation, the Host runner creating and selecting a fresh
      * execution session, settlement, other plugins), so closing on `current`
      * changes would evict the board without the user asking. The board closes
-     * only on explicit user navigation: a sidebar session/workspace row click
-     * (board-mount onClickSidebarRow) or the board's own actions
+     * only on explicit user navigation: selecting another panel (the layout owns
+     * selection, and `syncPanelSelection` follows it) or the board's own actions
      * (openSession / close). Keeping the hook preserves the subscription
      * contract for future listeners.
      */