@linxin666/dsh-remote-web-ui 0.1.1 → 0.1.2

package/lib/types/client/index.js

@@ -0,0 +1,111 @@
+/**
+ * Mobile remote control — browser half. Registers the `remote` dictionaries,
+ * the sidebar-foot entry (phone trigger + pairing panel) into the
+ * ui-sidebar-declared `sidebar.remote` seat, and runs the phone-side boot
+ * flow (pair accept + workspace deep-link + presence heartbeats) plus the
+ * one-time failed-pair notice. Export discipline: packages/client/AGENTS.md
+ * — the /client surface carries only what cordis loading needs plus types.
+ */
+import { createElement } from 'react';
+import { createRoot } from 'react-dom/client';
+import { RemoteEntry } from "./RemoteEntry.js";
+import { PairFailedNotice } from "./PairFailedNotice.js";
+import { RemoteSettingsCard, RemoteSettingsCardController } from "./RemoteSettingsCard.js";
+import { en, zh } from "./locales.js";
+import { PAIR_FAILED_MARKER, runPairBootFlow } from "./deep-link.js";
+import { sendHeartbeat } from "./pair-api.js";
+/** Dictionary namespace owned by this plugin. */
+const NS = 'remote';
+/** Settings namespace the remote-control card edits (the Host plugin registers it). */
+const REMOTE_WEB_UI_NS = 'remote-web-ui';
+/** Heartbeat cadence from a paired phone (presence + revocation liveness). */
+const HEARTBEAT_INTERVAL_MS = 10_000;
+/** Services required by this plugin. */
+export const inject = ['slots', 'locale', 'connection', 'settingsScope', 'remote'];
+/**
+ * Register the remote-control surface.
+ * @param ctx - client root context.
+ */
+export function apply(ctx) {
+    ctx.effect(() => ctx.locale.register(NS, { zh, en }), 'remote-web-ui: dictionaries');
+    const t = ctx.locale.bind(NS);
+    const settingsScope = ctx.settingsScope.bind({ namespace: REMOTE_WEB_UI_NS });
+    const enabled = () => {
+        const snapshot = settingsScope.getSnapshot();
+        return snapshot.status === 'ready'
+            ? snapshot.value?.enabled ?? true
+            : snapshot.status === 'unavailable';
+    };
+    // Sidebar foot entry: the shell declares 'sidebar.remote' in unconstrained
+    // order, so registration is declaration-aware — slots.inject waits on the
+    // declaration, removes the contribution when it collapses, and re-runs
+    // after a redeclaration. The entry follows the plugin's enabled setting:
+    // toggling it off removes the trigger, toggling it back on re-registers it.
+    ctx.slots.inject('sidebar.remote', () => {
+        let disposeEntry;
+        const syncEntry = () => {
+            if (enabled() && disposeEntry === undefined) {
+                disposeEntry = ctx.slots.register({ name: 'sidebar.remote', locale: NS }, RemoteEntry);
+            }
+            else if (!enabled() && disposeEntry !== undefined) {
+                disposeEntry();
+                disposeEntry = undefined;
+            }
+        };
+        const unsubscribe = settingsScope.subscribe(syncEntry);
+        syncEntry();
+        return () => {
+            unsubscribe();
+            disposeEntry?.();
+        };
+    });
+    // Plugin configuration card: one staged form over the `remote-web-ui`
+    // settings namespace, contributed to the Web UI plugin group.
+    const remoteSettings = new RemoteSettingsCardController(settingsScope);
+    ctx.slots.inject('web-ui.plugin.item', () => ctx.slots.register({
+        name: 'web-ui.plugin.item',
+        id: 'remote-web-ui',
+        order: 90,
+        locale: NS,
+        inject: () => remoteSettings.inject(),
+    }, RemoteSettingsCard));
+    // Phone-side boot flow + heartbeats. Loopback pages (the desktop) never
+    // heartbeat; the server ignores unpaired heartbeats anyway. Both run only
+    // while the plugin is enabled.
+    let disposeRuntime;
+    const syncRuntime = () => {
+        if (enabled() && disposeRuntime === undefined) {
+            disposeRuntime = ctx.effect(() => {
+                const connection = ctx.get('connection');
+                const loopback = connection?.isLoopback ?? true;
+                runPairBootFlow(ctx, window.location.search);
+                if (loopback)
+                    return () => { };
+                const timer = window.setInterval(() => { void sendHeartbeat().catch(() => { }); }, HEARTBEAT_INTERVAL_MS);
+                return () => { window.clearInterval(timer); };
+            }, 'remote-web-ui: pair flow + heartbeats');
+        }
+        else if (!enabled() && disposeRuntime !== undefined) {
+            disposeRuntime();
+            disposeRuntime = undefined;
+        }
+    };
+    settingsScope.subscribe(syncRuntime);
+    syncRuntime();
+    // One-time failed-pair toast. The accept result lands asynchronously, so
+    // the marker check is deferred past the accept round trip.
+    ctx.effect(() => {
+        const timer = window.setTimeout(() => {
+            if (sessionStorage.getItem(PAIR_FAILED_MARKER) === null)
+                return;
+            sessionStorage.removeItem(PAIR_FAILED_MARKER);
+            const mount = document.createElement('div');
+            document.body.appendChild(mount);
+            const root = createRoot(mount);
+            root.render(createElement(PairFailedNotice, { t }));
+            // The toast owns its dismissal; the root lives for the page lifetime.
+            void root;
+        }, 1500);
+        return () => { window.clearTimeout(timer); };
+    }, 'remote-web-ui: failed-pair notice');
+}

package/lib/types/client/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/client/index.ts"],"names":[],"mappings":"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"}

package/lib/types/client/locales.js

@@ -0,0 +1,141 @@
+/** `remote` namespace dictionaries: the mobile remote-control surface copy. */
+/** Simplified Chinese dictionary (the key-set source of truth). */
+export const zh = {
+    'entry.label': '移动端远程控制',
+    'title': '移动端远程控制',
+    'subtitle': '扫码或在手机上打开链接，即可远程控制当前工作区',
+    'card.title': '手机扫码连接',
+    'public.badge': '公网',
+    'status.waiting': '等待手机连接',
+    'status.connected': '已连接 {n} 台设备',
+    'status.disconnected': '已配对设备离线',
+    'status.stopped': '已停止移动端访问',
+    'status.lanRequired': '此功能需要以 --host 0.0.0.0 启动 dsh web，或配置公网地址才能使用',
+    'status.lanRequiredHint': '当前服务仅绑定在 127.0.0.1 且未配置公网地址，手机无法访问。请用 dsh web --host 0.0.0.0 重新启动，或在设置中填写内网穿透的公网地址。',
+    'status.loopbackRequired': '配对面板仅限本机使用',
+    'status.loopbackRequiredHint': '请通过 http://127.0.0.1 打开此页面后重试；手机请使用配对链接访问。',
+    'status.unreachable': '无法连接配对服务',
+    'status.unreachableHint': '请刷新页面后重试。',
+    'pair.hint': '无法扫码？可以在手机上打开链接',
+    'pair.publicHint': '公网链接：手机无需与电脑在同一网络',
+    'address.label': '选择二维码指向的网络',
+    'address.public': '公网地址',
+    'address.lan': '局域网',
+    'address.hint': '公网地址适合手机不在同一网络时使用；局域网地址仅在手机与电脑同一网络时可用。',
+    'pair.expires': '二维码有效至 {time}',
+    'pair.expired': '二维码已过期，请刷新',
+    'pair.failed.title': '配对失败',
+    'pair.failed.detail': '链接无效或已使用，请回到电脑端刷新二维码后重新扫码。',
+    'action.stop': '停止',
+    'action.refresh': '刷新二维码',
+    'action.copy': '复制链接',
+    'action.copied': '已复制',
+    'stopped.hint': '已停止移动端访问。点击"刷新二维码"重新开启。',
+    'tunnel.starting': '公网隧道启动中，二维码将自动变为公网链接…',
+    'tunnel.failed': '公网隧道启动失败：{error}',
+    'tunnel.unknownError': '未知错误',
+    'close.label': '关闭移动端远程控制面板',
+    // 插件设置卡片（settings.plugin.item 席位）。
+    'settings.title': '移动端远程控制',
+    'settings.description': '配对安全与设备限额。',
+    'settings.enabled': '启用移动端远程控制',
+    'settings.enabledHint': '关闭后移除侧边栏入口并停用配对路由与局域网栅栏。',
+    'settings.tokenTtlMs': '配对令牌有效期（毫秒）',
+    'settings.tokenTtlMsHint': '新生成的二维码链接在此时间后失效。',
+    'settings.offlineAfterMs': '设备离线判定（毫秒）',
+    'settings.offlineAfterMsHint': '配对设备超过该时长未上报心跳即视为离线。',
+    'settings.maxDevices': '已配对设备上限',
+    'settings.maxDevicesHint': '超过上限时淘汰最旧的设备会话。',
+    'settings.cookieName': '设备 Cookie 名',
+    'settings.cookieNameHint': '携带已配对设备标识的 Cookie 名称。',
+    'settings.requirePairingForLan': '局域网访问要求配对',
+    'settings.requirePairingForLanHint': '开启：所有非本机回环的 /api 请求必须携带有效配对 Cookie；关闭：局域网栅栏放开，配对仅用于令牌与状态管理。',
+    'settings.publicBaseUrl': '公网地址（可选）',
+    'settings.publicBaseUrlHint': '内网穿透的公网地址，如 Cloudflare Tunnel：https://xxx.trycloudflare.com。填写后二维码将生成公网链接，手机不在同一网络也能配对；留空则仅局域网可用。',
+    'settings.autoTunnel': '自动公网隧道',
+    'settings.autoTunnelHint': '开启后插件自动启动 Cloudflare quick tunnel（无需安装任何工具），并自动更新公网地址与信任配置，手机随时可用公网配对；关闭时使用上方手动填写的公网地址。',
+    'settings.inherit': '继承',
+    'settings.on': '开',
+    'settings.off': '关',
+    'settings.overridden': '已覆盖',
+    'settings.reset': '恢复默认',
+    'settings.readOnly': '当前部署的设置只读。',
+    'settings.expand': '展开设置',
+    'settings.collapse': '收起设置',
+    'settings.save': '保存',
+    'settings.saving': '保存中…',
+    'settings.discard': '放弃',
+    'settings.unsaved': '未保存',
+    'settings.saveFailed': '部署未接受这些值，已保留供你修改。',
+    'settings.invalidNumber': '请输入数字，留空则使用默认值。',
+};
+/** English dictionary, checked complete against the zh key set. */
+export const en = {
+    'entry.label': 'Mobile remote control',
+    'title': 'Mobile remote control',
+    'subtitle': 'Scan the QR code or open the link on your phone to control this workspace remotely',
+    'card.title': 'Scan to connect',
+    'public.badge': 'Public',
+    'status.waiting': 'Waiting for a phone',
+    'status.connected': '{n} device(s) connected',
+    'status.disconnected': 'Paired devices offline',
+    'status.stopped': 'Mobile access stopped',
+    'status.lanRequired': 'This feature needs dsh web started with --host 0.0.0.0, or a configured public address',
+    'status.lanRequiredHint': 'The server is bound to 127.0.0.1 and no public address is configured, so a phone cannot reach it. Restart with dsh web --host 0.0.0.0, or set the tunneled public address in settings.',
+    'status.loopbackRequired': 'The pairing panel works on this machine only',
+    'status.loopbackRequiredHint': 'Open this page at http://127.0.0.1 to mint a QR code; phones use the paired link.',
+    'status.unreachable': 'Cannot reach the pairing service',
+    'status.unreachableHint': 'Refresh the page and try again.',
+    'pair.hint': 'Cannot scan? Open the link on your phone',
+    'pair.publicHint': 'Public link: the phone does not need to be on the same network',
+    'address.label': 'Network the QR code points to',
+    'address.public': 'Public',
+    'address.lan': 'LAN',
+    'address.hint': 'Use the public address when the phone is not on the same network; LAN addresses only work on the same network.',
+    'pair.expires': 'QR code valid until {time}',
+    'pair.expired': 'QR code expired — refresh it',
+    'pair.failed.title': 'Pairing failed',
+    'pair.failed.detail': 'The link is invalid or was already used. Refresh the QR code on your computer and scan again.',
+    'action.stop': 'Stop',
+    'action.refresh': 'Refresh QR',
+    'action.copy': 'Copy link',
+    'action.copied': 'Copied',
+    'stopped.hint': 'Mobile access is stopped. Click "Refresh QR" to re-enable it.',
+    'tunnel.starting': 'The public tunnel is starting; the QR code will switch to a public link shortly…',
+    'tunnel.failed': 'The public tunnel failed to start: {error}',
+    'tunnel.unknownError': 'unknown error',
+    'close.label': 'Close mobile remote control panel',
+    // Plugin settings card (the `settings.plugin.item` seat).
+    'settings.title': 'Mobile remote control',
+    'settings.description': 'Pairing security and device limits.',
+    'settings.enabled': 'Enable mobile remote control',
+    'settings.enabledHint': 'When off, the sidebar entry is removed and pairing routes plus the LAN fence stop.',
+    'settings.tokenTtlMs': 'Pairing token lifetime (ms)',
+    'settings.tokenTtlMsHint': 'How long a minted QR link stays valid before it dies.',
+    'settings.offlineAfterMs': 'Device offline threshold (ms)',
+    'settings.offlineAfterMsHint': 'A paired device flips to offline when it has not been seen for this long.',
+    'settings.maxDevices': 'Paired device cap',
+    'settings.maxDevicesHint': 'Hard cap on paired device sessions; the oldest is evicted when full.',
+    'settings.cookieName': 'Device cookie name',
+    'settings.cookieNameHint': 'Cookie that carries the paired device id.',
+    'settings.requirePairingForLan': 'Require pairing for LAN access',
+    'settings.requirePairingForLanHint': 'On: every non-loopback /api request must carry a live paired-device cookie. Off: the LAN fence is open and pairing only manages tokens/status.',
+    'settings.publicBaseUrl': 'Public address (optional)',
+    'settings.publicBaseUrlHint': 'The public URL of a tunnel in front of this server, e.g. a Cloudflare Tunnel: https://xxx.trycloudflare.com. When set, the QR link is built from it so a phone anywhere can pair; leave blank for LAN-only usage.',
+    'settings.autoTunnel': 'Auto public tunnel',
+    'settings.autoTunnelHint': 'When on, the plugin runs its own Cloudflare quick tunnel (no tool installation needed) and keeps the public address and trust config in sync automatically, so a phone anywhere can pair at any time; when off, the manually entered public address above applies.',
+    'settings.inherit': 'Inherit',
+    'settings.on': 'On',
+    'settings.off': 'Off',
+    'settings.overridden': 'Overridden',
+    'settings.reset': 'Reset to default',
+    'settings.readOnly': 'This deployment stores settings read-only.',
+    'settings.expand': 'Show settings',
+    'settings.collapse': 'Hide settings',
+    'settings.save': 'Save',
+    'settings.saving': 'Saving…',
+    'settings.discard': 'Discard',
+    'settings.unsaved': 'Unsaved',
+    'settings.saveFailed': 'The deployment did not accept these values; they were left for you to correct.',
+    'settings.invalidNumber': 'Enter a number, or leave blank to use the default.',
+};

package/lib/types/client/locales.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"locales.js","sourceRoot":"","sources":["../../../src/client/locales.ts"],"names":[],"mappings":"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"}

package/lib/types/client/pair-api.js

@@ -0,0 +1,123 @@
+/**
+ * Browser-side wire helpers for the /api/pair surface. Plain fetch over
+ * same-origin /api (like the connection client); JSON bodies, string
+ * responses for the error codes.
+ */
+/**
+ * Mint a fresh pairing token (one active token at a time — this invalidates
+ * any previous link).
+ * @param workspaceId - optional current workspace to deep-link the phone into.
+ * @param address - optional LAN IP literal the QR must be built from (the
+ * default is the first interface); unknown literals refuse with
+ * 'unknown-address'.
+ * @returns the issued link, the lan-required refusal (server never bound
+ * 0.0.0.0), or the forbidden refusal (the loopback-only fence rejected this
+ * origin — the panel is a desktop control endpoint).
+ */
+export async function issuePair(workspaceId, address) {
+    const response = await fetch('/api/pair/issue', {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({
+            ...(workspaceId !== undefined ? { workspaceId } : {}),
+            ...(address !== undefined ? { address } : {}),
+        }),
+    });
+    if (!response.ok) {
+        if (response.status === 409)
+            return { ok: false, code: 'lan-required' };
+        if (response.status === 403)
+            return { ok: false, code: 'forbidden' };
+        if (response.status === 400)
+            return { ok: false, code: 'unknown-address' };
+        throw new Error(`remote-web-ui: issue failed with ${String(response.status)}`);
+    }
+    return await response.json();
+}
+/**
+ * Accept a pairing token (the phone's first open of the QR link). Success
+ * sets the device cookie; the page then reloads to boot with it.
+ * @param token - the token from the URL.
+ * @returns the wire result.
+ */
+export async function acceptPair(token) {
+    const response = await fetch('/api/pair/accept', {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ token }),
+    });
+    if (response.ok)
+        return { ok: true };
+    if (response.status === 404)
+        return { ok: false, code: 'invalid' };
+    if (response.status === 409)
+        return { ok: false, code: 'used' };
+    return { ok: false, code: 'forbidden' };
+}
+/** Revoke mobile access (paired devices + the current token). */
+export async function stopPair() {
+    const response = await fetch('/api/pair/stop', { method: 'POST' });
+    if (!response.ok)
+        throw new Error(`remote-web-ui: stop failed with ${String(response.status)}`);
+}
+/** Presence heartbeat from a paired phone (unpaired heartbeats 401 harmlessly). */
+export async function sendHeartbeat() {
+    await fetch('/api/pair/heartbeat', { method: 'POST' });
+}
+/** Whether the current page URL carries a pairing token / workspace target. */
+export function readPairParams(search) {
+    const params = new URLSearchParams(search);
+    const pair = params.get('pair');
+    const workspace = params.get('workspace');
+    return {
+        ...(pair !== null && pair !== '' ? { pair } : {}),
+        ...(workspace !== null && workspace !== '' ? { workspace } : {}),
+    };
+}
+/**
+ * Strip one query parameter from the current URL without reloading.
+ * @param name - the parameter to remove.
+ * @returns the new search string ('' when empty).
+ */
+export function stripParam(name) {
+    const url = new URL(window.location.href);
+    url.searchParams.delete(name);
+    return url.search;
+} /** Human-readable expiry clock, e.g. "10:35". */
+export function formatClock(epochMs) {
+    const date = new Date(epochMs);
+    const hours = String(date.getHours()).padStart(2, '0');
+    const minutes = String(date.getMinutes()).padStart(2, '0');
+    return `${hours}:${minutes}`;
+}
+/**
+ * Copy text to the clipboard with a fallback for insecure contexts
+ * (plain-HTTP LAN origins lack navigator.clipboard).
+ * @param text - the text to copy.
+ * @returns whether the copy succeeded.
+ */
+export async function copyText(text) {
+    if (typeof navigator !== 'undefined' && navigator.clipboard !== undefined) {
+        try {
+            await navigator.clipboard.writeText(text);
+            return true;
+        }
+        catch {
+            // fall through to the execCommand path
+        }
+    }
+    try {
+        const area = document.createElement('textarea');
+        area.value = text;
+        area.style.position = 'fixed';
+        area.style.opacity = '0';
+        document.body.appendChild(area);
+        area.select();
+        const ok = document.execCommand('copy');
+        area.remove();
+        return ok;
+    }
+    catch {
+        return false;
+    }
+}

package/lib/types/client/pair-api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pair-api.js","sourceRoot":"","sources":["../../../src/client/pair-api.ts"],"names":[],"mappings":"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"}

package/lib/types/client/settings-form.js

@@ -0,0 +1,211 @@
+/**
+ * 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.
+ */
+import { createSnapshotStore } from '@deepseek-ai/dsh-client-runtime/client';
+/** 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) {
+    return {
+        field,
+        format: value => typeof value === 'number' ? String(value) : '',
+        parse: (text) => {
+            const trimmed = text.trim();
+            if (trimmed === '')
+                return { kind: 'clear' };
+            const parsed = Number(trimmed);
+            return Number.isFinite(parsed) ? { kind: 'set', value: parsed } : undefined;
+        },
+    };
+}
+/** A free-text field. An empty draft clears the field. */
+export function textField(field) {
+    return {
+        field,
+        format: value => typeof value === 'string' ? value : '',
+        parse: (text) => {
+            const trimmed = text.trim();
+            return trimmed === '' ? { kind: 'clear' } : { kind: 'set', value: trimmed };
+        },
+    };
+}
+/** A boolean field, edited through true/false draft text. */
+export function booleanField(field) {
+    return {
+        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 };
+            return undefined;
+        },
+    };
+}
+/**
+ * Stages one card's edits over one settings namespace and writes them on save.
+ *
+ * The Host is the only authority on whether a value was accepted — its
+ * validators own the constraints no schema can express — so the outcome is
+ * read back from the section rather than predicted here. A save that did not
+ * land keeps its drafts, so the user can correct them instead of retyping.
+ */
+export class CardForm {
+    scope;
+    specs;
+    staged = new Map();
+    listeners = new Set();
+    saving = false;
+    failed = false;
+    /** @param scope - the bound settings scope for this card's namespace. */
+    constructor(scope, specs) {
+        this.scope = scope;
+        this.specs = new Map(specs.map(spec => [spec.field, spec]));
+        scope.subscribe(() => { this.publish(); });
+    }
+    /** Publish a projection of this form, rebuilt whenever the scope or a draft changes. */
+    bind(project) {
+        const store = createSnapshotStore(project());
+        this.listeners.add(() => { store.set(project()); });
+        return store;
+    }
+    /** Read the card-level state: what the Host serves, and what a save would do. */
+    shell() {
+        const snapshot = this.scope.getSnapshot();
+        const plan = this.plan();
+        return {
+            available: snapshot.status === 'ready',
+            writable: snapshot.writable,
+            dirty: plan.length > 0,
+            invalid: plan.some(item => item.run === undefined),
+            saving: this.saving,
+            failed: this.failed,
+        };
+    }
+    /** Read one field's state from the effective section and its staged draft. */
+    field(field) {
+        const spec = this.specOf(field);
+        const staged = this.staged.get(field);
+        if (staged === undefined) {
+            return { text: spec.format(this.sectionValue(field)), overridden: this.stored(field), invalid: false };
+        }
+        const write = staged.clear ? { kind: 'clear' } : spec.parse(staged.text);
+        return {
+            text: staged.text,
+            overridden: write?.kind === 'set',
+            invalid: write === undefined,
+        };
+    }
+    /** The actions the card's slot registration injects. */
+    actions() {
+        return {
+            edit: (field, text) => { this.stage(field, { text, clear: false }); },
+            resetField: (field) => {
+                this.stage(field, { text: this.specOf(field).format(this.baseValue(field)), clear: true });
+            },
+            save: () => { void this.save(); },
+            discard: () => {
+                if (this.staged.size === 0 && !this.failed)
+                    return;
+                this.staged.clear();
+                this.failed = false;
+                this.publish();
+            },
+        };
+    }
+    /**
+     * Write every staged edit, then re-seed from what the Host accepted.
+     * @returns settlement after every write and the read-back.
+     */
+    async save() {
+        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;
+        this.saving = true;
+        this.failed = false;
+        this.publish();
+        let landed = true;
+        for (const write of writes) {
+            landed = await write() && landed;
+        }
+        if (landed)
+            this.staged.clear();
+        this.saving = false;
+        this.failed = !landed;
+        this.publish();
+    }
+    /**
+     * Every staged edit a save would write. An entry whose draft is not a value
+     * its field accepts carries no write: the form is still dirty, and the save
+     * refuses rather than dropping the edit. A staged edit that matches the
+     * effective section is not a write at all.
+     * @returns the planned writes, in the order the fields were staged.
+     */
+    plan() {
+        const plan = [];
+        for (const [field, staged] of this.staged) {
+            const spec = this.specOf(field);
+            if (staged.clear) {
+                if (this.stored(field))
+                    plan.push({ field, run: () => this.clear(field) });
+                continue;
+            }
+            if (staged.text === spec.format(this.sectionValue(field)))
+                continue;
+            const write = spec.parse(staged.text);
+            if (write === undefined)
+                plan.push({ field, run: undefined });
+            else if (write.kind === 'clear')
+                plan.push({ field, run: () => this.clear(field) });
+            else
+                plan.push({ field, run: () => this.store(field, write.value) });
+        }
+        return plan;
+    }
+    async clear(field) {
+        await this.scope.unset(field);
+        return !this.stored(field);
+    }
+    async store(field, value) {
+        await this.scope.set(field, value);
+        return this.userLayer()?.[field] === value;
+    }
+    stage(field, edit) {
+        this.staged.set(field, edit);
+        this.failed = false;
+        this.publish();
+    }
+    specOf(field) {
+        const spec = this.specs.get(field);
+        // Every call site names a field this card declared; a missing one is a
+        // wiring mistake that must not degrade into a silently inert control.
+        if (spec === undefined)
+            throw new Error(`settings card has no field ${field}`);
+        return spec;
+    }
+    snapshotOf() {
+        return this.scope.getSnapshot();
+    }
+    sectionValue(field) {
+        return this.snapshotOf().value?.[field];
+    }
+    baseValue(field) {
+        return this.snapshotOf().base?.[field];
+    }
+    userLayer() {
+        return this.snapshotOf().user;
+    }
+    stored(field) {
+        const user = this.userLayer();
+        return user !== undefined && Object.hasOwn(user, field);
+    }
+    publish() {
+        for (const listener of this.listeners)
+            listener();
+    }
+}

package/lib/types/client/settings-form.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"settings-form.js","sourceRoot":"","sources":["../../../src/client/settings-form.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAE,mBAAmB,EAAE,MAAM,wCAAwC,CAAA;AA0E5E,0HAA0H;AAC1H,MAAM,UAAU,WAAW,CAAC,KAAa;IACvC,OAAO;QACL,KAAK;QACL,MAAM,EAAE,KAAK,CAAC,EAAE,CAAC,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE;QAC/D,KAAK,EAAE,CAAC,IAAI,EAAE,EAAE;YACd,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,CAAA;YAC3B,IAAI,OAAO,KAAK,EAAE;gBAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,CAAA;YAC5C,MAAM,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,CAAA;YAC9B,OAAO,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,SAAS,CAAA;QAC7E,CAAC;KACF,CAAA;AACH,CAAC;AAED,0DAA0D;AAC1D,MAAM,UAAU,SAAS,CAAC,KAAa;IACrC,OAAO;QACL,KAAK;QACL,MAAM,EAAE,KAAK,CAAC,EAAE,CAAC,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE;QACvD,KAAK,EAAE,CAAC,IAAI,EAAE,EAAE;YACd,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,CAAA;YAC3B,OAAO,OAAO,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,CAAA;QAC7E,CAAC;KACF,CAAA;AACH,CAAC;AAED,6DAA6D;AAC7D,MAAM,UAAU,YAAY,CAAC,KAAa;IACxC,OAAO;QACL,KAAK;QACL,MAAM,EAAE,KAAK,CAAC,EAAE,CAAC,OAAO,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE;QAChE,KAAK,EAAE,CAAC,IAAI,EAAE,EAAE;YACd,IAAI,IAAI,KAAK,MAAM;gBAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,CAAA;YACxD,IAAI,IAAI,KAAK,OAAO;gBAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,CAAA;YAC1D,OAAO,SAAS,CAAA;QAClB,CAAC;KACF,CAAA;AACH,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,OAAO,QAAQ;IASA;IARF,KAAK,CAAwB;IAC7B,MAAM,GAAG,IAAI,GAAG,EAAsB,CAAA;IACtC,SAAS,GAAG,IAAI,GAAG,EAAc,CAAA;IAC1C,MAAM,GAAG,KAAK,CAAA;IACd,MAAM,GAAG,KAAK,CAAA;IAEtB,yEAAyE;IACzE,YACmB,KAAuB,EACxC,KAAkB;QADD,UAAK,GAAL,KAAK,CAAkB;QAGxC,IAAI,CAAC,KAAK,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC,CAAC,CAAA;QAC3D,KAAK,CAAC,SAAS,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,OAAO,EAAE,CAAA,CAAC,CAAC,CAAC,CAAA;IAC3C,CAAC;IAED,wFAAwF;IACxF,IAAI,CAAI,OAAgB;QACtB,MAAM,KAAK,GAAG,mBAAmB,CAAC,OAAO,EAAE,CAAC,CAAA;QAC5C,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC,CAAA,CAAC,CAAC,CAAC,CAAA;QAClD,OAAO,KAAK,CAAA;IACd,CAAC;IAED,iFAAiF;IACjF,KAAK;QACH,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE,CAAA;QACzC,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,EAAE,CAAA;QACxB,OAAO;YACL,SAAS,EAAE,QAAQ,CAAC,MAAM,KAAK,OAAO;YACtC,QAAQ,EAAE,QAAQ,CAAC,QAAQ;YAC3B,KAAK,EAAE,IAAI,CAAC,MAAM,GAAG,CAAC;YACtB,OAAO,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,GAAG,KAAK,SAAS,CAAC;YAClD,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,MAAM,EAAE,IAAI,CAAC,MAAM;SACpB,CAAA;IACH,CAAC;IAED,8EAA8E;IAC9E,KAAK,CAAC,KAAa;QACjB,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;QAC/B,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAA;QACrC,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;YACzB,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,EAAE,UAAU,EAAE,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,CAAA;QACxG,CAAC;QACD,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,OAAgB,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;QACjF,OAAO;YACL,IAAI,EAAE,MAAM,CAAC,IAAI;YACjB,UAAU,EAAE,KAAK,EAAE,IAAI,KAAK,KAAK;YACjC,OAAO,EAAE,KAAK,KAAK,SAAS;SAC7B,CAAA;IACH,CAAC;IAED,wDAAwD;IACxD,OAAO;QACL,OAAO;YACL,IAAI,EAAE,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAA,CAAC,CAAC;YACpE,UAAU,EAAE,CAAC,KAAK,EAAE,EAAE;gBACpB,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,EAAE,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAA;YAC5F,CAAC;YACD,IAAI,EAAE,GAAG,EAAE,GAAG,KAAK,IAAI,CAAC,IAAI,EAAE,CAAA,CAAC,CAAC;YAChC,OAAO,EAAE,GAAG,EAAE;gBACZ,IAAI,IAAI,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM;oBAAE,OAAM;gBAClD,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAA;gBACnB,IAAI,CAAC,MAAM,GAAG,KAAK,CAAA;gBACnB,IAAI,CAAC,OAAO,EAAE,CAAA;YAChB,CAAC;SACF,CAAA;IACH,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,IAAI;QACR,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,EAAE,CAAA;QACxB,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAA;QAC7E,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,IAAI,IAAI,CAAC,MAAM,IAAI,MAAM,CAAC,MAAM,KAAK,IAAI,CAAC,MAAM;YAAE,OAAM;QAC7E,IAAI,CAAC,MAAM,GAAG,IAAI,CAAA;QAClB,IAAI,CAAC,MAAM,GAAG,KAAK,CAAA;QACnB,IAAI,CAAC,OAAO,EAAE,CAAA;QACd,IAAI,MAAM,GAAG,IAAI,CAAA;QACjB,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;YAC3B,MAAM,GAAG,MAAM,KAAK,EAAE,IAAI,MAAM,CAAA;QAClC,CAAC;QACD,IAAI,MAAM;YAAE,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAA;QAC/B,IAAI,CAAC,MAAM,GAAG,KAAK,CAAA;QACnB,IAAI,CAAC,MAAM,GAAG,CAAC,MAAM,CAAA;QACrB,IAAI,CAAC,OAAO,EAAE,CAAA;IAChB,CAAC;IAED;;;;;;OAMG;IACK,IAAI;QACV,MAAM,IAAI,GAAmB,EAAE,CAAA;QAC/B,KAAK,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YAC1C,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;YAC/B,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;gBACjB,IAAI,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC;oBAAE,IAAI,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC,CAAA;gBAC1E,SAAQ;YACV,CAAC;YACD,IAAI,MAAM,CAAC,IAAI,KAAK,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC;gBAAE,SAAQ;YACnE,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;YACrC,IAAI,KAAK,KAAK,SAAS;gBAAE,IAAI,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,GAAG,EAAE,SAAS,EAAE,CAAC,CAAA;iBACxD,IAAI,KAAK,CAAC,IAAI,KAAK,OAAO;gBAAE,IAAI,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC,CAAA;;gBAC9E,IAAI,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC,CAAA;QACtE,CAAC;QACD,OAAO,IAAI,CAAA;IACb,CAAC;IAEO,KAAK,CAAC,KAAK,CAAC,KAAa;QAC/B,MAAM,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,CAAA;QAC7B,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;IAC5B,CAAC;IAEO,KAAK,CAAC,KAAK,CAAC,KAAa,EAAE,KAAc;QAC/C,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,EAAE,KAAK,CAAC,CAAA;QAClC,OAAO,IAAI,CAAC,SAAS,EAAE,EAAE,CAAC,KAAK,CAAC,KAAK,KAAK,CAAA;IAC5C,CAAC;IAEO,KAAK,CAAC,KAAa,EAAE,IAAgB;QAC3C,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,EAAE,IAAI,CAAC,CAAA;QAC5B,IAAI,CAAC,MAAM,GAAG,KAAK,CAAA;QACnB,IAAI,CAAC,OAAO,EAAE,CAAA;IAChB,CAAC;IAEO,MAAM,CAAC,KAAa;QAC1B,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,CAAA;QAClC,uEAAuE;QACvE,sEAAsE;QACtE,IAAI,IAAI,KAAK,SAAS;YAAE,MAAM,IAAI,KAAK,CAAC,8BAA8B,KAAK,EAAE,CAAC,CAAA;QAC9E,OAAO,IAAI,CAAA;IACb,CAAC;IAEO,UAAU;QAChB,OAAO,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE,CAAA;IACjC,CAAC;IAEO,YAAY,CAAC,KAAa;QAChC,OAAQ,IAAI,CAAC,UAAU,EAAE,CAAC,KAA6C,EAAE,CAAC,KAAK,CAAC,CAAA;IAClF,CAAC;IAEO,SAAS,CAAC,KAAa;QAC7B,OAAQ,IAAI,CAAC,UAAU,EAAE,CAAC,IAA4C,EAAE,CAAC,KAAK,CAAC,CAAA;IACjF,CAAC;IAEO,SAAS;QACf,OAAO,IAAI,CAAC,UAAU,EAAE,CAAC,IAA2C,CAAA;IACtE,CAAC;IAEO,MAAM,CAAC,KAAa;QAC1B,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,EAAE,CAAA;QAC7B,OAAO,IAAI,KAAK,SAAS,IAAI,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,CAAA;IACzD,CAAC;IAEO,OAAO;QACb,KAAK,MAAM,QAAQ,IAAI,IAAI,CAAC,SAAS;YAAE,QAAQ,EAAE,CAAA;IACnD,CAAC;CACF"}