@gjsify/adwaita-web 0.52.0 → 0.53.0

package/lib/types/accent.d.ts

@@ -22,7 +22,17 @@ export interface ApplyAccentOptions {
  * `prefers-color-scheme` only decides when neither is present.
  */
 export declare function isAdwaitaDark(element: HTMLElement): boolean;
-/** Set the accent custom properties for `name`. */
+/** Whether the app has chosen `target`'s accent with {@link applyAdwaitaAccent}. */
+export declare function hasAppChosenAccent(target: HTMLElement): boolean;
+/** Write the two properties — the one place they are set, for the app's choice and the follower's alike. */
+export declare function writeAdwaitaAccent(name: AdwAccentColorName, target: HTMLElement, dark: boolean): void;
+/**
+ * Set the accent custom properties for `name` — the app's own choice, which
+ * from now on wins over the desktop's appearance on this element.
+ */
 export declare function applyAdwaitaAccent(name: AdwAccentColorName, options?: ApplyAccentOptions): void;
-/** Drop the properties, so the stylesheet's own values apply again. */
+/**
+ * Drop the properties, so the stylesheet's own values apply again, and hand
+ * the element back to the desktop's appearance.
+ */
 export declare function clearAdwaitaAccent(target?: HTMLElement): void;

package/lib/types/adw-appearance.spec.d.ts

@@ -0,0 +1,2 @@
+import '@gjsify/adwaita-web';
+export declare const AdwAppearanceTest: () => Promise<void>;

package/lib/types/appearance.d.ts

@@ -0,0 +1,41 @@
+import { type AdwAccentColorName } from '@gjsify/adwaita-core';
+/** Which source the root's accent currently comes from. */
+export type AdwAccentSource = 'app' | 'handoff' | 'system' | 'default';
+/**
+ * The browser's CSS system colour `AccentColor`, snapped to the nearest of the
+ * nine — or `null` where the engine does not support the keyword or the
+ * resolved colour cannot be read.
+ *
+ * SUPPORT IS UNEVEN AND NOT ASSUMED: Chrome announced shipping `AccentColor`
+ * only in 2026, and what Firefox resolves it to on Linux is not established;
+ * Firefox 156 on macOS resolves it to `rgb(0, 122, 255)`. An engine may also
+ * report a fixed default instead of the real accent (fingerprinting
+ * protection), which a page cannot detect.
+ */
+export declare function readSystemAccent(): {
+    accent: AdwAccentColorName;
+    accentRgb: string;
+} | null;
+/** The source the root's accent comes from right now. */
+export declare function adwaitaAccentSource(): AdwAccentSource;
+/**
+ * Start following: read the handoff tags, and re-apply when they change, when
+ * the colour scheme flips (the standalone accent differs between light and
+ * dark) and when the page regains focus (`AccentColor` changes with no event).
+ * Idempotent; `@gjsify/adwaita-web` calls it on import in a browser.
+ */
+export declare function followDesktopAppearance(): void;
+/**
+ * Follow the CSS system colour `AccentColor` (#1821); `false` stops following
+ * it. A server handoff and the app's own choice still win; where the engine
+ * cannot resolve `AccentColor` the page keeps Adwaita blue. Returns the accent
+ * the system colour snapped to, or `null` (always when disabling).
+ */
+export declare function applySystemAccent(enabled?: boolean): AdwAccentColorName | null;
+/**
+ * Apply a desktop appearance handed over at runtime — the JSON a gjsify server
+ * sends when the desktop changes (over SSE, a WebSocket, a message port). The
+ * value is validated, so an untrusted payload is safe to pass straight in; it
+ * REPLACES the previous handoff, including one from the `<meta>` tags.
+ */
+export declare function applyDesktopAppearance(appearance: unknown): void;

package/lib/types/font-stack.spec.d.ts

@@ -0,0 +1,2 @@
+import '@gjsify/adwaita-web';
+export declare const AdwFontStackTest: () => Promise<void>;

package/lib/types/index.d.ts

@@ -1,6 +1,8 @@
 export { addBreakpoints, bindBreakpointSetter } from './breakpoints.js';
 export { ACCENT_BG_PROPERTY, ACCENT_PROPERTY, applyAdwaitaAccent, clearAdwaitaAccent, isAdwaitaDark, } from './accent.js';
 export type { ApplyAccentOptions } from './accent.js';
+export { adwaitaAccentSource, applyDesktopAppearance, applySystemAccent, followDesktopAppearance, readSystemAccent, } from './appearance.js';
+export type { AdwAccentSource } from './appearance.js';
 export { AdwScrollShading } from './scroll-shading.js';
 export type { AdwUndershootEdges } from './scroll-shading.js';
 export { buildSharedTree, mountSharedTree } from './shared-tree-builder.js';