@yourrealm/sdk 0.0.0-alpha.1378.ce03c8dc

package/src/ui/install/install-app-panel.tsx

@@ -0,0 +1,912 @@
+import { useEffect } from "preact/hooks";
+import { useSignal, useComputed } from "@preact/signals";
+import type { SerializablePermission } from "../../sandbox.ts";
+import { Button } from "../components/button.tsx";
+import { ImagePosture } from "../components/image-posture.tsx";
+import { PermissionRow } from "../components/permission-row.tsx";
+import { PermissionSection, SectionLabel } from "../components/permission-section.tsx";
+import { CubeIcon } from "../components/icons.tsx";
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+} from "../components/dialog.tsx";
+import { Checkbox } from "../components/checkbox.tsx";
+import {
+  PERMISSION_META,
+  partitionHostKinds,
+  type HostPermissionKind,
+  type WorkerCapability,
+  type PermissionKind,
+} from "../../home.ts";
+import {
+  TabsForm,
+  type ConfigFieldTree,
+  type ConfigField,
+  type ConfigContainerNode,
+} from "./tabs-form.tsx";
+import { DeployTargetsPicker, type DeployTargets } from "./deploy-targets-picker.tsx";
+import { descriptorsToGrants } from "../../grants-builder.ts";
+import { permsInInactiveSections } from "./perms-inactive.ts";
+import { findMissingRequired } from "./required-fields.ts";
+import { InstallError, type InstallErrorShape } from "./install-error.tsx";
+import {
+  InstallAdapterError,
+  type InstallAdapter,
+  type PreviewResult,
+  type SiloOption,
+} from "./adapter.ts";
+
+interface Worker {
+  id: string;
+  slug: string;
+  name: string | null;
+  capabilities: WorkerCapability[];
+}
+
+// Rough "how old" string for the image posture card.
+function formatAge(iso: string | null): string {
+  if (!iso) return "unknown";
+  const then = new Date(iso).getTime();
+  if (Number.isNaN(then)) return "unknown";
+  const days = Math.floor((Date.now() - then) / 86_400_000);
+  if (days < 7) return days <= 1 ? "1 day" : `${days} days`;
+  const weeks = Math.floor(days / 7);
+  if (weeks < 9) return weeks === 1 ? "1 week" : `${weeks} weeks`;
+  const months = Math.floor(days / 30);
+  if (months < 24) return months === 1 ? "1 month" : `${months} months`;
+  const years = Math.floor(days / 365);
+  return years === 1 ? "1 year" : `${years} years`;
+}
+
+interface Props {
+  workers: Worker[];
+  plumbing: InstallAdapter;
+  /**
+   * Pre-fill the source on mount and run `preview` immediately, jumping
+   * straight to the summary step. The textarea isn't rendered when this
+   * is set — the panel assumes the host has authoritative access to the
+   * realm.ts on disk. Used by `realm-sdk dev`'s /install route.
+   */
+  initialSource?: string;
+  /**
+   * Upstream registry id (e.g. "realm/counter-fresh") forwarded to
+   * `plumbing.install` so the host can correlate the new app row with
+   * its store listing. Set by the host when `initialSource` came from a
+   * known listing.
+   */
+  sourceId?: string;
+  /**
+   * Skip the DeployTargetsPicker on the configure step. `deployTargets`
+   * stays at its `true` default so the install payload remains valid.
+   * Used in dev where there's exactly one local target.
+   */
+  hideDeployTargets?: boolean;
+  /**
+   * Render a secondary "Install as template" button next to the primary
+   * install button. A template install posts `role: "template"`, landing a
+   * parked row that never deploys — a `builder`-scoped app (e.g.
+   * Forge) stamps previews from it. Off by default, so the store-install and
+   * `realm-sdk dev` flows keep a single install button. Home's "from source"
+   * install page sets it.
+   */
+  showInstallAsTemplate?: boolean;
+}
+
+// The worker a single app starts pinned to: the first that
+// advertises every required host kind. `null` when none qualifies — the
+// picker then renders expanded and unpicked, because *why* nothing was
+// chosen (each worker's missing kinds) is what the operator needs to read.
+function autoPickWorker(workers: Worker[], requiredKinds: HostPermissionKind[]): string | null {
+  const capable = workers.find((w) => {
+    const caps = new Set(w.capabilities);
+    return requiredKinds.every((k) => caps.has(k));
+  });
+  return capable?.id ?? null;
+}
+
+function defaultConfigValues(schema: ConfigFieldTree): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const [name, field] of Object.entries(schema)) {
+    if (field.type === "permission") continue;
+    if (field.type === "tab" || field.type === "section") {
+      // Optional sections are `undefined` until the user toggles the
+      // feature on - that's the only way the sandbox learns the feature
+      // is active.
+      if (field.optional) continue;
+      out[name] = defaultConfigValues(field.fields);
+    } else if ("default" in field && field.default !== undefined) {
+      out[name] = field.default;
+    }
+  }
+  return out;
+}
+
+function setPath(
+  obj: Record<string, unknown>,
+  path: string,
+  value: unknown,
+): Record<string, unknown> {
+  const segments = path.split(".");
+  const clone: Record<string, unknown> = { ...obj };
+  let cursor = clone;
+  for (let i = 0; i < segments.length - 1; i++) {
+    const seg = segments[i]!;
+    const next = cursor[seg];
+    const nextObj =
+      next && typeof next === "object" && !Array.isArray(next)
+        ? { ...(next as Record<string, unknown>) }
+        : {};
+    cursor[seg] = nextObj;
+    cursor = nextObj;
+  }
+  if (value === undefined) {
+    delete cursor[segments[segments.length - 1]!];
+  } else {
+    cursor[segments[segments.length - 1]!] = value;
+  }
+  return clone;
+}
+
+// "Don't show this again" for the install-as-template explainer: one key
+// holding a level. 0 = never dismissed, 1 = base explainer, 2 = base + the
+// "no persistent volumes" note; a higher level subsumes the lower, so a
+// level-1 dismissal still surfaces the volumes note on the first
+// volume-declaring template. Guarded so SSR / disabled storage always show.
+const TEMPLATE_NOTICE_KEY = "realm.templateInstallNoticeDismissed";
+function dismissedLevel(): number {
+  try {
+    if (typeof localStorage === "undefined") return 0;
+    return Number(localStorage.getItem(TEMPLATE_NOTICE_KEY)) || 0;
+  } catch {
+    return 0;
+  }
+}
+function setDismissedLevel(level: number): void {
+  try {
+    // Never downgrade — a higher dismissal already covers the lower notice.
+    if (typeof localStorage !== "undefined") {
+      localStorage.setItem(TEMPLATE_NOTICE_KEY, String(Math.max(level, dismissedLevel())));
+    }
+  } catch {
+    // Private mode / storage disabled — the notice just keeps showing.
+  }
+}
+// The dismissal level a template needs: a volume-declaring template shows the
+// extra note (2); a volumeless one only the base explainer (1).
+function templateNoticeLevel(hasVolumes: boolean): number {
+  return hasVolumes ? 2 : 1;
+}
+function shouldShowTemplateDialog(hasVolumes: boolean): boolean {
+  return dismissedLevel() < templateNoticeLevel(hasVolumes);
+}
+
+export default function InstallAppPanel({
+  workers,
+  plumbing,
+  initialSource,
+  sourceId,
+  hideDeployTargets,
+  showInstallAsTemplate,
+}: Props) {
+  const step = useSignal<"discover" | "summary" | "configure">("discover");
+  const source = useSignal(initialSource ?? "");
+  const preview = useSignal<PreviewResult | null>(null);
+  const config = useSignal<Record<string, unknown>>({});
+  const enabled = useSignal<Set<string>>(new Set());
+  const grantValues = useSignal<Record<string, unknown>>({});
+  // Per-path: a `home.publicDomain` leaf whose add field still holds a
+  // hostname nobody turned into a row. Keyed rather than a flag because an
+  // app may declare two leaves.
+  const pendingDomains = useSignal<Record<string, boolean>>({});
+  const deployTargets = useSignal<DeployTargets | null>(null);
+  // Only loaded for apps that declare host.silo; every other install never
+  // asks the host for its Silos.
+  const silos = useSignal<SiloOption[]>([]);
+  const parsing = useSignal(false);
+  const installing = useSignal(false);
+  const error = useSignal<InstallErrorShape | null>(null);
+  // "Install as template" opens an explainer dialog (unless the operator
+  // dismissed it); the checkbox persists that dismissal to localStorage.
+  const templateDialogOpen = useSignal(false);
+  const dontShowAgain = useSignal(false);
+  // The host declares whether it does Silos by implementing the methods. A host
+  // without them gets no picker and no gate: `realm-sdk dev` has no Home to hold
+  // a Silo record, and its compiler already fails a silo app with an actionable
+  // message that a disabled button would replace with a dead end.
+  const hostHasSilos = typeof plumbing.listSilos === "function";
+
+  async function onParse() {
+    error.value = null;
+    if (!source.value.trim()) {
+      error.value = { kind: "message", message: "Paste a realm.ts source first." };
+      return;
+    }
+    parsing.value = true;
+    try {
+      const result = await plumbing.preview(source.value);
+      preview.value = result;
+      // Pre-fill from an existing install if the host surfaces one (`realm-sdk
+      // dev` does, via the on-disk realm-sdk.dev.ts), so a second visit to
+      // /install on the same app is an edit flow. Otherwise schema defaults.
+      config.value = result.currentConfig ?? defaultConfigValues(result.configFields);
+      // Default the deploy picker per app kind: "single" pre-selects the first
+      // worker that satisfies the app's required host kinds (null if none can);
+      // "system" has no choice to make and stays null, which is what the install
+      // payload omits. In dev (`hideDeployTargets`) there is no picker and the
+      // dev install handler ignores `deployed` either way.
+      deployTargets.value =
+        hideDeployTargets || result.kind === "system"
+          ? null
+          : autoPickWorker(
+              workers,
+              partitionHostKinds(result.permissionsFlat, result.configFields).required,
+            );
+      const initial = new Set<string>();
+      const initialGrantValues: Record<string, unknown> = {};
+      if (result.currentGrants) {
+        for (const [path, grant] of Object.entries(result.currentGrants)) {
+          initial.add(path);
+          // PeerGrant has no `data` field (peers are presence-only at
+          // grant time); skip those. For host grants, `data === true`
+          // is the presence-only flag (host.gpu/egress/management)
+          // and doesn't need a per-path override either.
+          if ("data" in grant && grant.data !== true && grant.data !== undefined) {
+            initialGrantValues[path] = grant.data;
+          }
+        }
+      } else {
+        // No existing fixture — start with every required permission
+        // toggled on; optional ones default off, admin can opt in from
+        // the configure step.
+        for (const [path, perm] of Object.entries(result.permissionsFlat)) {
+          if (!(perm.meta as { isOptional?: boolean }).isOptional) initial.add(path);
+        }
+      }
+      enabled.value = initial;
+      grantValues.value = initialGrantValues;
+      // Loaded before the step advances, so the configure step never renders a
+      // picker whose list is still in flight - an empty picker and a loading
+      // one look identical, and the difference is "create a duplicate Silo".
+      const listSilos = plumbing.listSilos?.bind(plumbing);
+      if (listSilos && Object.values(result.permissionsFlat).some((p) => p.kind === "host.silo")) {
+        try {
+          silos.value = await listSilos();
+        } catch (err) {
+          error.value = {
+            kind: "network",
+            message: `Couldn't load Silos: ${(err as Error).message}`,
+          };
+        }
+      }
+      step.value = "summary";
+    } catch (err) {
+      error.value =
+        err instanceof InstallAdapterError
+          ? err.shape
+          : { kind: "network", message: (err as Error).message };
+    } finally {
+      parsing.value = false;
+    }
+  }
+
+  async function onInstall(asTemplate: boolean) {
+    if (!preview.value) return;
+    error.value = null;
+    installing.value = true;
+    let installedId: string | null = null;
+    try {
+      // Drop any grants the admin left toggled on inside an
+      // optional section that's currently off - the feature isn't
+      // consumed so the grant shouldn't be stored.
+      const inactive = permsInInactiveSections(
+        preview.value.configFields,
+        config.value,
+        preview.value.permissionsFlat,
+      );
+      const effectiveEnabled = new Set<string>();
+      for (const p of enabled.value) {
+        if (!inactive.has(p)) effectiveEnabled.add(p);
+      }
+      const grants = descriptorsToGrants(preview.value.permissionsFlat, {
+        enabled: effectiveEnabled,
+        grantValues: grantValues.value,
+      });
+      // A single app has to name its worker; `missingDeployTarget` already
+      // disables the button, so this is the type narrowing. A system app
+      // sends nothing — the host derives its placement from the source.
+      const deployed = deployTargets.value;
+      if (missingDeployTarget.value) return;
+      const result = await plumbing.install({
+        source: source.value,
+        ...(deployed !== null ? { deployed } : {}),
+        config: config.value,
+        grants,
+        ...(sourceId ? { sourceId } : {}),
+        ...(asTemplate ? { role: "template" as const } : {}),
+      });
+      installedId = result.id;
+    } catch (err) {
+      error.value =
+        err instanceof InstallAdapterError
+          ? err.shape
+          : { kind: "network", message: (err as Error).message };
+      return;
+    } finally {
+      installing.value = false;
+    }
+    // Post-install side-effect runs only after `install` resolved.
+    // An exception thrown here must NOT masquerade as install
+    // failure — the DB row is real. installedId is set iff install
+    // resolved (the early `missingDeployTarget` / catch paths returned).
+    if (installedId !== null) plumbing.onInstalled(installedId);
+  }
+
+  // Auto-preview when host pre-fills the source. The host owns the
+  // file so there's no paste step; if preview fails we show the error
+  // in place of (the now-hidden) textarea.
+  useEffect(() => {
+    if (initialSource !== undefined) {
+      void onParse();
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  const togglePermission = (path: string, v: boolean) => {
+    const next = new Set(enabled.value);
+    if (v) next.add(path);
+    else next.delete(path);
+    enabled.value = next;
+  };
+
+  // The worker scoping the Silo choice. A system app has no worker (null),
+  // and never could: a Silo is a directory on one box, so `host.silo` is
+  // single-only (`appKinds`, schema/host.ts) and the declaration is refused
+  // before an install ever gets here.
+  const siloWorkerId = useComputed(() =>
+    typeof deployTargets.value === "string" ? deployTargets.value : null,
+  );
+
+  async function onCreateSilo(input: { name: string; containerPath?: string; hostPath?: string }) {
+    const workerId = siloWorkerId.value;
+    if (!workerId) throw new Error("Pick a worker first.");
+    if (!plumbing.createSilo) throw new Error("This host can't create Silos.");
+    const created = await plumbing.createSilo({ ...input, workerId });
+    silos.value = [...silos.value, created];
+    return created;
+  }
+
+  async function onAcknowledgeSilo(id: string) {
+    await plumbing.acknowledgeSilo!(id);
+    // Clearing the command locally is the same derivation the host does, and it
+    // beats re-listing: a refetch mid-install could hand back a list the
+    // operator's own create isn't in yet.
+    silos.value = silos.value.map((s) => (s.id === id ? { ...s, setupCommand: null } : s));
+  }
+
+  function onDeployTargetsChange(v: DeployTargets | null) {
+    deployTargets.value = v;
+    // A Silo picked for the old worker can't resolve on the new one, and the
+    // picker filters it out of view. Drop it rather than install a grant
+    // naming a box the app no longer runs on.
+    const workerId = typeof v === "string" ? v : null;
+    const next = { ...grantValues.value };
+    let dropped = false;
+    for (const [path, id] of Object.entries(next)) {
+      if (preview.value?.permissionsFlat[path]?.kind !== "host.silo") continue;
+      if (silos.value.some((s) => s.id === id && s.workerId === workerId)) continue;
+      delete next[path];
+      dropped = true;
+    }
+    if (dropped) grantValues.value = next;
+  }
+
+  // Required perms whose optional-section ancestors are all active: toggling a
+  // section off drops its perms from what the install still needs.
+  const requiredNow = useComputed(() => {
+    if (!preview.value) return [] as string[];
+    const inactive = permsInInactiveSections(
+      preview.value.configFields,
+      config.value,
+      preview.value.permissionsFlat,
+    );
+    return Object.entries(preview.value.permissionsFlat)
+      .filter(([p, m]) => !(m.meta as { isOptional?: boolean }).isOptional && !inactive.has(p))
+      .map(([p]) => p);
+  });
+  const missingPerms = useComputed(() => requiredNow.value.filter((p) => !enabled.value.has(p)));
+  const missingConfig = useComputed(() => {
+    if (!preview.value) return [] as string[];
+    return findMissingRequired(preview.value.configFields, config.value);
+  });
+  // `host.silo` has no descriptor to fall back on, so an unpicked Silo emits
+  // `data: undefined` and sanitizeGrants 400s. Catch it as a disabled button
+  // rather than a server error after the operator hit Install.
+  const missingSilo = useComputed(() => {
+    if (!preview.value || !hostHasSilos) return [] as string[];
+    const inactive = permsInInactiveSections(
+      preview.value.configFields,
+      config.value,
+      preview.value.permissionsFlat,
+    );
+    return Object.entries(preview.value.permissionsFlat)
+      .filter(([p, m]) => m.kind === "host.silo" && enabled.value.has(p) && !inactive.has(p))
+      .filter(([p]) => typeof grantValues.value[p] !== "string")
+      .map(([p]) => p);
+  });
+  // A domain typed but never added would be dropped at submit with nothing to
+  // show for it — blank is a valid grant, so no other gate catches it.
+  const pendingDomain = useComputed(() => Object.values(pendingDomains.value).some(Boolean));
+  // Single apps must be pinned to exactly one worker. In dev mode
+  // (`hideDeployTargets`) there's no picker and the host's single local
+  // target stands in, so skip the gate. System apps have no target to
+  // pick and stay null.
+  const missingDeployTarget = useComputed(() => {
+    if (!preview.value || hideDeployTargets) return false;
+    if (preview.value.kind !== "single") return false;
+    return typeof deployTargets.value !== "string";
+  });
+
+  // Top-level tabs (key → display title). Empty for flat apps.
+  const tabs = useComputed(() => {
+    if (!preview.value) return [] as { key: string; title: string }[];
+    return Object.entries(preview.value.configFields)
+      .filter(([, f]) => f.type === "tab")
+      .map(([key, f]) => ({ key, title: (f as ConfigContainerNode).title ?? key }));
+  });
+  // Bucket every still-unmet required item (config field or permission) by
+  // the tab it lives under, so each tab can show a count badge and the
+  // summary can say "Need N settings under <tab>". Items not under any tab
+  // (flat apps, or top-level fields alongside tabs) fall into `noTab`.
+  const needs = useComputed(() => {
+    const byTab: Record<string, number> = {};
+    let noTab = 0;
+    const tabKeys = new Set(tabs.value.map((t) => t.key));
+    for (const path of [...missingPerms.value, ...missingConfig.value]) {
+      const top = path.split(".")[0]!;
+      if (tabKeys.has(top)) byTab[top] = (byTab[top] ?? 0) + 1;
+      else noTab += 1;
+    }
+    return { byTab, noTab };
+  });
+  // Human-readable "still needed" lines for the configure step.
+  const needsLines = useComputed(() => {
+    const lines: string[] = [];
+    const plural = (n: number) => (n === 1 ? "setting" : "settings");
+    for (const t of tabs.value) {
+      const n = needs.value.byTab[t.key] ?? 0;
+      if (n > 0) lines.push(`${n} ${plural(n)} under ${t.title}`);
+    }
+    if (needs.value.noTab > 0) lines.push(`${needs.value.noTab} ${plural(needs.value.noTab)}`);
+    if (missingDeployTarget.value) lines.push("to choose a worker to deploy to");
+    if (missingSilo.value.length > 0) {
+      // A system app is a dead end, not a missing step: the app asks to run
+      // everywhere and a Silo is a directory on one box. Say that instead of
+      // pointing at a picker the operator will never be offered.
+      lines.push(
+        preview.value?.kind === "system"
+          ? "a Silo, which this app can't have — it deploys to every worker, and a Silo lives on one"
+          : "to pick a Silo",
+      );
+    }
+    if (pendingDomain.value) lines.push("to add the domain you typed, or clear the field");
+    return lines;
+  });
+
+  // Host kinds — required vs optional — alongside which of those any worker can
+  // satisfy. Optional rows backed by an unsupported kind gray out; unsupported
+  // required kinds warn that the app installs dormant until a capable worker
+  // joins.
+  const partitioned = useComputed(() =>
+    preview.value
+      ? partitionHostKinds(preview.value.permissionsFlat, preview.value.configFields)
+      : { required: [], optional: [] },
+  );
+  const supportedKinds = useComputed(() => {
+    const set = new Set<WorkerCapability>();
+    for (const w of workers) {
+      for (const k of w.capabilities) set.add(k);
+    }
+    return set;
+  });
+  const unsupportedRequiredKinds = useComputed(() =>
+    partitioned.value.required.filter((k) => !supportedKinds.value.has(k)),
+  );
+  const unsupportedOptionalKinds = useComputed(
+    () =>
+      new Set(
+        partitioned.value.optional.filter((k) => !supportedKinds.value.has(k)),
+      ) as Set<HostPermissionKind>,
+  );
+
+  // Rendered at the top of BOTH the Review and configure steps: the worker
+  // scopes capability-gated permissions and the Silo choice, so it stays
+  // visible and changeable while those are filled in. Only one step is mounted
+  // at a time, so the two slots never collide.
+  const deployPicker =
+    hideDeployTargets || !preview.value ? null : (
+      <section class="flex flex-col gap-2">
+        <DeployTargetsPicker
+          workers={workers}
+          value={deployTargets.value}
+          kind={preview.value.kind}
+          onChange={onDeployTargetsChange}
+          disabled={installing.value}
+          requiredKinds={partitioned.value.required}
+          collapsible
+        />
+      </section>
+    );
+
+  return (
+    <div class="flex flex-col gap-6 p-6 max-w-3xl">
+      {step.value === "discover" && initialSource !== undefined && (
+        <section class="flex flex-col gap-2">
+          {parsing.value && <div class="text-xs text-muted-foreground">Loading realm.ts…</div>}
+          {error.value && <InstallError error={error.value} />}
+        </section>
+      )}
+
+      {step.value === "discover" && initialSource === undefined && (
+        <section class="flex flex-col gap-2">
+          <textarea
+            class="font-mono text-xs rounded-2xl border border-border bg-card p-3 min-h-48 w-full outline-none focus:ring-2 focus:ring-ring/50"
+            placeholder='import { createApp, r } from "@yourrealm/sdk"; …'
+            value={source.value}
+            onInput={(e) => (source.value = (e.target as HTMLTextAreaElement).value)}
+            disabled={parsing.value || installing.value}
+            data-testid="install-source"
+          />
+          <div class="flex items-center gap-2">
+            <Button
+              onClick={onParse}
+              disabled={parsing.value || installing.value || !source.value.trim()}
+              data-testid="parse-source"
+            >
+              {parsing.value ? "Parsing…" : "Parse"}
+            </Button>
+            <a href="/" class="text-xs text-muted-foreground hover:underline">
+              Cancel
+            </a>
+          </div>
+          {error.value && <InstallError error={error.value} />}
+        </section>
+      )}
+
+      {step.value === "summary" && preview.value && (
+        <>
+          {deployPicker}
+          <SummaryStep
+            preview={preview.value}
+            grantValues={grantValues.value}
+            onGrantValueChange={(path, value) =>
+              (grantValues.value = { ...grantValues.value, [path]: value })
+            }
+            onConfirm={() => (step.value = "configure")}
+            onBack={() => (step.value = "discover")}
+            formatAge={formatAge}
+          />
+        </>
+      )}
+
+      {step.value === "configure" && preview.value && (
+        <>
+          {deployPicker}
+
+          {Object.keys(preview.value.configFields).length +
+            Object.keys(preview.value.permissionsFlat).length ===
+            0 &&
+            hideDeployTargets && (
+              <div class="rounded-2xl border border-border bg-card text-muted-foreground text-xs px-4 py-3">
+                Nothing to configure — this app declares no config fields or permissions. Click
+                Install app to continue.
+              </div>
+            )}
+          {Object.keys(preview.value.configFields).length +
+            Object.keys(preview.value.permissionsFlat).length >
+            0 && (
+            <section class="flex flex-col gap-3">
+              <TabsForm
+                configFields={preview.value.configFields}
+                permissionsFlat={preview.value.permissionsFlat}
+                configValues={config.value}
+                enabledPermissions={enabled.value}
+                grantValues={grantValues.value}
+                silos={hostHasSilos ? silos.value : undefined}
+                siloWorkerId={siloWorkerId.value}
+                siloKind={preview.value.kind}
+                onCreateSilo={plumbing.createSilo ? onCreateSilo : undefined}
+                onAcknowledgeSilo={plumbing.acknowledgeSilo ? onAcknowledgeSilo : undefined}
+                disabled={installing.value}
+                needsByTab={needs.value.byTab}
+                onConfigChange={(path, v) => (config.value = setPath(config.value, path, v))}
+                onPermissionToggle={togglePermission}
+                onGrantValueChange={(path, value) =>
+                  (grantValues.value = { ...grantValues.value, [path]: value })
+                }
+                onDomainPendingChange={(path, pending) =>
+                  (pendingDomains.value = { ...pendingDomains.value, [path]: pending })
+                }
+              />
+            </section>
+          )}
+
+          {error.value && <InstallError error={error.value} />}
+
+          {unsupportedRequiredKinds.value.length > 0 && (
+            <div
+              class="rounded-2xl border border-border bg-muted/40 text-muted-foreground text-xs px-4 py-3"
+              data-testid="unsupported-required-kinds"
+            >
+              No worker currently satisfies:{" "}
+              <span class="font-mono font-semibold">
+                {unsupportedRequiredKinds.value.join(", ")}
+              </span>
+              . The app will install dormant and start running when a capable worker joins.
+            </div>
+          )}
+
+          {unsupportedOptionalKinds.value.size > 0 && (
+            <div class="rounded-2xl border border-border bg-card text-muted-foreground text-xs px-4 py-3">
+              Not supported by any worker:{" "}
+              <span class="font-mono font-semibold">
+                {[...unsupportedOptionalKinds.value].join(", ")}
+              </span>
+            </div>
+          )}
+
+          {needsLines.value.length > 0 && (
+            <div
+              class="rounded-2xl border border-amber-300/50 bg-amber-50 text-amber-900 text-xs px-4 py-3 flex flex-col gap-1"
+              data-testid="missing-required"
+            >
+              <span class="font-medium">Almost there — still need:</span>
+              <ul class="list-disc pl-4 flex flex-col gap-0.5">
+                {needsLines.value.map((line) => (
+                  <li key={line}>{line}</li>
+                ))}
+              </ul>
+            </div>
+          )}
+
+          <div class="flex items-center gap-2">
+            <Button variant="outline" onClick={() => (step.value = "summary")}>
+              Back
+            </Button>
+            <Button
+              onClick={() => onInstall(false)}
+              disabled={
+                installing.value ||
+                missingPerms.value.length > 0 ||
+                missingConfig.value.length > 0 ||
+                missingDeployTarget.value ||
+                missingSilo.value.length > 0 ||
+                pendingDomain.value
+              }
+              data-testid="install-app"
+            >
+              {installing.value ? "Installing…" : "Install app"}
+            </Button>
+            {showInstallAsTemplate && (
+              <Button
+                variant="outline"
+                onClick={() => {
+                  // Explain what a template does (and that previews drop their
+                  // volumes) before stamping it — unless the operator already
+                  // dismissed this template's notice level.
+                  const hasVols = preview.value?.hasPersistentVolumes ?? false;
+                  if (!shouldShowTemplateDialog(hasVols)) {
+                    onInstall(true);
+                    return;
+                  }
+                  // A prior (lower-level) dismissal pre-fills "don't show again".
+                  dontShowAgain.value = dismissedLevel() > 0;
+                  templateDialogOpen.value = true;
+                }}
+                disabled={
+                  installing.value ||
+                  missingPerms.value.length > 0 ||
+                  missingConfig.value.length > 0 ||
+                  missingDeployTarget.value ||
+                  missingSilo.value.length > 0 ||
+                  pendingDomain.value
+                }
+                data-testid="install-as-template"
+              >
+                Install as template
+              </Button>
+            )}
+            <a href="/" class="text-xs text-muted-foreground hover:underline">
+              Cancel
+            </a>
+          </div>
+        </>
+      )}
+
+      <Dialog
+        open={templateDialogOpen.value}
+        onOpenChange={(d: { open: boolean }) => (templateDialogOpen.value = d.open)}
+      >
+        <DialogContent data-testid="install-template-dialog">
+          <DialogHeader>
+            <DialogTitle>Install as template</DialogTitle>
+            <DialogDescription>
+              A template is scaffolding — it doesn't run on its own. A builder app (like Forge)
+              creates an app from it for each pull request, and those previews are torn down
+              automatically when the request closes.
+            </DialogDescription>
+          </DialogHeader>
+          {preview.value?.hasPersistentVolumes && (
+            <div
+              class="rounded-2xl border border-border bg-card text-muted-foreground text-xs px-4 py-3"
+              data-testid="template-volumes-note"
+            >
+              No action needed — apps created from this template won't have persistent volumes and
+              will be garbage collected.
+            </div>
+          )}
+          <label class="flex items-center gap-2 text-sm">
+            <Checkbox
+              checked={dontShowAgain.value}
+              onCheckedChange={(d: { checked: boolean }) =>
+                (dontShowAgain.value = d.checked === true)
+              }
+            />
+            Don't show this again
+          </label>
+          <DialogFooter>
+            <Button variant="outline" onClick={() => (templateDialogOpen.value = false)}>
+              Cancel
+            </Button>
+            <Button
+              onClick={() => {
+                // Record dismissal at THIS template's level (volumeless → 1,
+                // volumes → 2); setDismissedLevel never downgrades a prior one.
+                if (dontShowAgain.value) {
+                  setDismissedLevel(
+                    templateNoticeLevel(preview.value?.hasPersistentVolumes ?? false),
+                  );
+                }
+                templateDialogOpen.value = false;
+                onInstall(true);
+              }}
+              data-testid="confirm-install-template"
+            >
+              Install as template
+            </Button>
+          </DialogFooter>
+        </DialogContent>
+      </Dialog>
+    </div>
+  );
+}
+
+// ---- Summary step -----------------------------------------------------------
+interface SummaryProps {
+  preview: PreviewResult;
+  grantValues: Record<string, unknown>;
+  onGrantValueChange: (path: string, value: unknown) => void;
+  onConfirm: () => void;
+  onBack: () => void;
+  formatAge: (iso: string | null) => string;
+}
+
+function SummaryStep({
+  preview,
+  grantValues,
+  onGrantValueChange,
+  onConfirm,
+  onBack,
+  formatAge,
+}: SummaryProps) {
+  // A permission is hidden here if ANY ancestor tab/section along its dotted
+  // path is optional - walking only the first segment misses perms inside an
+  // optional section that's itself inside a tab (e.g. `general.s3.bucket`).
+  // Those show up in the configure step once the feature toggle is on.
+  function isTopLevelPermission(path: string): boolean {
+    const segments = path.split(".");
+    // Skip the last segment (the permission name itself). Optionality
+    // on the leaf comes from meta.__optional, not from configFields.
+    let tree: Record<string, ConfigField> | undefined = preview.configFields;
+    for (let i = 0; i < segments.length - 1; i++) {
+      if (!tree) return true;
+      const node: ConfigField | undefined = tree[segments[i]!];
+      if (!node) return true;
+      if ((node.type === "section" || node.type === "tab") && node.optional) return false;
+      if (node.type === "tab" || node.type === "section") {
+        tree = node.fields;
+      } else {
+        return true;
+      }
+    }
+    return true;
+  }
+  const shown = Object.entries(preview.permissionsFlat).filter(([p]) => isTopLevelPermission(p));
+  const required = shown.filter(([, m]) => !(m.meta as { isOptional?: boolean }).isOptional);
+  const dangerousRequired = required.filter(
+    ([, m]) => PERMISSION_META[m.kind as PermissionKind]?.danger,
+  );
+  const normalRequired = required.filter(
+    ([, m]) => !PERMISSION_META[m.kind as PermissionKind]?.danger,
+  );
+  const renderRequiredRow = ([path, perm]: [string, SerializablePermission]) => {
+    const kindKey = perm.kind;
+    if (!(kindKey in PERMISSION_META)) return null;
+    // grantValues is sparse (only entries the admin actively edited);
+    // fall back to the descriptor's perm.data for the displayed value.
+    const portArg =
+      kindKey === "host.port"
+        ? ((grantValues[path] ?? perm.data) as string | number | undefined)
+        : undefined;
+    const urlArg =
+      kindKey === "remote.fetchUrl" || kindKey === "remote.artifact"
+        ? (perm.data as { url: string }).url
+        : undefined;
+    const titleLabel = portArg != null ? String(portArg) : undefined;
+    const reason = (perm.meta as { reason?: string }).reason ?? "";
+    return (
+      <PermissionRow
+        key={path}
+        kind={kindKey as PermissionKind}
+        reason={reason}
+        required
+        checked
+        onCheckedChange={() => {}}
+        label={titleLabel}
+        port={portArg}
+        onPortChange={kindKey === "host.port" ? (v) => onGrantValueChange(path, v) : undefined}
+        url={urlArg}
+      />
+    );
+  };
+  return (
+    <>
+      <section class="flex flex-col gap-3">
+        <h2 class="text-sm font-bold text-foreground">Review</h2>
+        {dangerousRequired.length > 0 && (
+          <PermissionSection danger label="Dangerous required permissions">
+            {dangerousRequired.map(renderRequiredRow)}
+          </PermissionSection>
+        )}
+        {normalRequired.length > 0 && (
+          <PermissionSection label="Required permissions">
+            {normalRequired.map(renderRequiredRow)}
+          </PermissionSection>
+        )}
+        {preview.images && preview.images.length > 0 && (
+          <div class="flex flex-col gap-3 bg-trust-bg rounded-3xl shadow-clay-blue p-4">
+            <SectionLabel
+              icon={<CubeIcon className="w-4 h-4 text-trust" />}
+              className="text-trust pl-0.5"
+            >
+              Images
+            </SectionLabel>
+            {preview.images.map((img) => (
+              <ImagePosture
+                key={img.ref}
+                image={img.ref}
+                digest={img.digest ?? "not yet pinned"}
+                runsAs={img.runsAs ?? "unknown (will resolve on install)"}
+                runsAsRoot={img.runsAsRoot}
+                exposes={img.exposes}
+                volumes={img.volumes}
+                age={formatAge(img.imageCreatedAt)}
+              />
+            ))}
+          </div>
+        )}
+      </section>
+      <div class="flex items-center gap-2">
+        <Button variant="outline" onClick={onBack}>
+          Back
+        </Button>
+        <Button onClick={onConfirm} data-testid="summary-continue">
+          Continue
+        </Button>
+      </div>
+    </>
+  );
+}