@linxin666/dsh-client-ui-task-board 0.1.14 → 0.1.15

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

@@ -1,22 +1,27 @@
 /**
- * Shared chrome for the plugin settings card: a disclosure header naming the
- * plugin and what its settings govern, the controls inside, and the save that
- * writes them. Renders nothing while the namespace is unavailable — a
+ * Family-shared chrome for plugin settings cards: a disclosure header naming
+ * the plugin and what its settings govern, the controls inside, and the save
+ * that writes them. Renders nothing while the namespace is unavailable — a
  * deployment that does not compose the owning plugin should show no trace of
- * it. Mirrors the official ui-plugin-config PluginCard in a self-contained
- * slice (this package must not depend on a sibling UI package).
+ * it. Inlined into each consumer's client bundle; mirrors the official
+ * ui-plugin-config PluginCard in a self-contained slice.
  */
 import { type ReactNode } from 'react';
 import type { CardShell } from './settings-form.ts';
-import type { SettingsCardKey } from './locales.ts';
+/** Copy keys the card chrome itself reads; every consumer locale carries this shared vocabulary. */
+export declare const CARD_COPY_KEYS: readonly ["settings.collapse", "settings.expand", "settings.notExposed", "settings.unsaved", "settings.readOnly", "settings.saveFailed", "settings.discard", "settings.save", "settings.saving"];
+/** Copy key the card chrome itself reads. */
+export type CardCopyKey = (typeof CARD_COPY_KEYS)[number];
+/** Key domain for the plugin's own copy (inferred per consumer). */
+export type SettingsCardKey<TKey extends string = string> = TKey | CardCopyKey;
 /** Card chrome shared by every plugin settings card. */
-export interface PluginSettingsCardProps {
+export interface PluginSettingsCardProps<TKey extends string = string> {
     /** Locale reader for this card's copy. */
-    t: (key: SettingsCardKey) => string;
+    t: (key: SettingsCardKey<TKey>, params?: Record<string, string | number>) => string;
     /** Locale key of the plugin's name. */
-    titleKey: SettingsCardKey;
+    titleKey: TKey;
     /** Locale key of the line describing what this plugin's settings govern. */
-    descriptionKey: SettingsCardKey;
+    descriptionKey: TKey;
     /** The card's form state: availability, writability, and what a save would do. */
     state: CardShell;
     /** Write every staged edit. */
@@ -31,7 +36,7 @@ export interface PluginSettingsCardProps {
  * @param props - the plugin's copy keys, its form state, and its controls.
  * @returns the card, or nothing while the namespace is still loading.
  */
-export declare function PluginSettingsCard(props: PluginSettingsCardProps): import("react").JSX.Element | null;
+export declare function PluginSettingsCard<TKey extends string = string>(props: PluginSettingsCardProps<TKey>): import("react").JSX.Element | null;
 /** Props every field control needs regardless of its value type. */
 export interface FieldProps {
     /** Stable id associating the label with its control. */
@@ -75,3 +80,13 @@ export declare function BooleanField(props: FieldProps & {
     /** Copy for the off option. */
     offLabel: string;
 }): import("react").JSX.Element;
+/** A staged enumerated field rendered as a select. */
+export declare function ChoiceField(props: FieldProps & {
+    /** Copy for the inherit option (draft text is the empty string). */
+    inheritLabel: string;
+    /** Choices rendered in order; `value` is the draft/stored text. */
+    choices: ReadonlyArray<{
+        value: string;
+        label: string;
+    }>;
+}): import("react").JSX.Element;

package/lib/types/client/board/TaskCard.d.ts

@@ -1,12 +1,11 @@
-/**
- * Task card: the board's column item. Clicking opens the task detail — it
- * never executes anything directly (detail holds the Run button).
- */
 import type { TaskRecord } from '../../core/tasks.ts';
 /** Compact relative/absolute time label. */
 export declare function formatTime(ms: number): string;
 /** One card in a column. */
-export declare function TaskCard({ task, onClick }: {
+declare function TaskCardInner({ task, onClick }: {
     task: TaskRecord;
     onClick: () => void;
 }): import("react").JSX.Element;
+/** Memoized card: re-renders only when the card's own task record changes. */
+export declare const TaskCard: import("react").MemoExoticComponent<typeof TaskCardInner>;
+export {};

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

@@ -2,9 +2,9 @@
  * Staged form model behind the plugin settings card. A card stages what the
  * user types and writes it only when they save — the settings write is a
  * durable, revision-fenced document mutation, so staging keeps what is on
- * screen exactly what a save would store. Mirrors the official
- * ui-plugin-config card-store pattern in a self-contained slice: this
- * package must not depend on a sibling UI package.
+ * screen exactly what a save would store. Family-shared slice inlined into
+ * each plugin's client bundle; mirrors the official ui-plugin-config
+ * card-store pattern.
  */
 import type { SettingsScope, SnapshotStore } from '@deepseek-ai/dsh-client-runtime/client';
 /** The write one field's staged text performs when the card is saved. */
@@ -69,12 +69,21 @@ export interface CardActions {
     /** Drop every staged edit. */
     discard: () => void;
 }
-/** A whole-number field. An empty draft clears the field; any other draft that is not a finite number blocks the save. */
-export declare function numberField(field: string): FieldSpec;
+/** Constraints a numeric field's accepted drafts must satisfy, mirroring the host schema. */
+export interface NumberConstraints {
+    /** The accepted value must be a whole number. */
+    integer?: boolean;
+    /** The accepted value must be at least this. */
+    min?: number;
+}
+/** A whole- or decimal-number field. An empty draft clears the field; any other draft that is not a finite number within the constraints blocks the save. */
+export declare function numberField(field: string, constraints?: NumberConstraints): FieldSpec;
 /** A free-text field. An empty draft clears the field. */
 export declare function textField(field: string): FieldSpec;
 /** A boolean field, edited through true/false draft text. */
 export declare function booleanField(field: string): FieldSpec;
+/** An enumerated string field; only the listed choices are accepted. An empty draft clears the field. */
+export declare function choiceField(field: string, choices: readonly string[]): FieldSpec;
 /**
  * Stages one card's edits over one settings namespace and writes them on save.
  *

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

@@ -7,6 +7,11 @@
  * navigates to a session (the sessions-list `current` selection changes).
  * Framework-free (structural runtime faces) so the whole orchestration is
  * unit-testable with fakes.
+ *
+ * The per use-case domain transitions (create/update/delete/schedule) live in
+ * dedicated modules under core/use-cases and are applied here; the controller
+ * owns only the orchestration seam (state, persistence, notify, execution,
+ * navigation, reconciliation).
  */
 import { ExecutionService } from './execution.ts';
 import type { TaskStore } from './store.ts';
@@ -76,7 +81,7 @@ export declare class BoardController {
      * Update a task's schedule rule. A blank or invalid cron expression is
      * rejected (returns false, state untouched). When the rule ends up enabled
      * the next run instant is computed immediately; a disabled rule carries no
-     * next-run instant.
+     * next-run instant. Delegates the domain transition to the schedule use case.
      * @param id - the task to schedule.
      * @param patch - fields to change (absent fields keep their current value).
      * @returns true when applied, false when rejected (invalid cron / unknown task).

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

@@ -31,11 +31,23 @@ export interface SchedulerDeps {
 export declare class SchedulerService {
     private readonly deps;
     private timer;
+    private environmentListener;
     private disposed;
+    private started;
     /** @param deps - tasks/clock/trigger/apply faces (see {@link SchedulerDeps}). */
     constructor(deps: SchedulerDeps);
-    /** Start ticking: one immediate check (catch-up after reload) + the interval. */
+    /**
+     * Start ticking: one immediate check (catch-up after reload) + the interval.
+     * Single-instance: a second start while already armed is a no-op, so a
+     * re-entrant mount can never stack a duplicate timer.
+     */
     start(): void;
+    /**
+     * Stop ticking and drop listeners (idempotent). Preferred shutdown verb for
+     * callers that treat the scheduler as a controlled ticker; `dispose` is an
+     * alias.
+     */
+    stop(): void;
     /** Stop ticking and drop listeners (idempotent). */
     dispose(): void;
     /**
@@ -45,5 +57,4 @@ export declare class SchedulerService {
      * tick instead of being silently dropped.
      */
     tick(): Promise<void>;
-    private readonly onVisibility;
 }

package/lib/types/core/use-cases/task-create.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Create-task use case: mint a new task from user input, rejecting a blank
+ * title. Pure ledger transition (no persistence or notify — the controller
+ * orchestrates those), so it is unit-testable without any runtime face.
+ */
+import { type NewTaskInput, type TaskRecord } from '../tasks.ts';
+/** Result of a create transition: the new task (when accepted) + the next ledger. */
+export interface CreateTaskResult {
+    /** The minted task, or undefined when the input was rejected (blank title). */
+    task: TaskRecord | undefined;
+    /** The next ledger; identical reference when rejected. */
+    tasks: readonly TaskRecord[];
+}
+/**
+ * Apply a create against the current ledger. Returns the new task and the
+ * appended ledger, or the unchanged ledger when the title is blank.
+ * @param tasks - current ledger.
+ * @param input - raw user input (title/description/prompt).
+ * @param now - clock instant (ms epoch).
+ * @param id - minted task id.
+ */
+export declare function applyCreateTask(tasks: readonly TaskRecord[], input: NewTaskInput, now: number, id: string): CreateTaskResult;

package/lib/types/core/use-cases/task-delete.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Delete-task use case: drop a task from the ledger and clear the selection
+ * when it pointed at the removed task. Pure ledger transition (no persistence
+ * or notify — the controller orchestrates those).
+ */
+import type { TaskRecord } from '../tasks.ts';
+/** Result of a delete transition. */
+export interface DeleteTaskResult {
+    /** The next ledger (the removed task absent). */
+    tasks: readonly TaskRecord[];
+    /** Whether the previous selection referenced the removed task. */
+    selectionCleared: boolean;
+}
+/**
+ * Apply a delete across the ledger. The selection (a task id) is cleared when
+ * it matches the removed task, so the UI never lingers on a vanished detail.
+ * @param tasks - current ledger.
+ * @param selectedTaskId - the currently selected task id (may be undefined).
+ * @param id - the task to remove.
+ */
+export declare function applyDeleteTask(tasks: readonly TaskRecord[], selectedTaskId: string | undefined, id: string): DeleteTaskResult;

package/lib/types/core/use-cases/task-schedule.d.ts

@@ -0,0 +1,34 @@
+import { type TaskRecord } from '../tasks.ts';
+/** Fields the schedule use case may change on a rule. */
+export interface SetSchedulePatch {
+    enabled?: boolean;
+    cron?: string;
+}
+/** Result of arming/disarming a rule. */
+export interface SetScheduleResult {
+    /** The next ledger; unchanged reference when rejected. */
+    tasks: readonly TaskRecord[];
+    /** Whether the rule was applied (false on unknown task / invalid cron). */
+    applied: boolean;
+}
+/**
+ * Set a task's schedule rule. A blank or invalid cron is rejected (state
+ * untouched); an enabled rule computes the next run instant immediately, a
+ * disabled or invalid one carries no next-run instant.
+ * @param tasks - current ledger.
+ * @param id - the task to schedule.
+ * @param patch - rule fields to change (absent fields keep their current value).
+ * @param now - clock instant (ms epoch).
+ */
+export declare function applySetSchedule(tasks: readonly TaskRecord[], id: string, patch: SetSchedulePatch, now: number): SetScheduleResult;
+/**
+ * Roll a task's schedule rule forward (scheduler callback): persist the next
+ * due instant and the trigger instant. No-op for tasks without a rule (deleted
+ * mid-tick, for example).
+ * @param tasks - current ledger.
+ * @param id - the task to roll forward.
+ * @param nextRunAt - next due instant (may be undefined to clear).
+ * @param lastTriggeredAt - the trigger instant of this run.
+ * @param now - clock instant (ms epoch).
+ */
+export declare function applyScheduleNextRun(tasks: readonly TaskRecord[], id: string, nextRunAt: number | undefined, lastTriggeredAt: number | undefined, now: number): readonly TaskRecord[];

package/lib/types/core/use-cases/task-update.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Update-task use case: apply an editable-field patch (title/description/
+ * prompt) with a fresh updatedAt. Pure ledger transition (no persistence or
+ * notify — the controller orchestrates those).
+ */
+import type { TaskRecord } from '../tasks.ts';
+/** Editable fields on a task (the update patch surface). */
+export type TaskUpdatePatch = Partial<Pick<TaskRecord, 'title' | 'description' | 'prompt'>>;
+/**
+ * Apply an update across the ledger. Tasks that do not match the id are left
+ * untouched; the matched task receives the patch plus a fresh updatedAt.
+ * @param tasks - current ledger.
+ * @param id - the task to update.
+ * @param patch - editable-field changes.
+ * @param now - clock instant (ms epoch).
+ */
+export declare function applyUpdateTask(tasks: readonly TaskRecord[], id: string, patch: TaskUpdatePatch, now: number): readonly TaskRecord[];

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@linxin666/dsh-client-ui-task-board",
   "description": "Task board for the dsh web GUI: a sidebar entry plus a multi-column kanban view with local persistence, task details, and real execution through dsh sessions (session.prompt). Hot-pluggable — mounted via ~/.dsh/cordis.patch.yml + a profile node_modules symlink, no dsh source changes.",
-  "version": "0.1.14",
+  "version": "0.1.15",
   "type": "module",
   "main": "lib/index.js",
   "types": "lib/types/index.d.ts",

package/src/client/PluginSettingsCard.tsx

@@ -1,25 +1,44 @@
+// Generated by scripts/sync-shared.mjs from shared/client/settings/PluginSettingsCard.tsx. Do not edit this copy; edit the shared source and run "node scripts/sync-shared.mjs".
 /**
- * Shared chrome for the plugin settings card: a disclosure header naming the
- * plugin and what its settings govern, the controls inside, and the save that
- * writes them. Renders nothing while the namespace is unavailable — a
+ * Family-shared chrome for plugin settings cards: a disclosure header naming
+ * the plugin and what its settings govern, the controls inside, and the save
+ * that writes them. Renders nothing while the namespace is unavailable — a
  * deployment that does not compose the owning plugin should show no trace of
- * it. Mirrors the official ui-plugin-config PluginCard in a self-contained
- * slice (this package must not depend on a sibling UI package).
+ * it. Inlined into each consumer's client bundle; mirrors the official
+ * ui-plugin-config PluginCard in a self-contained slice.
  */
 
 import { useState, type ReactNode } from 'react'
 import type { CardShell } from './settings-form.ts'
-import type { SettingsCardKey } from './locales.ts'
 import css from './settings-card.module.css'
 
+/** Copy keys the card chrome itself reads; every consumer locale carries this shared vocabulary. */
+export const CARD_COPY_KEYS = [
+  'settings.collapse',
+  'settings.expand',
+  'settings.notExposed',
+  'settings.unsaved',
+  'settings.readOnly',
+  'settings.saveFailed',
+  'settings.discard',
+  'settings.save',
+  'settings.saving',
+] as const
+
+/** Copy key the card chrome itself reads. */
+export type CardCopyKey = (typeof CARD_COPY_KEYS)[number]
+
+/** Key domain for the plugin's own copy (inferred per consumer). */
+export type SettingsCardKey<TKey extends string = string> = TKey | CardCopyKey
+
 /** Card chrome shared by every plugin settings card. */
-export interface PluginSettingsCardProps {
+export interface PluginSettingsCardProps<TKey extends string = string> {
   /** Locale reader for this card's copy. */
-  t: (key: SettingsCardKey) => string
+  t: (key: SettingsCardKey<TKey>, params?: Record<string, string | number>) => string
   /** Locale key of the plugin's name. */
-  titleKey: SettingsCardKey
+  titleKey: TKey
   /** Locale key of the line describing what this plugin's settings govern. */
-  descriptionKey: SettingsCardKey
+  descriptionKey: TKey
   /** The card's form state: availability, writability, and what a save would do. */
   state: CardShell
   /** Write every staged edit. */
@@ -35,11 +54,12 @@ export interface PluginSettingsCardProps {
  * @param props - the plugin's copy keys, its form state, and its controls.
  * @returns the card, or nothing while the namespace is still loading.
  */
-export function PluginSettingsCard(props: PluginSettingsCardProps) {
+export function PluginSettingsCard<TKey extends string = string>(props: PluginSettingsCardProps<TKey>) {
   const [open, setOpen] = useState(false)
   const { state } = props
   if (!state.available) return null
   const title = props.t(props.titleKey)
+  const description = props.t(props.descriptionKey)
   const blocked = !state.dirty || state.invalid || state.saving
   const cardClass = open ? `${css.cardOpen} ${css.card}` : css.card
   // The namespace exists but the Host does not serve it to this client (the
@@ -57,8 +77,8 @@ export function PluginSettingsCard(props: PluginSettingsCardProps) {
           onClick={() => { setOpen(!open) }}
         >
           <span className={css.headText}>
-            <span className={css.name}>{title}</span>
-            <span className={css.description}>{props.t(props.descriptionKey)}</span>
+            <span className={css.name} title={title}>{title}</span>
+            <span className={css.description} title={description}>{description}</span>
           </span>
           <svg
             width="14"
@@ -94,10 +114,10 @@ export function PluginSettingsCard(props: PluginSettingsCardProps) {
         onClick={() => { setOpen(!open) }}
       >
         <span className={css.headText}>
-          <span className={css.name}>{title}</span>
-          <span className={css.description}>{props.t(props.descriptionKey)}</span>
+          <span className={css.name} title={title}>{title}</span>
+          <span className={css.description} title={description}>{description}</span>
         </span>
-        {state.dirty ? <span className={css.pending}>{props.t('settings.unsaved')}</span> : null}
+        {state.dirty ? <span className={css.pending} title={props.t('settings.unsaved')}>{props.t('settings.unsaved')}</span> : null}
         <svg
           width="14"
           height="14"
@@ -259,4 +279,50 @@ export function BooleanField(props: FieldProps & {
       <p className={css.hint}>{props.hint}</p>
     </div>
   )
-}
+}
+
+/** A staged enumerated field rendered as a select. */
+export function ChoiceField(props: FieldProps & {
+  /** Copy for the inherit option (draft text is the empty string). */
+  inheritLabel: string
+  /** Choices rendered in order; `value` is the draft/stored text. */
+  choices: ReadonlyArray<{ value: string; label: string }>
+}) {
+  return (
+    <div className={css.field}>
+      <div className={css.head}>
+        <label className={css.label} htmlFor={props.id}>{props.label}</label>
+        {props.overridden
+          ? (
+            <span className={css.badges}>
+              <span className={css.badge}>{props.overriddenLabel}</span>
+              <button
+                type="button"
+                className={css.reset}
+                disabled={props.disabled}
+                onClick={props.onReset}
+              >
+                {props.resetLabel}
+              </button>
+            </span>
+          )
+          : null}
+      </div>
+      <select
+        id={props.id}
+        className={css.select}
+        value={props.text}
+        disabled={props.disabled}
+        onChange={(event) => { props.onEdit(event.target.value) }}
+      >
+        <option value="">{props.inheritLabel}</option>
+        {props.choices.map(choice => (
+          <option key={choice.value} value={choice.value}>{choice.label}</option>
+        ))}
+      </select>
+      <p className={props.invalid ? css.invalid : css.hint}>
+        {props.invalid ? props.invalidLabel : props.hint}
+      </p>
+    </div>
+  )
+}

package/src/client/board/TaskBoard.tsx

@@ -3,7 +3,7 @@
  * active. Cards open the task detail (never execute directly); the header
  * offers filter, new-task, and a back-to-chat escape.
  */
-import { useEffect, useState } from 'react'
+import { memo, useCallback, useEffect, useState } from 'react'
 import { selectedTaskOf, type BoardController } from '../../core/controller.ts'
 import { COLUMNS, type TaskRecord, type TaskStatus } from '../../core/tasks.ts'
 import { t, type TaskBoardKey } from '../locales.ts'
@@ -28,6 +28,17 @@ function matchesFilter(task: TaskRecord, filter: string): boolean {
   return task.title.toLowerCase().includes(needle) || task.description.toLowerCase().includes(needle)
 }
 
+/**
+ * Memoized per-card adapter: with a stable `onOpen` from the board and an
+ * immutable task record (only the changed card gets a new object ref), a card
+ * re-renders only when its own task changes — not when a sibling card status,
+ * the filter, or the selection moves.
+ */
+const MemoTaskCard = memo(function MemoTaskCard({ task, onOpen }: { task: TaskRecord; onOpen: (id: string) => void }) {
+  const onClick = useCallback(() => { onOpen(task.id) }, [task.id, onOpen])
+  return <TaskCard task={task} onClick={onClick} />
+})
+
 /** Board component; subscribes to the controller snapshot. */
 export function TaskBoard({ controller }: { controller: BoardController }) {
   const [snapshot, setSnapshot] = useState(controller.getSnapshot())
@@ -39,6 +50,7 @@ export function TaskBoard({ controller }: { controller: BoardController }) {
   const [showNew, setShowNew] = useState(false)
   const selected = selectedTaskOf(snapshot)
   const visible = snapshot.tasks.filter(task => matchesFilter(task, filter))
+  const openTask = useCallback((id: string): void => { controller.openTask(id) }, [controller])
 
   return (
     <div className={css.board} data-dsh-taskboard-board="">
@@ -80,11 +92,7 @@ export function TaskBoard({ controller }: { controller: BoardController }) {
               </header>
               <div className={css.cards}>
                 {tasks.map(task => (
-                  <TaskCard
-                    key={task.id}
-                    task={task}
-                    onClick={() => { controller.openTask(task.id) }}
-                  />
+                  <MemoTaskCard key={task.id} task={task} onOpen={openTask} />
                 ))}
                 {tasks.length === 0 && <div className={css.columnEmpty}>{t('board.empty')}</div>}
               </div>

package/src/client/board/TaskCard.tsx

@@ -1,7 +1,13 @@
 /**
  * Task card: the board's column item. Clicking opens the task detail — it
  * never executes anything directly (detail holds the Run button).
+ *
+ * Memoized: the card re-renders only when its own task record changes, so a
+ * status/filter update on one card (or scrolling) never re-renders every
+ * card on the board. The per-card onClick is built with a stable task reference
+ * by the board, so the memo boundary is effective.
  */
+import { memo } from 'react'
 import type { TaskRecord } from '../../core/tasks.ts'
 import { executionLabel } from '../../core/tasks.ts'
 import { t } from '../locales.ts'
@@ -19,7 +25,7 @@ export function formatTime(ms: number): string {
 }
 
 /** One card in a column. */
-export function TaskCard({ task, onClick }: { task: TaskRecord; onClick: () => void }) {
+function TaskCardInner({ task, onClick }: { task: TaskRecord; onClick: () => void }) {
   const latest = task.executions[task.executions.length - 1]
   const runs = task.executions.length
   return (
@@ -60,3 +66,6 @@ export function TaskCard({ task, onClick }: { task: TaskRecord; onClick: () => v
     </button>
   )
 }
+
+/** Memoized card: re-renders only when the card's own task record changes. */
+export const TaskCard = memo(TaskCardInner)

package/src/client/settings-card.module.css

@@ -1,3 +1,4 @@
+/* Generated by scripts/sync-shared.mjs from shared/client/settings/settings-card.module.css. Do not edit this copy; edit the shared source and run "node scripts/sync-shared.mjs". */
 /* Plugin settings card chrome + staged form fields.
  * Aligned with the official ui-settings-plugins PluginCard / fields CSS:
  * same semantic tokens, radius, typography and states so family cards read
@@ -229,6 +230,11 @@
   outline-offset: 2px;
 }
 
+.reset:focus-visible {
+  outline: 2px solid var(--dsw-alias-brand-primary);
+  outline-offset: 2px;
+}
+
 .input,
 .select {
   border: 1px solid var(--dsw-alias-border-l2);

package/src/client/settings-form.ts

@@ -1,10 +1,11 @@
+// Generated by scripts/sync-shared.mjs from shared/client/settings/settings-form.ts. Do not edit this copy; edit the shared source and run "node scripts/sync-shared.mjs".
 /**
  * Staged form model behind the plugin settings card. A card stages what the
  * user types and writes it only when they save — the settings write is a
  * durable, revision-fenced document mutation, so staging keeps what is on
- * screen exactly what a save would store. Mirrors the official
- * ui-plugin-config card-store pattern in a self-contained slice: this
- * package must not depend on a sibling UI package.
+ * screen exactly what a save would store. Family-shared slice inlined into
+ * each plugin's client bundle; mirrors the official ui-plugin-config
+ * card-store pattern.
  */
 
 import type { SettingsScope, SettingsScopeSnapshot, SnapshotStore } from '@deepseek-ai/dsh-client-runtime/client'
@@ -90,8 +91,17 @@ interface PlannedWrite {
   run: (() => Promise<boolean>) | undefined
 }
 
-/** A whole-number field. An empty draft clears the field; any other draft that is not a finite number blocks the save. */
-export function numberField(field: string): FieldSpec {
+/** Constraints a numeric field's accepted drafts must satisfy, mirroring the host schema. */
+export interface NumberConstraints {
+  /** The accepted value must be a whole number. */
+  integer?: boolean
+  /** The accepted value must be at least this. */
+  min?: number
+}
+
+/** A whole- or decimal-number field. An empty draft clears the field; any other draft that is not a finite number within the constraints blocks the save. */
+export function numberField(field: string, constraints: NumberConstraints = {}): FieldSpec {
+  const { integer = false, min } = constraints
   return {
     field,
     format: value => typeof value === 'number' ? String(value) : '',
@@ -99,7 +109,10 @@ export function numberField(field: string): FieldSpec {
       const trimmed = text.trim()
       if (trimmed === '') return { kind: 'clear' }
       const parsed = Number(trimmed)
-      return Number.isFinite(parsed) ? { kind: 'set', value: parsed } : undefined
+      if (!Number.isFinite(parsed)) return undefined
+      if (integer && !Number.isInteger(parsed)) return undefined
+      if (min !== undefined && parsed < min) return undefined
+      return { kind: 'set', value: parsed }
     },
   }
 }
@@ -122,13 +135,27 @@ export function booleanField(field: string): FieldSpec {
     field,
     format: value => typeof value === 'boolean' ? String(value) : '',
     parse: (text) => {
-      if (text === 'true') return { kind: 'set', value: true }
-      if (text === 'false') return { kind: 'set', value: false }
+      const trimmed = text.trim()
+      if (trimmed === '') return { kind: 'clear' }
+      if (trimmed === 'true') return { kind: 'set', value: true }
+      if (trimmed === 'false') return { kind: 'set', value: false }
       return undefined
     },
   }
 }
 
+/** An enumerated string field; only the listed choices are accepted. An empty draft clears the field. */
+export function choiceField(field: string, choices: readonly string[]): FieldSpec {
+  return {
+    field,
+    format: value => typeof value === 'string' && choices.includes(value) ? value : '',
+    parse: (text) => {
+      if (text === '') return { kind: 'clear' }
+      return choices.includes(text) ? { kind: 'set', value: text } : undefined
+    },
+  }
+}
+
 /**
  * Stages one card's edits over one settings namespace and writes them on save.
  *
@@ -215,6 +242,9 @@ export class CardForm<T> {
     const plan = this.plan()
     const writes = plan.flatMap(item => item.run === undefined ? [] : [item.run])
     if (plan.length === 0 || this.saving || writes.length !== plan.length) return
+    // Snapshot the fields this save writes, so edits staged while it is in
+    // flight survive: only the staged keys this save actually wrote are cleared.
+    const fields = new Set(plan.map(item => item.field))
     this.saving = true
     this.failed = false
     this.publish()
@@ -222,7 +252,9 @@ export class CardForm<T> {
     for (const write of writes) {
       landed = await write() && landed
     }
-    if (landed) this.staged.clear()
+    if (landed) {
+      for (const field of fields) this.staged.delete(field)
+    }
     this.saving = false
     this.failed = !landed
     this.publish()