@connextar/house 0.6.1 → 0.8.1

package/README.md

@@ -276,7 +276,8 @@ library, no HTTP client.
 change as a _patch_ beside them, folded in on render. `insert`, `update`,
 `remove`, `move` and `bulk` each take a commit function; `isPending(key)` marks
 one row without disabling the table. `useOptimisticValue` is the same for a
-switch, a status or a settings record; `useAction` and `useKeyedAction` are for
+switch, a status or a settings record — a queue there too, not one held value;
+`useAction` and `useKeyedAction` are for
 work that should not be guessed at — a payment, a model call, a sign-in — and
 give a control the `pending` flag it needs and nothing more.
 
@@ -301,6 +302,17 @@ which case they win and the screen corrects itself. Evidence, never a timer —
 screen that does not refetch has no truth to fall back to, and snapping to stale
 rows after N seconds is a bug that only appears on a slow connection.
 
+**Two writes at once.** Each one lands or rolls back on its own, which is why
+both hooks hold a queue rather than the current answer. A slow first write that
+comes back after a second one keeps its place in the queue instead of winning
+it, and a refusal takes down the change that was refused and nothing else.
+Holding a single value gets both of these backwards: the first write's answer
+reappears on screen a second after the person watched the second one save, and a
+failed early write rolls back a later change nobody asked to undo. `merge` takes
+the same discipline — two fields changed in the same breath both survive,
+because a merge is held as its fields rather than as a copy of the value it was
+read from.
+
 **The three seams that keep it portable.** A commit is
 `() => Promise<Row | void>` that **throws** on failure, which is the one failure
 contract every client already has; an app whose client returns a result object
@@ -578,6 +590,50 @@ filter is dropped rather than throwing when the menu entry is picked. Where view
 are stored — a table keyed by account, or the browser — is the app's decision,
 because only the app knows whether a view should follow someone to their phone.
 
+### `@connextar/house/web-search`
+
+Google's organic results for a query, from whichever search API a deployment
+has a key for — **Serper** or **VALUE SERP** — in one shape.
+
+This one is here by decision rather than by count. AltEd is the first app to
+search the web, but which search API a deployment pays for is a cost choice the
+owner makes across the portfolio — two providers whose prices cross over at a
+few thousand searches a month — and that choice should be one setting, not a
+rewrite in every app that later needs it. What differs between the providers is
+where the key goes, what the fields are called and how they bill; what an app
+wants is identical. So the module is a factory per provider and one picker:
+
+```ts
+import { webSearchProviderFromEnv, WebSearchError } from "@connextar/house/web-search";
+
+const search = webSearchProviderFromEnv(); // null without a key
+const { provider, results } = await search!.search(
+  { q: "chemistry tutor Leeds", country: "gb", language: "en", num: 20 },
+  { timeoutMs: 12_000 },
+);
+// results: [{ position, title, url, snippet }]
+```
+
+`webSearchProviderFromEnv` reads `SERPER_API_KEY` and `VALUESERP_API_KEY`,
+uses `WEB_SEARCH_PROVIDER` (`serper` or `valueserp`) to choose when both are
+set, and otherwise prefers Serper. A named provider without a key falls back to
+the other rather than to no search at all. `SERPER_URL` and `VALUESERP_URL`
+point either at a stand-in for local checks. `provider.label` is the name to
+list in a privacy policy.
+
+**A failure is a `WebSearchError` with a code** — `unauthorised`,
+`rate_limited`, `timeout`, `unreachable` or `bad_response` — and the HTTP status
+where there was one. **It never carries the request's address, headers or
+response body.** VALUE SERP takes the key in the query string, so a message that
+quoted the address, or a body that echoed it, would put a live key into whatever
+log caught the error; the tests assert the key appears nowhere in the message or
+the stack for every status and both providers. Serper takes it in a header.
+
+Billing differs and is the caller's to weigh: Serper charges one credit for up to
+ten results and two for eleven to a hundred; VALUE SERP charges per request.
+There is no caching here — what may be stored, and for how long, is each app's
+decision and each provider's terms.
+
 ### Styles — `@connextar/house/house.css`
 
 What the components need that utility classes cannot say: rich text, the editor's

package/dist/ux/index.d.ts

@@ -13,7 +13,7 @@
  */
 export { ActionError, errorMessage } from "./errors.js";
 export { ActionFeedbackProvider, useActionReporter, type ActionFeedback, type ActionReporter } from "./feedback.js";
-export { applyPatches, isRedundant, isTempKey, reconcile, sameRow, settlePatch, shouldDropSettled, supersede, tempKey, type Patch, type PatchKind, type RowKey, } from "./optimistic.js";
+export { applyPatches, applyValuePatches, isRedundant, isRedundantValue, isTempKey, reconcile, reconcileValue, sameRow, settlePatch, settleValuePatch, shouldDropSettled, shouldDropSettledValue, supersede, supersedeValue, tempKey, type Patch, type PatchKind, type RowKey, type ValuePatch, } from "./optimistic.js";
 export { useAction, useKeyedAction, type Action, type ActionOptions, type KeyedAction } from "./use-action.js";
 export { useOptimisticList, type OptimisticList, type OptimisticListOptions, type WriteOptions, } from "./use-optimistic-list.js";
 export { useOptimisticValue, type OptimisticValue, type OptimisticValueOptions } from "./use-optimistic-value.js";

package/dist/ux/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/ux/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AACxD,OAAO,EAAE,sBAAsB,EAAE,iBAAiB,EAAE,KAAK,cAAc,EAAE,KAAK,cAAc,EAAE,MAAM,eAAe,CAAC;AACpH,OAAO,EACL,YAAY,EACZ,WAAW,EACX,SAAS,EACT,SAAS,EACT,OAAO,EACP,WAAW,EACX,iBAAiB,EACjB,SAAS,EACT,OAAO,EACP,KAAK,KAAK,EACV,KAAK,SAAS,EACd,KAAK,MAAM,GACZ,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,KAAK,MAAM,EAAE,KAAK,aAAa,EAAE,KAAK,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAC/G,OAAO,EACL,iBAAiB,EACjB,KAAK,cAAc,EACnB,KAAK,qBAAqB,EAC1B,KAAK,YAAY,GAClB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,kBAAkB,EAAE,KAAK,eAAe,EAAE,KAAK,sBAAsB,EAAE,MAAM,2BAA2B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/ux/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AACxD,OAAO,EAAE,sBAAsB,EAAE,iBAAiB,EAAE,KAAK,cAAc,EAAE,KAAK,cAAc,EAAE,MAAM,eAAe,CAAC;AACpH,OAAO,EACL,YAAY,EACZ,iBAAiB,EACjB,WAAW,EACX,gBAAgB,EAChB,SAAS,EACT,SAAS,EACT,cAAc,EACd,OAAO,EACP,WAAW,EACX,gBAAgB,EAChB,iBAAiB,EACjB,sBAAsB,EACtB,SAAS,EACT,cAAc,EACd,OAAO,EACP,KAAK,KAAK,EACV,KAAK,SAAS,EACd,KAAK,MAAM,EACX,KAAK,UAAU,GAChB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,KAAK,MAAM,EAAE,KAAK,aAAa,EAAE,KAAK,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAC/G,OAAO,EACL,iBAAiB,EACjB,KAAK,cAAc,EACnB,KAAK,qBAAqB,EAC1B,KAAK,YAAY,GAClB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,kBAAkB,EAAE,KAAK,eAAe,EAAE,KAAK,sBAAsB,EAAE,MAAM,2BAA2B,CAAC"}

package/dist/ux/index.js

@@ -13,7 +13,7 @@
  */
 export { ActionError, errorMessage } from "./errors.js";
 export { ActionFeedbackProvider, useActionReporter } from "./feedback.js";
-export { applyPatches, isRedundant, isTempKey, reconcile, sameRow, settlePatch, shouldDropSettled, supersede, tempKey, } from "./optimistic.js";
+export { applyPatches, applyValuePatches, isRedundant, isRedundantValue, isTempKey, reconcile, reconcileValue, sameRow, settlePatch, settleValuePatch, shouldDropSettled, shouldDropSettledValue, supersede, supersedeValue, tempKey, } from "./optimistic.js";
 export { useAction, useKeyedAction } from "./use-action.js";
 export { useOptimisticList, } from "./use-optimistic-list.js";
 export { useOptimisticValue } from "./use-optimistic-value.js";

package/dist/ux/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/ux/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AACxD,OAAO,EAAE,sBAAsB,EAAE,iBAAiB,EAA4C,MAAM,eAAe,CAAC;AACpH,OAAO,EACL,YAAY,EACZ,WAAW,EACX,SAAS,EACT,SAAS,EACT,OAAO,EACP,WAAW,EACX,iBAAiB,EACjB,SAAS,EACT,OAAO,GAIR,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,SAAS,EAAE,cAAc,EAAqD,MAAM,iBAAiB,CAAC;AAC/G,OAAO,EACL,iBAAiB,GAIlB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,kBAAkB,EAAqD,MAAM,2BAA2B,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/ux/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AACxD,OAAO,EAAE,sBAAsB,EAAE,iBAAiB,EAA4C,MAAM,eAAe,CAAC;AACpH,OAAO,EACL,YAAY,EACZ,iBAAiB,EACjB,WAAW,EACX,gBAAgB,EAChB,SAAS,EACT,SAAS,EACT,cAAc,EACd,OAAO,EACP,WAAW,EACX,gBAAgB,EAChB,iBAAiB,EACjB,sBAAsB,EACtB,SAAS,EACT,cAAc,EACd,OAAO,GAKR,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,SAAS,EAAE,cAAc,EAAqD,MAAM,iBAAiB,CAAC;AAC/G,OAAO,EACL,iBAAiB,GAIlB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,kBAAkB,EAAqD,MAAM,2BAA2B,CAAC"}

package/dist/ux/optimistic.d.ts

@@ -36,6 +36,10 @@
  * A settled patch is dropped when fresh rows arrive that account for it. That
  * is the whole reconciliation rule, and it is deliberately evidence-based
  * rather than timed: see `shouldDropSettled`.
+ *
+ * The same rules apply to a single value — a switch, a status, a settings
+ * record — under the `…Value` names at the foot of this file. A queue there
+ * too, and for the sharper of the two reasons: see `ValuePatch`.
  */
 /** How a row is identified. Ids are strings here; numbers stringify fine. */
 export type RowKey = string;
@@ -136,4 +140,70 @@ export declare function supersede<T>(patches: readonly Patch<T>[], keys: Readonl
 export declare function tempKey(prefix?: string): string;
 /** Whether a key came from `tempKey` — a row that is still being created. */
 export declare function isTempKey(key: RowKey): boolean;
+/**
+ * A change to a single value — a switch, a status, a settings record.
+ *
+ * The same queue as above, for the case where the base is one thing instead of
+ * an array of them. It is a queue and not one held value for the reason a list
+ * is: two writes can be in flight at once, and each has to be able to land or
+ * roll back **on its own**. A single slot makes whichever request answers last
+ * the winner, so a slow first write landing after a second one quietly puts the
+ * first answer back on screen — a change the person watched save, undone by
+ * nothing they did.
+ */
+export interface ValuePatch<T> {
+    readonly id: string;
+    /** `set` replaces the value; `merge` lays fields over whatever is beneath it. */
+    readonly kind: "set" | "merge";
+    /** `set`: the value to show. */
+    readonly value?: T;
+    /** `merge`: the fields to lay over it. */
+    readonly fields?: Partial<T>;
+    readonly settled: boolean;
+    /** What the base was when the write landed — see `shouldDropSettledValue`. */
+    readonly witness?: T;
+}
+/** The value to render: the server's, with every change laid over it in order. */
+export declare function applyValuePatches<T>(base: T, patches: readonly ValuePatch<T>[]): T;
+/** Does the base already say what this change says? */
+export declare function isRedundantValue<T>(patch: ValuePatch<T>, base: T): boolean;
+/**
+ * Whether a settled change has been overtaken by a fresh value — the same two
+ * endings as `shouldDropSettled`: the base agrees, so the change has nothing
+ * left to show, or the base has moved since the write landed, in which case it
+ * wins whatever it says.
+ */
+export declare function shouldDropSettledValue<T>(patch: ValuePatch<T>, base: T): boolean;
+/**
+ * The queue after a fresh value arrived.
+ *
+ * Writes in flight are left alone. Settled ones go **together**, judged by the
+ * last of them: unlike a list, every change here is about the same one thing,
+ * so once fresh data has overtaken the newest of them the older ones have
+ * nothing to say either — and keeping some while dropping others is how a
+ * half-applied value would get on screen.
+ */
+export declare function reconcileValue<T>(patches: readonly ValuePatch<T>[], base: T): readonly ValuePatch<T>[];
+/**
+ * Mark a landed write as settled, taking the server's own answer where it sent
+ * one and noting what the base said, so the next refresh can be recognised.
+ *
+ * A `set` takes the answer whole, because the caller declared the value's own
+ * shape by passing it. A `merge` takes only the fields it wrote, for the reason
+ * `settlePatch` does: a write route often answers with a thinner record than
+ * the read did, and laying that over the value blanks everything the write said
+ * nothing about.
+ */
+export declare function settleValuePatch<T>(patch: ValuePatch<T>, answer: T | undefined, base: T): ValuePatch<T>;
+/**
+ * Drop what a write that has just landed supersedes: settled changes queued
+ * *before* a landed `set`, which replaced the whole value and so answered for
+ * them. Writes still in flight stay — each has a request that can still come
+ * back refused — and a landed `merge` supersedes nothing, because the changes
+ * under it may carry fields it says nothing about.
+ *
+ * Pruning only, never order: a landed change keeps its place in the queue, or a
+ * slow first write would jump ahead of the second one on landing and win.
+ */
+export declare function supersedeValue<T>(patches: readonly ValuePatch<T>[], landed: ValuePatch<T>): readonly ValuePatch<T>[];
 //# sourceMappingURL=optimistic.d.ts.map

package/dist/ux/optimistic.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"optimistic.d.ts","sourceRoot":"","sources":["../../src/ux/optimistic.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAEH,6EAA6E;AAC7E,MAAM,MAAM,MAAM,GAAG,MAAM,CAAC;AAE5B,MAAM,MAAM,SAAS,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,GAAG,MAAM,CAAC;AAEhE,MAAM,WAAW,KAAK,CAAC,CAAC;IACtB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB;;;OAGG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,iCAAiC;IACjC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IACjB,gDAAgD;IAChD,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;IAC7B,qDAAqD;IACrD,QAAQ,CAAC,EAAE,CAAC,EAAE,OAAO,GAAG,KAAK,CAAC;IAC9B,mEAAmE;IACnE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B;;;OAGG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC;CAC7B;AAID,0EAA0E;AAC1E,wBAAgB,WAAW,IAAI,MAAM,CAGpC;AAOD;;;GAGG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAC5B,IAAI,EAAE,SAAS,CAAC,EAAE,EAClB,OAAO,EAAE,SAAS,KAAK,CAAC,CAAC,CAAC,EAAE,EAC5B,KAAK,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,MAAM,GACxB,SAAS,CAAC,EAAE,CAoCd;AAUD,iFAAiF;AACjF,wBAAgB,OAAO,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,GAAG,IAAI,GAAG,SAAS,EAAE,CAAC,EAAE,CAAC,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CASpF;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,SAAS,CAAC,EAAE,EAAE,KAAK,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,MAAM,GAAG,OAAO,CAiBtG;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,SAAS,CAAC,EAAE,EAAE,KAAK,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,MAAM,GAAG,OAAO,CAG5G;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,CAAC,EACzB,OAAO,EAAE,SAAS,KAAK,CAAC,CAAC,CAAC,EAAE,EAC5B,IAAI,EAAE,SAAS,CAAC,EAAE,EAClB,KAAK,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,MAAM,GACxB,SAAS,KAAK,CAAC,CAAC,CAAC,EAAE,CAIrB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAC3B,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,EACf,SAAS,EAAE,CAAC,GAAG,SAAS,EACxB,IAAI,EAAE,SAAS,CAAC,EAAE,EAClB,KAAK,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,MAAM,GACxB,KAAK,CAAC,CAAC,CAAC,CAwBV;AAED;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,OAAO,EAAE,SAAS,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,IAAI,EAAE,WAAW,CAAC,MAAM,CAAC,GAAG,SAAS,KAAK,CAAC,CAAC,CAAC,EAAE,CAEzG;AAED;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,MAAM,SAAQ,GAAG,MAAM,CAG9C;AAED,6EAA6E;AAC7E,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAE9C"}
+{"version":3,"file":"optimistic.d.ts","sourceRoot":"","sources":["../../src/ux/optimistic.ts"],"names":[],"mappings":"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"}

package/dist/ux/optimistic.js

@@ -36,6 +36,10 @@
  * A settled patch is dropped when fresh rows arrive that account for it. That
  * is the whole reconciliation rule, and it is deliberately evidence-based
  * rather than timed: see `shouldDropSettled`.
+ *
+ * The same rules apply to a single value — a switch, a status, a settings
+ * record — under the `…Value` names at the foot of this file. A queue there
+ * too, and for the sharper of the two reasons: see `ValuePatch`.
  */
 let counter = 0;
 /** A patch id. Unique within a session; never stored or sent anywhere. */
@@ -239,4 +243,107 @@ export function tempKey(prefix = "tmp") {
 export function isTempKey(key) {
     return key.startsWith("tmp:");
 }
+/** The value to render: the server's, with every change laid over it in order. */
+export function applyValuePatches(base, patches) {
+    if (patches.length === 0)
+        return base;
+    let value = base;
+    for (const patch of patches) {
+        if (patch.kind === "set") {
+            value = patch.value;
+            continue;
+        }
+        // Fields need something to go over. A merge against a value that is not an
+        // object has nothing to lay them on and is dropped rather than turned into
+        // an object that was never that shape.
+        if (typeof value === "object" && value !== null) {
+            value = { ...value, ...patch.fields };
+        }
+    }
+    return value;
+}
+/** Does the base already say what this change says? */
+export function isRedundantValue(patch, base) {
+    if (patch.kind === "set")
+        return sameRow(base, patch.value);
+    if (typeof base !== "object" || base === null)
+        return true;
+    const fields = (patch.fields ?? {});
+    const current = base;
+    return Object.keys(fields).every((key) => Object.is(current[key], fields[key]));
+}
+/**
+ * Whether a settled change has been overtaken by a fresh value — the same two
+ * endings as `shouldDropSettled`: the base agrees, so the change has nothing
+ * left to show, or the base has moved since the write landed, in which case it
+ * wins whatever it says.
+ */
+export function shouldDropSettledValue(patch, base) {
+    return isRedundantValue(patch, base) || !sameRow(base, patch.witness);
+}
+/**
+ * The queue after a fresh value arrived.
+ *
+ * Writes in flight are left alone. Settled ones go **together**, judged by the
+ * last of them: unlike a list, every change here is about the same one thing,
+ * so once fresh data has overtaken the newest of them the older ones have
+ * nothing to say either — and keeping some while dropping others is how a
+ * half-applied value would get on screen.
+ */
+export function reconcileValue(patches, base) {
+    if (patches.length === 0)
+        return patches;
+    let newest = null;
+    for (const patch of patches)
+        if (patch.settled)
+            newest = patch;
+    if (newest === null || !shouldDropSettledValue(newest, base))
+        return patches;
+    return patches.filter((patch) => !patch.settled);
+}
+/**
+ * Mark a landed write as settled, taking the server's own answer where it sent
+ * one and noting what the base said, so the next refresh can be recognised.
+ *
+ * A `set` takes the answer whole, because the caller declared the value's own
+ * shape by passing it. A `merge` takes only the fields it wrote, for the reason
+ * `settlePatch` does: a write route often answers with a thinner record than
+ * the read did, and laying that over the value blanks everything the write said
+ * nothing about.
+ */
+export function settleValuePatch(patch, answer, base) {
+    const settled = { ...patch, settled: true, witness: base };
+    if (answer === null || answer === undefined)
+        return settled;
+    if (patch.kind === "set")
+        return { ...settled, value: answer };
+    if (typeof answer !== "object")
+        return settled;
+    const sent = answer;
+    const corrected = { ...(patch.fields ?? {}) };
+    for (const field of Object.keys(corrected)) {
+        if (field in sent)
+            corrected[field] = sent[field];
+    }
+    return { ...settled, fields: corrected };
+}
+/**
+ * Drop what a write that has just landed supersedes: settled changes queued
+ * *before* a landed `set`, which replaced the whole value and so answered for
+ * them. Writes still in flight stay — each has a request that can still come
+ * back refused — and a landed `merge` supersedes nothing, because the changes
+ * under it may carry fields it says nothing about.
+ *
+ * Pruning only, never order: a landed change keeps its place in the queue, or a
+ * slow first write would jump ahead of the second one on landing and win.
+ */
+export function supersedeValue(patches, landed) {
+    if (landed.kind !== "set")
+        return patches;
+    const at = patches.findIndex((patch) => patch.id === landed.id);
+    if (at <= 0)
+        return patches;
+    const kept = patches.filter((patch, index) => index >= at || !patch.settled);
+    return kept.length === patches.length ? patches : kept;
+}
 //# sourceMappingURL=optimistic.js.map

package/dist/ux/optimistic.js.map

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

package/dist/ux/use-optimistic-value.d.ts

@@ -20,7 +20,12 @@ export interface OptimisticValue<T> {
         success?: string;
         error?: string;
     }) => Promise<boolean>;
-    /** The same for an object value: lay these fields over it. */
+    /**
+     * The same for an object value: lay these fields over it, whatever else is
+     * held. Two fields changed in the same breath both survive, and the commit's
+     * answer corrects only the fields this write set — a thinner record than the
+     * read sent cannot blank the rest.
+     */
     merge: (fields: Partial<T>, commit: () => Promise<T | void>, options?: {
         success?: string;
         error?: string;
@@ -30,11 +35,14 @@ export interface OptimisticValue<T> {
  * One value the screen can change before the server has agreed: a switch, a
  * status, a counter, a settings record.
  *
- * Same rules as `useOptimisticList` and for the same reasons — the change is
- * held beside the server's value rather than replacing it, so a failure rolls
- * back to something real and a refresh always wins. A switch is the case where
- * getting this wrong is most obvious: flipping back a second after it was
- * flipped, with no explanation, is worse than not moving at all.
+ * Same rules as `useOptimisticList` and for the same reasons — changes are held
+ * beside the server's value rather than replacing it, so a failure rolls back to
+ * something real and a refresh always wins. A switch is the case where getting
+ * this wrong is most obvious: flipping back a second after it was flipped, with
+ * no explanation, is worse than not moving at all.
+ *
+ * Changes are a queue, not one slot, so two overlapping writes each land or roll
+ * back on their own. See `ValuePatch` for what a single slot got wrong.
  */
 export declare function useOptimisticValue<T>(base: T, options?: OptimisticValueOptions): OptimisticValue<T>;
 //# sourceMappingURL=use-optimistic-value.d.ts.map

package/dist/ux/use-optimistic-value.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"use-optimistic-value.d.ts","sourceRoot":"","sources":["../../src/ux/use-optimistic-value.ts"],"names":[],"mappings":"AAQA,MAAM,WAAW,sBAAsB;IACrC,kDAAkD;IAClD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,8DAA8D;IAC9D,SAAS,CAAC,EAAE,MAAM,IAAI,CAAC;CACxB;AAED,MAAM,WAAW,eAAe,CAAC,CAAC;IAChC,+EAA+E;IAC/E,KAAK,EAAE,CAAC,CAAC;IACT,4BAA4B;IAC5B,OAAO,EAAE,OAAO,CAAC;IACjB;;;;;;OAMG;IACH,GAAG,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,EAAE,OAAO,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACpH,8DAA8D;IAC9D,KAAK,EAAE,CACL,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,EAClB,MAAM,EAAE,MAAM,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,EAC/B,OAAO,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,KAC3C,OAAO,CAAC,OAAO,CAAC,CAAC;CACvB;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,OAAO,GAAE,sBAA2B,GAAG,eAAe,CAAC,CAAC,CAAC,CA8DvG"}
+{"version":3,"file":"use-optimistic-value.d.ts","sourceRoot":"","sources":["../../src/ux/use-optimistic-value.ts"],"names":[],"mappings":"AAiBA,MAAM,WAAW,sBAAsB;IACrC,kDAAkD;IAClD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,8DAA8D;IAC9D,SAAS,CAAC,EAAE,MAAM,IAAI,CAAC;CACxB;AAED,MAAM,WAAW,eAAe,CAAC,CAAC;IAChC,+EAA+E;IAC/E,KAAK,EAAE,CAAC,CAAC;IACT,4BAA4B;IAC5B,OAAO,EAAE,OAAO,CAAC;IACjB;;;;;;OAMG;IACH,GAAG,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,EAAE,OAAO,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACpH;;;;;OAKG;IACH,KAAK,EAAE,CACL,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,EAClB,MAAM,EAAE,MAAM,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,EAC/B,OAAO,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,KAC3C,OAAO,CAAC,OAAO,CAAC,CAAC;CACvB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,OAAO,GAAE,sBAA2B,GAAG,eAAe,CAAC,CAAC,CAAC,CAwEvG"}

package/dist/ux/use-optimistic-value.js

@@ -2,50 +2,49 @@
 import * as React from "react";
 import { errorMessage } from "./errors.js";
 import { useActionReporter } from "./feedback.js";
-import { sameRow } from "./optimistic.js";
+import { applyValuePatches, nextPatchId, reconcileValue, settleValuePatch, supersedeValue, } from "./optimistic.js";
+const NO_PATCHES = [];
 /**
  * One value the screen can change before the server has agreed: a switch, a
  * status, a counter, a settings record.
  *
- * Same rules as `useOptimisticList` and for the same reasons — the change is
- * held beside the server's value rather than replacing it, so a failure rolls
- * back to something real and a refresh always wins. A switch is the case where
- * getting this wrong is most obvious: flipping back a second after it was
- * flipped, with no explanation, is worse than not moving at all.
+ * Same rules as `useOptimisticList` and for the same reasons — changes are held
+ * beside the server's value rather than replacing it, so a failure rolls back to
+ * something real and a refresh always wins. A switch is the case where getting
+ * this wrong is most obvious: flipping back a second after it was flipped, with
+ * no explanation, is worse than not moving at all.
+ *
+ * Changes are a queue, not one slot, so two overlapping writes each land or roll
+ * back on their own. See `ValuePatch` for what a single slot got wrong.
  */
 export function useOptimisticValue(base, options = {}) {
     const report = useActionReporter();
-    // `witness` is what the server's value was when the write landed. A settled
-    // hold stands until that changes, which is how "nothing has refreshed yet"
-    // is told apart from "the server now says something else". Worked out on
-    // each render rather than stored, so an object rebuilt by the parent on
-    // every render cannot start a render loop.
-    const [held, setHeld] = React.useState(null);
-    const latest = React.useRef({ options, report });
-    React.useEffect(() => {
-        latest.current = { options, report };
-    });
-    // Nothing is stored when this flips: the next `set` replaces the hold
-    // anyway, and clearing it from an effect would only add a render.
-    const overtaken = held !== null && held.settled && !sameRow(held.witness, base);
-    const value = held && !overtaken ? held.value : base;
-    const valueRef = React.useRef(value);
-    const baseRef = React.useRef(base);
+    const [patches, setPatches] = React.useState(NO_PATCHES);
+    // Everything the asynchronous half needs, read at the time it runs.
+    const latest = React.useRef({ base, options, report });
     React.useEffect(() => {
-        valueRef.current = value;
-        baseRef.current = base;
+        latest.current = { base, options, report };
     });
-    const set = React.useCallback(async (next, commit, per) => {
-        setHeld({ value: next, settled: false });
+    // Worked out on each render rather than stored, so a value the parent rebuilds
+    // every render cannot start a render loop. A settled change knows what the
+    // base said when it landed, which is how "nothing has refreshed yet" is told
+    // apart from "the server now says something else".
+    const live = reconcileValue(patches, base);
+    const value = applyValuePatches(base, live);
+    const write = React.useCallback(async (patch, commit, per) => {
+        // Queued at the end, where it wins on render, and *without* clearing what
+        // is already held. Reconciling here is the only pruning the stored queue
+        // gets; render works it out without touching state, as it must.
+        setPatches((previous) => [...reconcileValue(previous, latest.current.base), patch]);
         const { options: opts, report: tell } = latest.current;
         try {
-            const result = (await commit());
-            // The server's own value where it sent one, so a clamped or normalised
-            // answer shows now rather than after the next refresh.
-            setHeld({
-                value: result === undefined || result === null ? next : result,
-                settled: true,
-                witness: baseRef.current,
+            const answer = (await commit());
+            setPatches((previous) => {
+                // In place, keeping its position: a slow first write that lands after
+                // a second one must not jump the queue and win.
+                const next = previous.map((held) => held.id === patch.id ? settleValuePatch(held, answer ?? undefined, latest.current.base) : held);
+                const landed = next.find((held) => held.id === patch.id);
+                return landed ? supersedeValue(next, landed) : next;
             });
             if (per?.success)
                 tell({ tone: "success", title: per.success });
@@ -53,7 +52,10 @@ export function useOptimisticValue(base, options = {}) {
             return true;
         }
         catch (thrown) {
-            setHeld(null);
+            // Roll back this write and only this one. A later change still in flight
+            // is a change the person can see, and taking it down because an earlier
+            // request was refused undoes something they never asked to undo.
+            setPatches((previous) => previous.filter((held) => held.id !== patch.id));
             tell({
                 tone: "error",
                 title: per?.error ?? opts.error ?? "That didn't save",
@@ -62,7 +64,8 @@ export function useOptimisticValue(base, options = {}) {
             return false;
         }
     }, []);
-    const merge = React.useCallback((fields, commit, per) => set({ ...valueRef.current, ...fields }, commit, per), [set]);
-    return { value, pending: held !== null && !held.settled, set, merge };
+    const set = React.useCallback((next, commit, per) => write({ id: nextPatchId(), kind: "set", value: next, settled: false }, commit, per), [write]);
+    const merge = React.useCallback((fields, commit, per) => write({ id: nextPatchId(), kind: "merge", fields, settled: false }, commit, per), [write]);
+    return { value, pending: live.some((patch) => !patch.settled), set, merge };
 }
 //# sourceMappingURL=use-optimistic-value.js.map

package/dist/ux/use-optimistic-value.js.map

@@ -1 +1 @@
-{"version":3,"file":"use-optimistic-value.js","sourceRoot":"","sources":["../../src/ux/use-optimistic-value.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"use-optimistic-value.js","sourceRoot":"","sources":["../../src/ux/use-optimistic-value.ts"],"names":[],"mappings":"AAAA,YAAY,CAAC;AAEb,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,EACL,iBAAiB,EACjB,WAAW,EACX,cAAc,EACd,gBAAgB,EAChB,cAAc,GAEf,MAAM,iBAAiB,CAAC;AAEzB,MAAM,UAAU,GAAiC,EAAE,CAAC;AAmCpD;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,kBAAkB,CAAI,IAAO,EAAE,UAAkC,EAAE;IACjF,MAAM,MAAM,GAAG,iBAAiB,EAAE,CAAC;IACnC,MAAM,CAAC,OAAO,EAAE,UAAU,CAAC,GAAG,KAAK,CAAC,QAAQ,CAA2B,UAAsC,CAAC,CAAC;IAE/G,oEAAoE;IACpE,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC;IACvD,KAAK,CAAC,SAAS,CAAC,GAAG,EAAE;QACnB,MAAM,CAAC,OAAO,GAAG,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC;IAC7C,CAAC,CAAC,CAAC;IAEH,+EAA+E;IAC/E,2EAA2E;IAC3E,6EAA6E;IAC7E,mDAAmD;IACnD,MAAM,IAAI,GAAG,cAAc,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;IAC3C,MAAM,KAAK,GAAG,iBAAiB,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IAE5C,MAAM,KAAK,GAAG,KAAK,CAAC,WAAW,CAC7B,KAAK,EACH,KAAoB,EACpB,MAA+B,EAC/B,GAAqD,EACnC,EAAE;QACpB,0EAA0E;QAC1E,yEAAyE;QACzE,gEAAgE;QAChE,UAAU,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC,GAAG,cAAc,CAAC,QAAQ,EAAE,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC;QAEpF,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,CAAC,OAAO,CAAC;QACvD,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,CAAC,MAAM,MAAM,EAAE,CAAkB,CAAC;YACjD,UAAU,CAAC,CAAC,QAAQ,EAAE,EAAE;gBACtB,sEAAsE;gBACtE,gDAAgD;gBAChD,MAAM,IAAI,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CACjC,IAAI,CAAC,EAAE,KAAK,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,gBAAgB,CAAC,IAAI,EAAE,MAAM,IAAI,SAAS,EAAE,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAC/F,CAAC;gBACF,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,EAAE,KAAK,KAAK,CAAC,EAAE,CAAC,CAAC;gBACzD,OAAO,MAAM,CAAC,CAAC,CAAC,cAAc,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;YACtD,CAAC,CAAC,CAAC;YACH,IAAI,GAAG,EAAE,OAAO;gBAAE,IAAI,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC;YAChE,IAAI,CAAC,SAAS,EAAE,EAAE,CAAC;YACnB,OAAO,IAAI,CAAC;QACd,CAAC;QAAC,OAAO,MAAM,EAAE,CAAC;YAChB,yEAAyE;YACzE,wEAAwE;YACxE,iEAAiE;YACjE,UAAU,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,EAAE,KAAK,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC;YAC1E,IAAI,CAAC;gBACH,IAAI,EAAE,OAAO;gBACb,KAAK,EAAE,GAAG,EAAE,KAAK,IAAI,IAAI,CAAC,KAAK,IAAI,kBAAkB;gBACrD,WAAW,EAAE,YAAY,CAAC,MAAM,CAAC;aAClC,CAAC,CAAC;YACH,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC,EACD,EAAE,CACH,CAAC;IAEF,MAAM,GAAG,GAAG,KAAK,CAAC,WAAW,CAC3B,CAAC,IAAO,EAAE,MAA+B,EAAE,GAA0C,EAAE,EAAE,CACvF,KAAK,CAAC,EAAE,EAAE,EAAE,WAAW,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,EAAE,MAAM,EAAE,GAAG,CAAC,EACrF,CAAC,KAAK,CAAC,CACR,CAAC;IAEF,MAAM,KAAK,GAAG,KAAK,CAAC,WAAW,CAC7B,CAAC,MAAkB,EAAE,MAA+B,EAAE,GAA0C,EAAE,EAAE,CAClG,KAAK,CAAC,EAAE,EAAE,EAAE,WAAW,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,EAAE,MAAM,EAAE,GAAG,CAAC,EAClF,CAAC,KAAK,CAAC,CACR,CAAC;IAEF,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC;AAC9E,CAAC"}

package/dist/web-search/index.d.ts

@@ -0,0 +1,3 @@
+export { WebSearchError, type FetchLike, type OrganicResult, type ProviderOptions, type WebSearchCallOptions, type WebSearchErrorCode, type WebSearchProvider, type WebSearchProviderName, type WebSearchRequest, type WebSearchResponse, } from "./types.js";
+export { serper, valueSerp, webSearchProviderFromEnv, type WebSearchEnv } from "./providers.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/web-search/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/web-search/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,cAAc,EACd,KAAK,SAAS,EACd,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,oBAAoB,EACzB,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,KAAK,qBAAqB,EAC1B,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,GACvB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,wBAAwB,EAAE,KAAK,YAAY,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/web-search/index.js

@@ -0,0 +1,3 @@
+export { WebSearchError, } from "./types.js";
+export { serper, valueSerp, webSearchProviderFromEnv } from "./providers.js";
+//# sourceMappingURL=index.js.map

package/dist/web-search/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/web-search/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,cAAc,GAUf,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,wBAAwB,EAAqB,MAAM,gBAAgB,CAAC"}

package/dist/web-search/providers.d.ts

@@ -0,0 +1,33 @@
+import { type FetchLike, type ProviderOptions, type WebSearchProvider } from "./types.js";
+/**
+ * Serper (serper.dev). The key goes in a header, never the address. One credit
+ * buys up to ten results; eleven to a hundred cost two.
+ */
+export declare function serper(options: ProviderOptions): WebSearchProvider;
+/**
+ * VALUE SERP (Traject Data). **The key goes in the query string** — that is
+ * their API, not a choice — so this module never lets the address reach an
+ * error message.
+ */
+export declare function valueSerp(options: ProviderOptions): WebSearchProvider;
+/** What a deployment's environment says about search. */
+export interface WebSearchEnv {
+    /** `serper` or `valueserp`, to choose when both keys are set. */
+    WEB_SEARCH_PROVIDER?: string;
+    SERPER_API_KEY?: string;
+    SERPER_URL?: string;
+    VALUESERP_API_KEY?: string;
+    VALUESERP_URL?: string;
+}
+/**
+ * The provider a deployment is set up for, or null when it has no key.
+ *
+ * `WEB_SEARCH_PROVIDER` decides when it names a provider that has a key;
+ * otherwise Serper is used if its key is set, then VALUE SERP. A named provider
+ * without a key falls back rather than failing, so a half-finished change to
+ * the environment degrades to the other provider instead of to no search.
+ */
+export declare function webSearchProviderFromEnv(env?: WebSearchEnv, options?: {
+    fetch?: FetchLike;
+}): WebSearchProvider | null;
+//# sourceMappingURL=providers.d.ts.map

package/dist/web-search/providers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"providers.d.ts","sourceRoot":"","sources":["../../src/web-search/providers.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,SAAS,EAEd,KAAK,eAAe,EAEpB,KAAK,iBAAiB,EAIvB,MAAM,YAAY,CAAC;AA4DpB;;;GAGG;AACH,wBAAgB,MAAM,CAAC,OAAO,EAAE,eAAe,GAAG,iBAAiB,CAsBlE;AAWD;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,eAAe,GAAG,iBAAiB,CA0BrE;AAED,yDAAyD;AACzD,MAAM,WAAW,YAAY;IAC3B,iEAAiE;IACjE,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CACtC,GAAG,GAAE,YAA0C,EAC/C,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,SAAS,CAAA;CAAO,GAClC,iBAAiB,GAAG,IAAI,CAe1B"}

package/dist/web-search/providers.js

@@ -0,0 +1,161 @@
+import { WebSearchError, } from "./types.js";
+const DEFAULT_TIMEOUT_MS = 12_000;
+function signalFor(options) {
+    const timeout = AbortSignal.timeout(options?.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+    return options?.signal ? AbortSignal.any([options.signal, timeout]) : timeout;
+}
+/** The status, as a code — and nothing of the response body, which can echo the request. */
+function codeFor(status) {
+    if (status === 401 || status === 403)
+        return "unauthorised";
+    if (status === 402 || status === 429)
+        return "rate_limited";
+    return "bad_response";
+}
+async function call(provider, doFetch, url, init) {
+    let response;
+    try {
+        response = await doFetch(url, init);
+    }
+    catch (error) {
+        // Never the error itself: a fetch failure can quote the address.
+        const aborted = error instanceof Error && (error.name === "TimeoutError" || error.name === "AbortError");
+        throw new WebSearchError(provider, aborted ? "timeout" : "unreachable");
+    }
+    if (!response.ok)
+        throw new WebSearchError(provider, codeFor(response.status), response.status);
+    try {
+        return await response.json();
+    }
+    catch {
+        throw new WebSearchError(provider, "bad_response", response.status);
+    }
+}
+const text = (value) => (typeof value === "string" && value.trim() ? value.trim() : null);
+/** Rows with a title and an address, numbered as the engine ranked them. */
+function organic(rows) {
+    if (!Array.isArray(rows))
+        return [];
+    const out = [];
+    for (const [index, row] of rows.entries()) {
+        if (!row || typeof row !== "object")
+            continue;
+        const r = row;
+        const title = text(r.title);
+        const url = text(r.link);
+        if (!title || !url)
+            continue;
+        out.push({
+            position: typeof r.position === "number" ? r.position : index + 1,
+            title,
+            url,
+            snippet: text(r.snippet),
+        });
+    }
+    return out;
+}
+/**
+ * Serper (serper.dev). The key goes in a header, never the address. One credit
+ * buys up to ten results; eleven to a hundred cost two.
+ */
+export function serper(options) {
+    const doFetch = options.fetch ?? fetch;
+    const endpoint = new URL("search", `${(options.baseUrl ?? "https://google.serper.dev").replace(/\/+$/, "")}/`);
+    return {
+        name: "serper",
+        label: "Serper",
+        async search(request, callOptions) {
+            const body = { q: request.q };
+            if (request.country)
+                body.gl = request.country.toLowerCase();
+            if (request.language)
+                body.hl = request.language.toLowerCase();
+            if (request.num)
+                body.num = request.num;
+            const data = await call("serper", doFetch, endpoint, {
+                method: "POST",
+                headers: { "X-API-KEY": options.apiKey, "Content-Type": "application/json", Accept: "application/json" },
+                body: JSON.stringify(body),
+                signal: signalFor(callOptions),
+            });
+            const answer = data;
+            if (!answer || !Array.isArray(answer.organic))
+                throw new WebSearchError("serper", "bad_response");
+            return { provider: "serper", results: organic(answer.organic) };
+        },
+    };
+}
+/** The Google domain for a country, so ValueSERP searches the same Google a person there would. */
+function googleDomain(country) {
+    if (!country)
+        return undefined;
+    const code = country.toLowerCase();
+    if (code === "gb" || code === "uk")
+        return "google.co.uk";
+    if (code === "us")
+        return "google.com";
+    return undefined;
+}
+/**
+ * VALUE SERP (Traject Data). **The key goes in the query string** — that is
+ * their API, not a choice — so this module never lets the address reach an
+ * error message.
+ */
+export function valueSerp(options) {
+    const doFetch = options.fetch ?? fetch;
+    const base = options.baseUrl ?? "https://api.valueserp.com/search";
+    return {
+        name: "valueserp",
+        label: "VALUE SERP",
+        async search(request, callOptions) {
+            const url = new URL(base);
+            url.searchParams.set("api_key", options.apiKey);
+            url.searchParams.set("q", request.q);
+            if (request.country)
+                url.searchParams.set("gl", request.country.toLowerCase());
+            if (request.language)
+                url.searchParams.set("hl", request.language.toLowerCase());
+            const domain = googleDomain(request.country);
+            if (domain)
+                url.searchParams.set("google_domain", domain);
+            if (request.num)
+                url.searchParams.set("num", String(request.num));
+            url.searchParams.set("output", "json");
+            const data = await call("valueserp", doFetch, url, {
+                headers: { Accept: "application/json" },
+                signal: signalFor(callOptions),
+            });
+            const answer = data;
+            if (!answer || answer.request_info?.success === false)
+                throw new WebSearchError("valueserp", "bad_response");
+            // A search with no results has no `organic_results` at all.
+            return { provider: "valueserp", results: organic(answer.organic_results ?? []) };
+        },
+    };
+}
+/**
+ * The provider a deployment is set up for, or null when it has no key.
+ *
+ * `WEB_SEARCH_PROVIDER` decides when it names a provider that has a key;
+ * otherwise Serper is used if its key is set, then VALUE SERP. A named provider
+ * without a key falls back rather than failing, so a half-finished change to
+ * the environment degrades to the other provider instead of to no search.
+ */
+export function webSearchProviderFromEnv(env = process.env, options = {}) {
+    const keys = {
+        serper: env.SERPER_API_KEY?.trim() || undefined,
+        valueserp: env.VALUESERP_API_KEY?.trim() || undefined,
+    };
+    const wanted = env.WEB_SEARCH_PROVIDER?.trim().toLowerCase();
+    const order = wanted === "valueserp" ? ["valueserp", "serper"] : ["serper", "valueserp"];
+    for (const name of order) {
+        const apiKey = keys[name];
+        if (!apiKey)
+            continue;
+        return name === "serper"
+            ? serper({ apiKey, baseUrl: env.SERPER_URL?.trim() || undefined, fetch: options.fetch })
+            : valueSerp({ apiKey, baseUrl: env.VALUESERP_URL?.trim() || undefined, fetch: options.fetch });
+    }
+    return null;
+}
+//# sourceMappingURL=providers.js.map

package/dist/web-search/providers.js.map

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

package/dist/web-search/types.d.ts

@@ -0,0 +1,82 @@
+/**
+ * One search engine, whichever company answers it.
+ *
+ * An app that looks further than its own database — AltEd's tutors from the
+ * wider web was the first — wants the same thing from a search API: Google's
+ * organic results for a query, in a country and a language, quickly, and an
+ * error that says what went wrong without repeating the key it was sent with. Providers differ in everything else —
+ * where the key goes, what the fields are called, what a result costs — and
+ * that is exactly what this module hides.
+ */
+/** The providers this module speaks to. */
+export type WebSearchProviderName = "serper" | "valueserp";
+/** What to search for. Everything but the words is optional. */
+export interface WebSearchRequest {
+    /** The words, as they would be typed into the engine. */
+    q: string;
+    /** Two-letter country the results are for — `gl`: "gb", "us". */
+    country?: string;
+    /** Two-letter interface language — `hl`: "en". */
+    language?: string;
+    /** How many results to ask for. Providers bill differently above ten; see each provider. */
+    num?: number;
+}
+/** One organic result, the same shape from every provider. */
+export interface OrganicResult {
+    /** 1-based, as the engine ranked it. */
+    position: number;
+    title: string;
+    /** The page's address, exactly as the engine gave it. */
+    url: string;
+    /** The engine's extract of the page, if it gave one. */
+    snippet: string | null;
+}
+export interface WebSearchResponse {
+    provider: WebSearchProviderName;
+    results: OrganicResult[];
+}
+export interface WebSearchCallOptions {
+    /** Abandon the request after this long. Default 12 seconds. */
+    timeoutMs?: number;
+    /** The caller's own cancellation, combined with the timeout. */
+    signal?: AbortSignal;
+}
+export interface WebSearchProvider {
+    readonly name: WebSearchProviderName;
+    /** A person-facing name, for a privacy policy's list of processors. */
+    readonly label: string;
+    search(request: WebSearchRequest, options?: WebSearchCallOptions): Promise<WebSearchResponse>;
+}
+/** Why a search failed, as a code an app can branch on. */
+export type WebSearchErrorCode = 
+/** The key was refused. */
+"unauthorised"
+/** The provider's rate limit or the account's credit ran out. */
+ | "rate_limited"
+/** The request never got an answer in time. */
+ | "timeout"
+/** The provider could not be reached at all. */
+ | "unreachable"
+/** It answered, but not with results. */
+ | "bad_response";
+/**
+ * A failed search. **Its message never contains the request's address or
+ * headers**: one provider takes the key in the query string, and an error that
+ * quoted the address would put a live key into whatever log caught it.
+ */
+export declare class WebSearchError extends Error {
+    readonly provider: WebSearchProviderName;
+    readonly code: WebSearchErrorCode;
+    /** The HTTP status, when there was one. */
+    readonly status: number | undefined;
+    constructor(provider: WebSearchProviderName, code: WebSearchErrorCode, status?: number);
+}
+/** Injected for tests and for runtimes with their own `fetch`. */
+export type FetchLike = (input: string | URL, init?: RequestInit) => Promise<Response>;
+export interface ProviderOptions {
+    apiKey: string;
+    /** Point at a stand-in for local checks. */
+    baseUrl?: string;
+    fetch?: FetchLike;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/web-search/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/web-search/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,2CAA2C;AAC3C,MAAM,MAAM,qBAAqB,GAAG,QAAQ,GAAG,WAAW,CAAC;AAE3D,gEAAgE;AAChE,MAAM,WAAW,gBAAgB;IAC/B,yDAAyD;IACzD,CAAC,EAAE,MAAM,CAAC;IACV,iEAAiE;IACjE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,kDAAkD;IAClD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,4FAA4F;IAC5F,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,8DAA8D;AAC9D,MAAM,WAAW,aAAa;IAC5B,wCAAwC;IACxC,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,yDAAyD;IACzD,GAAG,EAAE,MAAM,CAAC;IACZ,wDAAwD;IACxD,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,qBAAqB,CAAC;IAChC,OAAO,EAAE,aAAa,EAAE,CAAC;CAC1B;AAED,MAAM,WAAW,oBAAoB;IACnC,+DAA+D;IAC/D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gEAAgE;IAChE,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,qBAAqB,CAAC;IACrC,uEAAuE;IACvE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,MAAM,CAAC,OAAO,EAAE,gBAAgB,EAAE,OAAO,CAAC,EAAE,oBAAoB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;CAC/F;AAED,2DAA2D;AAC3D,MAAM,MAAM,kBAAkB;AAC5B,2BAA2B;AACzB,cAAc;AAChB,iEAAiE;GAC/D,cAAc;AAChB,+CAA+C;GAC7C,SAAS;AACX,gDAAgD;GAC9C,aAAa;AACf,yCAAyC;GACvC,cAAc,CAAC;AAEnB;;;;GAIG;AACH,qBAAa,cAAe,SAAQ,KAAK;IACvC,QAAQ,CAAC,QAAQ,EAAE,qBAAqB,CAAC;IACzC,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAC;IAClC,2CAA2C;IAC3C,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;gBAExB,QAAQ,EAAE,qBAAqB,EAAE,IAAI,EAAE,kBAAkB,EAAE,MAAM,CAAC,EAAE,MAAM;CAOvF;AAED,kEAAkE;AAClE,MAAM,MAAM,SAAS,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,GAAG,EAAE,IAAI,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;AAEvF,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,4CAA4C;IAC5C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,SAAS,CAAC;CACnB"}

package/dist/web-search/types.js

@@ -0,0 +1,29 @@
+/**
+ * One search engine, whichever company answers it.
+ *
+ * An app that looks further than its own database — AltEd's tutors from the
+ * wider web was the first — wants the same thing from a search API: Google's
+ * organic results for a query, in a country and a language, quickly, and an
+ * error that says what went wrong without repeating the key it was sent with. Providers differ in everything else —
+ * where the key goes, what the fields are called, what a result costs — and
+ * that is exactly what this module hides.
+ */
+/**
+ * A failed search. **Its message never contains the request's address or
+ * headers**: one provider takes the key in the query string, and an error that
+ * quoted the address would put a live key into whatever log caught it.
+ */
+export class WebSearchError extends Error {
+    provider;
+    code;
+    /** The HTTP status, when there was one. */
+    status;
+    constructor(provider, code, status) {
+        super(`The ${provider} search failed (${code}${status ? `, HTTP ${status}` : ""}).`);
+        this.name = "WebSearchError";
+        this.provider = provider;
+        this.code = code;
+        this.status = status;
+    }
+}
+//# sourceMappingURL=types.js.map

package/dist/web-search/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/web-search/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AA4DH;;;;GAIG;AACH,MAAM,OAAO,cAAe,SAAQ,KAAK;IAC9B,QAAQ,CAAwB;IAChC,IAAI,CAAqB;IAClC,2CAA2C;IAClC,MAAM,CAAqB;IAEpC,YAAY,QAA+B,EAAE,IAAwB,EAAE,MAAe;QACpF,KAAK,CAAC,OAAO,QAAQ,mBAAmB,IAAI,GAAG,MAAM,CAAC,CAAC,CAAC,UAAU,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;QACrF,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;QAC7B,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;CACF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@connextar/house",
-  "version": "0.6.1",
+  "version": "0.8.1",
   "description": "The pieces every app we build needs and none of them should own a copy of.",
   "license": "MIT",
   "repository": {
@@ -54,6 +54,10 @@
       "types": "./dist/grid/index.d.ts",
       "default": "./dist/grid/index.js"
     },
+    "./web-search": {
+      "types": "./dist/web-search/index.d.ts",
+      "default": "./dist/web-search/index.js"
+    },
     "./wizard": {
       "types": "./dist/wizard/index.d.ts",
       "default": "./dist/wizard/index.js"