DOM

PreferenceStore

Validated, versioned external store for user-controlled streaming and tool verbosity with optional persistence.

createPreferenceStore

createPreferenceStore validates loaded and assigned values before exposing a stable snapshot.

typescript
const store = createPreferenceStore({
  defaultValue: defaultPreferences,
  persistence: {
    key: "chat:a11y-preferences",
    storage: window.localStorage,
    events: {
      subscribe(listener) {
        const handle = (event: StorageEvent) => listener(event);
        window.addEventListener("storage", handle);
        return () => window.removeEventListener("storage", handle);
      },
    },
  },
});

const unsubscribe = store.subscribe(() => {
  const preferences = store.getSnapshot();
  const configuration = preferencesToCoreConfiguration(preferences);
  applyConfiguration(configuration);
});

store.setPreferences({
  version: 1,
  preset: "balanced",
  streaming: "sentence",
  tools: "status",
});

How this code works

  1. 01
    Supply storage

    Pass storage when you need persistence, server rendering, or controlled tests.

  2. 02
    Subscribe to changes

    getSnapshot returns validated, versioned preferences.

  3. 03
    Map preferences to core

    preferencesToCoreConfiguration converts selected verbosity into a core preset and policy override.

Options and return values

defaultValuePreferenceSchemaV1Optional

Validated snapshot used when persistence is missing or invalid.

Default
defaultPreferences
persistence.keystringOptional

Storage key for the serialized versioned schema.

Default
library key
persistence.storagePreferenceStorageOptional

Injected getItem and setItem surface.

Default
localStorage when available
persistence.eventsPreferenceStorageEventSourceOptional

Synchronizes validated changes from other documents.

Default
storage events when available
onDiagnosticcallbackOptional

Observes invalid, unavailable, read, write, and event-source outcomes.

Default
undefined

PreferenceSchemaV1 and helpers

A version field makes persistence migrations explicit.

Options and return values

defaultPreferencesPreferenceSchemaV1Constant

Frozen balanced user preference snapshot.

Default
balanced
normalizePreferences(value)PreferenceSchemaV1Function

Validates and freezes a schema value. Invalid fields or unsupported versions throw TypeError.

Default
n/a
samePreferences(left, right)booleanFunction

Compares the supported schema fields.

Default
n/a
preferencesToCoreConfiguration(value)CorePreferenceConfigurationFunction

Maps user verbosity to a core preset and policy overrides.

Default
n/a