@yourrealm/sdk 0.0.0-alpha.1378.ce03c8dc

package/src/ui/components/dialog.tsx

@@ -0,0 +1,137 @@
+import type { ComponentProps } from "preact";
+import { Dialog as DialogPrimitive } from "@ark-ui/react/dialog";
+
+import { cn, type ElementProps } from "../utils.ts";
+import { Button } from "./button.tsx";
+import { XBoldIcon } from "./icons.tsx";
+
+function Dialog(props: ComponentProps<typeof DialogPrimitive.Root>) {
+  return <DialogPrimitive.Root {...props} />;
+}
+
+function DialogTrigger({ ...props }: ComponentProps<typeof DialogPrimitive.Trigger>) {
+  return <DialogPrimitive.Trigger data-slot="dialog-trigger" {...props} />;
+}
+
+function DialogClose({ ...props }: ComponentProps<typeof DialogPrimitive.CloseTrigger>) {
+  return <DialogPrimitive.CloseTrigger data-slot="dialog-close" {...props} />;
+}
+
+function DialogOverlay({ className, ...props }: ComponentProps<typeof DialogPrimitive.Backdrop>) {
+  return (
+    <DialogPrimitive.Backdrop
+      data-slot="dialog-overlay"
+      className={cn(
+        "fixed inset-0 isolate z-50 bg-black/10 duration-100 supports-backdrop-filter:backdrop-blur-xs data-[state=open]:animate-in data-[state=open]:fade-in-0 data-[state=closed]:animate-out data-[state=closed]:fade-out-0",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+function DialogContent({
+  className,
+  children,
+  showCloseButton = true,
+  ...props
+}: ComponentProps<typeof DialogPrimitive.Content> & {
+  showCloseButton?: boolean;
+}) {
+  return (
+    <>
+      <DialogOverlay />
+      <DialogPrimitive.Positioner className="fixed inset-0 z-50 flex items-center justify-center p-4">
+        <DialogPrimitive.Content
+          data-slot="dialog-content"
+          className={cn(
+            "relative grid w-full max-w-[calc(100%-2rem)] gap-4 rounded-2xl bg-background p-4 text-sm shadow-lg duration-100 outline-none sm:max-w-sm data-[state=open]:animate-in data-[state=open]:fade-in-0 data-[state=open]:zoom-in-95 data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95",
+            className,
+          )}
+          {...props}
+        >
+          {children}
+          {showCloseButton && (
+            <DialogPrimitive.CloseTrigger asChild data-slot="dialog-close">
+              <Button variant="ghost" className="absolute top-2 right-2" size="icon-sm">
+                <XBoldIcon />
+                <span className="sr-only">Close</span>
+              </Button>
+            </DialogPrimitive.CloseTrigger>
+          )}
+        </DialogPrimitive.Content>
+      </DialogPrimitive.Positioner>
+    </>
+  );
+}
+
+function DialogHeader({ className, ...props }: ElementProps<"div">) {
+  return (
+    <div data-slot="dialog-header" className={cn("flex flex-col gap-2", className)} {...props} />
+  );
+}
+
+function DialogFooter({
+  className,
+  showCloseButton = false,
+  children,
+  ...props
+}: ElementProps<"div"> & {
+  showCloseButton?: boolean;
+}) {
+  return (
+    <div
+      data-slot="dialog-footer"
+      className={cn(
+        "-mx-4 -mb-4 flex flex-col-reverse gap-2 rounded-b-2xl border-t bg-muted/50 p-4 sm:flex-row sm:justify-end",
+        className,
+      )}
+      {...props}
+    >
+      {children}
+      {showCloseButton && (
+        <DialogPrimitive.CloseTrigger asChild>
+          <Button variant="outline">Close</Button>
+        </DialogPrimitive.CloseTrigger>
+      )}
+    </div>
+  );
+}
+
+function DialogTitle({ className, ...props }: ComponentProps<typeof DialogPrimitive.Title>) {
+  return (
+    <DialogPrimitive.Title
+      data-slot="dialog-title"
+      className={cn("text-base leading-none font-medium", className)}
+      {...props}
+    />
+  );
+}
+
+function DialogDescription({
+  className,
+  ...props
+}: ComponentProps<typeof DialogPrimitive.Description>) {
+  return (
+    <DialogPrimitive.Description
+      data-slot="dialog-description"
+      className={cn(
+        "text-sm text-muted-foreground *:[a]:underline *:[a]:underline-offset-3 *:[a]:hover:text-foreground",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+export {
+  Dialog,
+  DialogClose,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogOverlay,
+  DialogTitle,
+  DialogTrigger,
+};

package/src/ui/components/domain-editor.tsx

@@ -0,0 +1,317 @@
+// The operator's half of `home.publicDomain`: which hostnames the app is
+// served on, and whether the extras redirect to the first or serve alongside
+// it. Like `silo-picker.tsx`, the author declares the leaf, the operator
+// supplies the elevated value, and the control lives in the permission's row.
+//
+// `pushRoutes` short circuits on a single host, so with one domain both modes
+// emit byte-identical Caddy config; the mode checkbox appears at two, where the
+// choice starts to mean something, and the stored mode rides through hidden.
+//
+// This does not know the Realm base domain: the reservation rule ("no host
+// under the Realm domain") and cross-app uniqueness are both server-side, where
+// the messages are complete sentences naming the fix, and a client copy would
+// be a second rule to keep in step.
+
+import { useEffect, useId, useRef } from "preact/hooks";
+import { useSignal } from "@preact/signals";
+import type { DomainMode, PublicDomainGrantData } from "../../schema/public-domain.ts";
+import { Badge } from "./badge.tsx";
+import { Button } from "./button.tsx";
+import { Checkbox } from "./checkbox.tsx";
+import { Input } from "./input.tsx";
+import { Label } from "./label.tsx";
+import { PlusIcon, TrashIcon } from "./icons.tsx";
+import {
+  addHosts,
+  dedupeHosts,
+  modeSentence,
+  moveToFront,
+  removeAt,
+  wwwSuggestions,
+} from "./domain-list.ts";
+
+interface Props {
+  /** The stored grant record. Undefined until the operator touches it. */
+  value: PublicDomainGrantData | undefined;
+  onChange: (next: PublicDomainGrantData) => void;
+  /**
+   * Turn the permission on, called when a hostname is added.
+   *
+   * Adding a domain you own IS the grant, so making the operator find the
+   * switch first is asking them to say the same thing twice - and a hostname
+   * typed under an off switch is dropped at submit by `descriptorsToGrants`
+   * with nothing to show for it. Only adding does this. Removing a row leaves
+   * the switch alone, so tidying up a parked list can't silently re-grant.
+   */
+  onEnable?: () => void;
+  /**
+   * Whether the permission's switch is on. Not a lock - adding is live either
+   * way, because adding is what turns it on. It greys the rows and the mode
+   * checkbox, which is the only cue that a list under an off switch publishes
+   * nothing and is dropped at submit by `descriptorsToGrants`.
+   */
+  enabled?: boolean;
+  disabled?: boolean;
+  /**
+   * Text sits in the add field that hasn't been turned into a row. The panel
+   * gates Install/Save on it, so "typed a domain, hit Install, got an app with
+   * no domain" can't happen. Never true for an empty list: blank is a perfectly
+   * valid grant.
+   */
+  onPendingChange?: (pending: boolean) => void;
+}
+
+export function DomainEditor({
+  value,
+  onChange,
+  onEnable,
+  enabled = true,
+  disabled,
+  onPendingChange,
+}: Props) {
+  const draft = useSignal("");
+  const errors = useSignal<string[]>([]);
+  // Blur-commit has to know whether focus went somewhere inside this control:
+  // clicking Add, a trash button or the mode checkbox blurs the field first,
+  // and committing there would apply the click to a list one edit behind.
+  const root = useRef<HTMLDivElement>(null);
+  // `relatedTarget` alone doesn't answer that. Safari and Firefox don't focus
+  // a <button> on mousedown, so it arrives null for exactly the clicks this
+  // guard exists for. Track the pointer as well: focus clears the flag, a
+  // pointerdown inside sets it, and the blur that follows reads and clears it.
+  const pointerInside = useRef(false);
+  // Not a literal: an app may declare two publicDomain leaves, and duplicate
+  // ids would point every label at the first control's inputs.
+  const uid = useId();
+
+  // The parent owns identity, so keep the latest callback in a ref rather than
+  // in an effect's dependency list - the panels pass an inline arrow.
+  const notify = useRef(onPendingChange);
+  notify.current = onPendingChange;
+  useEffect(() => {
+    notify.current?.(!disabled && draft.value.trim().length > 0);
+  }, [disabled, draft.value]);
+  // A leaf can leave the tree with text still in it (step back, optional
+  // section switched off), and a gate nobody can clear is worse than no gate.
+  useEffect(() => () => notify.current?.(false), []);
+
+  // Seeded duplicates are rendered as-is: silently rewriting an untouched form
+  // is its own bug, and both rows are removable.
+  const hosts = value?.hosts ?? [];
+  const mode: DomainMode = value?.domainMode ?? "redirect";
+
+  function emit(nextHosts: string[], nextMode: DomainMode) {
+    // Any change to the list retires the last error. `commit` re-sets its own
+    // errors after calling through here, so its message survives; a remove, a
+    // reorder or a mode flip clears a line about a list that no longer exists.
+    errors.value = [];
+    // The mode is carried through, never derived from the list length. Writing
+    // `nextHosts.length >= 2 ? nextMode : "redirect"` would silently downgrade
+    // a stored "all" the moment the operator pulls a host out to retype it.
+    onChange({ hosts: dedupeHosts(nextHosts), domainMode: nextMode });
+  }
+
+  // Adding is the one mutation that grants. See `onEnable`.
+  function add(nextHosts: string[]) {
+    onEnable?.();
+    emit(nextHosts, mode);
+  }
+
+  function commit() {
+    const raw = draft.value;
+    // Nothing typed is nothing to answer for. Deliberately leaves `errors`
+    // alone: this runs on every blur of an empty field, and clearing here would
+    // wipe the line explaining why the last commit produced no row.
+    if (!raw.trim()) {
+      draft.value = "";
+      return;
+    }
+    const result = addHosts(hosts, raw);
+    // What failed to parse stays in the field - it is a typo to fix, and
+    // clearing it would leave an error line with nothing to correct. A
+    // duplicate leaves nothing behind: that name is already on the list.
+    draft.value = result.rejected.join(" ");
+    if (result.added.length > 0) add(result.hosts);
+    // Last, because `add` goes through `emit`, which clears errors.
+    errors.value = result.errors;
+  }
+
+  // Purely additive: offered only while a sibling is missing, and gone once it
+  // lands. Not a checkbox - that reads as a stored link between the two names,
+  // and `hosts` is a flat list.
+  const siblings = wwwSuggestions(hosts);
+  const sentence = modeSentence(hosts, mode);
+  // Occurrence ordinal, so a key survives a reorder. A bare host collides when
+  // a seeded grant holds the same name twice; a bare index changes for every
+  // row after a removal, which makes Preact tear down and rebuild the tail.
+  const ordinals = new Map<string, number>();
+  const rows = hosts.map((host, i) => {
+    const nth = ordinals.get(host) ?? 0;
+    ordinals.set(host, nth + 1);
+    return { host, i, key: `${host}#${nth}` };
+  });
+
+  return (
+    <div
+      ref={root}
+      class="mt-2 flex flex-col gap-2"
+      data-slot="domain-editor"
+      onPointerDown={() => (pointerInside.current = true)}
+    >
+      <Label htmlFor={`${uid}-add`} className="text-xs font-medium text-text-muted">
+        Hostnames
+      </Label>
+
+      {rows.length > 0 && (
+        // Greyed, not hidden, while the permission is off: the list is still
+        // the operator's and flipping the switch back on returns it, but
+        // `descriptorsToGrants` drops it at submit, so it must not read as live.
+        <ul class={`flex flex-col gap-1 ${enabled ? "" : "opacity-50"}`}>
+          {rows.map(({ host, i, key }) => (
+            <li
+              key={key}
+              data-testid="domain-row"
+              data-host={host}
+              class="flex items-center gap-2 rounded-xl border border-border bg-surface-tinted px-2.5 py-1"
+            >
+              <span class="min-w-0 flex-1 truncate font-mono text-xs text-text-dark">{host}</span>
+              {i === 0 && rows.length > 1 && (
+                <Badge variant="outline" className="shrink-0">
+                  Primary
+                </Badge>
+              )}
+              {i > 0 && (
+                <Button
+                  size="xs"
+                  variant="ghost"
+                  disabled={disabled || !enabled}
+                  data-testid={`domain-make-primary-${host}`}
+                  onClick={() => emit(moveToFront(hosts, i), mode)}
+                >
+                  Make primary
+                </Button>
+              )}
+              <Button
+                size="icon-xs"
+                variant="ghost"
+                disabled={disabled || !enabled}
+                aria-label={`Remove ${host}`}
+                data-testid={`domain-remove-${host}`}
+                onClick={() => emit(removeAt(hosts, i), mode)}
+              >
+                <TrashIcon />
+              </Button>
+            </li>
+          ))}
+        </ul>
+      )}
+
+      {hosts.length > 0 && !enabled && (
+        <p class="text-xs text-perm leading-snug" data-testid="domain-parked">
+          Not published while this permission is off. Turn it on, or add a hostname to turn it on.
+        </p>
+      )}
+
+      {sentence && enabled && <p class="text-xs text-muted-foreground leading-snug">{sentence}</p>}
+
+      <div class="flex items-center gap-2">
+        <Input
+          id={`${uid}-add`}
+          data-slot="domain-input"
+          // The placeholder is the discovery mechanism once a row exists: an
+          // empty field sitting under a list is what says "list", without
+          // helper text nobody reads.
+          placeholder={hosts.length === 0 ? "photos.example.com" : "Add another hostname…"}
+          value={draft.value}
+          disabled={disabled}
+          onFocus={() => (pointerInside.current = false)}
+          onValueChange={(v) => {
+            draft.value = v;
+            // Typing is the operator answering the error; keep it on screen no
+            // longer than that. `commit` sets `errors` by writing the signal
+            // directly, which doesn't come back through here, so it survives.
+            if (errors.value.length > 0) errors.value = [];
+          }}
+          onKeyDown={(e: KeyboardEvent) => {
+            // Comma too: it is how a list is written, and `splitHosts` already
+            // treats it as a separator on paste.
+            if (e.key !== "Enter" && e.key !== ",") return;
+            e.preventDefault();
+            commit();
+          }}
+          // Committing on the way out is what stops a typed domain from being
+          // silently dropped at Install. Skipped when the click landed inside
+          // the control, so Add, a row button or the mode checkbox acts on the
+          // list the operator was looking at. Both signals are needed: focus
+          // covers keyboard traversal, the pointer flag the browsers that leave
+          // `relatedTarget` null on a button click.
+          onBlur={(e: FocusEvent) => {
+            const next = e.relatedTarget as Node | null;
+            const inside = pointerInside.current || (next != null && root.current?.contains(next));
+            pointerInside.current = false;
+            if (inside) return;
+            commit();
+          }}
+        />
+        {/* Enter alone is a secret. The button is what tells an operator who
+            has never seen this screen that names get added one at a time. */}
+        <Button
+          size="sm"
+          variant="outline"
+          disabled={disabled || draft.value.trim().length === 0}
+          data-testid="domain-add"
+          onClick={commit}
+        >
+          Add
+        </Button>
+      </div>
+
+      {errors.value.map((message) => (
+        <p key={message} class="text-xs text-danger">
+          {message}
+        </p>
+      ))}
+
+      {siblings.length > 0 && (
+        <div class="flex flex-wrap items-center gap-1">
+          {siblings.map((sibling) => (
+            <Button
+              key={sibling}
+              size="xs"
+              variant="ghost"
+              disabled={disabled}
+              data-testid={`domain-add-www-${sibling}`}
+              onClick={() => add([...hosts, sibling])}
+            >
+              <PlusIcon />
+              Add {sibling}
+            </Button>
+          ))}
+        </div>
+      )}
+
+      {hosts.length > 1 && (
+        <div class="flex items-center gap-2">
+          <Checkbox
+            id={`${uid}-mode`}
+            checked={mode === "all"}
+            disabled={disabled || !enabled}
+            data-testid="domain-mode-all"
+            onCheckedChange={(details: { checked: boolean | "indeterminate" }) =>
+              emit(hosts, details.checked === true ? "all" : "redirect")
+            }
+          />
+          <Label htmlFor={`${uid}-mode`} className="text-xs text-muted-foreground">
+            Serve the app at every domain
+          </Label>
+        </div>
+      )}
+
+      <p class="text-xs text-muted-foreground leading-snug">
+        {hosts.length === 0
+          ? "Point this name at this worker. Leave it blank to keep the app on its Realm subdomain."
+          : "Point each name at this worker."}
+      </p>
+    </div>
+  );
+}

package/src/ui/components/domain-list.ts

@@ -0,0 +1,205 @@
+// The list rules behind the domain editor, with no JSX and no Preact in them,
+// so `deno test` can cover the parsing and ordering the control depends on.
+//
+// Every host that leaves here has been through `publicDomainHostSchema` - the
+// same schema the grant write parses against - so the editor never invents a
+// second hostname rule, and an error line is verbatim what the server would
+// have said.
+
+import {
+  dedupeHosts,
+  publicDomainHostSchema,
+  type DomainMode,
+} from "../../schema/public-domain.ts";
+
+export { dedupeHosts };
+
+/**
+ * Split one field's contents into candidate hostnames.
+ *
+ * Whitespace, commas and semicolons all separate, which covers a list pasted
+ * out of a registrar's UI as well as one typed by hand. There is no `onPaste`
+ * handler: the field holds the blob and committing splits it, so both routes
+ * are the same code path.
+ */
+export function splitHosts(raw: string): string[] {
+  return raw.split(/[\s,;]+/).filter((part) => part.length > 0);
+}
+
+export type ParsedHost = { ok: true; host: string } | { ok: false; error: string };
+
+// Scheme, per RFC 3986: a letter then letters, digits, +, - or dot.
+const URL_SCHEME = /^[a-z][a-z0-9+.-]*:\/\//i;
+
+/**
+ * The hostname out of something pasted from a browser's address bar.
+ *
+ * Only fires when there is an actual `scheme://` in front. A bare
+ * `example.com/photos` is left alone and rejected by the schema, because
+ * without a scheme there is nothing that reliably marks where the host ends,
+ * and quietly discarding half of what someone typed is worse than saying no.
+ *
+ * This is a convenience layer, never a security one: whatever comes out still
+ * goes through `publicDomainHostSchema`, which is the DNS-charset gate.
+ * Stripping in the schema itself would widen what the server accepts on
+ * the API path, which is exactly what that gate exists to prevent.
+ */
+export function stripUrlNoise(raw: string): string {
+  const trimmed = raw.trim();
+  if (!URL_SCHEME.test(trimmed)) return trimmed;
+  let rest = trimmed.replace(URL_SCHEME, "");
+  // The authority ends at the first path, query or fragment delimiter.
+  const end = rest.search(/[/?#]/);
+  if (end !== -1) rest = rest.slice(0, end);
+  // `user:pass@host` - the host is what follows the last `@`, which is also
+  // how a browser reads it. Taking the front half would name the wrong host.
+  const at = rest.lastIndexOf("@");
+  if (at !== -1) rest = rest.slice(at + 1);
+  return rest.replace(/:\d+$/, "");
+}
+
+/**
+ * One candidate, normalized and validated by the grant schema itself. The
+ * failure message is the schema's own, so the operator reads the same sentence
+ * whether the host was rejected here or at the API.
+ */
+export function parseHost(raw: string): ParsedHost {
+  const parsed = publicDomainHostSchema.safeParse(stripUrlNoise(raw));
+  if (parsed.success) return { ok: true, host: parsed.data };
+  return {
+    ok: false,
+    error: parsed.error.issues[0]?.message ?? "is not a hostname",
+  };
+}
+
+export interface AddResult {
+  /** The list to emit: `current` plus everything that landed, in order. */
+  hosts: string[];
+  /** What actually landed. Empty means nothing changed. */
+  added: string[];
+  /** Candidates that failed to parse, verbatim, so the field can keep them. */
+  rejected: string[];
+  /** One complete sentence per thing the operator should know about. */
+  errors: string[];
+}
+
+/**
+ * Add a field's worth of candidates to an existing list.
+ *
+ * Normalize-then-compare against the already-normalized list is exactly the
+ * comparison `domain_claim`'s primary key makes, so what the form calls a
+ * duplicate is what the server would have called one.
+ */
+export function addHosts(current: readonly string[], raw: string): AddResult {
+  const candidates = splitHosts(raw);
+  const seen = new Set(current);
+  const added: string[] = [];
+  const rejected: string[] = [];
+  const duplicates: string[] = [];
+  const errors: string[] = [];
+  for (const candidate of candidates) {
+    const parsed = parseHost(candidate);
+    if (!parsed.ok) {
+      // The same bad name twice is one thing to fix, not two. Saying it twice
+      // is noise, and it also collides on the message-keyed error rows the
+      // editor renders.
+      if (!rejected.includes(candidate)) {
+        rejected.push(candidate);
+        errors.push(`"${candidate}" ${parsed.error}`);
+      }
+      continue;
+    }
+    if (seen.has(parsed.host)) {
+      if (!duplicates.includes(parsed.host)) duplicates.push(parsed.host);
+      continue;
+    }
+    seen.add(parsed.host);
+    added.push(parsed.host);
+  }
+  // A duplicate alongside names that DID land is noise: the operator asked for
+  // "these domains", and these domains is what they have. A commit where
+  // nothing landed at all is the opposite - the field empties, no row appears,
+  // and silence there is indistinguishable from the paste being swallowed.
+  if (duplicates.length > 0 && added.length === 0) {
+    errors.push(
+      duplicates.length === 1
+        ? `"${duplicates[0]}" is already listed.`
+        : "Those hostnames are already listed.",
+    );
+  }
+  return { hosts: [...current, ...added], added, rejected, errors };
+}
+
+/**
+ * The `www.` sibling worth offering as a one-click shortcut, or null.
+ *
+ * Two labels is the entire rule, which makes it wrong for `example.co.uk` -
+ * that is an apex to its owner and a three-label name to this function, so no
+ * shortcut is offered. Telling the two apart needs a public-suffix list, and
+ * shipping (or fetching) one to decorate a checkbox is not a trade worth
+ * making. Nothing is lost: `www.example.co.uk` can still be typed into the
+ * field like any other host.
+ */
+export function wwwSibling(host: string): string | null {
+  if (host.startsWith("www.")) return null;
+  if (host.split(".").length !== 2) return null;
+  return `www.${host}`;
+}
+
+/**
+ * Every `www.` variant the list is missing, in list order.
+ *
+ * Scans the whole list rather than just the canonical host: a second brand
+ * domain wants its `www.` exactly as much as the first one does, and keying
+ * the offer to `hosts[0]` silently drops it for every name added after. One
+ * button each, so what is offered is always what is missing.
+ */
+export function wwwSuggestions(hosts: readonly string[]): string[] {
+  const have = new Set(hosts);
+  const out: string[] = [];
+  for (const host of hosts) {
+    const sibling = wwwSibling(host);
+    if (sibling === null || have.has(sibling) || out.includes(sibling)) continue;
+    out.push(sibling);
+  }
+  return out;
+}
+
+/**
+ * What the current list and mode actually do, in the operator's own hostnames.
+ *
+ * Naming both ends is the point. "Other domains redirect here" leaves the
+ * direction to be inferred from row order, and getting it backwards (www
+ * canonical, apex redirecting to it) is the single most likely mistake here -
+ * it is what you get by typing `www.` first. Spelled out, a backwards setup
+ * reads wrong at a glance.
+ *
+ * Null below two hosts: `pushRoutes` short-circuits there, so both modes emit
+ * identical config and there is nothing true to say.
+ */
+export function modeSentence(hosts: readonly string[], mode: DomainMode): string | null {
+  // Deduped first: the editor renders a seeded duplicate as two rows on
+  // purpose, and counting those would produce "a.com redirects to a.com."
+  // The routes are built from the deduped list, so this describes them.
+  const unique = dedupeHosts([...hosts]);
+  if (unique.length < 2) return null;
+  const [primary, ...rest] = unique;
+  if (mode === "all") return `All ${unique.length} hostnames serve the app.`;
+  if (rest.length === 1) return `${rest[0]} redirects to ${primary}.`;
+  return `The other ${rest.length} hostnames redirect to ${primary}.`;
+}
+
+/** Promote one host to canonical. Out-of-range indexes leave the list alone. */
+export function moveToFront(hosts: readonly string[], index: number): string[] {
+  if (index <= 0 || index >= hosts.length) return [...hosts];
+  const next = [...hosts];
+  const [moved] = next.splice(index, 1);
+  next.unshift(moved!);
+  return next;
+}
+
+/** Drop one row. Out-of-range indexes leave the list alone. */
+export function removeAt(hosts: readonly string[], index: number): string[] {
+  if (index < 0 || index >= hosts.length) return [...hosts];
+  return hosts.filter((_, i) => i !== index);
+}