@antelopejs/dms 0.11.1 → 0.12.1

package/frontend-vue/layers/dms-core/app/composables/useFieldErrors.ts

@@ -4,6 +4,7 @@ import {
   resolveApiMessage,
 } from "./translation/useTranslation";
 import { resolveApiErrorMessage } from "./useApiError";
+import { isBoolean, isNumber, isObject, isString } from "../utils/type-check";
 
 /**
  * The dashboard's error rule: an error that belongs to one field (a value
@@ -77,6 +78,17 @@ interface FetchErrorLike {
   data?: unknown;
 }
 
+interface FieldErrorBody {
+  field?: unknown;
+  message?: unknown;
+  values?: unknown;
+  params?: unknown;
+  code?: unknown;
+  fields?: unknown;
+  issues?: unknown;
+  errors?: unknown;
+}
+
 /** A zod issue, as the API serializes it or as zod hands it to an error map. */
 export interface ValidationIssue {
   path?: unknown;
@@ -119,40 +131,44 @@ const FIELD_ERROR_KEYS = {
 /** Issue types whose size is a count (characters, items), not a value. */
 const COUNTED_TYPES = new Set(["string", "array", "set"]);
 
-// The codes the data API (`@antelopejs/interface-data-api`) refuses a body
-// with, `{ code, fields }`: the message each field shows.
-const DATA_API_CODES: Readonly<Record<string, string>> = {
+const DATA_API_CODES: Readonly<
+  Record<ReturnType<typeof resolveApiErrorMessage>, ApiFieldError["message"]>
+> = {
   missing_mandatory_fields: FIELD_ERROR_KEYS.required,
   invalid_field_types: FIELD_ERROR_KEYS.invalid,
 };
 
-// The same, naming the field: "Loss reason is required".
-const NAMED_FIELD_ERROR_KEYS: Readonly<Record<string, string>> = {
+const NAMED_FIELD_ERROR_KEYS: Readonly<
+  Record<ApiFieldError["message"], Parameters<I18nTranslate>[0]>
+> = {
   [FIELD_ERROR_KEYS.required]: "dms.field_errors.named_required",
   [FIELD_ERROR_KEYS.invalid]: "dms.field_errors.named_invalid",
 };
 
-// `name: String must contain…`: one validation issue prefixed with its field.
 const FIELD_PREFIXED_MESSAGE = /^([\w.]+):\s+(.+)$/s;
-// `error.invalid_2fa_code`, `page.settings.roles.error.name_taken`.
+
 const BARE_I18N_KEY = /^[a-z0-9_]+(\.[a-z0-9_]+)+$/i;
 
 /** The HTTP status of a fetch error; undefined for a network failure. */
-export function apiErrorStatus(error: unknown): number | undefined {
-  if (typeof error !== "object" || error === null) return undefined;
-  const { statusCode, status, response } = error as FetchErrorLike;
+export function apiErrorStatus(
+  error: Parameters<typeof resolveApiErrorMessage>[0],
+): number | undefined {
+  if (!isObject(error) || error === null) return undefined;
+  const { statusCode, status, response }: FetchErrorLike = error;
   return statusCode ?? status ?? response?.status;
 }
 
 /** The error body, parsed when the server sent JSON as plain text. */
-function bodyOf(error: unknown): unknown {
-  if (typeof error !== "object" || error === null) return undefined;
-  const { data } = error as FetchErrorLike;
-  if (typeof data !== "string") return data;
+function bodyOf(
+  error: Parameters<typeof resolveApiErrorMessage>[0],
+): FetchErrorLike["data"] {
+  if (!isObject(error) || error === null) return undefined;
+  const { data } = error;
+  if (!isString(data)) return data;
   const text = data.trim();
   if (!text.startsWith("[") && !text.startsWith("{")) return data;
   try {
-    return JSON.parse(text) as unknown;
+    return JSON.parse(text);
   } catch {
     return data;
   }
@@ -168,7 +184,7 @@ function tooSmallMessage(issue: ValidationIssue): string {
   if (issue.type !== undefined && !COUNTED_TYPES.has(String(issue.type))) {
     return FIELD_ERROR_KEYS.tooSmall;
   }
-  return typeof issue.minimum === "number" && issue.minimum <= 1
+  return isNumber(issue.minimum) && issue.minimum <= 1
     ? FIELD_ERROR_KEYS.required
     : FIELD_ERROR_KEYS.tooShort;
 }
@@ -178,7 +194,7 @@ function tooSmallMessage(issue: ValidationIssue): string {
  * `$dms.field_errors.*` key by issue code (zod words its own in English).
  */
 export function validationIssueMessage(issue: ValidationIssue): string {
-  if (typeof issue.message === "string" && isI18nKey(issue.message)) {
+  if (isString(issue.message) && isI18nKey(issue.message)) {
     return issue.message;
   }
   switch (issue.code) {
@@ -201,15 +217,14 @@ export function validationIssueMessage(issue: ValidationIssue): string {
   }
 }
 
-function isIssueList(body: unknown): body is ValidationIssue[] {
+function isIssueList(
+  body: ReturnType<typeof bodyOf>,
+): body is Array<ValidationIssue & { path: unknown[] }> {
   return (
     Array.isArray(body) &&
     body.length > 0 &&
     body.every(
-      (issue) =>
-        typeof issue === "object" &&
-        issue !== null &&
-        Array.isArray((issue as ValidationIssue).path),
+      (issue) => isObject(issue) && issue !== null && Array.isArray(issue.path),
     )
   );
 }
@@ -217,66 +232,61 @@ function isIssueList(body: unknown): body is ValidationIssue[] {
 /** `field.part.0` for a path reaching into a field, else undefined. */
 function partPath(path: readonly unknown[]): string | undefined {
   if (path.length < 2) return undefined;
-  return path.every((step) => ["string", "number"].includes(typeof step))
+  return path.every((step) => isString(step) || isNumber(step))
     ? path.join(".")
     : undefined;
 }
 
-function fromIssues(issues: ValidationIssue[]): ApiFieldError[] {
+function fromIssues(
+  issues: Array<ValidationIssue & { path: unknown[] }>,
+): ApiFieldError[] {
   return issues.map((issue) => {
-    const path = issue.path as unknown[];
+    const path = issue.path;
     const [field] = path;
     const part = partPath(path);
     return {
-      field: typeof field === "string" ? field : "",
+      field: isString(field) ? field : "",
       message: validationIssueMessage(issue),
       ...(part && { path: part }),
     };
   });
 }
 
-const PARAM_TYPES = new Set(["string", "number", "boolean"]);
-
 /** The placeholder values of a body, keeping only the plain ones. */
-function paramsOf(params: unknown): ApiFieldErrorParams | undefined {
-  if (typeof params !== "object" || params === null || Array.isArray(params)) {
+function paramsOf(
+  params: FieldErrorBody["params"],
+): ApiFieldErrorParams | undefined {
+  if (!isObject(params) || params === null || Array.isArray(params)) {
     return undefined;
   }
-  const entries = Object.entries(params).filter(([, value]) =>
-    PARAM_TYPES.has(typeof value),
+  const entries = Object.entries(params).filter(
+    (entry): entry is [string, ApiFieldErrorParams[string]] =>
+      isString(entry[1]) || isNumber(entry[1]) || isBoolean(entry[1]),
   );
-  return entries.length > 0
-    ? (Object.fromEntries(entries) as ApiFieldErrorParams)
-    : undefined;
+  return entries.length > 0 ? Object.fromEntries(entries) : undefined;
 }
 
 /** `{ field, message, values?, params? }`, the shape the DMS answers with. */
-function fromFieldObject(body: Record<string, unknown>): ApiFieldError[] {
+function fromFieldObject(body: FieldErrorBody): ApiFieldError[] {
   const { field, message, values, params } = body;
-  if (typeof field !== "string" || typeof message !== "string") return [];
+  if (!isString(field) || !isString(message)) return [];
   const placeholders = paramsOf(params);
   return [
     {
       field,
       message,
-      values: Array.isArray(values)
-        ? values.filter((value): value is string => typeof value === "string")
-        : undefined,
+      values: Array.isArray(values) ? values.filter(isString) : undefined,
       ...(placeholders && { params: placeholders }),
     },
   ];
 }
 
 /** `{ code, fields }`, the data API's refusal of a body; undefined otherwise. */
-function fromCodedFields(
-  body: Record<string, unknown>,
-): ApiFieldError[] | undefined {
+function fromCodedFields(body: FieldErrorBody): ApiFieldError[] | undefined {
   const { code, fields } = body;
-  const message = typeof code === "string" ? DATA_API_CODES[code] : undefined;
+  const message = isString(code) ? DATA_API_CODES[code] : undefined;
   if (!message || !Array.isArray(fields)) return undefined;
-  return fields
-    .filter((field): field is string => typeof field === "string")
-    .map((field) => ({ field, message }));
+  return fields.filter(isString).map((field) => ({ field, message }));
 }
 
 function fromText(text: string): ApiFieldError[] {
@@ -296,11 +306,11 @@ function fromText(text: string): ApiFieldError[] {
 }
 
 /** The text code of an error body: the body itself or its `message`. */
-function codeOf(body: unknown): string | undefined {
-  if (typeof body === "string") return body;
-  if (typeof body === "object" && body !== null && !Array.isArray(body)) {
-    const { message } = body as Record<string, unknown>;
-    return typeof message === "string" ? message : undefined;
+function codeOf(body: ReturnType<typeof bodyOf>): string | undefined {
+  if (isString(body)) return body;
+  if (isObject(body) && body !== null && !Array.isArray(body)) {
+    const { message } = body;
+    return isString(message) ? message : undefined;
   }
   return undefined;
 }
@@ -313,16 +323,16 @@ function lookupCode<F extends string>(
   const bare = code.startsWith("$") ? code.slice(1) : code;
   const entry = codes[code] ?? codes[bare] ?? codes[`$${bare}`];
   if (!entry) return undefined;
-  return typeof entry === "string"
+  return isString(entry)
     ? { field: entry, message: code }
     : { field: entry.field, message: entry.message };
 }
 
-function fromBody(body: unknown): ApiFieldError[] {
+function fromBody(body: ReturnType<typeof bodyOf>): ApiFieldError[] {
   if (isIssueList(body)) return fromIssues(body);
-  if (typeof body === "string") return fromText(body);
-  if (typeof body !== "object" || body === null) return [];
-  const record = body as Record<string, unknown>;
+  if (isString(body)) return fromText(body);
+  if (!isObject(body) || body === null) return [];
+  const record: FieldErrorBody = body;
   if (isIssueList(record.issues)) return fromIssues(record.issues);
   if (isIssueList(record.errors)) return fromIssues(record.errors);
   return fromCodedFields(record) ?? fromFieldObject(record);
@@ -350,7 +360,7 @@ function isClientError(status: number | undefined): status is number {
  *   whether part of the error belongs to no field of the form
  */
 export function resolveFieldErrors<F extends string>(
-  error: unknown,
+  error: Parameters<typeof resolveApiErrorMessage>[0],
   options: ResolveFieldErrorsOptions<F>,
 ): FieldErrorResolution {
   const status = apiErrorStatus(error);
@@ -383,7 +393,7 @@ export function resolveFieldErrors<F extends string>(
  * stands in for one it does not know.
  */
 export function describeFieldErrors(
-  error: unknown,
+  error: Parameters<typeof resolveApiErrorMessage>[0],
   translate: I18nTranslate,
   labelOf: (field: string) => string | undefined,
 ): string | undefined {
@@ -392,10 +402,10 @@ export function describeFieldErrors(
     return undefined;
   }
   const body = bodyOf(error);
-  if (typeof body !== "object" || body === null || Array.isArray(body)) {
+  if (!isObject(body) || body === null || Array.isArray(body)) {
     return undefined;
   }
-  const entries = fromCodedFields(body as Record<string, unknown>);
+  const entries = fromCodedFields(body);
   if (!entries?.length) return undefined;
   return entries
     .map(({ field, message }) =>
@@ -411,7 +421,9 @@ export function describeFieldErrors(
  * message key, the first validation issue's (or a generic one), else the
  * generic server error.
  */
-export function describeApiError(error: unknown): string {
+export function describeApiError(
+  error: Parameters<typeof resolveApiErrorMessage>[0],
+): string {
   return apiErrorText(error) ?? resolveApiErrorMessage(error);
 }
 
@@ -420,7 +432,9 @@ export function describeApiError(error: unknown): string {
  * validation issue's), or `undefined` when it carries none (a network
  * failure).
  */
-export function apiErrorText(error: unknown): string | undefined {
+export function apiErrorText(
+  error: Parameters<typeof resolveApiErrorMessage>[0],
+): string | undefined {
   const body = bodyOf(error);
   if (isIssueList(body)) return validationIssueMessage(body[0]!);
   const text = codeOf(body);
@@ -471,19 +485,21 @@ export interface HandleApiErrorOptions {
  * Bind `errors[field]` to the message element (id `errorId(field)`) and
  * `aria(field)` onto the control; call `clear(field)` when its value changes.
  */
+/* oxlint-disable anti-slop/require-safety-comment-for-type-assertion -- Object.keys erases F. The options owner and resolveFieldErrors membership check cannot prove runtime extra keys are F. Filtering would change extra-key behavior. */
 export function useFieldErrors<F extends string>(
   options: UseFieldErrorsOptions<F>,
 ) {
   const { t } = useI18n();
   const toast = useToast();
-  const translate = (key: string, params: Record<string, unknown> = {}) =>
+  const consumeReadOnlyRefusal = useReadOnlyRefusal();
+  const translate = (key: string, params: Parameters<I18nTranslate>[1] = {}) =>
     t(key, params);
   const fieldIds = Object.keys(options.fields) as F[];
-  const errors = reactive({}) as Partial<Record<F, string>>;
+  const errors: Partial<Record<F, string>> = reactive({});
 
   function controlId(field: F): string {
     const control = options.fields[field];
-    return typeof control === "string" ? control : `field-${field}`;
+    return isString(control) ? control : `field-${field}`;
   }
 
   function errorId(field: F): string {
@@ -506,10 +522,9 @@ export function useFieldErrors<F extends string>(
     await nextTick();
     if (typeof document === "undefined") return;
     const control = options.fields[field];
-    const element =
-      typeof control === "string"
-        ? document.getElementById(control)
-        : control();
+    const element = isString(control)
+      ? document.getElementById(control)
+      : control();
     element?.focus();
   }
 
@@ -531,7 +546,9 @@ export function useFieldErrors<F extends string>(
    * @returns Whether the error was a field one; `false` leaves it to the
    *   caller (a toast)
    */
-  async function applyApiError(error: unknown): Promise<boolean> {
+  async function applyApiError(
+    error: Parameters<typeof resolveApiErrorMessage>[0],
+  ): Promise<boolean> {
     const { fields } = resolveFieldErrors(error, {
       fields: fieldIds,
       codes: options.codes,
@@ -548,9 +565,14 @@ export function useFieldErrors<F extends string>(
     await focus(fields[0]!.field as F);
     return true;
   }
+  /* oxlint-enable anti-slop/require-safety-comment-for-type-assertion */
 
   /** The toast of an error that belongs to no field. */
-  function toastError(error: unknown, toastOptions: HandleApiErrorOptions) {
+  function toastError(
+    error: Parameters<typeof resolveApiErrorMessage>[0],
+    toastOptions: HandleApiErrorOptions,
+  ) {
+    if (consumeReadOnlyRefusal(error)) return;
     toast.add({
       title: t(toastOptions.toastTitle),
       description: toastOptions.toastDescription
@@ -566,9 +588,10 @@ export function useFieldErrors<F extends string>(
    * @returns Whether the error went under a field
    */
   async function handleApiError(
-    error: unknown,
+    error: Parameters<typeof resolveApiErrorMessage>[0],
     toastOptions: HandleApiErrorOptions,
   ): Promise<boolean> {
+    if (consumeReadOnlyRefusal(error)) return false;
     if (await applyApiError(error)) return true;
     toastError(error, toastOptions);
     return false;

package/frontend-vue/layers/dms-core/app/composables/useFormValidation.ts

@@ -1,7 +1,12 @@
 import { type Ref, watch } from "vue";
+import type { Form } from "@nuxt/ui";
 import type { ZodErrorMap, ZodType, ZodTypeDef } from "zod";
-import { resolveApiMessage } from "./translation/useTranslation";
+import {
+  type I18nTranslate,
+  resolveApiMessage,
+} from "./translation/useTranslation";
 import { type ValidationIssue, validationIssueMessage } from "./useFieldErrors";
+import { isBoolean, isNumber, isObject, isString } from "../utils/type-check";
 
 /**
  * Client-side checks of the hand-built forms (auth pages, onboarding,
@@ -16,7 +21,7 @@ export const CODE_INCOMPLETE_MESSAGE = "$dms.field_errors.code_incomplete";
 /** A new password that misses one of the listed rules. */
 export const PASSWORD_RULES_MESSAGE = "$dms.field_errors.password_rules";
 
-type Translate = (key: string, params?: Record<string, unknown>) => string;
+type Translate = (key: string, params?: Parameters<I18nTranslate>[1]) => string;
 
 /** A UForm validation issue, as a Standard Schema reports it. */
 interface FormIssue {
@@ -33,11 +38,12 @@ export interface LocalizedSchema<Output> {
   "~standard": {
     version: 1;
     vendor: string;
-    validate: (value: unknown) => Promise<FormValidationResult<Output>>;
+    validate: (
+      value: Parameters<ZodType<Output>["safeParseAsync"]>[0],
+    ) => Promise<FormValidationResult<Output>>;
   };
 }
 
-// Markup that is content on its own, without any text around it.
 const RICH_TEXT_MEDIA = /<(img|hr|iframe|video|audio|embed|object)\b/i;
 const HTML_TAG = /<[^>]*>/g;
 const HTML_SPACE = /&nbsp;|&#160;|\u00A0/g;
@@ -57,19 +63,22 @@ export function isRichTextBlank(html: string): boolean {
  *
  * @param type The DMS data type id of the value, when it changes the reading
  */
-export function isBlankValue(value: unknown, type?: string): boolean {
+export function isBlankValue(
+  value: Parameters<typeof isString>[0],
+  type?: string,
+): boolean {
   if (value === undefined || value === null) return true;
-  if (typeof value === "string") {
+  if (isString(value)) {
     return type === "rich_text" ? isRichTextBlank(value) : value.trim() === "";
   }
-  if (typeof value === "number") return Number.isNaN(value);
+  if (isNumber(value)) return Number.isNaN(value);
   if (value instanceof Date) return Number.isNaN(value.getTime());
   if (Array.isArray(value)) {
     return value.every((item) => isBlankValue(item, type));
   }
-  if (typeof value === "object") {
+  if (isObject(value)) {
     return Object.values(value)
-      .filter((part) => typeof part !== "boolean")
+      .filter((part) => !isBoolean(part))
       .every((part) => isBlankValue(part, type));
   }
   return false;
@@ -82,7 +91,7 @@ export function isBlankValue(value: unknown, type?: string): boolean {
  */
 export function formIssueMessage(
   issue: ValidationIssue,
-  data: unknown,
+  data: Parameters<typeof isBlankValue>[0],
 ): string {
   return isBlankValue(data) ? REQUIRED_MESSAGE : validationIssueMessage(issue);
 }
@@ -147,14 +156,19 @@ export function codeEntryError(
 }
 
 /** The message key of a required value left empty, else `undefined`. */
-export function requiredError(value: unknown): string | undefined {
+export function requiredError(
+  value: Parameters<typeof isBlankValue>[0],
+): string | undefined {
   return isBlankValue(value) ? REQUIRED_MESSAGE : undefined;
 }
 
 /** What `UForm` exposes that {@link useLiveFormErrors} needs. */
 export interface LiveFormHandle {
   getErrors: (name?: string) => ReadonlyArray<unknown>;
-  validate: (options: { name: string; silent: boolean }) => Promise<unknown>;
+  validate: (options: {
+    name: string;
+    silent: boolean;
+  }) => ReturnType<Form<Parameters<typeof watch>[0]>["validate"]>;
 }
 
 /**
@@ -168,10 +182,13 @@ export interface LiveFormHandle {
  */
 export function useLiveFormErrors(
   form: Ref<LiveFormHandle | null | undefined>,
-  state: object,
+  state: Parameters<typeof watch>[0],
 ): void {
   watch(
-    () => ({ ...state }) as Record<string, unknown>,
+    (): Record<
+      ReturnType<typeof Object.keys>[number],
+      Parameters<typeof isBlankValue>[0]
+    > => ({ ...state }),
     (current, previous) => {
       const handle = form.value;
       if (!handle) return;

package/frontend-vue/layers/dms-core/app/composables/useReadOnlyRefusal.ts

@@ -0,0 +1,49 @@
+import { isFunction, isObject } from "../utils/type-check";
+
+const READ_ONLY_STATUS = 403;
+const READ_ONLY_HEADER = "x-dms-readonly";
+const READ_ONLY_MARK = "1";
+const READ_ONLY_TOAST_ID = "dms-read-only";
+const READ_ONLY_STATE_KEY = "dms.readOnly.presentedResponses";
+
+function refusedResponse(
+  failure: Parameters<typeof isObject>[0],
+): object | undefined {
+  if (!failure || !isObject(failure)) return;
+  const response = failure.response;
+  if (!response || !isObject(response) || response.status !== READ_ONLY_STATUS)
+    return;
+  const headers = response.headers;
+  if (!headers || !isObject(headers) || !isFunction(headers.get)) return;
+  return headers.get(READ_ONLY_HEADER) === READ_ONLY_MARK
+    ? response
+    : undefined;
+}
+
+/**
+ * Captures app-local refusal presentation. The returned consumer shows one
+ * generic toast per marked response and returns whether it owns presentation.
+ * A consumed refusal remains a failed operation; callers skip only local notices.
+ */
+export function useReadOnlyRefusal() {
+  const toast = useToast();
+  const { processApiMessage } = getAppTranslation();
+  const presented = useDmsState(
+    READ_ONLY_STATE_KEY,
+    () => new WeakSet<object>(),
+  );
+
+  return (failure: Parameters<typeof refusedResponse>[0]): boolean => {
+    const response = refusedResponse(failure);
+    if (!response) return false;
+    if (presented.value.has(response)) return true;
+    presented.value.add(response);
+    toast.add({
+      id: READ_ONLY_TOAST_ID,
+      color: "warning",
+      icon: "i-ph-lock-simple",
+      title: processApiMessage("error.read_only_demo"),
+    });
+    return true;
+  };
+}

package/frontend-vue/layers/dms-core/app/composables/useTrailingDeduper.ts

@@ -1,7 +1,7 @@
 const DEDUPER_KEY_PREFIX = "$dmsTrailingDeduper:";
 
 interface DeduperHost {
-  [key: string]: unknown;
+  [key: `$dmsTrailingDeduper:${string}`]: TrailingDeduper | undefined;
 }
 
 /**
@@ -14,9 +14,10 @@ interface DeduperHost {
  * serializable payload.
  */
 export function useTrailingDeduper(name: string): TrailingDeduper {
-  const host = useDmsApp() as unknown as DeduperHost;
-  const key = `${DEDUPER_KEY_PREFIX}${name}`;
-  const existing = host[key] as TrailingDeduper | undefined;
+  // SAFETY: This module alone writes the private prefix, always with createTrailingDeduper(); absent slots are undefined.
+  const host = useDmsApp() as ReturnType<typeof useDmsApp> & DeduperHost;
+  const key = `${DEDUPER_KEY_PREFIX}${name}` as const;
+  const existing = host[key];
   if (existing) return existing;
   const deduper = createTrailingDeduper();
   host[key] = deduper;

package/frontend-vue/layers/dms-core/app/composables/user/usePreferences.ts

@@ -7,12 +7,12 @@ import {
   PREFERENCES_COOKIE_NAME,
   readAt,
   writeAt,
+  type PreferencesTree,
 } from "../../build/composables/user/preferencesCookie";
 import { clearLocalTableEntries } from "../../build/composables/user/tablePreferences";
+import { isString } from "../../utils/type-check";
 
-export interface UserPreferences {
-  [key: string]: unknown;
-}
+export interface UserPreferences extends PreferencesTree {}
 
 const COOKIE_MAX_AGE_ONE_YEAR = 60 * 60 * 24 * 365;
 
@@ -30,10 +30,8 @@ const LEGACY_COOKIE_NAME = "user-preferences";
  */
 export const MAX_PREFERENCES_COOKIE_BYTES = 3 * 1024;
 
-// A plain copy, as the cookie will read it back: the refs hand out reactive
-// proxies, which a caller may keep mutating after the write.
 const toPlain = <T>(value: T): T =>
-  value === undefined ? value : (JSON.parse(JSON.stringify(value)) as T);
+  value === undefined ? value : JSON.parse(JSON.stringify(value));
 
 const expireLegacyCookie = (): void => {
   if (typeof document === "undefined") return;
@@ -59,9 +57,8 @@ export const usePreferences = () => {
   });
   expireLegacyCookie();
 
-  // The cookie ref is shared by name, so every caller decodes the same value.
   const tree = computed<UserPreferences>(() =>
-    typeof preferenceCookie.value === "string"
+    isString(preferenceCookie.value)
       ? decodePreferencesTree(preferenceCookie.value)
       : {},
   );
@@ -81,10 +78,14 @@ export const usePreferences = () => {
 
   const getPreference = <T = unknown>(keyPath: string, defaultValue?: T): T => {
     const value = readAt(tree.value, keyPath.split("."));
+    // oxlint-disable-next-line anti-slop/require-safety-comment-for-type-assertion -- The stored tree does not validate caller-selected T. Returning the tree value type would change the public generic contract; retain existing unchecked reads.
     return (value === undefined ? defaultValue : value) as T;
   };
 
-  const setPreference = (keyPath: string, value: unknown): void => {
+  const setPreference = (
+    keyPath: string,
+    value: UserPreferences[string],
+  ): void => {
     const keys = keyPath.split(".");
     const next = toPlain(tree.value);
     writeAt(next, keys, toPlain(value));
@@ -107,7 +108,7 @@ export const usePreferences = () => {
     keyPath: string,
     value: Partial<T>,
   ): void => {
-    const current = getPreference<T>(keyPath, {} as T);
+    const current = getPreference(keyPath, {});
     const merged = { ...current, ...value };
     setPreference(keyPath, merged);
   };