@elizaos/ui 2.0.3-beta.2 → 2.0.3-beta.3

package/state/persistence.js

@@ -6,6 +6,7 @@ import { DEFAULT_UI_LANGUAGE, normalizeLanguage, } from "../i18n/index.js";
 import { detectClientLanguage } from "../i18n/region.js";
 import { normalizeDirectCloudSharedAgentApiBase } from "../utils/cloud-agent-base.js";
 import { DEFAULT_LOCAL_ASR_AUTO_STOP } from "../voice/local-asr-capture.js";
+import { DEFAULT_BACKGROUND_COLOR, DEFAULT_BACKGROUND_CONFIG, } from "./ui-preferences.js";
 import { normalizeAvatarIndex } from "./vrm.js";
 /* ── Shared localStorage helper ──────────────────────────────────────── */
 function tryLocalStorage(fn, fallback) {
@@ -34,14 +35,20 @@ export { normalizeUiThemeMode };
  * keep their shape.
  */
 export function getSystemTheme() {
+    if (typeof window !== "undefined" &&
+        typeof window.matchMedia === "function") {
+        return window.matchMedia("(prefers-color-scheme: dark)").matches
+            ? "dark"
+            : "light";
+    }
     return "light";
 }
 /**
- * Resolve a {@link UiThemeMode} to a concrete {@link UiTheme}. The app is
- * light-only, so every mode resolves to `light`.
+ * Resolve a {@link UiThemeMode} to a concrete {@link UiTheme}: an explicit
+ * `light`/`dark` choice wins; `system` follows the OS color-scheme.
  */
-export function resolveUiTheme(_mode) {
-    return "light";
+export function resolveUiTheme(mode) {
+    return mode === "system" ? getSystemTheme() : mode;
 }
 /**
  * Load the persisted theme mode. New users (no stored value) default to
@@ -98,6 +105,66 @@ export function saveUiTheme(theme) {
         localStorage.setItem(LEGACY_UI_THEME_STORAGE_KEY, normalized);
     }, undefined);
 }
+/* ── Background persistence ───────────────────────────────────────────── */
+const UI_BACKGROUND_STORAGE_KEY = "eliza:ui-background";
+/** Accept a 6-digit hex color; anything else falls back to the default. */
+function normalizeHexColor(value) {
+    return typeof value === "string" && /^#[0-9a-fA-F]{6}$/.test(value)
+        ? value.toLowerCase()
+        : DEFAULT_BACKGROUND_COLOR;
+}
+export function normalizeBackgroundConfig(value) {
+    const record = asRecord(value);
+    if (!record)
+        return { ...DEFAULT_BACKGROUND_CONFIG };
+    const color = normalizeHexColor(record.color);
+    const imageUrl = typeof record.imageUrl === "string" && record.imageUrl.length > 0
+        ? record.imageUrl
+        : undefined;
+    // Image mode without a usable source is meaningless — fall back to the shader.
+    if (record.mode === "image" && imageUrl) {
+        return { mode: "image", color, imageUrl };
+    }
+    return { mode: "shader", color };
+}
+export function loadBackgroundConfig() {
+    return tryLocalStorage(() => {
+        const raw = localStorage.getItem(UI_BACKGROUND_STORAGE_KEY);
+        return raw
+            ? normalizeBackgroundConfig(JSON.parse(raw))
+            : { ...DEFAULT_BACKGROUND_CONFIG };
+    }, { ...DEFAULT_BACKGROUND_CONFIG });
+}
+export function saveBackgroundConfig(config) {
+    tryLocalStorage(() => {
+        localStorage.setItem(UI_BACKGROUND_STORAGE_KEY, JSON.stringify(normalizeBackgroundConfig(config)));
+    }, undefined);
+}
+/**
+ * Bounded undo history for the background. The most recent previous config is
+ * last. Capped so a long session never grows localStorage without bound; image
+ * configs carry a data/media URL so the cap is deliberately small.
+ */
+const UI_BACKGROUND_HISTORY_STORAGE_KEY = "eliza:ui-background-history";
+export const MAX_BACKGROUND_HISTORY = 10;
+export function normalizeBackgroundHistory(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value
+        .map((entry) => normalizeBackgroundConfig(entry))
+        .slice(-MAX_BACKGROUND_HISTORY);
+}
+export function loadBackgroundHistory() {
+    return tryLocalStorage(() => {
+        const raw = localStorage.getItem(UI_BACKGROUND_HISTORY_STORAGE_KEY);
+        return raw ? normalizeBackgroundHistory(JSON.parse(raw)) : [];
+    }, []);
+}
+export function saveBackgroundHistory(history) {
+    tryLocalStorage(() => {
+        localStorage.setItem(UI_BACKGROUND_HISTORY_STORAGE_KEY, JSON.stringify(normalizeBackgroundHistory(history)));
+    }, undefined);
+}
 const COMPANION_VRM_POWER_STORAGE_KEY = "eliza:companion-vrm-power";
 /** Legacy; migrated into `eliza:companion-vrm-power` on first read. */
 const LEGACY_COMPANION_EFFICIENCY_KEY = "eliza:companion-efficiency";
@@ -842,3 +909,18 @@ export function clearPersistedActiveServer() {
         localStorage.removeItem(ACTIVE_SERVER_STORAGE_KEY);
     }, undefined);
 }
+/**
+ * Drop the bearer access token from the persisted active server while keeping
+ * the server selection (kind/apiBase/label). Call this on sign-out: the token
+ * is a JWT and leaving it in localStorage after sign-out is an at-rest leak,
+ * but clearing the whole record would needlessly forget which backend to
+ * re-authenticate against.
+ */
+export function scrubPersistedActiveServerToken() {
+    const current = loadPersistedActiveServer();
+    if (!current?.accessToken)
+        return;
+    const scrubbed = { ...current };
+    delete scrubbed.accessToken;
+    savePersistedActiveServer(scrubbed);
+}

package/state/screen-capture-bridge.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Idempotent boot: start the capture-request poller on Android/iOS native.
+ * No-op on web/desktop and on repeat calls.
+ */
+export declare function initScreenCaptureBridge(): void;
+/** Test-only reset hook. */
+export declare function __resetScreenCaptureBridgeForTests(): void;
+//# sourceMappingURL=screen-capture-bridge.d.ts.map

package/state/screen-capture-bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"screen-capture-bridge.d.ts","sourceRoot":"","sources":["../../../../../src/state/screen-capture-bridge.ts"],"names":[],"mappings":"AAuHA;;;GAGG;AACH,wBAAgB,uBAAuB,IAAI,IAAI,CAO9C;AAED,4BAA4B;AAC5B,wBAAgB,kCAAkC,IAAI,IAAI,CAMzD"}

package/state/screen-capture-bridge.js

@@ -0,0 +1,124 @@
+import { Capacitor } from "@capacitor/core";
+import { getScreenCapturePlugin } from "../bridge/native-plugins.js";
+/**
+ * Renderer side of the Android agent-triggered screen-capture bridge (#9105).
+ *
+ * On Android the agent (musl bun) has no Capacitor and there is no
+ * agent->renderer push channel, so capture is renderer-PULLED: this module
+ * interval-polls `GET /api/vision/capture-requests` (routed to the agent by the
+ * installed Android fetch bridge), and for each queued request captures a frame
+ * via the Capacitor ScreenCapture plugin (MediaProjection) and POSTs the PNG
+ * back to `POST /api/vision/screen-frame`. A short interval (not long-poll)
+ * keeps the agent's 30s capture timeout decoupled from the 10s JNI
+ * fetch-timeout.
+ */
+const POLL_INTERVAL_MS = 1500;
+let started = false;
+let pollTimer = null;
+/** Frugal screen-understanding defaults: half-res, q70 → tens of KB per frame. */
+function clampScale(scale) {
+    if (!Number.isFinite(scale))
+        return 0.5;
+    return Math.min(1, Math.max(0.1, scale));
+}
+function clampQuality(quality) {
+    if (!Number.isFinite(quality))
+        return 70;
+    return Math.min(100, Math.max(1, Math.round(quality)));
+}
+function isNativeMobile() {
+    try {
+        const platform = Capacitor.getPlatform();
+        return platform === "android" || platform === "ios";
+    }
+    catch {
+        return false;
+    }
+}
+function isCaptureRequest(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        typeof value.requestId === "string");
+}
+async function postScreenFrame(body) {
+    await fetch("/api/vision/screen-frame", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(body),
+    });
+}
+async function serveRequest(request) {
+    try {
+        // Capture as a scaled JPEG so the resize + encode happen NATIVELY (the
+        // VirtualDisplay renders at the target resolution and Skia compresses) —
+        // the agent never resizes or re-encodes pixels in JS. A ~half-res q70 JPEG
+        // of a phone screen is tens of KB (vs a multi-MB full PNG), which is what
+        // the IMAGE_DESCRIPTION (on-device GPU) describe path wants. Honour an
+        // optional per-request maxScale/quality from the agent, else use frugal
+        // defaults tuned for screen understanding + battery/latency.
+        const scale = clampScale(request.scale ?? 0.5);
+        const quality = clampQuality(request.quality ?? 70);
+        const shot = await getScreenCapturePlugin().captureScreenshot({
+            format: "jpeg",
+            quality,
+            scale,
+        });
+        await postScreenFrame({
+            requestId: request.requestId,
+            base64: shot.base64,
+            format: shot.format,
+            width: shot.width,
+            height: shot.height,
+        });
+    }
+    catch (error) {
+        // Report the failure so the agent's pending request settles immediately
+        // (as null) instead of waiting out its timeout, and so this poller keeps
+        // running for the next request.
+        const reason = error instanceof Error ? error.message : String(error);
+        await postScreenFrame({
+            requestId: request.requestId,
+            error: reason,
+        }).catch(() => { });
+    }
+}
+async function poll() {
+    let requests;
+    try {
+        const res = await fetch("/api/vision/capture-requests");
+        if (!res.ok)
+            return;
+        const data = (await res.json());
+        const list = Array.isArray(data.requests) ? data.requests : [];
+        requests = list.filter(isCaptureRequest);
+    }
+    catch {
+        // Agent not reachable yet (early boot) — next tick retries.
+        return;
+    }
+    for (const request of requests) {
+        await serveRequest(request);
+    }
+}
+/**
+ * Idempotent boot: start the capture-request poller on Android/iOS native.
+ * No-op on web/desktop and on repeat calls.
+ */
+export function initScreenCaptureBridge() {
+    if (started)
+        return;
+    if (!isNativeMobile())
+        return;
+    started = true;
+    pollTimer = setInterval(() => {
+        void poll();
+    }, POLL_INTERVAL_MS);
+}
+/** Test-only reset hook. */
+export function __resetScreenCaptureBridgeForTests() {
+    if (pollTimer) {
+        clearInterval(pollTimer);
+        pollTimer = null;
+    }
+    started = false;
+}

package/state/setup-resume.d.ts

@@ -1,5 +1,5 @@
-import type { BuildFirstRunConnectionArgs } from "../first-run/first-run-config";
-import type { SetupStep } from "./types";
+import type { BuildFirstRunConnectionArgs } from "../first-run/first-run-config.js";
+import type { SetupStep } from "./types.js";
 export declare function hasPartialSetupConnectionConfig(config: Record<string, unknown> | null | undefined): boolean;
 export declare function inferSetupResumeStep(args: {
     config?: Record<string, unknown> | null;

package/state/shell-routing.d.ts

@@ -1,6 +1,6 @@
-import type { Tab } from "../navigation";
-import type { FirstRunMode, ShellView } from "./types";
-import type { UiShellMode } from "./ui-preferences";
+import type { Tab } from "../navigation/index.js";
+import type { FirstRunMode, ShellView } from "./types.js";
+import type { UiShellMode } from "./ui-preferences.js";
 export declare function deriveUiShellModeForTab(tab: Tab): UiShellMode;
 export declare function getTabForShellView(view: ShellView, lastNativeTab: Tab): Tab;
 export declare function shouldStartAtCharacterSelectOnLaunch(_params: {

package/state/shell-surface-store.d.ts

@@ -0,0 +1,50 @@
+import { type HomeSpringboardPage } from "../components/shell/home-springboard-events.js";
+/**
+ * Shell-surface store — the SINGLE source of truth for the home/springboard
+ * launcher's navigation state.
+ *
+ * Before this store there were four uncoordinated navigation state machines
+ * (the route `tab`, HomeSpringboardSurface's local `page`, the Springboard's
+ * local `page` + `editing`, and the chat overlay's `mode`). Because no single
+ * thing owned "which launcher screen am I on", a horizontal swipe was claimed by
+ * two machines, two page-indicators rendered at once, and the springboard's
+ * `editing` flag survived navigation — leaving the user stranded in jiggle mode
+ * with no way back. This store collapses the launcher's navigation (machines 2
+ * and 3) into one model that every surface DERIVES from.
+ *
+ * The non-negotiable invariant lives here, not in a component: leaving the
+ * springboard (page !== "springboard") ALWAYS resets the transient sub-state
+ * (`springboardEditing` → false, `springboardPage` → 0). That makes the
+ * "swipe-back lands in edit mode / re-entering is still jiggling" class of bug
+ * structurally impossible regardless of how the user left the surface.
+ *
+ * Module-level store shared via globalThis (survives HMR + reachable from the
+ * gesture handlers and the chat controller outside any one React subtree) +
+ * useSyncExternalStore, mirroring `view-chat-binding.ts`.
+ */
+export type ShellSurfacePage = HomeSpringboardPage;
+export interface ShellSurfaceState {
+    /** Which half of the launcher rail is showing. */
+    readonly page: ShellSurfacePage;
+    /** Active page index within the springboard's icon grid (0-based). */
+    readonly springboardPage: number;
+    /** Total springboard icon-grid pages, reported by the springboard surface. */
+    readonly springboardPageCount: number;
+    /** Whether the springboard is in edit/jiggle mode. */
+    readonly springboardEditing: boolean;
+}
+export declare function goHome(): void;
+export declare function goSpringboard(): void;
+export declare function setShellSurfacePage(page: ShellSurfacePage): void;
+export declare function setSpringboardPage(index: number): void;
+export declare function setSpringboardPageCount(count: number): void;
+export declare function setSpringboardEditing(editing: boolean): void;
+export declare function enterSpringboardEdit(): void;
+export declare function exitSpringboardEdit(): void;
+export declare function toggleSpringboardEdit(): void;
+/** Read the surface state imperatively (tests / non-React callers). */
+export declare function getShellSurface(): ShellSurfaceState;
+/** Reset to defaults. Test-only — the app never returns to the initial state. */
+export declare function resetShellSurfaceForTests(): void;
+export declare function useShellSurface(): ShellSurfaceState;
+//# sourceMappingURL=shell-surface-store.d.ts.map

package/state/shell-surface-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shell-surface-store.d.ts","sourceRoot":"","sources":["../../../../../src/state/shell-surface-store.ts"],"names":[],"mappings":"AACA,OAAO,EAGL,KAAK,mBAAmB,EACzB,MAAM,6CAA6C,CAAC;AAErD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,MAAM,MAAM,gBAAgB,GAAG,mBAAmB,CAAC;AAEnD,MAAM,WAAW,iBAAiB;IAChC,kDAAkD;IAClD,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAChC,sEAAsE;IACtE,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,8EAA8E;IAC9E,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAC;IACtC,sDAAsD;IACtD,QAAQ,CAAC,kBAAkB,EAAE,OAAO,CAAC;CACtC;AAmGD,wBAAgB,MAAM,IAAI,IAAI,CAE7B;AAED,wBAAgB,aAAa,IAAI,IAAI,CAEpC;AAED,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,gBAAgB,GAAG,IAAI,CAEhE;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAEtD;AAED,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAE3D;AAED,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAE5D;AAED,wBAAgB,oBAAoB,IAAI,IAAI,CAE3C;AAED,wBAAgB,mBAAmB,IAAI,IAAI,CAE1C;AAED,wBAAgB,qBAAqB,IAAI,IAAI,CAG5C;AAED,uEAAuE;AACvE,wBAAgB,eAAe,IAAI,iBAAiB,CAEnD;AAED,iFAAiF;AACjF,wBAAgB,yBAAyB,IAAI,IAAI,CAIhD;AAID,wBAAgB,eAAe,IAAI,iBAAiB,CAUnD"}

package/state/shell-surface-store.js

@@ -0,0 +1,130 @@
+import * as React from "react";
+import { HOME_SPRINGBOARD_NAV_EVENT, } from "../components/shell/home-springboard-events.js";
+const INITIAL_STATE = {
+    page: "home",
+    springboardPage: 0,
+    springboardPageCount: 1,
+    springboardEditing: false,
+};
+/**
+ * Enforce the cross-field invariants on every transition so no caller can
+ * produce an inconsistent surface state:
+ *  - off the springboard ⇒ never editing, always page 0;
+ *  - the active page is always clamped into [0, pageCount).
+ */
+function normalize(next) {
+    const pageCount = Math.max(1, Math.floor(next.springboardPageCount));
+    if (next.page !== "springboard") {
+        return {
+            page: next.page,
+            springboardPage: 0,
+            springboardPageCount: pageCount,
+            springboardEditing: false,
+        };
+    }
+    const springboardPage = Math.min(Math.max(0, Math.floor(next.springboardPage)), pageCount - 1);
+    return {
+        page: "springboard",
+        springboardPage,
+        springboardPageCount: pageCount,
+        springboardEditing: next.springboardEditing,
+    };
+}
+function statesEqual(a, b) {
+    return (a.page === b.page &&
+        a.springboardPage === b.springboardPage &&
+        a.springboardPageCount === b.springboardPageCount &&
+        a.springboardEditing === b.springboardEditing);
+}
+function store() {
+    const g = globalThis;
+    const k = Symbol.for("elizaos.ui.shell-surface-store");
+    const existing = g[k];
+    if (existing) {
+        ensureWindowBridge(existing);
+        return existing;
+    }
+    const created = {
+        state: INITIAL_STATE,
+        listeners: new Set(),
+    };
+    g[k] = created;
+    ensureWindowBridge(created);
+    return created;
+}
+function ensureWindowBridge(s) {
+    // Bridge the legacy `eliza:home-springboard:navigate` window event into the
+    // store so existing dispatchers (useShellController.navigateHome /
+    // navigateToSpringboard) keep driving the same single source of truth. The
+    // store never re-dispatches the event, so there is no feedback loop.
+    if (typeof window !== "undefined") {
+        if (s.bridgedWindow === window)
+            return;
+        window.addEventListener(HOME_SPRINGBOARD_NAV_EVENT, (event) => {
+            const detail = event
+                .detail;
+            commit(s, { ...s.state, page: detail?.page ?? "home" });
+        });
+        s.bridgedWindow = window;
+    }
+}
+function commit(s, next) {
+    const normalized = normalize(next);
+    if (statesEqual(s.state, normalized))
+        return;
+    s.state = normalized;
+    for (const l of s.listeners)
+        l();
+}
+function update(partial) {
+    const s = store();
+    commit(s, { ...s.state, ...partial });
+}
+// ── Imperative actions (callable from gesture handlers + non-React code) ──────
+export function goHome() {
+    update({ page: "home" });
+}
+export function goSpringboard() {
+    update({ page: "springboard" });
+}
+export function setShellSurfacePage(page) {
+    update({ page });
+}
+export function setSpringboardPage(index) {
+    update({ springboardPage: index });
+}
+export function setSpringboardPageCount(count) {
+    update({ springboardPageCount: count });
+}
+export function setSpringboardEditing(editing) {
+    update({ springboardEditing: editing });
+}
+export function enterSpringboardEdit() {
+    update({ springboardEditing: true });
+}
+export function exitSpringboardEdit() {
+    update({ springboardEditing: false });
+}
+export function toggleSpringboardEdit() {
+    const s = store();
+    update({ springboardEditing: !s.state.springboardEditing });
+}
+/** Read the surface state imperatively (tests / non-React callers). */
+export function getShellSurface() {
+    return store().state;
+}
+/** Reset to defaults. Test-only — the app never returns to the initial state. */
+export function resetShellSurfaceForTests() {
+    const s = store();
+    s.state = INITIAL_STATE;
+    for (const l of s.listeners)
+        l();
+}
+// ── React bindings ────────────────────────────────────────────────────────────
+export function useShellSurface() {
+    const s = store();
+    return React.useSyncExternalStore((l) => {
+        s.listeners.add(l);
+        return () => s.listeners.delete(l);
+    }, () => s.state, () => s.state);
+}

package/state/springboard-layout.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Springboard layout — persisted icon arrangement for the iOS-like launcher.
+ *
+ * The catalog renders as a paged home-screen ("springboard"): a fixed dock of
+ * favorites plus one or more swipeable pages of view icons. This module owns the
+ * pure, persisted layout model (which icon sits on which page, in what order,
+ * and which icons are favorited into the dock). The rendering/gesture layer
+ * consumes these helpers; all reconciliation logic lives here so it is unit
+ * testable without a DOM.
+ *
+ * Mirrors the persistence style of `view-recents.ts`.
+ */
+export declare const SPRINGBOARD_STORAGE_KEY = "elizaos.views.springboard";
+/**
+ * Icons per springboard page (4 columns × 5 rows, iOS-like). Now that the top
+ * double safe-area gap is gone and the page indicator clears the chat composer,
+ * a full 5-row page fits a normal phone; smaller phones scroll the grid. The
+ * grid is `overflow-y-auto`, so overflow scrolls rather than clipping.
+ */
+export declare const SPRINGBOARD_PAGE_SIZE = 20;
+/** Maximum icons pinned to the dock (favorites). */
+export declare const SPRINGBOARD_DOCK_LIMIT = 4;
+/**
+ * Default favorites dock for a fresh install (#9144). Capped at
+ * SPRINGBOARD_DOCK_LIMIT. These are stable built-in `system` view ids; any that
+ * are not actually available in the live catalog are dropped during
+ * `reconcileLayout` (favorites ∩ available), so an unknown id never leaves a
+ * hole. Order matches the dock left-to-right. Chat/Home and Springboard are one
+ * combined surface now, so the dock carries destinations from inside the
+ * launcher rather than self-links back to the launcher:
+ *   - settings — universal, stable system view
+ *   - activity — pairs with the default activity surface when present
+ *   - files    — durable user content
+ *   - tasks    — work queue / task surface
+ */
+export declare const DEFAULT_SPRINGBOARD_FAVORITES: readonly string[];
+export interface SpringboardLayout {
+    /** Ordered view ids pinned to the dock. Capped at SPRINGBOARD_DOCK_LIMIT. */
+    favorites: string[];
+    /** Ordered pages; each page is an ordered list of view ids. */
+    pages: string[][];
+    /**
+     * True once the user has manually reordered icons (drag). Until then the
+     * springboard follows the incoming catalog order, so sort-mode changes and
+     * newly-installed views reflow naturally; after a manual drag the user's
+     * arrangement is preserved.
+     */
+    manual?: boolean;
+}
+export declare function emptyLayout(): SpringboardLayout;
+/**
+ * First-run layout — seeds the default favorites dock (#9144) so the dock is
+ * never empty on a fresh install. Unknown default ids are dropped during
+ * `reconcileLayout`. Returns a fresh array so callers can't mutate the constant.
+ */
+export declare function defaultLayout(): SpringboardLayout;
+export declare function readSpringboardLayout(): SpringboardLayout;
+export declare function writeSpringboardLayout(layout: SpringboardLayout): void;
+/** All view ids currently placed somewhere in the layout (dock + pages). */
+export declare function placedIds(layout: SpringboardLayout): Set<string>;
+/**
+ * Reconcile a stored layout against the live set of available view ids:
+ * - drop ids that no longer exist (uninstalled / hidden views),
+ * - append newly-available ids (preserving their catalog order) to the end,
+ * - keep dock favorites out of the page grid (the dock is a separate surface),
+ * - repack pages to SPRINGBOARD_PAGE_SIZE so removals never leave holes.
+ *
+ * Deterministic and pure — safe to run on every render.
+ */
+export declare function reconcileLayout(layout: SpringboardLayout, availableIds: string[], pageSize?: number): SpringboardLayout;
+/** Toggle an id in/out of the dock. Adding evicts the oldest when full. */
+export declare function toggleFavorite(layout: SpringboardLayout, id: string): SpringboardLayout;
+/**
+ * Move an icon to a target page at a target index, repacking the flattened
+ * page order so the move never leaves holes or duplicates. The id is removed
+ * from the dock if it was a favorite (an icon lives in exactly one surface).
+ *
+ * NOTE: cross-page moves (`targetPage > 0`) are fully supported by this model,
+ * but the Springboard's current drag gesture is `axis="y"` within the active
+ * page only — so cross-page reorder is exercised by tests and available to
+ * callers, not by a user gesture today. Do not build cross-page drag UI unless
+ * product asks; this capability exists so paging stays correct under repack.
+ */
+export declare function moveIcon(layout: SpringboardLayout, id: string, targetPage: number, targetIndex: number, pageSize?: number): SpringboardLayout;
+//# sourceMappingURL=springboard-layout.d.ts.map

package/state/springboard-layout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"springboard-layout.d.ts","sourceRoot":"","sources":["../../../../../src/state/springboard-layout.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,eAAO,MAAM,uBAAuB,8BAA8B,CAAC;AAEnE;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,KAAK,CAAC;AACxC,oDAAoD;AACpD,eAAO,MAAM,sBAAsB,IAAI,CAAC;AAExC;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,6BAA6B,EAAE,SAAS,MAAM,EAK1D,CAAC;AAEF,MAAM,WAAW,iBAAiB;IAChC,6EAA6E;IAC7E,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,+DAA+D;IAC/D,KAAK,EAAE,MAAM,EAAE,EAAE,CAAC;IAClB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,wBAAgB,WAAW,IAAI,iBAAiB,CAE/C;AAED;;;;GAIG;AACH,wBAAgB,aAAa,IAAI,iBAAiB,CAEjD;AAQD,wBAAgB,qBAAqB,IAAI,iBAAiB,CAqBzD;AAED,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,iBAAiB,GAAG,IAAI,CAUtE;AAED,4EAA4E;AAC5E,wBAAgB,SAAS,CAAC,MAAM,EAAE,iBAAiB,GAAG,GAAG,CAAC,MAAM,CAAC,CAMhE;AAWD;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,iBAAiB,EACzB,YAAY,EAAE,MAAM,EAAE,EACtB,QAAQ,GAAE,MAA8B,GACvC,iBAAiB,CAkCnB;AAED,2EAA2E;AAC3E,wBAAgB,cAAc,CAC5B,MAAM,EAAE,iBAAiB,EACzB,EAAE,EAAE,MAAM,GACT,iBAAiB,CAMnB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,QAAQ,CACtB,MAAM,EAAE,iBAAiB,EACzB,EAAE,EAAE,MAAM,EACV,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,EACnB,QAAQ,GAAE,MAA8B,GACvC,iBAAiB,CAUnB"}