@flamingo-stack/openframe-frontend-core 0.0.583 → 0.0.584-1967.5424.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flamingo-stack/openframe-frontend-core",
-  "version": "0.0.583",
+  "version": "0.0.584-1967.5424.1",
   "description": "Shared design system and components for all Flamingo platforms",
   "type": "module",
   "main": "./dist/index.js",

package/src/utils/__tests__/dismiss-cookie.test.ts

@@ -0,0 +1,133 @@
+/**
+ * Tier selection on both sides of the cookie-averse split, plus the match rule
+ * the two tiers feed.
+ *
+ * `document.URL` is stubbed rather than the document navigated: jsdom will not
+ * take a `tauri://` document URL, and the scheme is the only input the tier
+ * choice reads — so the stub sits exactly at the seam production reads.
+ *
+ * The round-trips run against the real stores rather than spies: reading a
+ * value back is the only proof a write actually stuck, which is the whole
+ * subject of this file.
+ */
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { clearDismissCookie, isDismissedCookieValue, readDismissCookie, writeDismissCookie } from '../dismiss-cookie';
+
+const KEY = 'openframe-walkthrough-video-dismissed';
+const nativeUrlDescriptor = Object.getOwnPropertyDescriptor(Document.prototype, 'URL');
+
+function setDocumentUrl(url: string): void {
+  Object.defineProperty(document, 'URL', { value: url, writable: true, configurable: true });
+}
+
+afterEach(() => {
+  // Restore the native accessor rather than re-stubbing a hardcoded URL, which
+  // would silently diverge from jsdom's own document URL if the vitest
+  // environment is ever given an explicit one.
+  if (nativeUrlDescriptor) Object.defineProperty(document, 'URL', nativeUrlDescriptor);
+  clearDismissCookie(KEY);
+});
+
+describe('dismissal on an http(s) origin', () => {
+  beforeEach(() => setDocumentUrl('https://openframe.ai/dashboard'));
+
+  it('round-trips through the cookie', () => {
+    writeDismissCookie(KEY, 'video-7');
+    expect(document.cookie).toContain(`${KEY}=video-7`);
+    expect(readDismissCookie(KEY)).toBe('video-7');
+  });
+
+  it('takes the cookie tier on plain http too', () => {
+    // Dev runs on `http://localhost`. Were only `https:` accepted, it would
+    // silently drop to the fallback tier, where SSR cannot see the dismissal.
+    setDocumentUrl('http://localhost:3000/dashboard');
+    writeDismissCookie(KEY, 'video-7');
+    expect(document.cookie).toContain(`${KEY}=video-7`);
+  });
+
+  it('leaves the fallback tier untouched', () => {
+    // Pins fallback-not-mirror; see `fallbackStore`.
+    writeDismissCookie(KEY, 'video-7');
+    expect(window.localStorage.getItem(KEY)).toBeNull();
+  });
+
+  it('fails open on a malformed cookie value', () => {
+    // `decodeURIComponent` throws `URIError` on bad percent-encoding; the other
+    // half of the guarantee `readDismissCookie` documents.
+    document.cookie = `${KEY}=%E0%A4%A; path=/`;
+    expect(readDismissCookie(KEY)).toBeUndefined();
+  });
+
+  it('clears the cookie tier', () => {
+    writeDismissCookie(KEY, 'video-7');
+    clearDismissCookie(KEY);
+    expect(document.cookie).not.toContain(KEY);
+    expect(readDismissCookie(KEY)).toBeUndefined();
+  });
+});
+
+describe('dismissal on a cookie-averse origin (tauri://, capacitor://)', () => {
+  beforeEach(() => setDocumentUrl('tauri://localhost/index.html'));
+
+  it('writes no cookie', () => {
+    writeDismissCookie(KEY, 'video-7');
+    expect(document.cookie).not.toContain(KEY);
+  });
+
+  it('persists through localStorage and keeps the id-match rule', () => {
+    writeDismissCookie(KEY, 'video-7');
+    // jsdom keys its cookie jar off the REAL document URL, not the stub above,
+    // so a cookie-only implementation's write would still land here and serve
+    // the reads below. Emptying the jar first is what makes them prove the
+    // value came from the fallback tier; the assertion confirms the wipe took,
+    // since a path or domain mismatch would leave the cookie in place and
+    // hollow out both reads.
+    document.cookie = `${KEY}=; path=/; max-age=0`;
+    expect(document.cookie).not.toContain(KEY);
+
+    // The positive half is the discriminator — asserting only the `video-8`
+    // false would also pass against a fallback tier that stored nothing.
+    expect(isDismissedCookieValue(readDismissCookie(KEY), 'video-7')).toBe(true);
+    expect(isDismissedCookieValue(readDismissCookie(KEY), 'video-8')).toBe(false);
+  });
+
+  it('fails open on a corrupted stored value', () => {
+    // Seeded through the real writer first, so this also pins the fallback key
+    // to the cookie name: read a different key and the pre-corruption value
+    // would still come back.
+    writeDismissCookie(KEY, 'video-7');
+    window.localStorage.setItem(KEY, 'not-json');
+    // Callers reveal the surface off this read, so an unreadable value must
+    // mean "not dismissed" rather than throwing and hiding it permanently.
+    expect(readDismissCookie(KEY)).toBeUndefined();
+
+    // Parses, but is not the string the tier stores — what `validate` is for.
+    window.localStorage.setItem(KEY, '123');
+    expect(readDismissCookie(KEY)).toBeUndefined();
+  });
+});
+
+describe('the match rule itself', () => {
+  it('treats "nothing stored, nothing active" as NOT dismissed', () => {
+    // Both sides undefined is the case the `!!id` guard exists for: a bare
+    // equality would call it dismissed and suppress a surface that has no
+    // active item to be dismissed against.
+    expect(isDismissedCookieValue(undefined, undefined)).toBe(false);
+  });
+});
+
+describe('clearing across the tier split', () => {
+  it('clears the tier the current scheme does NOT select', () => {
+    // Written on the fallback tier, cleared from a document on the cookie tier
+    // — the case a same-origin `blob:`/`about:blank` child produces, and the
+    // one a tier-checking clear would leave stranded.
+    setDocumentUrl('tauri://localhost/index.html');
+    writeDismissCookie(KEY, 'video-7');
+
+    setDocumentUrl('https://openframe.ai/dashboard');
+    clearDismissCookie(KEY);
+
+    setDocumentUrl('tauri://localhost/index.html');
+    expect(readDismissCookie(KEY)).toBeUndefined();
+  });
+});

package/src/utils/announcement-storage.ts

@@ -1,18 +1,24 @@
 /**
  * Announcement dismissal store.
  *
- * The dismissal COOKIE is the single source of truth: the hub's root layout
- * reads it server-side to decide whether to SSR-seed the bar (no flash for
- * dismissed users), and the client reads it via `isAnnouncementDismissed`.
- * One cookie per platform holding the LAST dismissed announcement id —
- * dismissal is an id-match, never mere cookie presence, so a new announcement
- * always shows after an old one was dismissed, and re-activating an old
- * announcement intentionally re-shows it.
+ * The dismissal COOKIE is the source of truth wherever cookies work: the hub's
+ * root layout reads it server-side to decide whether to SSR-seed the bar (no
+ * flash for dismissed users), and the client reads it via
+ * `isAnnouncementDismissed`. One cookie per platform holding the LAST dismissed
+ * announcement id — dismissal is an id-match, never mere cookie presence, so a
+ * new announcement always shows after an old one was dismissed, and
+ * re-activating an old announcement intentionally re-shows it.
+ *
+ * On a cookie-averse document (see `utils/dismiss-cookie.ts`) the primitive
+ * writes `<platform>-announcement-dismissed` to localStorage instead. Do not
+ * mistake it for the legacy key below and delete the write: it is the ONLY
+ * thing making a dismissal persist in a shell. `clearAnnouncementDismissals`' prefix sweep does match it, which
+ * is right — a full reset should take both.
  *
  * The legacy per-id localStorage key (`<platform>-announcement-<id>-dismissed`)
  * is READ-ONLY legacy: consulted only when no cookie exists for the platform,
  * purely as the migration trigger (the bar's mount effect backfills the
- * cookie). New dismissals write the cookie only, so the second store dies out.
+ * cookie). Nothing writes it any more, so that store dies out.
  *
  * No `"use client"` directive on purpose — `announcementDismissCookieName` and
  * `isDismissedCookieValue` are pure/isomorphic and imported by the hub's
@@ -36,18 +42,21 @@ export { isDismissedCookieValue } from './dismiss-cookie';
 
 const legacyDismissKey = (platform: string, id: string) => `${platform}-announcement-${id}-dismissed`;
 
-/** Persist a dismissal: cookie only (1 year). The SSR layout sees it on the
- *  next request; localStorage is intentionally NOT written (read-only legacy). */
+/** Persist a dismissal (1 year). The SSR layout sees it on the next request —
+ *  except in a native shell, where the primitive falls back to localStorage and
+ *  there is no SSR layout to see it anyway. The LEGACY per-id key is still never
+ *  written. */
 export function dismissAnnouncement(platform: string, id: string): void {
   if (typeof document === 'undefined') return;
   writeDismissCookie(announcementDismissCookieName(platform), id);
 }
 
 /**
- * Client-side dismissal check — cookie-first: the legacy localStorage key is
- * consulted ONLY when no cookie exists for the platform. Reads browser
- * storage, so callers must invoke it from effects, never during render
- * (a render-time read would desync hydration from the SSR HTML).
+ * Client-side dismissal check — primary store first, with the legacy
+ * localStorage key consulted ONLY when that comes back empty. Reads browser
+ * storage, so callers must invoke it
+ * from effects, never during render (a render-time read would desync hydration
+ * from the SSR HTML).
  */
 export function isAnnouncementDismissed(platform: string, id: string): boolean {
   if (typeof document === 'undefined') return false;
@@ -60,8 +69,8 @@ export function isAnnouncementDismissed(platform: string, id: string): boolean {
   }
 }
 
-/** Remove ALL dismissal state for a platform (cookie + legacy localStorage
- *  keys) — test/story helper so callers never restate the key encoding. */
+/** Remove ALL dismissal state for a platform — test/story helper so callers
+ *  never restate the key encoding. The header owns the tier inventory. */
 export function clearAnnouncementDismissals(platform: string): void {
   if (typeof document === 'undefined') return;
   clearDismissCookie(announcementDismissCookieName(platform));

package/src/utils/dismiss-cookie.ts

@@ -3,31 +3,92 @@
  * dismissed", shared by every dismissible surface (announcement bar, floating
  * walkthrough video, and anything added later).
  *
- * The dismissal rule is an ID MATCH, never mere cookie presence: the cookie
- * stores the id of the LAST dismissed item, so publishing a NEW item re-shows
+ * The dismissal rule is an ID MATCH, never mere cookie presence: the store
+ * holds the id of the LAST dismissed item, so publishing a NEW item re-shows
  * the surface while the old dismissal still suppresses the old item.
  *
+ * TWO TIERS. The cookie is primary wherever cookies work; on a cookie-averse
+ * document `localStorage` takes over under the same key. See `canUseCookies`
+ * for when that is, and `fallbackStore` for why it is a fallback and not a
+ * mirror.
+ *
  * No `"use client"` on purpose — `isDismissedCookieValue` is pure and is used by
  * server code (the hub's root layout reads the cookie during SSR to avoid a
  * flash); the DOM-touching helpers guard on `typeof document`.
  */
 
-/** One year, the standard dismissal horizon for these surfaces. */
+import { createLocalStorageAdapter } from './local-storage-adapter';
+
+/** One year — the COOKIE tier's horizon. The fallback tier has no expiry, so a
+ *  dismissal in a native shell is permanent; adding an expiry envelope there
+ *  would be inventing a second encoding to answer a question nobody has asked. */
 const DISMISS_COOKIE_MAX_AGE_SECONDS = 31_536_000;
 
+/**
+ * Whether `document.cookie` actually stores anything here.
+ *
+ * A Document whose URL scheme is not http(s) is COOKIE-AVERSE — the HTML spec's
+ * term for one where the `document.cookie` setter is a silent no-op and the
+ * getter returns ''. That is where the custom-scheme shells run: Tauri serves
+ * the bundle from `tauri://localhost` on macOS/Linux, Capacitor from
+ * `capacitor://localhost` on iOS. Every dismissal there was dropped on write
+ * and unreadable on the next mount, so the surface came back in every new
+ * window and on every launch. Tauri on Windows and Capacitor on Android serve
+ * http(s), were never affected, and stay on the cookie tier.
+ *
+ * The scheme is read directly rather than probed with a throwaway write: a lib
+ * whose consumers are consent-regulated marketing sites should not set a
+ * cookie, however briefly, to answer a question the URL already answers.
+ * Deliberately NOT covered: cookies blocked by user or enterprise policy on an
+ * http(s) origin — the surface reappears there exactly as it always has, which
+ * is what someone who blocked cookies asked for.
+ *
+ * Read off `document.URL`, not `window.location`: averseness is a property of
+ * the DOCUMENT's URL, and this file must stay usable wherever `document` is the
+ * only thing the other helpers here already require. `about:blank` and
+ * `about:srcdoc` are the one miss: they carry their creator's origin and are
+ * served its cookies, yet land on the fallback tier here. Accepted — nothing
+ * hosts this lib in one, and the cost is a re-show, not a broken surface.
+ */
+function canUseCookies(): boolean {
+  if (typeof document === 'undefined') return false;
+  return document.URL.startsWith('http:') || document.URL.startsWith('https:');
+}
+
+/**
+ * The fallback tier for cookie-averse documents, keyed identically to the
+ * cookie so a host needs no second key.
+ *
+ * A FALLBACK, never a mirror: cookies stay primary wherever they work, because
+ * they are the only tier a server can read — which is what lets the hub
+ * suppress a dismissed surface during SSR instead of flashing it — and writing
+ * both would mean clearing cookies no longer clears a dismissal.
+ */
+function fallbackStore(name: string) {
+  return createLocalStorageAdapter<string>({
+    key: name,
+    logTag: '[dismiss-cookie]',
+    validate: (parsed): parsed is string => typeof parsed === 'string',
+  });
+}
+
 /** THE dismissal match rule. `undefined` id (nothing active) → not dismissed. */
 export function isDismissedCookieValue(cookieValue: string | undefined, id: string | undefined): boolean {
   return !!id && cookieValue === id;
 }
 
 /**
- * Read a dismissal cookie. Returns `undefined` when absent OR malformed:
- * `decodeURIComponent` throws `URIError` on bad percent-encoding, and callers
- * run this inside reveal paths where an uncaught throw would hide the surface
- * permanently. Failing open (treated as not-dismissed) is always the safe side.
+ * Read a dismissal. Returns `undefined` when absent OR unreadable — one
+ * guarantee with two causes: a cookie with bad percent-encoding, where
+ * `decodeURIComponent` throws `URIError`, and a fallback value that is not the
+ * JSON string it should be, where the adapter swallows the parse failure.
+ * Callers run this inside reveal paths where an uncaught throw would hide the
+ * surface permanently, so failing open — treated as not-dismissed — is always
+ * the safe side.
  */
 export function readDismissCookie(name: string): string | undefined {
   if (typeof document === 'undefined') return undefined;
+  if (!canUseCookies()) return fallbackStore(name).load() ?? undefined;
   const match = document.cookie.split('; ').find(row => row.startsWith(`${name}=`));
   if (!match) return undefined;
   try {
@@ -37,14 +98,30 @@ export function readDismissCookie(name: string): string | undefined {
   }
 }
 
-/** Persist a dismissal (cookie only, 1 year). */
+/** Persist a dismissal. */
 export function writeDismissCookie(name: string, id: string): void {
   if (typeof document === 'undefined') return;
+  if (!canUseCookies()) {
+    fallbackStore(name).save(id);
+    return;
+  }
   document.cookie = `${name}=${encodeURIComponent(id)}; path=/; max-age=${DISMISS_COOKIE_MAX_AGE_SECONDS}; SameSite=Lax`;
 }
 
-/** Clear a dismissal (test/story helper). */
+/**
+ * Clear a dismissal (test/story helper).
+ *
+ * BOTH tiers, unconditionally — the tier check governs writes, not removal.
+ * Clearing writes nothing and cannot resurrect a dismissal, so it carries none
+ * of the reasons the write path commits to one tier, and a clear that leaves
+ * the other tier holding a value is a lie.
+ *
+ * NOT for a shell that changes the scheme it serves under: that is an origin
+ * change, so the old tier moves to a storage bucket no code in the new origin
+ * can reach — `clear` included.
+ */
 export function clearDismissCookie(name: string): void {
   if (typeof document === 'undefined') return;
+  fallbackStore(name).clear();
   document.cookie = `${name}=; path=/; max-age=0`;
 }

package/src/utils/dismissal-storage.ts

@@ -22,8 +22,8 @@ export function walkthroughDismissCookieName(platform: string): string {
   return `${platform}-${WALKTHROUGH_VIDEO_DISMISS_KEY}`;
 }
 
-/** Client-side dismissal check (id-match). Reads a cookie, so call it from an
- *  effect, never during render. */
+/** Client-side dismissal check (id-match). Reads browser storage, so call it
+ *  from an effect, never during render. */
 export function isWalkthroughDismissed(key: string, id: string | undefined): boolean {
   return isDismissedCookieValue(readDismissCookie(key), id);
 }