@lostgradient/cinder 0.8.0 → 0.11.0

package/dist/server/{index.server-atjc1qcq.js → index.server-z7hxtqs1.js}

@@ -1,6 +1,6 @@
 import {
   conversationSummaryTimestamp
-} from "./index.server-s9khh4ry.js";
+} from "./index.server-2bbwajb2.js";
 import {
   classNames
 } from "./index.server-z7nvkz8v.js";

package/dist/server/{index.server-w6k62afr.js → index.server-ze1ymmbw.js}

@@ -55,7 +55,7 @@ function _json_viewer_node($$renderer, $$props) {
       } else {
         $$renderer2.push("<!--[-1-->");
       }
-      $$renderer2.push(`<!--]--> <span class="cinder-json-viewer__caret"${$.attr("data-cinder-collapsed", collapsed || undefined)}></span> <span class="cinder-json-viewer__brace">${$.escape(isArray() ? "[" : "{")}</span> `);
+      $$renderer2.push(`<!--]--> <svg class="cinder-json-viewer__caret"${$.attr("data-cinder-collapsed", collapsed || undefined)} xmlns="http://www.w3.org/2000/svg" viewBox="0 0 20 20" fill="currentColor" aria-hidden="true" focusable="false"><path fill-rule="evenodd" d="M5.22 8.22a.75.75 0 0 1 1.06 0L10 11.94l3.72-3.72a.75.75 0 1 1 1.06 1.06l-4.25 4.25a.75.75 0 0 1-1.06 0L5.22 9.28a.75.75 0 0 1 0-1.06z" clip-rule="evenodd"></path></svg> <span class="cinder-json-viewer__brace">${$.escape(isArray() ? "[" : "{")}</span> `);
       if (collapsed) {
         $$renderer2.push("<!--[0-->");
         $$renderer2.push(`<span class="cinder-json-viewer__summary">${$.escape(itemCount())} ${$.escape(itemCount() === 1 ? "item" : "items")}</span> <span class="cinder-json-viewer__brace">${$.escape(isArray() ? "]" : "}")}</span>`);
@@ -220,4 +220,4 @@ function Json_viewer($$renderer, $$props) {
 
 export { Json_viewer };
 
-//# debugId=4610D0EF23A4B97D64756E2164756E21
+//# debugId=73E01DFC934121F164756E2164756E21

package/dist/server/{index.server-914v805w.js → index.server-zgd1g8mk.js}

@@ -1,6 +1,6 @@
 import {
   Json_viewer
-} from "./index.server-w6k62afr.js";
+} from "./index.server-ze1ymmbw.js";
 
 // src/components/json-viewer/index.ts
 var json_viewer_default = Json_viewer;

package/dist/server/{index.server-aeexcxdp.js → index.server-zh3r8vfd.js}

@@ -1,6 +1,6 @@
 import {
   Payload_inspector
-} from "./index.server-vt6sn9y4.js";
+} from "./index.server-m0ezemav.js";
 
 // src/components/payload-inspector/index.ts
 var payload_inspector_default = Payload_inspector;

package/dist/server/{index.server-10jb2jzm.js → index.server-zsjf8enc.js}

@@ -1,9 +1,9 @@
-import {
-  getFormFieldContext
-} from "./index.server-weae7gs2.js";
 import {
   commitValue
 } from "./index.server-42qeekwc.js";
+import {
+  getFormFieldContext
+} from "./index.server-weae7gs2.js";
 import {
   classNames
 } from "./index.server-z7nvkz8v.js";
@@ -50,4 +50,4 @@ function Toggle($$renderer, $$props) {
 var toggle_default = Toggle;
 export { Toggle, toggle_default };
 
-//# debugId=426B7366973E509A64756E2164756E21
+//# debugId=12CB9C541A47207164756E2164756E21

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lostgradient/cinder",
-  "version": "0.8.0",
+  "version": "0.11.0",
   "description": "A Svelte 5 component library and design system focused on accessibility, theming, and per-component tree-shaking.",
   "keywords": [
     "svelte",
@@ -967,6 +967,38 @@
       "import": "./src/components/chat/chat.examples.json",
       "default": "./src/components/chat/chat.examples.json"
     },
+    "./chat-composer-popover": {
+      "types": "./dist/components/chat-composer-popover/index.d.ts",
+      "browser": "./src/components/chat-composer-popover/index.ts",
+      "node": "./dist/server/components/chat-composer-popover/index.js",
+      "svelte": "./src/components/chat-composer-popover/index.ts",
+      "import": "./src/components/chat-composer-popover/index.ts",
+      "default": "./dist/components/chat-composer-popover/index.js"
+    },
+    "./chat-composer-popover/schema": {
+      "types": "./dist/components/chat-composer-popover/chat-composer-popover.schema.d.ts",
+      "browser": "./src/components/chat-composer-popover/chat-composer-popover.schema.ts",
+      "node": "./dist/components/chat-composer-popover/chat-composer-popover.schema.js",
+      "svelte": "./src/components/chat-composer-popover/chat-composer-popover.schema.ts",
+      "import": "./src/components/chat-composer-popover/chat-composer-popover.schema.ts",
+      "default": "./dist/components/chat-composer-popover/chat-composer-popover.schema.js"
+    },
+    "./chat-composer-popover/variables": {
+      "types": "./dist/components/chat-composer-popover/chat-composer-popover.variables.d.ts",
+      "browser": "./src/components/chat-composer-popover/chat-composer-popover.variables.ts",
+      "node": "./dist/components/chat-composer-popover/chat-composer-popover.variables.js",
+      "svelte": "./src/components/chat-composer-popover/chat-composer-popover.variables.ts",
+      "import": "./src/components/chat-composer-popover/chat-composer-popover.variables.ts",
+      "default": "./dist/components/chat-composer-popover/chat-composer-popover.variables.js"
+    },
+    "./chat-composer-popover/styles": {
+      "types": "./dist/components/chat-composer-popover/chat-composer-popover.css.d.ts",
+      "default": "./dist/components/chat-composer-popover/chat-composer-popover.css"
+    },
+    "./chat-composer-popover/examples": {
+      "import": "./src/components/chat-composer-popover/chat-composer-popover.examples.json",
+      "default": "./src/components/chat-composer-popover/chat-composer-popover.examples.json"
+    },
     "./chat-conversation-header": {
       "types": "./dist/components/chat-conversation-header/index.d.ts",
       "browser": "./src/components/chat-conversation-header/index.ts",
@@ -1531,6 +1563,38 @@
       "import": "./src/components/confirm-dialog/confirm-dialog.examples.json",
       "default": "./src/components/confirm-dialog/confirm-dialog.examples.json"
     },
+    "./connection-indicator": {
+      "types": "./dist/components/connection-indicator/index.d.ts",
+      "browser": "./src/components/connection-indicator/index.ts",
+      "node": "./dist/server/components/connection-indicator/index.js",
+      "svelte": "./src/components/connection-indicator/index.ts",
+      "import": "./src/components/connection-indicator/index.ts",
+      "default": "./dist/components/connection-indicator/index.js"
+    },
+    "./connection-indicator/schema": {
+      "types": "./dist/components/connection-indicator/connection-indicator.schema.d.ts",
+      "browser": "./src/components/connection-indicator/connection-indicator.schema.ts",
+      "node": "./dist/components/connection-indicator/connection-indicator.schema.js",
+      "svelte": "./src/components/connection-indicator/connection-indicator.schema.ts",
+      "import": "./src/components/connection-indicator/connection-indicator.schema.ts",
+      "default": "./dist/components/connection-indicator/connection-indicator.schema.js"
+    },
+    "./connection-indicator/variables": {
+      "types": "./dist/components/connection-indicator/connection-indicator.variables.d.ts",
+      "browser": "./src/components/connection-indicator/connection-indicator.variables.ts",
+      "node": "./dist/components/connection-indicator/connection-indicator.variables.js",
+      "svelte": "./src/components/connection-indicator/connection-indicator.variables.ts",
+      "import": "./src/components/connection-indicator/connection-indicator.variables.ts",
+      "default": "./dist/components/connection-indicator/connection-indicator.variables.js"
+    },
+    "./connection-indicator/styles": {
+      "types": "./dist/components/connection-indicator/connection-indicator.css.d.ts",
+      "default": "./dist/components/connection-indicator/connection-indicator.css"
+    },
+    "./connection-indicator/examples": {
+      "import": "./src/components/connection-indicator/connection-indicator.examples.json",
+      "default": "./src/components/connection-indicator/connection-indicator.examples.json"
+    },
     "./container": {
       "types": "./dist/components/container/index.d.ts",
       "browser": "./src/components/container/index.ts",
@@ -4243,6 +4307,38 @@
       "import": "./src/components/run-step-timeline/run-step-timeline.examples.json",
       "default": "./src/components/run-step-timeline/run-step-timeline.examples.json"
     },
+    "./schedule-builder": {
+      "types": "./dist/components/schedule-builder/index.d.ts",
+      "browser": "./src/components/schedule-builder/index.ts",
+      "node": "./dist/server/components/schedule-builder/index.js",
+      "svelte": "./src/components/schedule-builder/index.ts",
+      "import": "./src/components/schedule-builder/index.ts",
+      "default": "./dist/components/schedule-builder/index.js"
+    },
+    "./schedule-builder/schema": {
+      "types": "./dist/components/schedule-builder/schedule-builder.schema.d.ts",
+      "browser": "./src/components/schedule-builder/schedule-builder.schema.ts",
+      "node": "./dist/components/schedule-builder/schedule-builder.schema.js",
+      "svelte": "./src/components/schedule-builder/schedule-builder.schema.ts",
+      "import": "./src/components/schedule-builder/schedule-builder.schema.ts",
+      "default": "./dist/components/schedule-builder/schedule-builder.schema.js"
+    },
+    "./schedule-builder/variables": {
+      "types": "./dist/components/schedule-builder/schedule-builder.variables.d.ts",
+      "browser": "./src/components/schedule-builder/schedule-builder.variables.ts",
+      "node": "./dist/components/schedule-builder/schedule-builder.variables.js",
+      "svelte": "./src/components/schedule-builder/schedule-builder.variables.ts",
+      "import": "./src/components/schedule-builder/schedule-builder.variables.ts",
+      "default": "./dist/components/schedule-builder/schedule-builder.variables.js"
+    },
+    "./schedule-builder/styles": {
+      "types": "./dist/components/schedule-builder/schedule-builder.css.d.ts",
+      "default": "./dist/components/schedule-builder/schedule-builder.css"
+    },
+    "./schedule-builder/examples": {
+      "import": "./src/components/schedule-builder/schedule-builder.examples.json",
+      "default": "./src/components/schedule-builder/schedule-builder.examples.json"
+    },
     "./schema-form": {
       "types": "./dist/components/schema-form/index.d.ts",
       "browser": "./src/components/schema-form/index.ts",
@@ -6418,8 +6514,7 @@
     "diff-match-patch": "^1.0.5",
     "esm-env": "^1.2.0",
     "libphonenumber-js": "^1.13.3",
-    "qrcode": "^1.5.4",
-    "zod": "4.4.1"
+    "qrcode": "^1.5.4"
   },
   "devDependencies": {
     "@changesets/parse": "0.4.3",
@@ -6446,7 +6541,8 @@
     "svelte-check": "^4.0.0",
     "svelte2tsx": "^0.7.33",
     "ts-morph": "^28.0.0",
-    "typescript": "^5.9.0"
+    "typescript": "^5.9.0",
+    "zod": "4.4.1"
   },
   "peerDependencies": {
     "@milkdown/ctx": "^7.17.3",
@@ -6480,7 +6576,8 @@
     "svelte": ">=5.56.0 <6",
     "unified": "^11.0.5",
     "unist-util-remove": "^4.0.0",
-    "unist-util-visit": "^5.0.0"
+    "unist-util-visit": "^5.0.0",
+    "zod": "4.4.1"
   },
   "peerDependenciesMeta": {
     "@milkdown/ctx": {

package/src/components/_internal/command-list-context.ts

@@ -34,18 +34,18 @@ export type CommandItemRegistrationInput = {
  * Context provided by CommandPalette and consumed by CommandItem.
  */
 export type CommandListContext = {
-  /** Stable id for the listbox; items compose their own ids from this. */
+  /** Live id for the listbox; items keep their ids in sync with it. */
   readonly listboxId: string;
   /** Id of the currently active (virtually focused) item, or null. */
   readonly activeItemId: string | null;
   /**
    * Called by each CommandItem when it mounts.
-   * Returns a stable id and an unregister function.
+   * Returns a live id handle and an unregister function.
    */
   register: (
     input: CommandItemRegistrationInput,
     node: HTMLElement,
-  ) => { id: string; unregister: () => void };
+  ) => { readonly id: string; unregister: () => void };
   /** Called by items on pointerenter to sync hover with arrow-key navigation. */
   setActiveById: (id: string) => void;
   /** Called by items and owners to activate the current item by id. */

package/src/components/_internal/create-command-list-state.svelte.ts

@@ -1,6 +1,7 @@
 import { inDocumentOrder } from '../../utilities/document-order.ts';
 export class CommandListState {
-    listboxId;
+    #getListboxId;
+    #registeredListboxId = $state('');
     registrations = $state([]);
     registrationsReady = $state(false);
     #itemCounter = 0;
@@ -15,7 +16,24 @@ export class CommandListState {
         ? this.#intendedActiveId
         : (this.enabledIds[0] ?? null));
     constructor(listboxId) {
-        this.listboxId = listboxId;
+        this.#getListboxId = typeof listboxId === 'function' ? listboxId : () => listboxId;
+        this.#registeredListboxId = this.#getListboxId();
+    }
+    get listboxId() {
+        return this.#registeredListboxId;
+    }
+    syncListboxId(nextListboxId = this.#getListboxId()) {
+        const listboxId = nextListboxId;
+        if (this.#registeredListboxId === listboxId)
+            return;
+        this.#registeredListboxId = listboxId;
+        this.#intendedActiveId = null;
+        this.registrations = this.registrations.map((registration, index) => ({
+            ...registration,
+            id: updateRegistrationHandleId(registration, `${listboxId}-item-${index + 1}`),
+        }));
+        this.#itemCounter = this.registrations.length;
+        this.refreshRegistrationsReady();
     }
     resetActiveItem() {
         this.#intendedActiveId = null;
@@ -38,22 +56,26 @@ export class CommandListState {
         this.#intendedActiveId = id;
     }
     register(input, node) {
+        this.syncListboxId();
         const id = `${this.listboxId}-item-${++this.#itemCounter}`;
-        this.registrations.push({
-            id,
-            node,
-            getValue: input.getValue,
-            getOnselect: input.getOnselect,
-            getDisabled: input.getDisabled,
-        });
-        return {
+        const handle = $state({
             id,
             unregister: () => {
-                const index = this.registrations.findIndex((registration) => registration.id === id);
+                const index = this.registrations.findIndex((registeredItem) => registeredItem.node === node);
                 if (index !== -1)
                     this.registrations.splice(index, 1);
             },
+        });
+        const registration = {
+            id,
+            node,
+            handle,
+            getValue: input.getValue,
+            getOnselect: input.getOnselect,
+            getDisabled: input.getDisabled,
         };
+        this.registrations.push(registration);
+        return handle;
     }
     activateItemById(id) {
         const record = this.registrations.find((registration) => registration.id === id);
@@ -122,13 +144,13 @@ export class CommandListState {
         return false;
     }
     createContext(activateItemById = (id) => void this.activateItemById(id)) {
-        const listboxId = this.listboxId;
+        const getListboxId = () => this.listboxId;
         const getActiveItemId = () => this.activeItemId;
         const register = (input, node) => this.register(input, node);
         const setActiveById = (id) => this.setActiveById(id);
         return {
             get listboxId() {
-                return listboxId;
+                return getListboxId();
             },
             get activeItemId() {
                 return getActiveItemId();
@@ -142,3 +164,7 @@ export class CommandListState {
 export function createCommandListState(listboxId) {
     return new CommandListState(listboxId);
 }
+function updateRegistrationHandleId(registration, id) {
+    registration.handle.id = id;
+    return id;
+}

package/src/components/approval-card/approval-card-actions.svelte

@@ -0,0 +1,168 @@
+<script lang="ts">
+import Button from '../button/button.svelte';
+import { formatEditableArguments, parseJsonText } from './approval-card-state.ts';
+let { idBase, requestKey, canEditArguments, argumentsValue, resolve } = $props();
+const reasonId = $derived(`${idBase}-resolution-reason`);
+const editorId = $derived(`${idBase}-edited-arguments`);
+const editRegionId = $derived(`${idBase}-edit-region`);
+const editDescriptionId = $derived(`${idBase}-edit-description`);
+const editErrorId = $derived(`${idBase}-edit-error`);
+let resolutionReason = $state('');
+let rememberResolution = $state(false);
+let editingArguments = $state(false);
+let editedArgumentsText = $state('');
+// A writable `$derived` that reads `requestKey` looked like the simpler
+// reset mechanism, but a $derived re-runs whenever ANY parent prop update
+// touches its host — not only when the tracked value actually changes —
+// so it silently wiped in-progress reason text / edits on every unrelated
+// host re-render. `{#key requestKey}` has the same intent but was
+// unreliable in practice here (a fresh DOM node with a stale value).
+// Comparing the previous value explicitly, inside the effect, is the
+// one thing that's actually gated on requestKey CHANGING, not merely
+// being re-touched.
+let previousRequestKey = requestKey;
+$effect(() => {
+    if (requestKey === previousRequestKey)
+        return;
+    previousRequestKey = requestKey;
+    resolutionReason = '';
+    rememberResolution = false;
+    // A new request must never leave a stale editor open, even if its
+    // arguments happen to serialize identically to the previous request's
+    // (the separate snapshot effect below wouldn't see a change in that
+    // case) — an edit must never be confirmed against the wrong request.
+    editingArguments = false;
+    editedArgumentsText = '';
+});
+// Separate from the identity reset above: a host can revise
+// `operation.argsPreview` for the SAME request (e.g. a live update) while
+// the edit panel is open. Comparing the formatted snapshot — not object
+// identity, which changes on unrelated re-renders too — closes a stale
+// editor whenever the underlying arguments actually change, so a confirmed
+// edit can never be based on arguments older than what PayloadInspector is
+// currently showing. Re-opening reseeds from the current value.
+let previousArgumentsSnapshot = formatEditableArguments(argumentsValue);
+$effect(() => {
+    const snapshot = formatEditableArguments(argumentsValue);
+    if (snapshot === previousArgumentsSnapshot)
+        return;
+    previousArgumentsSnapshot = snapshot;
+    editingArguments = false;
+    editedArgumentsText = '';
+});
+const editParseResult = $derived(parseJsonText(editedArgumentsText));
+function emitResolution(decision, editedArgs) {
+    const trimmedReason = resolutionReason.trim();
+    const resolution = {
+        decision,
+        remember: rememberResolution,
+    };
+    if (decision === 'approve_with_edits') {
+        resolution.editedArgs = editedArgs;
+    }
+    if (trimmedReason) {
+        resolution.reason = trimmedReason;
+    }
+    resolve(resolution);
+}
+function toggleEditingArguments() {
+    if (!canEditArguments)
+        return;
+    if (!editingArguments) {
+        editedArgumentsText = formatEditableArguments(argumentsValue);
+    }
+    editingArguments = !editingArguments;
+}
+function handleConfirmEditedApproval() {
+    if (!canEditArguments || !editParseResult.ok)
+        return;
+    emitResolution('approve_with_edits', editParseResult.value);
+}
+</script>
+
+<div class="cinder-approval-card__actions">
+  <div class="cinder-approval-card__resolution-controls">
+    <label class="cinder-approval-card__control-label" for={reasonId}>Reason</label>
+    <textarea
+      id={reasonId}
+      class="cinder-approval-card__textarea cinder-approval-card__textarea--reason"
+      bind:value={resolutionReason}
+      rows="2"
+    ></textarea>
+  </div>
+
+  <div class="cinder-approval-card__action-row" role="group" aria-label="Approval actions">
+    <label class="cinder-approval-card__remember-control">
+      <input type="checkbox" bind:checked={rememberResolution} />
+      <span>Don't ask again for operations like this</span>
+    </label>
+
+    <div class="cinder-approval-card__action-buttons">
+      <Button
+        type="button"
+        variant="ghost"
+        class="cinder-approval-card__dismiss"
+        onclick={() => emitResolution('cancel')}
+      >
+        Dismiss
+      </Button>
+      <Button type="button" variant="soft-danger" onclick={() => emitResolution('deny')}>
+        Deny
+      </Button>
+      {#if canEditArguments}
+        <Button
+          type="button"
+          variant="secondary"
+          onclick={toggleEditingArguments}
+          aria-expanded={editingArguments}
+          aria-controls={editingArguments ? editRegionId : undefined}
+        >
+          Approve with edits
+        </Button>
+      {/if}
+      <Button type="button" variant="primary" onclick={() => emitResolution('approve')}>
+        Approve
+      </Button>
+    </div>
+  </div>
+
+  {#if editingArguments && canEditArguments}
+    <div id={editRegionId} class="cinder-approval-card__editor">
+      <label class="cinder-approval-card__control-label" for={editorId}>
+        Edited arguments JSON
+      </label>
+      <p id={editDescriptionId} class="cinder-approval-card__muted">
+        Approving sends the parsed JSON below instead of the original arguments.
+      </p>
+      <textarea
+        id={editorId}
+        class="cinder-approval-card__textarea"
+        bind:value={editedArgumentsText}
+        rows="8"
+        spellcheck="false"
+        aria-describedby={editParseResult.ok
+          ? editDescriptionId
+          : `${editDescriptionId} ${editErrorId}`}
+        aria-invalid={editParseResult.ok ? undefined : 'true'}
+        {@attach (element) => {
+          element.focus();
+        }}
+      ></textarea>
+      {#if !editParseResult.ok}
+        <p id={editErrorId} class="cinder-approval-card__error" role="alert">
+          {editParseResult.message}
+        </p>
+      {/if}
+      <div class="cinder-approval-card__editor-actions">
+        <Button
+          type="button"
+          variant="primary"
+          onclick={handleConfirmEditedApproval}
+          disabled={!editParseResult.ok}
+        >
+          Confirm edited approval
+        </Button>
+      </div>
+    </div>
+  {/if}
+</div>

package/src/components/approval-card/approval-card-state.ts

@@ -1,5 +1,40 @@
-import type { ApprovalState } from './approval-card.types.ts';
+import type { StatusDotStatus } from '../status-dot/status-dot.types.ts';
+import type { ApprovalState, ApprovalToolRisk } from './approval-card.types.ts';
 
+/** Character budget for the serialized arguments preview before truncation. */
+export const ARGUMENTS_PREVIEW_MAX_CHARACTERS = 4_096;
+
+/** Visible label for each risk level. */
+export const RISK_LABELS = {
+  low: 'Low risk',
+  medium: 'Medium risk',
+  high: 'High risk',
+} as const satisfies Record<ApprovalToolRisk, string>;
+
+/** Visible label for each approval state. */
+export const STATE_LABELS = {
+  pending: 'Pending',
+  approved: 'Approved',
+  approved_with_edits: 'Approved with edits',
+  denied: 'Denied',
+  expired: 'Expired',
+  cancelled: 'Cancelled',
+} as const satisfies Record<ApprovalState, string>;
+
+/** StatusDot status for each approval state. */
+export const STATE_DOT_STATUS = {
+  pending: 'pending',
+  approved: 'success',
+  approved_with_edits: 'success',
+  denied: 'danger',
+  expired: 'neutral',
+  cancelled: 'offline',
+} as const satisfies Record<ApprovalState, StatusDotStatus>;
+
+/**
+ * Resolves the state shown to the approver: a pending approval whose
+ * expiration timestamp has passed presents as expired.
+ */
 export function resolveEffectiveApprovalState(
   approvalState: ApprovalState,
   expirationTimestamp: number | undefined,
@@ -9,6 +44,7 @@ export function resolveEffectiveApprovalState(
   return resolveComparisonTime(currentTime) >= expirationTimestamp ? 'expired' : approvalState;
 }
 
+/** Whether approval actions may still be taken on the request. */
 export function isApprovalActionable(
   approvalState: ApprovalState,
   expirationTimestamp: number | undefined,
@@ -22,3 +58,118 @@ export function isApprovalActionable(
 function resolveComparisonTime(currentTime: number | undefined): number {
   return currentTime ?? Date.now();
 }
+
+/** Parses an ISO expiration timestamp, returning undefined for invalid input. */
+export function parseExpirationTimestamp(value: string | undefined): number | undefined {
+  if (!value) return undefined;
+  const timestamp = Date.parse(value);
+  return Number.isFinite(timestamp) ? timestamp : undefined;
+}
+
+/** Formats a millisecond duration as a compact countdown such as `2h 5m` or `45s`. */
+export function formatRemainingTime(milliseconds: number): string {
+  const totalSeconds = Math.max(0, Math.ceil(milliseconds / 1_000));
+  const hours = Math.floor(totalSeconds / 3_600);
+  const minutes = Math.floor((totalSeconds % 3_600) / 60);
+  const seconds = totalSeconds % 60;
+
+  if (hours > 0) return `${hours}h ${minutes}m`;
+  if (minutes > 0) return `${minutes}m ${seconds}s`;
+  return `${seconds}s`;
+}
+
+/**
+ * Accepts serialized JSON strings as argument previews by parsing them into
+ * their structured form; any other value passes through unchanged.
+ */
+export function normalizeArgumentsPreviewValue(value: unknown): unknown {
+  if (typeof value !== 'string') return value;
+
+  try {
+    return JSON.parse(value);
+  } catch {
+    return value;
+  }
+}
+
+/**
+ * Bounds the arguments preview: values whose serialized form exceeds the
+ * character budget are replaced with a truncation notice and an excerpt.
+ */
+export function prepareArgumentsPreview(value: unknown): { value: unknown; truncated: boolean } {
+  try {
+    const serialized = JSON.stringify(value);
+    if (typeof serialized !== 'string' || serialized.length <= ARGUMENTS_PREVIEW_MAX_CHARACTERS) {
+      // Pass the original value through unchanged — including strings.
+      // PayloadInspector does its own parsing/display/copy handling for
+      // strings; re-serializing here would hand it an already-quoted JSON
+      // string, which displays unquoted but copies quoted (a mismatch).
+      return { value, truncated: false };
+    }
+    return {
+      value: {
+        notice: 'Arguments preview truncated',
+        originalCharacters: serialized.length,
+        displayedCharacters: ARGUMENTS_PREVIEW_MAX_CHARACTERS,
+        excerpt: serialized.slice(0, ARGUMENTS_PREVIEW_MAX_CHARACTERS),
+      },
+      truncated: true,
+    };
+  } catch {
+    return { value, truncated: false };
+  }
+}
+
+/** Serializes the arguments preview as the editable JSON seed text. */
+export function formatEditableArguments(value: unknown): string {
+  try {
+    const serialized = JSON.stringify(value, null, 2);
+    return serialized ?? 'null';
+  } catch {
+    return '{}';
+  }
+}
+
+/** Parses editor text as JSON, returning a friendly error for invalid input. */
+export function parseJsonText(
+  text: string,
+): { ok: true; value: unknown } | { ok: false; message: string } {
+  try {
+    return { ok: true, value: JSON.parse(text) };
+  } catch {
+    return { ok: false, message: 'Edited arguments must be valid JSON.' };
+  }
+}
+
+/**
+ * Reduces environment entries to unique variable names. Values accidentally
+ * supplied as `NAME=value` are stripped so no secret material is rendered.
+ */
+export function sanitizeEnvironmentNames(names: string[]): string[] {
+  const seen = new Set<string>();
+  const sanitizedNames: string[] = [];
+
+  for (const name of names) {
+    const [firstPart] = name.split('=');
+    const sanitizedName = firstPart?.trim() ?? '';
+    if (!sanitizedName || seen.has(sanitizedName)) continue;
+    seen.add(sanitizedName);
+    sanitizedNames.push(sanitizedName);
+  }
+
+  return sanitizedNames;
+}
+
+/** Collapses duplicate file paths while preserving first-seen order. */
+export function dedupeFilePaths(paths: string[]): string[] {
+  const seen = new Set<string>();
+  const uniquePaths: string[] = [];
+
+  for (const path of paths) {
+    if (seen.has(path)) continue;
+    seen.add(path);
+    uniquePaths.push(path);
+  }
+
+  return uniquePaths;
+}