@expofp/debug 3.11.12 → 3.12.1

package/dist/lib/debug-keys.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Storage keys of the debug package's own settings. Both are
+ * `LocalStorageConfigSchema` fields (`efp-` + field name), so the debug panel
+ * and the config's localStorage layer read the same values — but the debug
+ * package needs them before any config exists, hence the literals here.
+ */
+export declare const DEBUG_PATTERN_KEY = "efp-debugPattern";
+export declare const SHOW_DEBUG_BUTTON_KEY = "efp-showDebugButton";
+//# sourceMappingURL=debug-keys.d.ts.map

package/dist/lib/debug-keys.js

@@ -0,0 +1,8 @@
+/**
+ * Storage keys of the debug package's own settings. Both are
+ * `LocalStorageConfigSchema` fields (`efp-` + field name), so the debug panel
+ * and the config's localStorage layer read the same values — but the debug
+ * package needs them before any config exists, hence the literals here.
+ */
+export const DEBUG_PATTERN_KEY = 'efp-debugPattern';
+export const SHOW_DEBUG_BUTTON_KEY = 'efp-showDebugButton';

package/dist/lib/init-debug.js

@@ -1,5 +1,18 @@
+import { safeLocalStorage } from '@expofp/utils';
+import debug from 'debug';
+import { DEBUG_PATTERN_KEY } from './debug-keys.js';
 import { appendLog } from './log-store.js';
 const hasDom = typeof window !== 'undefined' && typeof document !== 'undefined';
+if (hasDom) {
+    // The debug library self-initializes from its own `debug` localStorage key;
+    // apply the SDK's persisted pattern (the panel's `efp-debugPattern` setting,
+    // also the config's localStorage layer) on top, before the first loggers
+    // fire. Guarded read: this runs at module-eval, where a cookie-blocked
+    // cross-origin iframe throwing SecurityError would kill the whole SDK.
+    const pattern = safeLocalStorage()?.getItem(DEBUG_PATTERN_KEY);
+    if (pattern)
+        debug.enable(pattern);
+}
 if (hasDom && typeof console !== 'undefined') {
     const wrap = (level, original) => (...args) => {
         appendLog({ level, args, ts: Date.now() });

package/dist/lib/settings/adopt-global-settings.d.ts

@@ -1,20 +1,11 @@
-export type GlobalSettingSchema = {
-    type: 'boolean';
-    default?: boolean;
-} | {
-    type: 'string';
-    default?: string;
-    placeholder?: string;
-} | {
-    type: 'enum';
-    values: readonly string[];
-    default: string;
-};
-export type EfpDebugUi = Record<string, GlobalSettingSchema>;
+import { type SettingDescriptor } from './register-settings.js';
+export type GlobalSettingSchema = SettingDescriptor;
+export type EfpDebugUi = Record<string, SettingDescriptor>;
 declare global {
     interface Window {
         efpDebugUi?: EfpDebugUi;
     }
 }
+/** Declare the host page's `window.efpDebugUi` settings (see {@link registerSettings}). */
 export declare function adoptGlobalSettings(): void;
 //# sourceMappingURL=adopt-global-settings.d.ts.map

package/dist/lib/settings/adopt-global-settings.js

@@ -1,38 +1,7 @@
-import { registerBooleanSetting } from './register-boolean-setting.js';
-import { registerEnumSetting } from './register-enum-setting.js';
-import { registerStringSetting } from './register-string-setting.js';
-const adopted = new Set();
+import { registerSettings } from './register-settings.js';
+/** Declare the host page's `window.efpDebugUi` settings (see {@link registerSettings}). */
 export function adoptGlobalSettings() {
-    if (typeof window === 'undefined')
+    if (typeof window === 'undefined' || !window.efpDebugUi)
         return;
-    const settings = window.efpDebugUi;
-    if (!settings)
-        return;
-    for (const [key, schema] of Object.entries(settings)) {
-        if (adopted.has(key))
-            continue;
-        adopted.add(key);
-        switch (schema.type) {
-            case 'boolean':
-                registerBooleanSetting({
-                    key,
-                    default: schema.default,
-                });
-                break;
-            case 'string':
-                registerStringSetting({
-                    key,
-                    default: schema.default,
-                    placeholder: schema.placeholder,
-                });
-                break;
-            case 'enum':
-                registerEnumSetting({
-                    key,
-                    values: schema.values,
-                    default: schema.default,
-                });
-                break;
-        }
-    }
+    registerSettings(window.efpDebugUi);
 }

package/dist/lib/settings/index.d.ts

@@ -2,6 +2,7 @@ export * from './adopt-global-settings.js';
 export * from './register-boolean-setting.js';
 export * from './register-enum-setting.js';
 export * from './register-setting.js';
+export * from './register-settings.js';
 export * from './register-string-setting.js';
 export * from './reset-all-settings.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/lib/settings/index.js

@@ -2,5 +2,6 @@ export * from './adopt-global-settings.js';
 export * from './register-boolean-setting.js';
 export * from './register-enum-setting.js';
 export * from './register-setting.js';
+export * from './register-settings.js';
 export * from './register-string-setting.js';
 export * from './reset-all-settings.js';

package/dist/lib/settings/register-enum-setting.js

@@ -4,11 +4,16 @@ export function registerEnumSetting(options) {
     const EnumEditorLazy = React.lazy(() => import('../ui/enum-editor.js').then((mod) => ({
         default: mod.EnumEditor,
     })));
+    // Strings are stored as-is — the plain-scalar format of @expofp/config's
+    // localStorage codec; non-string values fall back to JSON.
+    const serialize = (v) => (typeof v === 'string' ? v : JSON.stringify(v));
     return registerSetting({
         key: options.key,
         default: options.default,
         Editor: EnumEditorLazy,
         context: { values: options.values },
         onChange: options.onChange,
+        serialize,
+        deserialize: (raw) => options.values.find((v) => serialize(v) === raw) ?? options.default,
     });
 }

package/dist/lib/settings/register-setting.js

@@ -1,9 +1,16 @@
 import { jsx as _jsx } from "react/jsx-runtime";
+import debug from 'debug';
 import { useEffect, useState } from 'react';
-import { editors, resets } from './setting-registry.js';
+import { registry } from './setting-registry.js';
+const log = debug('efp:debug');
 const LOCAL_STORAGE_EVENT = 'efp-local-storage';
 export function registerSetting(options) {
     const { key, default: defaultValue, Editor, context, onChange, serialize = JSON.stringify, deserialize = (raw) => JSON.parse(raw), } = options;
+    const existing = registry.get(key);
+    if (existing) {
+        log('registerSetting', 'duplicate key, keeping the first registration:', key);
+        return existing.setting;
+    }
     const get = () => {
         const raw = localStorage.getItem(key);
         if (raw === null)
@@ -16,7 +23,14 @@ export function registerSetting(options) {
         }
     };
     const set = (value) => {
-        localStorage.setItem(key, serialize(value));
+        if (value === undefined) {
+            // An optional setting explicitly unset — the key's absence means "no
+            // opinion" (for config-backed settings, the lower config layers win).
+            localStorage.removeItem(key);
+        }
+        else {
+            localStorage.setItem(key, serialize(value));
+        }
         onChange?.(value);
         emitLocalStorageChange(key);
     };
@@ -25,7 +39,6 @@ export function registerSetting(options) {
         onChange?.(defaultValue);
         emitLocalStorageChange(key);
     };
-    resets.push(reset);
     function useLocalStorageState() {
         const [state, setState] = useState(get());
         useEffect(() => {
@@ -53,13 +66,14 @@ export function registerSetting(options) {
         return _jsx(Editor, { label: key, value: state, context: context, onChange: setState });
     };
     EditorImpl.displayName = `DebugSetting(${key})`;
-    editors.push({ key, Editor: EditorImpl });
-    return {
+    const setting = {
         get,
         set,
         reset,
         useState: useLocalStorageState,
     };
+    registry.set(key, { key, Editor: EditorImpl, setting, reset });
+    return setting;
 }
 function emitLocalStorageChange(key) {
     window.dispatchEvent(new CustomEvent(LOCAL_STORAGE_EVENT, { detail: { key } }));

package/dist/lib/settings/register-settings.d.ts

@@ -0,0 +1,40 @@
+/**
+ * A declarative debug setting — plain data, so descriptors can come from
+ * anywhere: the host page's `window.efpDebugUi`, or `@expofp/config`'s
+ * `toDebugSettings(...)` (one descriptor per `LocalStorageConfigSchema` field,
+ * under the storage key the config's localStorage layer reads).
+ *
+ * An `optional` setting treats the key's absence as an explicit "default"
+ * state: editors render it, picking it removes the key — for config-backed
+ * settings that hands the decision back to the lower config layers. Values are
+ * stored as plain scalar strings, matching `@expofp/config`'s localStorage
+ * codec.
+ */
+export type SettingDescriptor = {
+    type: 'boolean';
+    optional?: boolean;
+    default?: boolean;
+    onChange?: (value: boolean | undefined) => void;
+} | {
+    type: 'string';
+    optional?: boolean;
+    default?: string;
+    placeholder?: string;
+    onChange?: (value: string | undefined) => void;
+} | {
+    type: 'enum';
+    values: readonly string[];
+    optional?: boolean;
+    default?: string;
+    onChange?: (value: string | undefined) => void;
+};
+/**
+ * Declare settings for the debug panel. Descriptors are materialized into
+ * editors when the panel renders; per key, the first declaration wins — and a
+ * key registered imperatively (`registerSetting` and friends) by then keeps
+ * that richer registration.
+ */
+export declare function registerSettings(settings: Record<string, SettingDescriptor>): void;
+/** Materialize declared descriptors into setting editors (idempotent). */
+export declare function materializeSettings(): void;
+//# sourceMappingURL=register-settings.d.ts.map

package/dist/lib/settings/register-settings.js

@@ -0,0 +1,101 @@
+import React from 'react';
+import { registerBooleanSetting } from './register-boolean-setting.js';
+import { registerEnumSetting } from './register-enum-setting.js';
+import { registerSetting } from './register-setting.js';
+import { registerStringSetting } from './register-string-setting.js';
+import { registry } from './setting-registry.js';
+const pending = new Map();
+/**
+ * Declare settings for the debug panel. Descriptors are materialized into
+ * editors when the panel renders; per key, the first declaration wins — and a
+ * key registered imperatively (`registerSetting` and friends) by then keeps
+ * that richer registration.
+ */
+export function registerSettings(settings) {
+    for (const [key, descriptor] of Object.entries(settings)) {
+        if (!pending.has(key))
+            pending.set(key, descriptor);
+    }
+}
+/** Materialize declared descriptors into setting editors (idempotent). */
+export function materializeSettings() {
+    for (const [key, descriptor] of pending) {
+        if (!registry.has(key))
+            register(key, descriptor);
+    }
+}
+const OptionalBooleanEditorLazy = React.lazy(() => import('../ui/optional-boolean-editor.js').then((mod) => ({
+    default: mod.OptionalBooleanEditor,
+})));
+const OptionalStringEditorLazy = React.lazy(() => import('../ui/optional-string-editor.js').then((mod) => ({
+    default: mod.OptionalStringEditor,
+})));
+const OptionalEnumEditorLazy = React.lazy(() => import('../ui/optional-enum-editor.js').then((mod) => ({
+    default: mod.OptionalEnumEditor,
+})));
+function register(key, descriptor) {
+    switch (descriptor.type) {
+        case 'boolean':
+            if (descriptor.optional) {
+                registerSetting({
+                    key,
+                    default: undefined,
+                    Editor: OptionalBooleanEditorLazy,
+                    onChange: descriptor.onChange,
+                    serialize: String,
+                    // mirrors @expofp/config's localStorage codec coercion
+                    deserialize: (raw) => /^(1|true|yes|on)$/i.test(raw),
+                });
+            }
+            else {
+                registerBooleanSetting({
+                    key,
+                    default: descriptor.default,
+                    onChange: descriptor.onChange,
+                });
+            }
+            return;
+        case 'string':
+            if (descriptor.optional) {
+                registerSetting({
+                    key,
+                    default: undefined,
+                    Editor: OptionalStringEditorLazy,
+                    context: { placeholder: descriptor.placeholder },
+                    onChange: descriptor.onChange,
+                    serialize: (value) => value, // set() never serializes undefined
+                    deserialize: (raw) => raw,
+                });
+            }
+            else {
+                registerStringSetting({
+                    key,
+                    default: descriptor.default,
+                    placeholder: descriptor.placeholder,
+                    onChange: descriptor.onChange,
+                });
+            }
+            return;
+        case 'enum':
+            if (descriptor.optional) {
+                registerSetting({
+                    key,
+                    default: undefined,
+                    Editor: OptionalEnumEditorLazy,
+                    context: { values: descriptor.values },
+                    onChange: descriptor.onChange,
+                    serialize: (value) => value, // set() never serializes undefined
+                    deserialize: (raw) => raw,
+                });
+            }
+            else {
+                registerEnumSetting({
+                    key,
+                    values: descriptor.values,
+                    default: descriptor.default ?? descriptor.values[0],
+                    onChange: descriptor.onChange,
+                });
+            }
+            return;
+    }
+}

package/dist/lib/settings/reset-all-settings.js

@@ -1,4 +1,4 @@
-import { resets } from './setting-registry.js';
+import { registry } from './setting-registry.js';
 export function resetAllSettings() {
-    resets.forEach((reset) => reset());
+    registry.forEach((setting) => setting.reset());
 }

package/dist/lib/settings/setting-registry.d.ts

@@ -1,8 +1,11 @@
 import { type FC } from 'react';
-export interface RegisteredEditor {
+export interface RegisteredSetting {
     key: string;
     Editor: FC;
+    /** The `DebugSetting<T>` handle `registerSetting` returned for this key. */
+    setting: unknown;
+    reset: () => void;
 }
-export declare const editors: RegisteredEditor[];
-export declare const resets: (() => void)[];
+/** Every registered setting by storage key — the first registration wins. */
+export declare const registry: Map<string, RegisteredSetting>;
 //# sourceMappingURL=setting-registry.d.ts.map

package/dist/lib/settings/setting-registry.js

@@ -1,2 +1,2 @@
-export const editors = [];
-export const resets = [];
+/** Every registered setting by storage key — the first registration wins. */
+export const registry = new Map();

package/dist/lib/ui/optional-boolean-editor.d.ts

@@ -0,0 +1,4 @@
+import { type EditorProps } from '../settings/editor-props.js';
+/** Tri-state boolean: `default` (key absent — lower config layers decide) / on / off. */
+export declare const OptionalBooleanEditor: React.FC<EditorProps<boolean | undefined>>;
+//# sourceMappingURL=optional-boolean-editor.d.ts.map

package/dist/lib/ui/optional-boolean-editor.js

@@ -0,0 +1,8 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { OptionalEnumEditor } from './optional-enum-editor.js';
+const VALUES = ['on', 'off'];
+/** Tri-state boolean: `default` (key absent — lower config layers decide) / on / off. */
+export const OptionalBooleanEditor = (props) => {
+    return (_jsx(OptionalEnumEditor, { label: props.label, context: { values: VALUES }, value: props.value === undefined ? undefined : props.value ? 'on' : 'off', onChange: (value) => props.onChange(value === undefined ? undefined : value === 'on') }));
+};
+OptionalBooleanEditor.displayName = 'OptionalBooleanEditor';

package/dist/lib/ui/optional-enum-editor.d.ts

@@ -0,0 +1,5 @@
+import { type EditorProps } from '../settings/editor-props.js';
+export declare const OptionalEnumEditor: React.FC<EditorProps<string | undefined, {
+    values: readonly string[];
+}>>;
+//# sourceMappingURL=optional-enum-editor.d.ts.map

package/dist/lib/ui/optional-enum-editor.js

@@ -0,0 +1,12 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Select } from '@radix-ui/themes';
+import { SettingsItem } from './settings-item.js';
+// `undefined` (key absent — the lower config layers decide) rides through the
+// Select as a sentinel, so a literal value spelled "default" stays representable.
+const DEFAULT_SENTINEL = '__DEFAULT__';
+export const OptionalEnumEditor = (props) => {
+    return (_jsx(SettingsItem, { label: props.label, children: _jsxs(Select.Root, { value: props.value ?? DEFAULT_SENTINEL, onValueChange: (selected) => {
+                props.onChange(selected === DEFAULT_SENTINEL ? undefined : selected);
+            }, children: [_jsx(Select.Trigger, {}), _jsxs(Select.Content, { children: [_jsx(Select.Item, { value: DEFAULT_SENTINEL, children: "default" }), props.context.values.map((value) => (_jsx(Select.Item, { value: value, children: value }, value)))] })] }) }));
+};
+OptionalEnumEditor.displayName = 'OptionalEnumEditor';

package/dist/lib/ui/optional-string-editor.d.ts

@@ -0,0 +1,6 @@
+import { type EditorProps } from '../settings/editor-props.js';
+/** A string setting where an empty input unsets the key (lower config layers decide). */
+export declare const OptionalStringEditor: React.FC<EditorProps<string | undefined, {
+    placeholder?: string;
+}>>;
+//# sourceMappingURL=optional-string-editor.d.ts.map

package/dist/lib/ui/optional-string-editor.js

@@ -0,0 +1,8 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { TextField } from '@radix-ui/themes';
+import { SettingsItem } from './settings-item.js';
+/** A string setting where an empty input unsets the key (lower config layers decide). */
+export const OptionalStringEditor = (props) => {
+    return (_jsx(SettingsItem, { label: props.label, children: _jsx(TextField.Root, { placeholder: props.context?.placeholder ?? 'default', value: props.value ?? '', onChange: (e) => props.onChange(e.target.value === '' ? undefined : e.target.value), style: { flexGrow: 1, minWidth: 220 } }) }));
+};
+OptionalStringEditor.displayName = 'OptionalStringEditor';

package/dist/lib/ui/render-debug-ui.js

@@ -1,5 +1,6 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import debug from 'debug';
+import { DEBUG_PATTERN_KEY, SHOW_DEBUG_BUTTON_KEY } from '../debug-keys.js';
 import { registerBooleanSetting, registerStringSetting } from '../settings/index.js';
 import { addDebugSecretListener } from '../utils/add-debug-secret-listener.js';
 let rendered = false;
@@ -9,10 +10,10 @@ export function renderDebugUi() {
     }
     rendered = true;
     const showDebugButtonSetting = registerBooleanSetting({
-        key: 'efp:show-debug-button',
+        key: SHOW_DEBUG_BUTTON_KEY,
     });
     registerStringSetting({
-        key: 'debug',
+        key: DEBUG_PATTERN_KEY,
         placeholder: 'e.g. efp:*',
         onChange: (value) => {
             if (value)

package/dist/lib/ui/settings-list.js

@@ -2,10 +2,12 @@ import { jsx as _jsx } from "react/jsx-runtime";
 import { Skeleton } from '@radix-ui/themes';
 import { Suspense } from 'react';
 import { adoptGlobalSettings } from '../settings/adopt-global-settings.js';
-import { editors } from '../settings/setting-registry.js';
+import { materializeSettings } from '../settings/register-settings.js';
+import { registry } from '../settings/setting-registry.js';
 export const SettingsList = () => {
     adoptGlobalSettings();
-    return [...editors]
+    materializeSettings();
+    return [...registry.values()]
         .sort((a, b) => a.key.localeCompare(b.key))
         .map(({ key, Editor }) => (_jsx(Suspense, { fallback: _jsx(Skeleton, { height: "60px" }), children: _jsx(Editor, {}) }, key)));
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@expofp/debug",
-  "version": "3.11.12",
+  "version": "3.12.1",
   "type": "module",
   "description": "ExpoFP SDK internal: debug utilities",
   "homepage": "https://developer.expofp.com/",
@@ -29,7 +29,8 @@
     "@radix-ui/react-icons": "^1.3.2",
     "@radix-ui/themes": "^3.2.1",
     "debug": "^4.4.3",
-    "tslib": "^2.3.0"
+    "tslib": "^2.3.0",
+    "@expofp/utils": "3.12.1"
   },
   "devDependencies": {
     "@types/react": "^19.2.17",