@monkey-mini-app/panel 0.1.0 → 0.1.4

package/dist/index.d.cts

@@ -1,5 +1,5 @@
 import { TokenSet } from './themes.cjs';
-export { CustomPaletteMap, ModeId, PALETTES, PaletteId, applyThemeTo, clampMode, clampPalette, cssVars, parseThemeCss, runnerThemeCss, themeLabelFromCss, tokensOf } from './themes.cjs';
+export { CustomPaletteMap, GLOBAL_PALETTE_ID, LOCAL_PALETTE_ID, ModeId, PALETTES, PaletteId, applyThemeTo, clampMode, clampPalette, cssVars, effectivePalette, parseThemeCss, resolveMode, runnerThemeCss, selectedPalette, themeCssVars, themeLabelFromCss, tokensOf } from './themes.cjs';
 import * as react from 'react';
 
 declare const LOCALE_IDS: readonly ["zh-CN", "en"];
@@ -15,6 +15,15 @@ type AppItem = {
         theme: string;
         palette: string;
     } | null;
+    /** Parsed from the app's `theme.css` when present. */
+    localPalette?: {
+        label: string;
+        swatch: string;
+        tokens: {
+            light: TokenSet;
+            dark: TokenSet;
+        };
+    } | null;
 };
 type TabKind = "all" | "app";
 type TabItem = {
@@ -27,6 +36,25 @@ type BrowseKind = "history" | "storage";
 type ThemeScope = "global" | "app";
 type DockId = "fill" | "side";
 type CardStyle = "stamp" | "etch" | "hero" | "list";
+type AboutPackage = {
+    name: string;
+    version: string;
+};
+type AboutInfo = {
+    adapter: string;
+    env: string;
+    packages: AboutPackage[];
+};
+type UpdateCheck = {
+    name: string;
+    current: string;
+    latest: string | null;
+    updateAvailable: boolean;
+    error?: string;
+};
+type UpdateCheckState = UpdateCheck & {
+    status: "idle" | "loading" | "done";
+};
 type CommitFile = {
     path: string;
     add?: number;
@@ -43,6 +71,22 @@ type StorageTable = {
     name: string;
     size?: number;
     updatedAt?: string;
+    /** Top-level key count when the host knows. */
+    keys?: number;
+};
+/** Soft notice when a table crossed a size band — banner + copy-paste AI prompt. */
+type StorageNotice = {
+    appId: string;
+    table: string;
+    bytes: number;
+    keys: number;
+    heavy: Array<{
+        key: string;
+        bytes: number;
+        kind: "list" | "map" | "value";
+        entries?: number;
+    }>;
+    prompt: string;
 };
 type PanelCapabilities = {
     history: boolean;
@@ -69,11 +113,14 @@ type PanelActions = {
     toggleSettings: (open: boolean) => void;
     getCfg: () => Record<string, string>;
     saveHostConfig: (form: Record<string, string>) => void;
+    checkUpdates: () => void;
     toggleBrowse: (kind: string) => void;
     loadCommitDetail: (id: string) => void;
     loadTable: (name: string) => void;
     browseBack: () => void;
     browseFile: (path: string) => void;
+    dismissStorageNotice: () => void;
+    applyStorageNotice: (notice: StorageNotice) => void;
     reloadActive: () => void;
     askDelete: () => void;
     hideModal: () => void;
@@ -106,6 +153,8 @@ type PanelState = {
     cfgMsg: string;
     cfgVersion: number;
     cfg: Record<string, string>;
+    about: AboutInfo | null;
+    updateCheck: UpdateCheckState | null;
     emptyText: string | undefined;
     capabilities: PanelCapabilities;
     locale: LocaleId;
@@ -120,6 +169,8 @@ type PanelState = {
     browseTable: string | null;
     browseTableValue: unknown;
     browseOpenFile: string | null;
+    /** Latest storage-size notice for the active app; banner is dismissible. */
+    storageNotice: StorageNotice | null;
 };
 
 type I18nParams = Record<string, string | number>;
@@ -172,12 +223,20 @@ interface PanelHost {
         load(): Promise<Record<string, string>>;
         save(cfg: Record<string, string>): Promise<void>;
     };
+    /** Settings → About: adapter / env / package versions + update check. */
+    about?: {
+        load(): Promise<AboutInfo>;
+        checkUpdates(): Promise<UpdateCheck>;
+    };
     history?: {
         list(appId: string): Promise<Commit[]>;
         detail(appId: string, id: string): Promise<Commit>;
     };
     storage?: {
-        listTables(appId: string): Promise<StorageTable[]>;
+        listTables(appId: string): Promise<{
+            tables: StorageTable[];
+            notices: StorageNotice[];
+        }>;
         readTable(appId: string, name: string): Promise<unknown>;
     };
     onOpenRequest?(cb: (appId?: string) => void): () => void;
@@ -237,6 +296,24 @@ type FrameEnv = {
     theme: string;
     palette: string;
     dock: string;
+    vars?: Record<string, string>;
+};
+/**
+ * A `mini_app_view_eval` query the host asked a rendered view to run. It arrives on the
+ * shell's existing event stream, and only the shell can cross into the iframe with it.
+ */
+type ViewEvalQuery = {
+    requestId: string;
+    appId: string;
+    code?: string;
+    maxBytes?: number;
+};
+type ViewEvalAnswer = {
+    requestId: string;
+    /** Set instead of `ok` when the shell holds no frame for the app. */
+    view?: "not-open";
+    ok?: boolean;
+    error?: Record<string, unknown>;
 };
 type FrameRecord = {
     wrap: HTMLElement;
@@ -250,6 +327,11 @@ type FrameController = {
     reload(appId: string): void;
     postEnv(appId: string): void;
     postEnvAll(): void;
+    /**
+     * Relay a view query into an app iframe. False means this shell holds no frame for the
+     * app — the caller must answer `not-open` rather than let the host wait out its timeout.
+     */
+    postViewEval(query: ViewEvalQuery): boolean;
     /** Set/rebind the container the app iframes mount into (e.g. the panel's #mma-frames). */
     setContainer(el: HTMLElement): void;
     readonly map: Map<string, FrameRecord>;
@@ -371,11 +453,53 @@ declare class HostUnreachableError extends Error {
     constructor(url: string, cause?: unknown);
 }
 declare function isHostUnreachable(e: unknown): e is HostUnreachableError;
+/**
+ * The frame URL carries exactly what the runner reads back out of `location.search`
+ * (`http/app-runner-html.ts`: theme / palette / dock). CSS variables do **not** travel here —
+ * they go over the `mma-set-env` postMessage.
+ *
+ * Callers hand us the whole app env, which also holds a `vars` map. Letting that reach
+ * `URLSearchParams` stringifies it to `[object Object]` and puts the junk in every iframe src,
+ * and TypeScript cannot catch it: excess-property checks apply to fresh literals, and this
+ * arrives as a variable. Picking the keys here keeps the invariant in one place, so a future
+ * caller cannot reintroduce it.
+ */
 declare function appFrameUrl(origin: string, appId: string, query: {
     theme: string;
     palette: string;
     dock: string;
 }): string;
+/** What the host pushes on `GET /api/events`. */
+type HostEventHandlers = {
+    onOpen?: (appId: string, title?: string) => void;
+    /** Sources were recompiled: an already-open iframe must refetch, not keep old code. */
+    onReload?: (appId: string) => void;
+    /**
+     * The host wants an answer from a rendered view. Only the shell can deliver it: the iframe
+     * is cross-origin, so `postMessage` is the one door from this page into that one.
+     */
+    onEval?: (query: ViewEvalQuery) => void;
+    /** A storage table crossed a size band — soft banner, writes were not blocked. */
+    onStorageNotice?: (notice: StorageNotice) => void;
+};
+/**
+ * Relay one host view query into the iframe that renders `appId`, or answer on the app's
+ * behalf when no shell here is showing it.
+ *
+ * Answering `not-open` immediately is what makes the distinction real: without it the host
+ * can only see "nobody replied" and has to guess between a closed app and a wedged one.
+ * Reused by every adapter (panel shell, dsh client) so hosts get identical freshness
+ * semantics instead of subtly different ones.
+ */
+declare function relayViewEval(origin: string, frames: FrameController, query: ViewEvalQuery): void;
+/**
+ * Subscribe to the host event stream. Returns an unsubscribe function.
+ *
+ * Lives here rather than in each adapter so every host gets the same freshness
+ * semantics for free. A missing/blocked stream is not fatal — it only costs live
+ * refresh, so failures degrade to the old behaviour and stay silent.
+ */
+declare function subscribeHostEvents(origin: string, handlers: HostEventHandlers): () => void;
 declare function parseAppsResponse(raw: unknown): AppItem[];
 declare function hostConfigToForm(raw: unknown, cardStyle: string): Record<string, string>;
 declare function formToHostConfigBody(form: Record<string, string>): Record<string, unknown>;
@@ -398,4 +522,4 @@ declare function injectPanelCss(): void;
 
 declare const packageName = "@monkey-mini-app/panel";
 
-export { type AppItem, AppList, Browse, type BrowseKind, type CardStyle, type Commit, type CommitFile, type CreateMiniAppPanelOptions, type DockId, type FrameController, type FrameControllerOptions, type FrameEnv, type FrameRecord, type HostShellInstance, type HostShellOptions, HostUnreachableError, type I18nParams, LOCALE_IDS, ListRegion, Loading, type LocaleId, MiniAppPanel, Modal, PANEL_CSS_TAG, type Palette, type PanelActions, type PanelCapabilities, PanelError, type PanelHost, type PanelI18n, type PanelInstance, PanelProvider, type PanelState, type RestOptions, Settings, type StorageTable, type TabItem, type TabKind, Tabs, ThemePop, type ThemeScope, TokenSet, Toolbar, activeAppFrom, appBlurb, appFrameUrl, capabilitiesOf, clampPaletteId, createFrameController, createHostShell, createMiniAppPanel, createPanelActions, createPanelI18n, createRestPanelHost, defaultHideThemePop, formToHostConfigBody, getPanelState, hostConfigToForm, hue, injectPanelCss, isHostUnreachable, monoOf, packageName, parseAppsResponse, parseCommitDetail, parseCommitList, parsePalettes, parseStorageTables, readJson, resetPanelState, resolvePanelLocale, setPanelState, subscribePanel, usePanelActions, usePanelI18n, usePanelState };
+export { type AboutInfo, type AboutPackage, type AppItem, AppList, Browse, type BrowseKind, type CardStyle, type Commit, type CommitFile, type CreateMiniAppPanelOptions, type DockId, type FrameController, type FrameControllerOptions, type FrameEnv, type FrameRecord, type HostEventHandlers, type HostShellInstance, type HostShellOptions, HostUnreachableError, type I18nParams, LOCALE_IDS, ListRegion, Loading, type LocaleId, MiniAppPanel, Modal, PANEL_CSS_TAG, type Palette, type PanelActions, type PanelCapabilities, PanelError, type PanelHost, type PanelI18n, type PanelInstance, PanelProvider, type PanelState, type RestOptions, Settings, type StorageNotice, type StorageTable, type TabItem, type TabKind, Tabs, ThemePop, type ThemeScope, TokenSet, Toolbar, type UpdateCheck, type UpdateCheckState, type ViewEvalAnswer, type ViewEvalQuery, activeAppFrom, appBlurb, appFrameUrl, capabilitiesOf, clampPaletteId, createFrameController, createHostShell, createMiniAppPanel, createPanelActions, createPanelI18n, createRestPanelHost, defaultHideThemePop, formToHostConfigBody, getPanelState, hostConfigToForm, hue, injectPanelCss, isHostUnreachable, monoOf, packageName, parseAppsResponse, parseCommitDetail, parseCommitList, parsePalettes, parseStorageTables, readJson, relayViewEval, resetPanelState, resolvePanelLocale, setPanelState, subscribeHostEvents, subscribePanel, usePanelActions, usePanelI18n, usePanelState };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { TokenSet } from './themes.js';
-export { CustomPaletteMap, ModeId, PALETTES, PaletteId, applyThemeTo, clampMode, clampPalette, cssVars, parseThemeCss, runnerThemeCss, themeLabelFromCss, tokensOf } from './themes.js';
+export { CustomPaletteMap, GLOBAL_PALETTE_ID, LOCAL_PALETTE_ID, ModeId, PALETTES, PaletteId, applyThemeTo, clampMode, clampPalette, cssVars, effectivePalette, parseThemeCss, resolveMode, runnerThemeCss, selectedPalette, themeCssVars, themeLabelFromCss, tokensOf } from './themes.js';
 import * as react from 'react';
 
 declare const LOCALE_IDS: readonly ["zh-CN", "en"];
@@ -15,6 +15,15 @@ type AppItem = {
         theme: string;
         palette: string;
     } | null;
+    /** Parsed from the app's `theme.css` when present. */
+    localPalette?: {
+        label: string;
+        swatch: string;
+        tokens: {
+            light: TokenSet;
+            dark: TokenSet;
+        };
+    } | null;
 };
 type TabKind = "all" | "app";
 type TabItem = {
@@ -27,6 +36,25 @@ type BrowseKind = "history" | "storage";
 type ThemeScope = "global" | "app";
 type DockId = "fill" | "side";
 type CardStyle = "stamp" | "etch" | "hero" | "list";
+type AboutPackage = {
+    name: string;
+    version: string;
+};
+type AboutInfo = {
+    adapter: string;
+    env: string;
+    packages: AboutPackage[];
+};
+type UpdateCheck = {
+    name: string;
+    current: string;
+    latest: string | null;
+    updateAvailable: boolean;
+    error?: string;
+};
+type UpdateCheckState = UpdateCheck & {
+    status: "idle" | "loading" | "done";
+};
 type CommitFile = {
     path: string;
     add?: number;
@@ -43,6 +71,22 @@ type StorageTable = {
     name: string;
     size?: number;
     updatedAt?: string;
+    /** Top-level key count when the host knows. */
+    keys?: number;
+};
+/** Soft notice when a table crossed a size band — banner + copy-paste AI prompt. */
+type StorageNotice = {
+    appId: string;
+    table: string;
+    bytes: number;
+    keys: number;
+    heavy: Array<{
+        key: string;
+        bytes: number;
+        kind: "list" | "map" | "value";
+        entries?: number;
+    }>;
+    prompt: string;
 };
 type PanelCapabilities = {
     history: boolean;
@@ -69,11 +113,14 @@ type PanelActions = {
     toggleSettings: (open: boolean) => void;
     getCfg: () => Record<string, string>;
     saveHostConfig: (form: Record<string, string>) => void;
+    checkUpdates: () => void;
     toggleBrowse: (kind: string) => void;
     loadCommitDetail: (id: string) => void;
     loadTable: (name: string) => void;
     browseBack: () => void;
     browseFile: (path: string) => void;
+    dismissStorageNotice: () => void;
+    applyStorageNotice: (notice: StorageNotice) => void;
     reloadActive: () => void;
     askDelete: () => void;
     hideModal: () => void;
@@ -106,6 +153,8 @@ type PanelState = {
     cfgMsg: string;
     cfgVersion: number;
     cfg: Record<string, string>;
+    about: AboutInfo | null;
+    updateCheck: UpdateCheckState | null;
     emptyText: string | undefined;
     capabilities: PanelCapabilities;
     locale: LocaleId;
@@ -120,6 +169,8 @@ type PanelState = {
     browseTable: string | null;
     browseTableValue: unknown;
     browseOpenFile: string | null;
+    /** Latest storage-size notice for the active app; banner is dismissible. */
+    storageNotice: StorageNotice | null;
 };
 
 type I18nParams = Record<string, string | number>;
@@ -172,12 +223,20 @@ interface PanelHost {
         load(): Promise<Record<string, string>>;
         save(cfg: Record<string, string>): Promise<void>;
     };
+    /** Settings → About: adapter / env / package versions + update check. */
+    about?: {
+        load(): Promise<AboutInfo>;
+        checkUpdates(): Promise<UpdateCheck>;
+    };
     history?: {
         list(appId: string): Promise<Commit[]>;
         detail(appId: string, id: string): Promise<Commit>;
     };
     storage?: {
-        listTables(appId: string): Promise<StorageTable[]>;
+        listTables(appId: string): Promise<{
+            tables: StorageTable[];
+            notices: StorageNotice[];
+        }>;
         readTable(appId: string, name: string): Promise<unknown>;
     };
     onOpenRequest?(cb: (appId?: string) => void): () => void;
@@ -237,6 +296,24 @@ type FrameEnv = {
     theme: string;
     palette: string;
     dock: string;
+    vars?: Record<string, string>;
+};
+/**
+ * A `mini_app_view_eval` query the host asked a rendered view to run. It arrives on the
+ * shell's existing event stream, and only the shell can cross into the iframe with it.
+ */
+type ViewEvalQuery = {
+    requestId: string;
+    appId: string;
+    code?: string;
+    maxBytes?: number;
+};
+type ViewEvalAnswer = {
+    requestId: string;
+    /** Set instead of `ok` when the shell holds no frame for the app. */
+    view?: "not-open";
+    ok?: boolean;
+    error?: Record<string, unknown>;
 };
 type FrameRecord = {
     wrap: HTMLElement;
@@ -250,6 +327,11 @@ type FrameController = {
     reload(appId: string): void;
     postEnv(appId: string): void;
     postEnvAll(): void;
+    /**
+     * Relay a view query into an app iframe. False means this shell holds no frame for the
+     * app — the caller must answer `not-open` rather than let the host wait out its timeout.
+     */
+    postViewEval(query: ViewEvalQuery): boolean;
     /** Set/rebind the container the app iframes mount into (e.g. the panel's #mma-frames). */
     setContainer(el: HTMLElement): void;
     readonly map: Map<string, FrameRecord>;
@@ -371,11 +453,53 @@ declare class HostUnreachableError extends Error {
     constructor(url: string, cause?: unknown);
 }
 declare function isHostUnreachable(e: unknown): e is HostUnreachableError;
+/**
+ * The frame URL carries exactly what the runner reads back out of `location.search`
+ * (`http/app-runner-html.ts`: theme / palette / dock). CSS variables do **not** travel here —
+ * they go over the `mma-set-env` postMessage.
+ *
+ * Callers hand us the whole app env, which also holds a `vars` map. Letting that reach
+ * `URLSearchParams` stringifies it to `[object Object]` and puts the junk in every iframe src,
+ * and TypeScript cannot catch it: excess-property checks apply to fresh literals, and this
+ * arrives as a variable. Picking the keys here keeps the invariant in one place, so a future
+ * caller cannot reintroduce it.
+ */
 declare function appFrameUrl(origin: string, appId: string, query: {
     theme: string;
     palette: string;
     dock: string;
 }): string;
+/** What the host pushes on `GET /api/events`. */
+type HostEventHandlers = {
+    onOpen?: (appId: string, title?: string) => void;
+    /** Sources were recompiled: an already-open iframe must refetch, not keep old code. */
+    onReload?: (appId: string) => void;
+    /**
+     * The host wants an answer from a rendered view. Only the shell can deliver it: the iframe
+     * is cross-origin, so `postMessage` is the one door from this page into that one.
+     */
+    onEval?: (query: ViewEvalQuery) => void;
+    /** A storage table crossed a size band — soft banner, writes were not blocked. */
+    onStorageNotice?: (notice: StorageNotice) => void;
+};
+/**
+ * Relay one host view query into the iframe that renders `appId`, or answer on the app's
+ * behalf when no shell here is showing it.
+ *
+ * Answering `not-open` immediately is what makes the distinction real: without it the host
+ * can only see "nobody replied" and has to guess between a closed app and a wedged one.
+ * Reused by every adapter (panel shell, dsh client) so hosts get identical freshness
+ * semantics instead of subtly different ones.
+ */
+declare function relayViewEval(origin: string, frames: FrameController, query: ViewEvalQuery): void;
+/**
+ * Subscribe to the host event stream. Returns an unsubscribe function.
+ *
+ * Lives here rather than in each adapter so every host gets the same freshness
+ * semantics for free. A missing/blocked stream is not fatal — it only costs live
+ * refresh, so failures degrade to the old behaviour and stay silent.
+ */
+declare function subscribeHostEvents(origin: string, handlers: HostEventHandlers): () => void;
 declare function parseAppsResponse(raw: unknown): AppItem[];
 declare function hostConfigToForm(raw: unknown, cardStyle: string): Record<string, string>;
 declare function formToHostConfigBody(form: Record<string, string>): Record<string, unknown>;
@@ -398,4 +522,4 @@ declare function injectPanelCss(): void;
 
 declare const packageName = "@monkey-mini-app/panel";
 
-export { type AppItem, AppList, Browse, type BrowseKind, type CardStyle, type Commit, type CommitFile, type CreateMiniAppPanelOptions, type DockId, type FrameController, type FrameControllerOptions, type FrameEnv, type FrameRecord, type HostShellInstance, type HostShellOptions, HostUnreachableError, type I18nParams, LOCALE_IDS, ListRegion, Loading, type LocaleId, MiniAppPanel, Modal, PANEL_CSS_TAG, type Palette, type PanelActions, type PanelCapabilities, PanelError, type PanelHost, type PanelI18n, type PanelInstance, PanelProvider, type PanelState, type RestOptions, Settings, type StorageTable, type TabItem, type TabKind, Tabs, ThemePop, type ThemeScope, TokenSet, Toolbar, activeAppFrom, appBlurb, appFrameUrl, capabilitiesOf, clampPaletteId, createFrameController, createHostShell, createMiniAppPanel, createPanelActions, createPanelI18n, createRestPanelHost, defaultHideThemePop, formToHostConfigBody, getPanelState, hostConfigToForm, hue, injectPanelCss, isHostUnreachable, monoOf, packageName, parseAppsResponse, parseCommitDetail, parseCommitList, parsePalettes, parseStorageTables, readJson, resetPanelState, resolvePanelLocale, setPanelState, subscribePanel, usePanelActions, usePanelI18n, usePanelState };
+export { type AboutInfo, type AboutPackage, type AppItem, AppList, Browse, type BrowseKind, type CardStyle, type Commit, type CommitFile, type CreateMiniAppPanelOptions, type DockId, type FrameController, type FrameControllerOptions, type FrameEnv, type FrameRecord, type HostEventHandlers, type HostShellInstance, type HostShellOptions, HostUnreachableError, type I18nParams, LOCALE_IDS, ListRegion, Loading, type LocaleId, MiniAppPanel, Modal, PANEL_CSS_TAG, type Palette, type PanelActions, type PanelCapabilities, PanelError, type PanelHost, type PanelI18n, type PanelInstance, PanelProvider, type PanelState, type RestOptions, Settings, type StorageNotice, type StorageTable, type TabItem, type TabKind, Tabs, ThemePop, type ThemeScope, TokenSet, Toolbar, type UpdateCheck, type UpdateCheckState, type ViewEvalAnswer, type ViewEvalQuery, activeAppFrom, appBlurb, appFrameUrl, capabilitiesOf, clampPaletteId, createFrameController, createHostShell, createMiniAppPanel, createPanelActions, createPanelI18n, createRestPanelHost, defaultHideThemePop, formToHostConfigBody, getPanelState, hostConfigToForm, hue, injectPanelCss, isHostUnreachable, monoOf, packageName, parseAppsResponse, parseCommitDetail, parseCommitList, parsePalettes, parseStorageTables, readJson, relayViewEval, resetPanelState, resolvePanelLocale, setPanelState, subscribeHostEvents, subscribePanel, usePanelActions, usePanelI18n, usePanelState };