@adea-ai/ui 0.36.0 → 0.37.0

package/dist/components/appearance.d.ts

@@ -19,6 +19,21 @@ export type SurfacePreference = 'opaque' | 'frosted' | 'translucent';
 export declare const APPEARANCE_STORAGE_KEY = "appearance";
 /** The pre-#425 key. Migration reads it and never deletes it. */
 export declare const LEGACY_THEME_STORAGE_KEY = "theme";
+/**
+ * Recovery envelope for unread preference documents (Dev Runtime spec,
+ * "Compatibility, migrations, and waivers": a failed migration retains the
+ * original record; it never silently rewrites or deletes the input). A
+ * malformed or future-version document is quarantined here — before any
+ * write can touch the main key — so saving valid preferences later can never
+ * destroy the user's unread data.
+ */
+export declare const APPEARANCE_RECOVERY_STORAGE_KEY = "appearance.recovery";
+export type AppearanceRecoveryEnvelope = Readonly<{
+    schemaVersion: 1;
+    reason: 'corrupt_json' | 'unsupported_record';
+    capturedAt: string;
+    raw: string;
+}>;
 export declare const DARK_QUERY = "(prefers-color-scheme: dark)";
 export declare const REDUCED_TRANSPARENCY_QUERY = "(prefers-reduced-transparency: reduce)";
 export declare const defaultAppearancePreferences: AppearancePreferencesV2;
@@ -197,8 +212,9 @@ export declare function migrateLegacyThemeValue(stored: string | null): Appearan
 type AppearanceStorage = Pick<Storage, 'getItem' | 'setItem' | 'removeItem'>;
 /**
  * Read the appearance preferences: the v2 key first, then the legacy `theme`
- * key, then defaults. Storage failures degrade to defaults like every other
- * blocked-storage consumer.
+ * key, then defaults. A malformed or future-version document is quarantined
+ * into the recovery envelope and the defaults are returned; storage failures
+ * degrade to defaults like every other blocked-storage consumer.
  */
 export declare function readAppearancePreferences(storage: AppearanceStorage | undefined): AppearancePreferencesV2;
 export declare function writeAppearancePreferences(storage: AppearanceStorage | undefined, preferences: AppearancePreferencesV2): void;

package/dist/components/appearance.js

@@ -2,6 +2,15 @@
 var APPEARANCE_STORAGE_KEY = "appearance";
 /** The pre-#425 key. Migration reads it and never deletes it. */
 var LEGACY_THEME_STORAGE_KEY = "theme";
+/**
+* Recovery envelope for unread preference documents (Dev Runtime spec,
+* "Compatibility, migrations, and waivers": a failed migration retains the
+* original record; it never silently rewrites or deletes the input). A
+* malformed or future-version document is quarantined here — before any
+* write can touch the main key — so saving valid preferences later can never
+* destroy the user's unread data.
+*/
+var APPEARANCE_RECOVERY_STORAGE_KEY = "appearance.recovery";
 var DARK_QUERY = "(prefers-color-scheme: dark)";
 var REDUCED_TRANSPARENCY_QUERY = "(prefers-reduced-transparency: reduce)";
 var defaultAppearancePreferences = Object.freeze({
@@ -599,9 +608,27 @@ function migrateLegacyThemeValue(stored) {
 	};
 }
 /**
+* Quarantine an unread raw document into the recovery envelope. Runs at read
+* time — before any later write can overwrite the main key — and is
+* idempotent: re-reading the same unread value refreshes the capture without
+* losing it.
+*/
+function retainRecoveryEnvelope(storage, raw, reason) {
+	try {
+		const envelope = {
+			schemaVersion: 1,
+			reason,
+			capturedAt: (/* @__PURE__ */ new Date()).toISOString(),
+			raw
+		};
+		storage.setItem(APPEARANCE_RECOVERY_STORAGE_KEY, JSON.stringify(envelope));
+	} catch {}
+}
+/**
 * Read the appearance preferences: the v2 key first, then the legacy `theme`
-* key, then defaults. Storage failures degrade to defaults like every other
-* blocked-storage consumer.
+* key, then defaults. A malformed or future-version document is quarantined
+* into the recovery envelope and the defaults are returned; storage failures
+* degrade to defaults like every other blocked-storage consumer.
 */
 function readAppearancePreferences(storage) {
 	if (!storage) return defaultAppearancePreferences;
@@ -612,9 +639,12 @@ function readAppearancePreferences(storage) {
 			try {
 				parsed = JSON.parse(raw);
 			} catch {
+				retainRecoveryEnvelope(storage, raw, "corrupt_json");
 				return defaultAppearancePreferences;
 			}
-			return normalizeAppearancePreferences(parsed).value;
+			const normalized = normalizeAppearancePreferences(parsed);
+			if (normalized.retainedRaw !== void 0) retainRecoveryEnvelope(storage, raw, typeof parsed === "object" && parsed !== null ? "unsupported_record" : "corrupt_json");
+			return normalized.value;
 		}
 		return migrateLegacyThemeValue(storage.getItem("theme")) ?? defaultAppearancePreferences;
 	} catch {
@@ -765,4 +795,4 @@ function kebabCase(value) {
 	return value.replaceAll(/[A-Z]/g, (character) => `-${character.toLocaleLowerCase()}`);
 }
 //#endregion
-export { APPEARANCE_STORAGE_KEY, ColorParseError, DARK_QUERY, LEGACY_THEME_STORAGE_KEY, REDUCED_TRANSPARENCY_QUERY, accentPresetById, accentPresets, appearanceThemeScript, applyAppearanceToDocument, builtinThemeRegistry, colorToHex, contrastRatio, defaultAppearancePreferences, deriveAccentRoles, flatVariantTokens, migrateLegacyThemeValue, normalizeAccentValue, normalizeAppearancePreferences, parseColor, readAppearancePreferences, resolveAppearanceMode, resolveAppearanceState, resolveSurface, resolveThemeVariant, themeSelectionVariantId, validateThemeRegistry, writeAppearancePreferences };
+export { APPEARANCE_RECOVERY_STORAGE_KEY, APPEARANCE_STORAGE_KEY, ColorParseError, DARK_QUERY, LEGACY_THEME_STORAGE_KEY, REDUCED_TRANSPARENCY_QUERY, accentPresetById, accentPresets, appearanceThemeScript, applyAppearanceToDocument, builtinThemeRegistry, colorToHex, contrastRatio, defaultAppearancePreferences, deriveAccentRoles, flatVariantTokens, migrateLegacyThemeValue, normalizeAccentValue, normalizeAppearancePreferences, parseColor, readAppearancePreferences, resolveAppearanceMode, resolveAppearanceState, resolveSurface, resolveThemeVariant, themeSelectionVariantId, validateThemeRegistry, writeAppearancePreferences };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adea-ai/ui",
-  "version": "0.36.0",
+  "version": "0.37.0",
   "description": "Shared UI kit for Adea: Kobalte/corvu-backed Solid primitives, workspace shells, and theme styles.",
   "keywords": [
     "components",

package/src/components/appearance.ts

@@ -41,6 +41,22 @@ export type SurfacePreference = 'opaque' | 'frosted' | 'translucent'
 export const APPEARANCE_STORAGE_KEY = 'appearance'
 /** The pre-#425 key. Migration reads it and never deletes it. */
 export const LEGACY_THEME_STORAGE_KEY = 'theme'
+/**
+ * Recovery envelope for unread preference documents (Dev Runtime spec,
+ * "Compatibility, migrations, and waivers": a failed migration retains the
+ * original record; it never silently rewrites or deletes the input). A
+ * malformed or future-version document is quarantined here — before any
+ * write can touch the main key — so saving valid preferences later can never
+ * destroy the user's unread data.
+ */
+export const APPEARANCE_RECOVERY_STORAGE_KEY = 'appearance.recovery'
+
+export type AppearanceRecoveryEnvelope = Readonly<{
+  schemaVersion: 1
+  reason: 'corrupt_json' | 'unsupported_record'
+  capturedAt: string
+  raw: string
+}>
 
 export const DARK_QUERY = '(prefers-color-scheme: dark)'
 export const REDUCED_TRANSPARENCY_QUERY = '(prefers-reduced-transparency: reduce)'
@@ -837,10 +853,35 @@ export function migrateLegacyThemeValue(
 
 type AppearanceStorage = Pick<Storage, 'getItem' | 'setItem' | 'removeItem'>
 
+/**
+ * Quarantine an unread raw document into the recovery envelope. Runs at read
+ * time — before any later write can overwrite the main key — and is
+ * idempotent: re-reading the same unread value refreshes the capture without
+ * losing it.
+ */
+function retainRecoveryEnvelope(
+  storage: AppearanceStorage,
+  raw: string,
+  reason: AppearanceRecoveryEnvelope['reason']
+): void {
+  try {
+    const envelope: AppearanceRecoveryEnvelope = {
+      schemaVersion: 1,
+      reason,
+      capturedAt: new Date().toISOString(),
+      raw,
+    }
+    storage.setItem(APPEARANCE_RECOVERY_STORAGE_KEY, JSON.stringify(envelope))
+  } catch {
+    // Quarantine is best-effort; the active preference still fails closed.
+  }
+}
+
 /**
  * Read the appearance preferences: the v2 key first, then the legacy `theme`
- * key, then defaults. Storage failures degrade to defaults like every other
- * blocked-storage consumer.
+ * key, then defaults. A malformed or future-version document is quarantined
+ * into the recovery envelope and the defaults are returned; storage failures
+ * degrade to defaults like every other blocked-storage consumer.
  */
 export function readAppearancePreferences(
   storage: AppearanceStorage | undefined
@@ -853,9 +894,18 @@ export function readAppearancePreferences(
       try {
         parsed = JSON.parse(raw)
       } catch {
+        retainRecoveryEnvelope(storage, raw, 'corrupt_json')
         return defaultAppearancePreferences
       }
-      return normalizeAppearancePreferences(parsed).value
+      const normalized = normalizeAppearancePreferences(parsed)
+      if (normalized.retainedRaw !== undefined) {
+        retainRecoveryEnvelope(
+          storage,
+          raw,
+          typeof parsed === 'object' && parsed !== null ? 'unsupported_record' : 'corrupt_json'
+        )
+      }
+      return normalized.value
     }
     return (
       migrateLegacyThemeValue(storage.getItem(LEGACY_THEME_STORAGE_KEY)) ??

package/src/styles/dev-view.css

@@ -791,3 +791,98 @@
     transition: none;
   }
 }
+
+/* Session deep-link recovery: a visible, announced banner above the body. */
+.dev-recovery-banner {
+  margin: 0;
+  padding: 0.5rem 1.25rem;
+  border-block-end: 1px solid var(--dev-border);
+  color: var(--dev-muted);
+  font-size: 0.8125rem;
+  background: var(--dev-surface-muted, transparent);
+}
+
+/* Provider-backed archive shelf content. */
+.dev-archive-shelf__content {
+  max-block-size: 14rem;
+  overflow-y: auto;
+  border-block-start: 1px solid var(--dev-border);
+  padding-block-end: 0.5rem;
+}
+
+.dev-archive-shelf__list {
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+.dev-archive-shelf__item {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  padding: 0.35rem 0.75rem;
+  font-size: 0.8125rem;
+}
+
+.dev-archive-shelf__item .dev-tree-row__title {
+  min-width: 0;
+  flex: 1;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.dev-archive-shelf__actions {
+  display: flex;
+  align-items: center;
+  gap: 0.25rem;
+  flex: none;
+}
+
+.dev-archive-shelf__confirm {
+  display: flex;
+  align-items: center;
+  gap: 0.375rem;
+  font-size: 0.75rem;
+  color: var(--dev-muted);
+}
+
+.dev-archive-action {
+  border: 1px solid var(--dev-border);
+  border-radius: 0.375rem;
+  background: transparent;
+  color: inherit;
+  padding: 0.125rem 0.5rem;
+  font-size: 0.75rem;
+  cursor: pointer;
+}
+
+.dev-archive-action:hover {
+  background: color-mix(in srgb, var(--foreground) 8%, transparent);
+}
+
+.dev-archive-action--destructive {
+  color: var(--destructive);
+  border-color: color-mix(in srgb, var(--destructive) 40%, transparent);
+}
+
+.dev-archive-shelf__handoff {
+  margin: 0;
+  padding: 0.5rem 0.75rem;
+  font-size: 0.75rem;
+  line-height: 1.45;
+  color: var(--dev-muted);
+  border-block-start: 1px solid var(--dev-border);
+}
+
+/* Truthful per-pane provider states inside the utility slots. */
+.dev-pane-state {
+  padding: 0.75rem 0.875rem;
+}
+
+.dev-pane-state__line {
+  margin: 0;
+  font-size: 0.8125rem;
+  line-height: 1.5;
+  color: var(--dev-muted);
+}