@mind-harness/mh-browser 0.2.5 → 0.2.6

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

@@ -0,0 +1,142 @@
+import { type ReactElement, type ReactNode } from 'react';
+/**
+ * A staged settings form drawn by this plugin. It follows the host's settings
+ * form: edits stay local until Save, leaving the page drops them, and a field
+ * is overridden while the user layer carries it. Styles use host theme tokens
+ * only, so the page matches the host without loading its components.
+ */
+/** What `ctx.configForms.get()` serves for one Host entry. */
+export interface SettingsFormScopeSnapshot<T> {
+    status: 'loading' | 'ready' | 'unavailable';
+    value: T | undefined;
+    /** The layer a cleared field falls back to. */
+    base: unknown;
+    /** The user layer as stored. A field present here is overridden. */
+    user: unknown;
+    writable: boolean;
+    revision: number | undefined;
+}
+export type SettingsFormPathOp = {
+    op: 'set';
+    path: readonly string[];
+    value: unknown;
+} | {
+    op: 'unset';
+    path: readonly string[];
+};
+export interface SettingsFormScope<T> {
+    getSnapshot(): SettingsFormScopeSnapshot<T>;
+    subscribe(listener: () => void): () => void;
+    /** One revision-fenced write. Resolves to whether the Host accepted it. */
+    mutate(ops: readonly SettingsFormPathOp[], expectedRevision?: number): Promise<boolean>;
+}
+export type FieldWrite = {
+    kind: 'set';
+    value: unknown;
+} | {
+    kind: 'clear';
+};
+export interface FieldSpec {
+    field: string;
+    /** Stored value as draft text. */
+    format: (value: unknown) => string;
+    /** The write a draft stages. Undefined blocks the save. */
+    parse: (text: string) => FieldWrite | undefined;
+}
+export interface FieldState {
+    text: string;
+    /** Saving would leave this field in the user layer. */
+    overridden: boolean;
+    invalid: boolean;
+}
+export interface FormShell {
+    available: boolean;
+    writable: boolean;
+    dirty: boolean;
+    invalid: boolean;
+    saving: boolean;
+    /** The last save did not land. Cleared by the next edit or save. */
+    failed: boolean;
+}
+export interface FormLabels {
+    unavailable: string;
+    readOnly: string;
+    saveFailed: string;
+    discard: string;
+    save: string;
+    saving: string;
+}
+export interface Store<S> {
+    getSnapshot(): S;
+    subscribe(listener: () => void): () => void;
+}
+/** Drafts over one entry's fields, written together on save. */
+export declare class StagedForm<T> {
+    private readonly scope;
+    private readonly specs;
+    private readonly staged;
+    private readonly listeners;
+    private baseline;
+    private saving;
+    private failed;
+    private readonly unsubscribe;
+    constructor(scope: SettingsFormScope<T>, specs: readonly FieldSpec[]);
+    /** A store over `project`, rebuilt whenever the entry or a draft changes. */
+    bind<S>(project: () => S): Store<S>;
+    shell(): FormShell;
+    field(field: string): FieldState;
+    edit(field: string, text: string): void;
+    /** Stage removing the field from the user layer. The draft shows what it falls back to. */
+    reset(field: string): void;
+    discard(): void;
+    /**
+     * Write every staged edit. A save the Host refuses keeps the drafts, and the
+     * next save is fenced on what the Host holds now, so trying again can land.
+     */
+    save(): Promise<void>;
+    dispose(): void;
+    private plan;
+    private stage;
+    private spec;
+    private read;
+    private stored;
+    private publish;
+}
+/** Free text. An empty draft clears the field. */
+export declare function textField(field: string): FieldSpec;
+/** The page frame: read-only notice, the fields, and Save. Unmounting drops every draft. */
+export declare function SettingsFrame(props: {
+    labels: FormLabels;
+    state: FormShell;
+    onSave: () => void;
+    onDiscard: () => void;
+    children?: ReactNode;
+}): ReactElement;
+export interface FieldProps extends FieldState {
+    id: string;
+    label: string;
+    hint?: string;
+    overriddenLabel: string;
+    resetLabel: string;
+    /** Shown instead of the hint while the draft is invalid. A field that cannot be invalid omits it. */
+    invalidLabel?: string;
+    disabled: boolean;
+    /** Text behind the information button beside the label. */
+    help?: {
+        label: string;
+        content: ReactNode;
+    };
+    onReset: () => void;
+}
+export declare function TextField(props: FieldProps & {
+    placeholder?: string;
+    onEdit: (text: string) => void;
+}): ReactElement;
+export declare function ChoiceField(props: FieldProps & {
+    options: readonly {
+        value: string;
+        label: string;
+    }[];
+    onEdit: (value: string) => void;
+}): ReactElement;
+//# sourceMappingURL=settings-form.d.ts.map

package/lib/types/settings.d.ts

@@ -0,0 +1,121 @@
+import { type ReactElement } from 'react';
+import { type Translate } from './locales.ts';
+import { type FieldState, type FieldWrite, type FormShell, type SettingsFormScope } from './settings-form.ts';
+/** Loader row id, and the settings namespace for that row. */
+export declare const ENTRY_ID = "mh-browser";
+/** `plugins.row.config` key: the bundle package, then the row id. */
+export declare const ROW_KEY = "@mind-harness/mh-bundle#mh-browser";
+export declare const BROWSER_CHOICES: readonly ["chrome", "msedge", "chromium"];
+export type BrowserChoice = (typeof BROWSER_CHOICES)[number];
+/** Matches the host's `BrowserLocation`. The client bundle cannot import the host file. */
+export type BrowserLocation = {
+    found: string;
+} | {
+    missing: {
+        path: string;
+        reason: string;
+    }[];
+};
+export type LocateResult = {
+    ok: true;
+    value: BrowserLocation;
+} | {
+    ok: false;
+    error: {
+        code: string;
+        message: string;
+    };
+};
+export type LocateFor = (browser: BrowserChoice, signal?: AbortSignal) => Promise<LocateResult>;
+export type LookupView = {
+    status: 'loading';
+} | {
+    status: 'found';
+    path: string;
+} | {
+    status: 'missing';
+    tried: {
+        path: string;
+        reason: string;
+    }[];
+} | {
+    status: 'failed';
+};
+/** The host entry's config. Only these two fields are edited here. */
+export interface BrowserSettingsConfig {
+    browser?: string;
+    executablePath?: string;
+}
+interface BrowserState extends FormShell {
+    browser: FieldState;
+    executablePath: FieldState;
+}
+interface ConfigForms {
+    get<T>(entryId: string): SettingsFormScope<T>;
+}
+export interface SettingsHost {
+    slots: {
+        inject(name: string, register: () => unknown): unknown;
+        register(options: {
+            name: string;
+            key: string;
+            locale: string;
+        }, component: (props: {
+            t: Translate;
+            view?: 'summary' | 'page';
+        }) => ReactElement | null): () => void;
+    };
+    configForms: ConfigForms;
+    remote: {
+        mhBrowser: {
+            locateFor: LocateFor;
+        };
+    };
+    effect(execute: () => () => void): unknown;
+}
+/** Empty text clears the field. Anything else must be absolute, or start with `~`. */
+export declare function parseExecutable(text: string): FieldWrite | undefined;
+/** Placeholder for an empty path field: the path an empty value would use. */
+export declare function pathPlaceholder(lookup: LookupView, browser: BrowserChoice, t: Translate): string | undefined;
+/** The full path, or every place that was tried. Absent while looking or after a failed lookup. */
+export declare function pathHelpText(lookup: LookupView, t: Translate): string | undefined;
+/**
+ * One browser name's lookup, kept until the settings page unmounts.
+ * A newer lookup cancels the one still running.
+ */
+export declare class ExecutableLookup {
+    private readonly locate;
+    private readonly cache;
+    private inflight;
+    private controller;
+    private readonly listeners;
+    constructor(locate: LocateFor);
+    subscribe: (listener: () => void) => (() => void);
+    /** Cached answer for `browser`, or loading when that answer is not in yet. */
+    view(browser: BrowserChoice): LookupView;
+    watch(browser: BrowserChoice): void;
+    dispose(): void;
+    private publish;
+}
+/** Staged browser choice and path. A save the host accepts restarts the browser when it is idle. */
+export declare class BrowserForm {
+    private readonly form;
+    readonly lookup: ExecutableLookup;
+    readonly state: {
+        getSnapshot(): BrowserState;
+        subscribe(listener: () => void): () => void;
+    };
+    constructor(scope: SettingsFormScope<BrowserSettingsConfig>, locate: LocateFor);
+    edit(field: 'browser' | 'executablePath', text: string): void;
+    reset(field: 'browser' | 'executablePath'): void;
+    save(): void;
+    discard(): void;
+    dispose(): void;
+}
+export declare function registerSettings(ctx: SettingsHost): void;
+export declare function BrowserSettings(props: {
+    t: Translate;
+    form: BrowserForm;
+}): ReactElement;
+export {};
+//# sourceMappingURL=settings.d.ts.map

package/lib/types/typeprobe.d.ts

@@ -0,0 +1,49 @@
+import type { Volatile } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+interface Full {
+    presence: {
+        maxBytes: number;
+    };
+    browser: Volatile<'chrome' | 'msedge' | 'chromium'>;
+    executablePath: Volatile<string | undefined>;
+    profileDir?: string;
+    headless: boolean;
+}
+export declare const full: z<Full>;
+declare const oldShape: z<Schemastery.ObjectS<NoInfer<{
+    browser: z<"chrome" | "msedge" | "chromium", "chrome" | "msedge" | "chromium", "defined">;
+    profileDir: z<string, string, "plain">;
+    headless: z<boolean, boolean, "defined">;
+}>>, Schemastery.ObjectT<NoInfer<{
+    browser: z<"chrome" | "msedge" | "chromium", "chrome" | "msedge" | "chromium", "defined">;
+    profileDir: z<string, string, "plain">;
+    headless: z<boolean, boolean, "defined">;
+}>>, "plain">;
+declare const newShape: z<Schemastery.ObjectS<NoInfer<{
+    browser: z<"chrome" | "msedge" | "chromium", "chrome" | "msedge" | "chromium", "volatile-defined">;
+    executablePath: z<string, string, "volatile">;
+    profileDir: z<string, string, "plain">;
+    headless: z<boolean, boolean, "defined">;
+}>>, Schemastery.ObjectT<NoInfer<{
+    browser: z<"chrome" | "msedge" | "chromium", "chrome" | "msedge" | "chromium", "volatile-defined">;
+    executablePath: z<string, string, "volatile">;
+    profileDir: z<string, string, "plain">;
+    headless: z<boolean, boolean, "defined">;
+}>>, "plain">;
+type Old = ReturnType<typeof oldShape>;
+type New = ReturnType<typeof newShape>;
+export type Probe = {
+    oldProfile: Old['profileDir'];
+    oldBrowser: Old['browser'];
+    newProfile: New['profileDir'];
+    newBrowser: New['browser'];
+    newPath: New['executablePath'];
+    oldKeys: keyof Old;
+    newKeys: keyof New;
+};
+export declare const showOldProfile: Old['profileDir'];
+export declare const showNewProfile: New['profileDir'];
+export declare const showNewPath: New['executablePath'];
+export declare const showNewBrowser: New['browser'];
+export {};
+//# sourceMappingURL=typeprobe.d.ts.map

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@mind-harness/mh-browser",
-  "version": "0.2.5",
+  "version": "0.2.6",
   "description": "Opens pages in a real browser for the agent, keeps chosen Agent Views in context, and hands the browser to you when a person is needed.",
   "license": "SEE LICENSE IN LICENSE",
   "files": [
     "lib/index.js",
     "lib/types/representation/agent-view.js",
+    "lib/types/location.js",
     "lib/types/**/*.d.ts",
     "lib/typert.host.js",
     "lib/typert.host.d.ts",
@@ -29,6 +30,10 @@
       "types": "./lib/types/representation/agent-view.d.ts",
       "default": "./lib/types/representation/agent-view.js"
     },
+    "./location": {
+      "types": "./lib/types/location.d.ts",
+      "default": "./lib/types/location.js"
+    },
     "./typert": {
       "types": "./lib/typert.host.d.ts",
       "default": "./lib/typert.host.js"
@@ -60,6 +65,7 @@
     "@deepseek-ai/dsh-agent-loop-testkit": "^0.2.2-rc.1",
     "@deepseek-ai/dsh-attachment": "^0.2.2-rc.1",
     "@deepseek-ai/dsh-browser-use": "^0.2.2-rc.1",
+    "@deepseek-ai/dsh-client-ui-settings": "^0.2.2-rc.1",
     "@deepseek-ai/dsh-home-paths": "^0.2.2-rc.1",
     "@deepseek-ai/dsh-llm": "^0.2.2-rc.1",
     "@deepseek-ai/dsh-llm-mock-server": "^0.2.2-rc.1",
@@ -77,6 +83,7 @@
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.1.0",
+    "@deepseek-ai/dsh-client-ui-settings": ">=0.2.2-rc.1 <0.2.3-0",
     "@deepseek-ai/dsh-home-paths": ">=0.2.2-rc.1 <0.2.3-0",
     "@deepseek-ai/dsh-llm": ">=0.2.2-rc.1 <0.2.3-0",
     "@deepseek-ai/dsh-tools": ">=0.2.2-rc.1 <0.2.3-0",
@@ -94,7 +101,8 @@
       "platform": "web",
       "inject": [
         "@deepseek-ai/dsh-client-locale",
-        "@deepseek-ai/dsh-client-ui-conversation"
+        "@deepseek-ai/dsh-client-ui-conversation",
+        "@deepseek-ai/dsh-client-ui-settings"
       ]
     }
   },