@wssto2/vue-core 0.12.1 → 0.13.0

package/dist/platform-DtISOEt7.js

@@ -0,0 +1,284 @@
+import { c as U } from "./client-Dg303Pmc.js";
+import { d as _ } from "./context-Ch1r4fdN.js";
+import { a as A, A as z } from "./error-CD7x0Jrz.js";
+import { shallowRef as C } from "vue";
+const I = (e, r) => e.level === r.level && e.id === r.id, T = (e, r) => Object.prototype.hasOwnProperty.call(e, r);
+function N(e, r = {}) {
+  const n = r.covers ?? I;
+  function o(s) {
+    const t = e();
+    return !t || !T(t.permissions, s) || t.unavailable.includes(s) ? null : t.permissions[s] ?? null;
+  }
+  function u(s, t) {
+    const c = o(s);
+    return c ? t ? (c.clauses.length > 0 ? c.clauses.map((i) => i.scope) : [c.scope]).some((i) => n(i, t)) : !0 : !1;
+  }
+  return {
+    get root() {
+      return e()?.root ?? !1;
+    },
+    can: u,
+    canAny: (s) => s.some((t) => u(t)),
+    canAll: (s) => s.every((t) => u(t)),
+    held: o
+  };
+}
+const $ = ["own", "own_location", "all"], y = (e) => typeof e == "object" && e !== null && !Array.isArray(e);
+function S(e, r, n) {
+  return !y(e) || typeof e.level != "string" ? (n.push(`${r}: expected { level: string, id?: number }`), { level: "" }) : (e.id !== void 0 && typeof e.id != "number" && n.push(`${r}.id: expected number`), typeof e.id == "number" ? { level: e.level, id: e.id } : { level: e.level });
+}
+function O(e, r, n) {
+  return typeof e == "string" && $.includes(e) ? e : (n.push(`${r}: expected one of ${$.join(", ")}`), "own");
+}
+function B(e) {
+  const r = [], n = {}, o = { root: !1, permissions: {}, unavailable: [] };
+  if (!y(e)) return { snapshot: o, issues: ["access: expected an object"] };
+  if (!y(e.permissions)) r.push("access.permissions: expected an object");
+  else
+    for (const [s, t] of Object.entries(e.permissions)) {
+      const c = `access.permissions.${s}`;
+      if (!y(t)) {
+        r.push(`${c}: expected an object`);
+        continue;
+      }
+      const f = (Array.isArray(t.clauses) ? t.clauses : []).map((i, x) => {
+        const m = `${c}.clauses[${x}]`;
+        if (!y(i))
+          return r.push(`${m}: expected an object`), { scope: { level: "" }, qualifier: "own" };
+        const d = { scope: S(i.scope, `${m}.scope`, r), qualifier: O(i.qualifier, `${m}.qualifier`, r) };
+        return typeof i.role == "string" ? { ...d, role: i.role } : d;
+      });
+      n[s] = {
+        scope: S(t.scope, `${c}.scope`, r),
+        qualifier: O(t.qualifier, `${c}.qualifier`, r),
+        clauses: f
+      };
+    }
+  const u = e.unavailable ?? [];
+  return (!Array.isArray(u) || !u.every((s) => typeof s == "string")) && r.push("access.unavailable: expected an array of strings"), {
+    snapshot: {
+      root: e.root === !0,
+      permissions: n,
+      unavailable: Array.isArray(u) ? u.filter((s) => typeof s == "string") : []
+    },
+    issues: r
+  };
+}
+const F = (e) => typeof e == "object" && e !== null && !Array.isArray(e);
+function P(e, r, n = "navigation") {
+  return Array.isArray(e) ? e.flatMap((o, u) => {
+    const s = `${n}[${u}]`;
+    if (!F(o) || typeof o.i18n != "string")
+      return r.push(`${s}: expected an object with an i18n key`), [];
+    for (const c of ["icon", "route"])
+      o[c] != null && typeof o[c] != "string" && r.push(`${s}.${c}: expected a string`);
+    const t = o.children == null ? void 0 : P(o.children, r, `${s}.children`);
+    return [
+      {
+        i18n: o.i18n,
+        ...typeof o.icon == "string" && { icon: o.icon },
+        ...typeof o.route == "string" && { route: o.route },
+        ...t && { children: t }
+      }
+    ];
+  }) : (r.push(`${n}: expected an array`), []);
+}
+const b = (e) => typeof e == "object" && e !== null && !Array.isArray(e), H = (e) => {
+  if (b(e) && (typeof e.id == "number" || typeof e.id == "string")) return { id: e.id };
+  throw new TypeError("expected an object with a numeric or string id");
+};
+function Q(e, r = H) {
+  const n = [];
+  if (!b(e)) throw j(["expected an object"]);
+  let o = null;
+  try {
+    o = r(e.user);
+  } catch (i) {
+    n.push(`user: ${i instanceof Error ? i.message : "invalid"}`);
+  }
+  let u = null;
+  if (e.expires_at !== void 0 && e.expires_at !== null) {
+    const i = typeof e.expires_at == "string" ? new Date(e.expires_at) : null;
+    i === null || Number.isNaN(i.getTime()) ? n.push("expires_at: expected an ISO date-time string") : u = i;
+  }
+  let s;
+  if (e.impersonator !== void 0 && e.impersonator !== null) {
+    const i = e.impersonator;
+    b(i) && (typeof i.id == "number" || typeof i.id == "string") && typeof i.name == "string" ? s = { id: i.id, name: i.name } : n.push("impersonator: expected { id, name }");
+  }
+  const t = B(e.access);
+  n.push(...t.issues);
+  const c = e.navigation === void 0 || e.navigation === null ? void 0 : P(e.navigation, n), f = b(e.preferences) ? e.preferences : {};
+  if (o === null || n.length > 0) throw j(n);
+  return { user: o, expiresAt: u, access: t.snapshot, preferences: f, ...s && { impersonator: s }, ...c && { navigation: c } };
+}
+const j = (e) => new z({ kind: "malformed", message: `Unreadable session payload: ${e.join("; ")}` });
+function R(e, r = {}) {
+  const { mePath: n = "/auth/me", signOutPath: o = "/auth/logout", parseUser: u } = r;
+  return {
+    async load(s) {
+      try {
+        const { data: t } = await e.get(n, { signal: s, handleUnauthorized: !1 });
+        return Q(t, u);
+      } catch (t) {
+        if (A(t) && t.kind === "unauthorized") return null;
+        throw t;
+      }
+    },
+    async signOut() {
+      try {
+        await e.post(o, void 0, { handleUnauthorized: !1 });
+      } catch (s) {
+        if (!(A(s) && s.kind === "unauthorized")) throw s;
+      }
+    }
+  };
+}
+function k(e) {
+  return e.status === "authenticated" ? e : e.status === "anonymous" && e.reason === "expired" ? e.previous ?? null : null;
+}
+const E = 3e3;
+function D(e, r = {}) {
+  const n = C({ status: "unknown" });
+  let o = 0;
+  const u = new Set(r.beforeSignOut ? [r.beforeSignOut] : []);
+  let s = !1, t = null, c = null, f = null;
+  function i() {
+    o++, f?.controller.abort(), f = null;
+  }
+  async function x(a) {
+    const l = new AbortController();
+    let g;
+    const v = new Promise((h) => {
+      g = setTimeout(() => {
+        l.abort(), r.onError?.(new Error(`A before-sign-out hook did not finish within ${E} ms; signing out without it.`)), h();
+      }, E);
+    }), w = Promise.all(
+      [...u].map(async (h) => {
+        try {
+          await h(a, l.signal);
+        } catch (p) {
+          r.onError?.(p);
+        }
+      })
+    ).then(() => {
+    });
+    await Promise.race([w, v]), clearTimeout(g);
+  }
+  function m() {
+    if (f) return f.promise;
+    const a = o, l = new AbortController(), g = n.value, v = k(g) !== null;
+    v || (n.value = { status: "loading" });
+    const w = async () => {
+      try {
+        const p = await e.load(l.signal);
+        if (o !== a) return n.value;
+        n.value = p ? { status: "authenticated", ...p } : { status: "anonymous", reason: "none" };
+      } catch (p) {
+        if (o !== a) return n.value;
+        r.onError?.(p), n.value = v ? g : { status: "failed", error: p };
+      } finally {
+        o === a && (f = null);
+      }
+      return n.value;
+    }, h = Promise.resolve().then(w);
+    return f = { controller: l, promise: h }, h;
+  }
+  const d = {
+    state: n,
+    restore: () => n.value.status === "unknown" || n.value.status === "failed" ? m() : f?.promise ?? Promise.resolve(n.value),
+    refresh: m,
+    establish(a) {
+      i(), n.value = { status: "authenticated", ...a };
+    },
+    update(a) {
+      const l = n.value;
+      if (l.status === "authenticated") {
+        if (a.user && a.user.id !== l.user.id)
+          throw new Error(`session.update cannot change who is signed in (user ${String(l.user.id)} to ${String(a.user.id)}); use session.establish for a different person.`);
+        n.value = {
+          ...l,
+          user: a.user ?? l.user,
+          access: a.access ?? l.access,
+          ...(a.navigation ?? l.navigation) && { navigation: a.navigation ?? l.navigation },
+          ...(a.preferences ?? l.preferences) && { preferences: a.preferences ?? l.preferences }
+        };
+      }
+    },
+    expire() {
+      if (n.value.status !== "authenticated") return;
+      const { status: a, ...l } = n.value;
+      i(), n.value = s && !n.value.impersonator ? { status: "anonymous", reason: "expired", previous: l } : { status: "anonymous", reason: "expired" }, r.onExpired?.();
+    },
+    signOut() {
+      return t ?? (t = (async () => {
+        try {
+          const a = n.value;
+          a.status === "authenticated" && u.size > 0 && await x(a.user), i(), n.value = { status: "anonymous", reason: "signedOut" }, await e.signOut();
+        } finally {
+          t = null;
+        }
+      })()), t;
+    },
+    get renewable() {
+      return r.renew !== void 0 && (r.renewable?.() ?? !0);
+    },
+    renew() {
+      return n.value.status !== "authenticated" ? Promise.resolve(!1) : (c ?? (c = (async () => {
+        try {
+          if (d.renewable && await r.renew(d)) return !0;
+        } catch {
+        }
+        return d.expire(), !1;
+      })().finally(() => {
+        c = null;
+      })), c);
+    },
+    holdExpired(a) {
+      s = a;
+    },
+    onBeforeSignOut(a) {
+      return u.add(a), () => void u.delete(a);
+    }
+  };
+  return d;
+}
+function V(e) {
+  const r = U({
+    baseUrl: e.config.apiBase,
+    transport: e.transport,
+    headers: e.headers,
+    credentials: e.credentials,
+    requestId: e.requestId,
+    async onUnauthorized() {
+      return await u.renew() ? "retry" : "fail";
+    }
+  }), n = e.session ?? ((t) => R(t)), o = typeof n == "function" ? n(r) : n, u = D(o, {
+    onError: e.onSessionError,
+    onExpired: e.onSessionExpired,
+    beforeSignOut: e.beforeSignOut,
+    renew: e.renewSession && ((t) => e.renewSession(t, r)),
+    renewable: e.renewable
+  }), s = N(
+    () => k(u.state.value)?.access ?? null,
+    { covers: e.covers }
+  );
+  return { config: e.config, http: r, session: u, access: s };
+}
+const q = _("platform"), K = q[0], W = q[1];
+function X(e, r) {
+  e.provide(K, r);
+}
+export {
+  V as a,
+  E as b,
+  N as c,
+  D as d,
+  R as e,
+  Q as f,
+  K as g,
+  k as h,
+  X as i,
+  P as p,
+  W as u
+};

package/dist/playwright/session.d.ts

@@ -28,6 +28,7 @@ export declare function accessOf(policies: string[], qualifiers?: Record<string,
 export declare function authResponse(policies?: string[], extra?: SessionExtra): {
     navigation: Node[];
     user: unknown;
+    preferences?: unknown;
     impersonator?: (import("../identity").Impersonator | null) | undefined;
     expires_at: string;
     access: MyAccess;
@@ -39,6 +40,7 @@ export declare const authBody: (policies?: string[], extra?: SessionExtra) => {
     data: {
         navigation: Node[];
         user: unknown;
+        preferences?: unknown;
         impersonator?: (import("../identity").Impersonator | null) | undefined;
         expires_at: string;
         access: MyAccess;

package/dist/preferences-hYhrw8Uy.js

@@ -0,0 +1,91 @@
+import { computed as P } from "vue";
+import { A as S } from "./error-CD7x0Jrz.js";
+import { r as e } from "./route-goWMxDUN.js";
+const w = {
+  login: e("POST", "/v1/auth/login", { public: !0 }),
+  refresh: e("POST", "/v1/auth/refresh", { public: !0 }),
+  logout: e("POST", "/v1/auth/logout"),
+  me: e("GET", "/v1/auth/me"),
+  changeLocale: e("POST", "/v1/auth/change-locale"),
+  loginAs: e("POST", "/v1/auth/login-as"),
+  loginAsReturn: e("POST", "/v1/auth/login-as/return"),
+  usersList: e("GET", "/v1/iam/users", { permission: "iam.user:view" }),
+  usersShow: e("GET", "/v1/iam/users/:id", { permission: "iam.user:view" }),
+  usersCreate: e("POST", "/v1/iam/users", { permission: "iam.user:manage" }),
+  usersUpdate: e("PUT", "/v1/iam/users/:id", { permission: "iam.user:manage" }),
+  usersSetPassword: e("PUT", "/v1/iam/users/:id/password", { permission: "iam.user:manage" }),
+  usersDeactivate: e("POST", "/v1/iam/users/:id/deactivate", { permission: "iam.user:manage" }),
+  usersActivate: e("POST", "/v1/iam/users/:id/activate", { permission: "iam.user:manage" }),
+  usersUnlock: e("POST", "/v1/iam/users/:id/unlock", { permission: "iam.user:manage" }),
+  usersSignins: e("GET", "/v1/iam/users/:id/signins", { permission: "iam.user:view" }),
+  usersChanges: e("GET", "/v1/iam/users/:id/changes", { permission: "iam.user:view" }),
+  usersActivity: e("GET", "/v1/iam/users/:id/activity", { permission: "iam.user.activity:view" }),
+  usersSessions: e("GET", "/v1/iam/users/:id/sessions", { permission: "iam.user:view" }),
+  usersRevokeSession: e("DELETE", "/v1/iam/users/:id/sessions/:session_id", { permission: "iam.user:manage" }),
+  usersRevokeSessions: e("DELETE", "/v1/iam/users/:id/sessions", { permission: "iam.user:manage" }),
+  profileShow: e("GET", "/v1/iam/profile"),
+  profileUpdate: e("PUT", "/v1/iam/profile"),
+  profileChangePassword: e("PUT", "/v1/iam/profile/password"),
+  profileRequestEmail: e("POST", "/v1/iam/profile/email"),
+  profileResendEmail: e("POST", "/v1/iam/profile/email/resend"),
+  profileConfirmEmail: e("POST", "/v1/iam/profile/email/confirm"),
+  profileCancelEmail: e("DELETE", "/v1/iam/profile/email"),
+  profileSignins: e("GET", "/v1/iam/profile/signins"),
+  profileSessions: e("GET", "/v1/iam/profile/sessions"),
+  profileRevokeSession: e("DELETE", "/v1/iam/profile/sessions/:session_id"),
+  preferencesUpdate: e("PUT", "/v1/auth/preferences")
+}, f = (s) => typeof s == "object" && s !== null && !Array.isArray(s);
+function E(s, a) {
+  if (!f(a)) return a;
+  const o = f(s) ? { ...s } : {};
+  for (const [n, t] of Object.entries(a))
+    n !== "__proto__" && (t === null ? delete o[n] : t !== void 0 && (o[n] = E(o[n], t)));
+  return o;
+}
+const T = /* @__PURE__ */ new WeakMap();
+function k(s) {
+  let a = T.get(s);
+  return a || (a = O(s), T.set(s, a)), a;
+}
+function O({ session: s, http: a }) {
+  const o = () => {
+    const r = s.state.value;
+    return r.status === "authenticated" ? { ...r.preferences } : {};
+  }, n = () => {
+    const r = s.state.value;
+    return r.status === "authenticated" ? r.user.id : null;
+  };
+  let t = {}, m = null;
+  const u = [];
+  let v = Promise.resolve();
+  const c = () => s.update({ preferences: u.reduce((r, { patch: i }) => E(r, i), t) }), d = (r) => {
+    const i = u.indexOf(r);
+    i >= 0 && u.splice(i, 1);
+  };
+  return {
+    value: P(() => o()),
+    save(r) {
+      const i = n();
+      if (i === null) return Promise.resolve();
+      (u.length === 0 || m !== i) && (t = o(), m = i, u.length = 0);
+      const p = { patch: r };
+      u.push(p), c();
+      const h = async () => {
+        try {
+          const { data: l } = await a.request(w.preferencesUpdate, { preferences: r });
+          if (!f(l?.preferences)) throw new S({ kind: "malformed", message: "Unreadable preferences answer: expected { preferences: {} }" });
+          m === i && (t = l.preferences), d(p), m === i && n() === i && c();
+        } catch (l) {
+          throw d(p), m === i && n() === i && c(), l;
+        }
+      }, g = v.then(h);
+      return v = g.catch(() => {
+      }), g;
+    }
+  };
+}
+export {
+  w as i,
+  E as m,
+  k as p
+};

package/dist/resource/index.d.ts

@@ -1,5 +1,6 @@
 export { positiveInteger, useResource } from "./resource";
 export type { Resource, ResourceContext, ResourceId, ResourceOptions, ResourceState } from "./resource";
+export { found, readRecord, readRecordWithMeta } from "./read";
 export { useRouteResource, useRouteResourceContext } from "./routeResource";
 export type { RouteResource, RouteResourceOptions } from "./routeResource";
 export type { RecordListContext, RecordNeighbors } from "./listContext";

package/dist/resource/index.js

@@ -1,10 +1,26 @@
-import { p as o, u as r, a, b as u } from "../routeResource-DlTsGTg_.js";
-import { _ as R, a as c } from "../ResourcePage.vue_vue_type_script_setup_true_lang-DljhsTU4.js";
+import { p as g, u as m, a as l, b as R } from "../routeResource-DlTsGTg_.js";
+import { c as a } from "../current-B0lHKTWr.js";
+import { A as n } from "../error-CD7x0Jrz.js";
+import { _ as w, a as x } from "../ResourcePage.vue_vue_type_script_setup_true_lang-Coz91xht.js";
+async function i(t, e) {
+  return (await a().platform.http.get(t, { signal: e.signal })).data;
+}
+async function c(t, e) {
+  const { data: o, meta: r } = await a().platform.http.get(t, { signal: e.signal });
+  return { data: o, meta: r };
+}
+function p(t) {
+  if (t === null) throw new n({ kind: "notFound", message: "Not found", status: 404 });
+  return t;
+}
 export {
-  R as RecordPager,
-  c as ResourcePage,
-  o as positiveInteger,
-  r as useResource,
-  a as useRouteResource,
-  u as useRouteResourceContext
+  w as RecordPager,
+  x as ResourcePage,
+  p as found,
+  g as positiveInteger,
+  i as readRecord,
+  c as readRecordWithMeta,
+  m as useResource,
+  l as useRouteResource,
+  R as useRouteResourceContext
 };

package/dist/resource/read.d.ts

@@ -0,0 +1,16 @@
+import type { ResourceContext } from "./resource";
+/**
+ * The `load` of a record page on `useRouteResource` / `useResource`: one GET through the current application's client, which answers
+ * with `ApiError` (so a 404 reads as "not found" and a page that was left aborts its read). The client is read on each call, so a feature's
+ * api declares its reads at module level, before the application exists.
+ *
+ *   const dealerRecord = (id: number, context: ResourceContext) => readRecord<DealerRecord>(`/v1/dealers/${id}`, context);
+ */
+export declare function readRecord<T>(path: string, context: Pick<ResourceContext, "signal">): Promise<T>;
+/** `readRecord` for an answer that carries `meta` beside the record (the authors, the comments); `meta` is the caller's word, not checked. */
+export declare function readRecordWithMeta<T, M>(path: string, context: Pick<ResourceContext, "signal">): Promise<{
+    data: T;
+    meta: M | null;
+}>;
+/** The record a read found: the server answers `null` only where there is none, which a page reads as "not found" (404), never as a record. */
+export declare function found<T>(record: T | null): T;

package/dist/router/index.js

@@ -1,9 +1,9 @@
 import { _ as a, c as o, a as r, i as t } from "../NoAccess.vue_vue_type_script_setup_true_lang-BHzZtZ50.js";
 import { d as c } from "../defineRoutes-BGAdiIrt.js";
 import { A as u, f as p, i as f, r as A, u as m } from "../access-DmAceEo5.js";
-import { i as l, r as x } from "../guards-Biv_SlGn.js";
-import { u as y } from "../sections-CvUwZ-S1.js";
-import { b as v, c as N, n as H, u as b } from "../navigation-TnVFYRaX.js";
+import { i as l, r as x } from "../guards-DGcSfTEh.js";
+import { u as y } from "../sections-fkW_IJLc.js";
+import { b as v, c as N, n as H, u as b } from "../navigation-CctcxT51.js";
 export {
   u as AppRouterView,
   a as NoAccess,

package/dist/{rowLayout-BsKEzEME.js → rowLayout-y1IB_h2r.js}

@@ -6,9 +6,9 @@ import { _ as J } from "./Icon.vue_vue_type_script_lang-BhhsFYwp.js";
 import { _ as Ne } from "./Menu.vue_vue_type_script_setup_true_lang-wKc9gdCn.js";
 import { _ as ze } from "./Tooltip.vue_vue_type_script_setup_true_lang-Dtg5Y6pf.js";
 import { _ as he } from "./EmptyState.vue_vue_type_script_setup_true_lang-DbZiO2RF.js";
-import { u as Fe } from "./format-D8KUBmbS.js";
+import { u as Fe } from "./format-DoKs29bZ.js";
 import { _ as Ve } from "./Badge.vue_vue_type_script_setup_true_lang-DJyZc0C7.js";
-import { _ as Oe } from "./Timestamp.vue_vue_type_script_setup_true_lang-ClZAAUMd.js";
+import { _ as Oe } from "./Timestamp.vue_vue_type_script_setup_true_lang-DlEUKWra.js";
 import { _ as me } from "./Highlight.vue_vue_type_script_setup_true_lang-DZGBmwcX.js";
 import { a as je } from "./mediaQuery-CygcXmFW.js";
 const Ue = ["data-row-click-ignore"], be = "col-start-1 row-start-1", Ye = "col-span-full row-start-2 max-w-full", ke = /* @__PURE__ */ oe({

package/dist/{sections-CvUwZ-S1.js → sections-fkW_IJLc.js}

@@ -1,7 +1,7 @@
 import { computed as n, watch as h } from "vue";
 import { useI18n as b } from "vue-i18n";
 import { useRoute as g, useRouter as p } from "vue-router";
-import { u as y } from "./platform-BQOX_Ntw.js";
+import { u as y } from "./platform-DtISOEt7.js";
 import { i as w } from "./access-DmAceEo5.js";
 function j() {
   const t = g(), u = p(), { access: c } = y(), { t: r } = b(), i = n(() => {

package/dist/{serverMessages-B6GHgi40.js → serverMessages-Ddghrewh.js}

@@ -1,6 +1,6 @@
 import { useI18n as f } from "vue-i18n";
 import { a as c } from "./error-CD7x0Jrz.js";
-import { u as m } from "./format-D8KUBmbS.js";
+import { u as m } from "./format-DoKs29bZ.js";
 import { u as l } from "./describeError-B-NMa--w.js";
 function E() {
   const { t: i, te: u } = f(), a = m(), d = l(), s = (e) => [`errors.${e}`, `core.errors.${e}`].find((t) => u(t));

package/dist/shell/darkMode.d.ts

@@ -1,9 +1,9 @@
 import { type Feature } from "../app/feature";
 export interface DarkModeOptions {
-    /** Whether this person wants dark mode now: read in a reactive context (their session user's preference, a store). */
-    dark: () => boolean;
-    /** Stores the choice. It handles its own failure (a toast): the switch only flips what `dark()` says next. */
-    set: (dark: boolean) => void | Promise<void>;
+    /** Whether this person wants dark mode now: read in a reactive context. Default: `dark_mode` of their stored preferences. */
+    dark?: () => boolean;
+    /** Stores the choice. It handles its own failure (a toast): the switch only flips what `dark()` says next. Default: saves `dark_mode` in their stored preferences. */
+    set?: (dark: boolean) => void | Promise<void>;
     /** The colour of an installed app's status bar, which follows the mode. Default white and `#18181B`. */
     themeColor?: {
         light: string;
@@ -17,10 +17,15 @@ export declare function applyDarkMode(dark: boolean, themeColor?: {
 }): void;
 /**
  * The person's dark-mode preference, as an opt-in feature: a switch in the account menu and the mode on the page.
- * Where the preference lives is the app's (usually a field of the session user, saved on the server):
+ * The preference is `dark_mode` of the preferences go-core's identity module keeps for the person (`usePreferences`): the
+ * switch shows at once and is saved with `PUT /v1/auth/preferences`; a refusal is a toast and the mode goes back.
  *
- *   darkMode({ dark: () => session.user.value?.preferences.dark_mode ?? false, set: (dark) => savePreferences({ dark_mode: dark }) })
+ *   darkMode()
  *
- * The page follows `dark()` from the moment the application mounts, signed in or not.
+ * A preference kept elsewhere (a store, a cookie) is `dark` and `set`:
+ *
+ *   darkMode({ dark: () => store.dark, set: (dark) => store.save(dark) })
+ *
+ * The page follows `dark()` from the moment the application mounts, signed in or not (light while nobody is).
  */
-export declare function darkMode(options: DarkModeOptions): Feature;
+export declare function darkMode(options?: DarkModeOptions): Feature;