@k2b/cloud 0.23.0 → 0.24.0

package/src/browser/CloudResourceSearch.tsx

@@ -1,17 +1,27 @@
-import { query, timed } from "@k2b/stdlib/solid";
-import { Button, IconButton, ScrollArea, useLocale } from "@k2b/ui";
+import { timed } from "@k2b/stdlib/solid";
+import { announce, Button, IconButton, ScrollArea, useLocale } from "@k2b/ui";
 import { createEffect, createMemo, createSignal, createUniqueId, For, on, onCleanup, onMount, Show } from "solid-js";
-import type { SearchItem, SearchResponse } from "../api/search/schemas";
+import type { SearchApp, SearchItem } from "../api/search/schemas";
 import type { CloudResourceRef } from "../contracts";
-import { LOCALE_HEADER } from "../shared/locale";
 import { shortcutLabel } from "./command-shortcuts";
 import { matchNavigationSearchItems, type NavigationSearchItem } from "./navigation-search";
 import { cloudResourceSearchUrl, filterCloudResourceSearchItems } from "./resource-search";
 import { commitTypedTags, matchingSearchTags, searchTags, tagAtCursor } from "./resource-search-input";
 import { resourceSearchMessages } from "./resource-search-messages";
 import type { GlobalSearchOptions, SearchScope } from "./search-bridge";
-
 import { commandSearchItem, matchingCommands, type PaletteCommand } from "./search-commands";
+import {
+  applySearchLine,
+  breakSearchRun,
+  emptySearchRun,
+  failedSearchApps,
+  retrySearchApp,
+  type SearchBlock,
+  type SearchRun,
+  searchFinished,
+  searchingApps,
+  streamCloudResourceSearch,
+} from "./search-stream";
 
 export type CloudResourceSearchProps = {
   commands?: readonly PaletteCommand[];
@@ -37,6 +47,7 @@ export type CloudResourceSearchProps = {
 const isLinkableCommand = (command: PaletteCommand) => typeof command.action !== "function" && "command" in command.action;
 
 const itemKey = (item: SearchItem) => `${item.ref.type}:${item.ref.id}`;
+const URL_BASE = "https://cloud.invalid";
 const groupByApp = (items: SearchItem[]) => {
   const groups = new Map<string, SearchItem[]>();
   for (const item of items) {
@@ -59,7 +70,7 @@ export default function CloudResourceSearch(props: CloudResourceSearchProps) {
   const appId = () => scope()?.appId ?? scope()?.ref?.type.split(".")[0];
   const scopeLabel = () =>
     !props.request && props.initialAppId
-      ? (response()?.apps.find((app) => app.id === props.initialAppId)?.name ?? scope()?.label)
+      ? (catalogApps()?.find((app) => app.id === props.initialAppId)?.name ?? scope()?.label)
       : scope()?.label;
   createEffect(() => {
     const request = props.request;
@@ -114,23 +125,80 @@ export default function CloudResourceSearch(props: CloudResourceSearchProps) {
     }),
   );
   const [searchUrl, setSearchUrl] = createSignal(desiredUrl());
-  const searchQuery = query.create({
-    source: searchUrl,
-    load: async (url, { abortSignal }) => {
-      if (props.searchResources === false) {
-        const data: SearchResponse = { query: "", count: 0, apps: [], items: [] };
-        return { url, data };
-      }
-      const response = await fetch(url, { signal: abortSignal, headers: { [LOCALE_HEADER]: locale() } });
-      if (!response.ok) throw new Error(t().searchFailed);
-      const data: SearchResponse = await response.json();
-      return { url, data };
-    },
-  });
-  const response = () => searchQuery.data()?.data;
-  const fresh = () => searchQuery.data()?.url === desiredUrl() && !searchQuery.error();
-  const pending = () => searchUrl() !== desiredUrl() || searchQuery.loading() || searchQuery.refreshing();
-  const catalog = createMemo(() => searchTags(response()?.apps ?? [], appId()));
+  // One streamed run per search URL. Apps answer in any order; their rows are appended and never reordered.
+  const [run, setRun] = createSignal<SearchRun>(emptySearchRun());
+  const [runUrl, setRunUrl] = createSignal<string>();
+  const [catalogApps, setCatalogApps] = createSignal<SearchApp[]>();
+  // The last rows a run showed stay until the next run shows its first rows, so typing does not blank the list.
+  const [stale, setStale] = createSignal<{ url: string; blocks: SearchBlock[] }>();
+  /** The run shows its own rows, or that it found none, instead of the stale ones. */
+  const shownRun = () => run().blocks.length > 0 || searchFinished(run());
+  let controller: AbortController | undefined;
+  const startRun = (url: string) => {
+    controller?.abort();
+    const own = new AbortController();
+    controller = own;
+    const previous = runUrl();
+    // What is on screen stays: the last run's rows, or none after it found nothing; a run that showed nothing yet
+    // leaves the rows before it.
+    if (previous && shownRun()) setStale({ url: previous, blocks: run().blocks });
+    setRunUrl(url);
+    if (props.searchResources === false) {
+      setCatalogApps([]);
+      setRun({ ...emptySearchRun(), done: true });
+      return;
+    }
+    setRun(emptySearchRun());
+    void streamCloudResourceSearch(url, {
+      signal: own.signal,
+      locale: locale(),
+      onLine: (line) => {
+        if (controller !== own) return;
+        if (line.type === "start") setCatalogApps(line.apps);
+        setRun((current) => applySearchLine(current, line));
+      },
+    }).catch(() => {
+      if (controller === own && !own.signal.aborted) setRun(breakSearchRun);
+    });
+  };
+  /** Searches one app again within the current run; its rows, if any, are appended at the end. */
+  const retryApp = (appId: string) => {
+    const own = controller;
+    const url = runUrl();
+    if (!own || !url) return;
+    const target = new URL(url, URL_BASE);
+    target.searchParams.set("app", appId);
+    // Narrowed to one app, the server samples more; the retried section keeps the size the others have.
+    const limit = run().providers.length > 1 ? Number(target.searchParams.get("provider_limit")) : undefined;
+    setRun((current) => retrySearchApp(current, appId));
+    const giveUp = () => {
+      if (controller === own && run().status[appId] === "searching")
+        setRun((current) => applySearchLine(current, { type: "provider", provider: appId, status: "error", results: [], ms: 0 }));
+    };
+    void streamCloudResourceSearch(`${target.pathname}${target.search}`, {
+      signal: own.signal,
+      locale: locale(),
+      onLine: (line) => {
+        if (controller !== own || line.type !== "provider" || line.provider !== appId) return;
+        setRun((current) => applySearchLine(current, { ...line, results: line.results.slice(0, limit) }));
+      },
+    }).then(giveUp, giveUp);
+  };
+  createEffect(on(searchUrl, startRun));
+  onCleanup(() => controller?.abort());
+
+  const current = () => runUrl() === desiredUrl();
+  const started = () => run().providers.length > 0 || run().done || run().failed;
+  const finished = () => current() && searchFinished(run());
+  const waiting = () => searchUrl() !== desiredUrl() || !started();
+  const pendingApps = () => (current() ? searchingApps(run()) : []);
+  const failedApps = () => (current() ? failedSearchApps(run()) : []);
+  const appName = (appId: string) => run().apps.find((app) => app.id === appId)?.name ?? appId;
+  const failureText = (failure: ReturnType<typeof failedSearchApps>[number]) =>
+    failure.status === "timeout" ? t().appTimedOut({ app: appName(failure.appId) }) : t().appUnavailable({ app: appName(failure.appId) });
+  // Only a search the user narrowed with the app chip or a tag names its one app when nothing matched.
+  const narrowedApp = () => ((Boolean(appId()) || tags().length > 0) && run().providers.length === 1 ? run().providers[0] : undefined);
+  const catalog = createMemo(() => searchTags(catalogApps() ?? [], appId()));
   const quickTags = createMemo(() =>
     catalog()
       .filter((tag, index, all) => all.findIndex((other) => other.appName === tag.appName) === index)
@@ -147,31 +215,64 @@ export default function CloudResourceSearch(props: CloudResourceSearchProps) {
         })
       : [],
   );
+  // Keep last-good rows only within the same context, never across scope changes.
+  const sameScope = (url: string) => {
+    const loaded = new URL(url, URL_BASE).searchParams;
+    return (
+      (loaded.get("scope_type") ?? undefined) === scope()?.ref?.type &&
+      (loaded.get("scope_id") ?? undefined) === scope()?.ref?.id &&
+      (loaded.get("app") ?? undefined) === appId() &&
+      (loaded.get("scope_tag") ?? undefined) === scope()?.tag
+    );
+  };
+  const shownBlocks = () => {
+    const source = shownRun() ? { url: runUrl() ?? "", blocks: run().blocks } : stale();
+    return source && sameScope(source.url) ? source.blocks : [];
+  };
+  /** Rows of the run for the current input; anything older is visible but cannot be chosen. */
+  const freshResults = () => current() && shownRun();
+  const results = createMemo(() =>
+    canSearch()
+      ? [...groupByApp(navigation()), ...shownBlocks().flatMap((block) => filterCloudResourceSearchItems(block.items, props))]
+      : [],
+  );
+  const searchContext = () => JSON.stringify([desiredUrl(), commandMode(), commandQuery()]);
+  /**
+   * Actions come first. One that starts to match after rows below the actions are on screen, such as from a catalog
+   * that loaded late, waits for the next keystroke instead of pushing those rows down.
+   */
+  const shownCommands = createMemo<{ context: string; commands: PaletteCommand[] }>((previous) => {
+    const context = searchContext();
+    const matching = visibleCommands();
+    if (previous?.context !== context || results().length === 0) return { context, commands: matching };
+    return { context, commands: matching.filter((command) => previous.commands.some((shown) => shown.id === command.id)) };
+  });
   const items = createMemo(() => {
-    const commands = visibleCommands().map((command) => commandSearchItem(command, command.context ? t().contextActions : t().actions));
-    if (!canSearch()) return commands;
-    // Keep last-good rows only within the same context, never across scope changes.
-    const loaded = new URL(searchQuery.data()?.url ?? "/api/search", "https://cloud.invalid");
-    const sameScope =
-      (loaded.searchParams.get("scope_type") ?? undefined) === scope()?.ref?.type &&
-      (loaded.searchParams.get("scope_id") ?? undefined) === scope()?.ref?.id &&
-      (loaded.searchParams.get("app") ?? undefined) === appId() &&
-      (loaded.searchParams.get("scope_tag") ?? undefined) === scope()?.tag;
-    const resources = filterCloudResourceSearchItems(sameScope ? (response()?.items ?? []) : [], props).sort(
-      (a, b) => (b.priority ?? 0) - (a.priority ?? 0) || a.title.localeCompare(b.title),
+    const commands = shownCommands().commands.map((command) =>
+      commandSearchItem(command, command.context ? t().contextActions : t().actions),
     );
-    const results = [...groupByApp(resources), ...groupByApp(navigation())];
-    // Context actions stay visible when opening an app-scoped search without text.
-    return textQuery() ? [...results, ...commands] : [...commands, ...results];
+    // Instant rows come first: streamed app sections are appended below them and never push them down.
+    return [...commands, ...results()];
   });
   const selectable = (item: SearchItem) =>
-    !props.disabled && !choosingTag() && (commandFor(item) || navigation().includes(item) || (fresh() && !pending()));
+    !props.disabled &&
+    !choosingTag() &&
+    (commandFor(item) || navigation().includes(item) || (freshResults() && searchUrl() === desiredUrl()));
   const activeItem = () => items()[activeIndex()];
   const selectedItem = () => items().find((item) => itemKey(item) === selectedKey());
   const previewItem = () => (props.selectionMode ? (selectedItem() ?? activeItem()) : activeItem());
   const showList = () => !choosingTag() && items().length > 0;
-  const showResults = () => showList() && (canSearch() || commandMode());
-  const unknownTags = () => (fresh() && !pending() ? (response()?.unsupportedTags ?? []) : []);
+  // An active search keeps the full height from its first keystroke, so arriving rows never resize the dialog.
+  const searching = () => !choosingTag() && (canSearch() || commandMode());
+  const showResults = () => showList() && searching();
+  const unknownTags = () => (current() && started() ? run().unsupportedTags : []);
+  const noMatches = () =>
+    !items().length && (commandMode() ? !props.commandsLoading : canSearch() && finished() && !run().failed && failedApps().length === 0);
+  const stillSearching = () => {
+    const names = pendingApps().map(appName);
+    const shown = names.length > 3 ? [...names.slice(0, 2), t().moreApps({ count: names.length - 2 })] : names;
+    return t().stillSearching({ apps: new Intl.ListFormat(locale(), { type: "conjunction" }).format(shown), count: names.length });
+  };
 
   const { debouncedFn: scheduleSearch, cancel } = timed.debounce((url: string) => setSearchUrl(url), 200);
   createEffect(() => {
@@ -197,7 +298,7 @@ export default function CloudResourceSearch(props: CloudResourceSearchProps) {
   });
   createEffect(
     on(
-      () => ({ rows: items(), context: JSON.stringify([desiredUrl(), commandMode(), commandQuery()]) }),
+      () => ({ rows: items(), context: searchContext() }),
       (current, previous) => {
         if (userSelected && previous?.context === current.context) {
           const selected = previous.rows[activeIndex()];
@@ -207,11 +308,24 @@ export default function CloudResourceSearch(props: CloudResourceSearchProps) {
         } else {
           userSelected = false;
           const explicitCommand = commandMode() && Boolean(commandQuery());
-          setActiveIndex(current.rows[0]?.ref.type === "cloud.command" && !explicitCommand ? -1 : 0);
+          const firstResult = current.rows.findIndex((row) => row.ref.type !== "cloud.command");
+          // Actions are never implicitly selected; with text, the first result is.
+          setActiveIndex(explicitCommand ? 0 : current.rows[0]?.ref.type === "cloud.command" && !textQuery() ? -1 : firstResult);
         }
       },
     ),
   );
+  createEffect(
+    on(
+      () => canSearch() && !commandMode() && finished(),
+      (done, wasDone) => {
+        if (!done || wasDone) return;
+        // Apps that did not answer are part of the outcome, so a missing answer never sounds like “not found”.
+        if (run().failed) announce(t().searchFailed);
+        else announce([t().searchDone({ count: results().length }), ...failedApps().map(failureText)].join(". "));
+      },
+    ),
+  );
   createEffect(() => {
     suggestions();
     setTagIndex(0);
@@ -349,7 +463,7 @@ export default function CloudResourceSearch(props: CloudResourceSearchProps) {
       role="group"
       aria-label={props.title ?? t().searchCloudResources}
       class="cloud-resource-search"
-      classList={{ "has-results": showResults(), "is-picker": props.selectionMode, "shows-details": mobileDetails() && showResults() }}
+      classList={{ "has-results": searching(), "is-picker": props.selectionMode, "shows-details": mobileDetails() && showResults() }}
       onKeyDown={(event) => {
         if (event.target === inputRef) return;
         if (event.key === "Escape") handleKeyDown(event);
@@ -366,7 +480,7 @@ export default function CloudResourceSearch(props: CloudResourceSearchProps) {
       </IconButton>
       <label class="cloud-resource-search__input">
         <Show
-          when={commandMode() ? props.commandsLoading : pending() && !choosingTag()}
+          when={commandMode() ? props.commandsLoading : canSearch() && waiting() && !choosingTag()}
           fallback={<i class="ti ti-search" aria-hidden="true" />}
         >
           <i class="ti ti-loader-2 animate-spin" role="status" aria-label={t().loading} />
@@ -446,7 +560,11 @@ export default function CloudResourceSearch(props: CloudResourceSearchProps) {
           />
         </div>
       </label>
-      <ScrollArea ref={bodyRef} class="cloud-resource-search__body" aria-busy={pending() && !choosingTag()}>
+      <ScrollArea
+        ref={bodyRef}
+        class="cloud-resource-search__body"
+        aria-busy={canSearch() && !choosingTag() && (waiting() || pendingApps().length > 0)}
+      >
         <Show
           when={choosingTag()}
           fallback={
@@ -458,25 +576,12 @@ export default function CloudResourceSearch(props: CloudResourceSearchProps) {
                   </p>
                 )}
               </Show>
-              <Show when={searchQuery.error()}>
-                <div class="cloud-resource-search__hint" role="status">
-                  {t().searchFailed}{" "}
-                  <Button variant="text" size="xs" onClick={() => void searchQuery.refresh()}>
-                    {t().retry}
-                  </Button>
-                </div>
-              </Show>
-              <Show when={fresh() && response()?.failedApps?.length}>
-                <p class="cloud-resource-search__hint" role="status">
-                  {t().partialFailure}
-                </p>
-              </Show>
               <Show when={!canSearch() && !commandMode()}>
                 <div class="cloud-resource-search__idle">
                   <p>{props.selectionMode ? t().pickerHint : props.searchResources === false ? t().navigationHint : t().startHint}</p>
-                  <div class="cloud-resource-search__quick" aria-busy={!response() && !searchQuery.error()}>
+                  <div class="cloud-resource-search__quick" aria-busy={!catalogApps() && !run().failed}>
                     <Show
-                      when={response() || searchQuery.error()}
+                      when={catalogApps() || run().failed}
                       fallback={<For each={[0, 1, 2]}>{() => <span class="cloud-resource-search__tag-skeleton" aria-hidden="true" />}</For>}
                     >
                       <For each={quickTags()}>
@@ -487,7 +592,7 @@ export default function CloudResourceSearch(props: CloudResourceSearchProps) {
                         )}
                       </For>
                     </Show>
-                    <Show when={!response() || catalog().length > 0}>
+                    <Show when={!catalogApps() || catalog().length > 0}>
                       <Button
                         variant="ghost"
                         size="sm"
@@ -523,10 +628,10 @@ export default function CloudResourceSearch(props: CloudResourceSearchProps) {
                   {t().commandFailed}
                 </p>
               </Show>
+              <Show when={searching()}>
+                <div class="cloud-resource-search__count">{items().length > 0 ? t().resultCount({ count: items().length }) : "\u00a0"}</div>
+              </Show>
               <Show when={showList()}>
-                <div class="cloud-resource-search__count" aria-live="polite">
-                  {t().resultCount({ count: items().length })}
-                </div>
                 <section id={`${id}-options`} role="listbox" aria-label={t().searchCloudResources} class="cloud-resource-search__results">
                   <For each={items()}>
                     {(item, index) => (
@@ -575,18 +680,43 @@ export default function CloudResourceSearch(props: CloudResourceSearchProps) {
                   </For>
                 </section>
               </Show>
-              <Show
-                when={
-                  (canSearch() || commandMode()) &&
-                  !items().length &&
-                  !pending() &&
-                  fresh() &&
-                  !searchQuery.error() &&
-                  !response()?.failedApps?.length
-                }
-              >
+              <Show when={canSearch() && !commandMode() && (pendingApps().length > 0 || failedApps().length > 0)}>
+                <div class="cloud-resource-search__status">
+                  <Show when={pendingApps().length > 0}>
+                    <p>
+                      <i class="ti ti-loader-2 animate-spin motion-reduce:animate-none" aria-hidden="true" />
+                      {stillSearching()}
+                    </p>
+                  </Show>
+                  <For each={failedApps()}>
+                    {(failure) => (
+                      <p>
+                        {failureText(failure)}
+                        <span aria-hidden="true">·</span>
+                        <Button variant="text" size="xs" onClick={() => retryApp(failure.appId)}>
+                          {t().retry}
+                        </Button>
+                      </p>
+                    )}
+                  </For>
+                </div>
+              </Show>
+              {/* Below the rows, so pages and actions already on screen stay where they are. */}
+              <Show when={current() && run().failed}>
+                <div class="cloud-resource-search__hint" role="status">
+                  {t().searchFailed}{" "}
+                  <Button variant="text" size="xs" onClick={() => startRun(searchUrl())}>
+                    {t().retry}
+                  </Button>
+                </div>
+              </Show>
+              <Show when={noMatches()}>
                 <p class="cloud-resource-search__hint" role="status">
-                  {unknownTags().length ? t().unsupportedTags : t().noMatches}
+                  {unknownTags().length
+                    ? t().unsupportedTags
+                    : !commandMode() && narrowedApp()
+                      ? t().appNoMatches({ app: appName(narrowedApp()!), query: textQuery() })
+                      : t().noMatches}
                 </p>
               </Show>
             </>
@@ -601,9 +731,7 @@ export default function CloudResourceSearch(props: CloudResourceSearchProps) {
           <Show
             when={suggestions().length > 0}
             fallback={
-              <p class="cloud-resource-search__hint">
-                {searchQuery.loading() ? t().loadingTags : searchQuery.error() ? t().searchFailed : t().noTags}
-              </p>
+              <p class="cloud-resource-search__hint">{run().failed ? t().searchFailed : catalogApps() ? t().noTags : t().loadingTags}</p>
             }
           >
             <div role="listbox" id={`${id}-options`} aria-label={t().tagSuggestions} class="cloud-resource-search__tags">
@@ -634,9 +762,9 @@ export default function CloudResourceSearch(props: CloudResourceSearchProps) {
           </Show>
         </Show>
       </ScrollArea>
-      <Show when={showResults() || (choosingTag() && suggestions().length > 0)}>
+      <Show when={searching() || (choosingTag() && suggestions().length > 0)}>
         <footer class="cloud-resource-search__footer">
-          <Show when={showResults()}>
+          <Show when={searching()}>
             <Button
               class="cloud-resource-search__details"
               disabled={!previewItem()}

package/src/browser/resource-search-messages.ts

@@ -12,7 +12,15 @@ export const resourceSearchMessages = i18n.define({
       commandHint: "Choose an action, or type > next time.",
       searchFailed: "Search is currently unavailable. Try again.",
       navigationFailed: "Could not open this result. Try again.",
-      partialFailure: "Some search sources are unavailable. Results may be incomplete.",
+      stillSearching: ({ apps, count }: { apps: string; count: number }) =>
+        count === 1 ? `${apps} is still searching…` : `${apps} are still searching…`,
+      moreApps: ({ count }: { count: number }) => `${count} more`,
+      appTimedOut: ({ app }: { app: string }) => `${app} did not respond in time`,
+      appUnavailable: ({ app }: { app: string }) => `${app} is not available right now`,
+      appNoMatches: ({ app, query }: { app: string; query: string }) =>
+        query ? `${app}: no matches for “${query}”` : `${app}: no matches`,
+      searchDone: ({ count }: { count: number }) =>
+        i18n.plural(count, "en", { one: `Search complete, ${count} result`, other: `Search complete, ${count} results` }),
       searchPlaceholder: "Search Cloud…",
       scopedSearchPlaceholder: "Search…",
       searchCloudResources: "Search Cloud resources",
@@ -54,7 +62,12 @@ export const resourceSearchMessages = i18n.define({
       commandHint: "Wähle eine Aktion – beim nächsten Mal geht auch >.",
       searchFailed: "Suche gerade nicht erreichbar. Versuche es erneut.",
       navigationFailed: "Der Treffer konnte nicht geöffnet werden. Versuche es erneut.",
-      partialFailure: "Einige Suchquellen sind nicht erreichbar. Ergebnisse können unvollständig sein.",
+      stillSearching: ({ apps, count }) => (count === 1 ? `${apps} sucht noch …` : `${apps} suchen noch …`),
+      moreApps: ({ count }) => `${count} weitere`,
+      appTimedOut: ({ app }) => `${app} hat nicht rechtzeitig geantwortet`,
+      appUnavailable: ({ app }) => `${app} ist gerade nicht erreichbar`,
+      appNoMatches: ({ app, query }) => (query ? `${app}: keine Treffer für „${query}“` : `${app}: keine Treffer`),
+      searchDone: ({ count }) => `Suche abgeschlossen, ${count} Treffer`,
       searchPlaceholder: "Cloud durchsuchen…",
       scopedSearchPlaceholder: "Durchsuchen…",
       searchCloudResources: "Cloud-Inhalte durchsuchen",

package/src/browser/search-stream.ts

@@ -0,0 +1,151 @@
+import type { SearchApp, SearchItem, SearchProviderStatus, SearchResponse, SearchStreamLine } from "../api/search/schemas";
+import { LOCALE_HEADER } from "../shared/locale";
+
+/** Kept local so the browser bundle does not load the server-side search schemas. */
+const STREAM_CONTENT_TYPE = "application/x-ndjson";
+
+export type SearchAppStatus = SearchProviderStatus | "searching";
+
+/** Rows one provider line added. A retried app adds a block of its own at the end. */
+export type SearchBlock = { appId: string; items: SearchItem[] };
+
+/**
+ * One streamed search as the browser shows it. Blocks only ever grow at the end, so nothing already visible moves;
+ * `status` says for every app named in `start` whether it is still searching and how it finished.
+ */
+export type SearchRun = {
+  apps: SearchApp[];
+  providers: string[];
+  status: Record<string, SearchAppStatus>;
+  blocks: SearchBlock[];
+  unsupportedTags: string[];
+  /** The stream has ended; a retried app may still search afterwards. */
+  done: boolean;
+  /** The request failed before any app was named. */
+  failed: boolean;
+};
+
+export const emptySearchRun = (): SearchRun => ({
+  apps: [],
+  providers: [],
+  status: {},
+  blocks: [],
+  unsupportedTags: [],
+  done: false,
+  failed: false,
+});
+
+const itemKey = (item: SearchItem) => `${item.ref.type}\u0000${item.ref.id}`;
+
+export const applySearchLine = (run: SearchRun, line: SearchStreamLine): SearchRun => {
+  if (line.type === "start")
+    return {
+      ...run,
+      apps: line.apps,
+      providers: line.providers,
+      status: Object.fromEntries(line.providers.map((appId) => [appId, "searching" as const])),
+      unsupportedTags: line.unsupportedTags ?? [],
+    };
+  if (line.type === "done") return { ...run, done: true };
+  // Only an app that is searching takes a line, which bounds the lines a run accepts.
+  if (run.status[line.provider] !== "searching") return run;
+  const shown = new Set(run.blocks.flatMap((block) => block.items.map(itemKey)));
+  const items = line.results.filter((item) => !shown.has(itemKey(item)));
+  return {
+    ...run,
+    status: { ...run.status, [line.provider]: line.status },
+    blocks: items.length ? [...run.blocks, { appId: line.provider, items }] : run.blocks,
+  };
+};
+
+/**
+ * The request failed or the stream broke off. Once apps were named, the rows that arrived stay and every app still
+ * searching has failed on its own, with its own retry; before that, the search failed as a whole.
+ */
+export const breakSearchRun = (run: SearchRun): SearchRun =>
+  run.providers.length
+    ? {
+        ...run,
+        done: true,
+        status: Object.fromEntries(Object.entries(run.status).map(([appId, status]) => [appId, status === "searching" ? "error" : status])),
+      }
+    : { ...run, failed: true };
+
+/** Marks an app as searching again before its retry starts. */
+export const retrySearchApp = (run: SearchRun, appId: string): SearchRun => ({
+  ...run,
+  status: { ...run.status, [appId]: "searching" },
+});
+
+export const searchingApps = (run: SearchRun) => run.providers.filter((appId) => run.status[appId] === "searching");
+export const failedSearchApps = (run: SearchRun) =>
+  run.providers.flatMap((appId) => {
+    const status = run.status[appId];
+    return status === "timeout" || status === "error" ? [{ appId, status }] : [];
+  });
+/** Every app has answered: only now may an empty run say that nothing was found. */
+export const searchFinished = (run: SearchRun) => (run.done || run.failed) && searchingApps(run).length === 0;
+
+/** An older Core answers with merged JSON; it becomes the same lines, without per-app timing. */
+const linesFromResponse = (body: SearchResponse): SearchStreamLine[] => {
+  const failed = body.failedApps ?? [];
+  const found = [...new Set(body.items.map((item) => item.appId))];
+  return [
+    {
+      type: "start",
+      query: body.query,
+      apps: body.apps,
+      providers: [...new Set([...found, ...failed])],
+      ...(body.unsupportedTags ? { unsupportedTags: body.unsupportedTags } : {}),
+    },
+    ...found.map((appId): SearchStreamLine => {
+      const results = body.items.filter((item) => item.appId === appId);
+      return { type: "provider", provider: appId, status: failed.includes(appId) ? "error" : "ok", results, ms: 0 };
+    }),
+    ...failed
+      .filter((appId) => !found.includes(appId))
+      .map((appId): SearchStreamLine => ({ type: "provider", provider: appId, status: "error", results: [], ms: 0 })),
+    { type: "done", status: failed.length ? "partial" : "complete", count: body.items.length },
+  ];
+};
+
+/**
+ * Runs one search against `/api/search` and hands over each line as it arrives. Aborting `signal` ends the request,
+ * and with it every provider the server still waits for. Rejects when the request fails or the stream breaks off.
+ */
+export const streamCloudResourceSearch = async (
+  url: string,
+  options: { signal: AbortSignal; locale: string; onLine: (line: SearchStreamLine) => void },
+): Promise<void> => {
+  const response = await fetch(url, {
+    signal: options.signal,
+    headers: { accept: STREAM_CONTENT_TYPE, [LOCALE_HEADER]: options.locale },
+  });
+  if (!response.ok) throw new Error(`Search failed with ${response.status}`);
+  if (!response.headers.get("content-type")?.startsWith(STREAM_CONTENT_TYPE)) {
+    const body: SearchResponse = await response.json();
+    for (const line of linesFromResponse(body)) options.onLine(line);
+    return;
+  }
+  if (!response.body) throw new Error("Search returned no body");
+  const reader = response.body.pipeThrough(new TextDecoderStream()).getReader();
+  let buffer = "";
+  let closed = false;
+  while (!closed) {
+    const chunk = await reader.read();
+    if (chunk.done) break;
+    buffer += chunk.value;
+    let end = buffer.indexOf("\n");
+    while (end >= 0) {
+      const text = buffer.slice(0, end).trim();
+      buffer = buffer.slice(end + 1);
+      if (text) {
+        const line: SearchStreamLine = JSON.parse(text);
+        options.onLine(line);
+        if (line.type === "done") closed = true;
+      }
+      end = buffer.indexOf("\n");
+    }
+  }
+  if (!closed) throw new Error("Search stream ended early");
+};