mp-taro-kit 0.0.1 → 0.0.4

package/README.md

@@ -1,9 +1,9 @@
 # mp-taro-kit
 
-基于 Taro + React 的小程序 UI 基础库：遮罩、弹出层、面板、安全区等容器能力，业务内容通过 `children` / 插槽注入。
+基于 Taro + React 的小程序基础库（kit）。叫 kit 不叫 UI，是因为能力域不止界面：既有遮罩、弹出层、面板、安全区等 UI 容器能力，也会收纳跨项目通用的操作功能封装；具体业务内容通过 `children` / 插槽或宿主提供。
 
 - Skyline 为主路径，WebView 必须可用
-- 对外样式值走 CSS 变量（`var(--mp-*, 兜底值)`），可整体换肤
+- 对外样式值走 CSS 变量（`var(--mptk-*)`），默认值集中在 `mp-taro-kit/styles/tokens`；宿主覆盖同名变量即可整体换肤
 - 按需 import，靠 tree-shaking 控体积
 
-> 基础建设阶段，API 未定，暂不提供使用文档。
+> 能力源码已落码，尚未发版；使用文档待宿主 demo 双端验证通过后补齐。

package/dist/core/configure.cjs

@@ -0,0 +1,75 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.configure = configure;
+exports.getFaces = getFaces;
+exports.getConfig = getConfig;
+exports.resetForTests = resetForTests;
+const singleton_js_1 = require("../runtime/singleton.cjs");
+const DEFAULT_CONFIG = {
+    baseURL: '',
+    timeout: 10000,
+    storagePrefix: 'mptk:',
+    debug: false,
+    headers: {},
+};
+const REQUIRED_FACES = [
+    'request',
+    'getStorage',
+    'setStorage',
+    'removeStorage',
+    'clearStorage',
+    'navigateTo',
+    'redirectTo',
+    'switchTab',
+    'navigateBack',
+    'reLaunch',
+    'login',
+    'scanCode',
+    'requestPayment',
+];
+const NOT_CONFIGURED = '[mp-taro-kit/core] 未调用 configure() 注入平台能力；请在 app 入口配置一次（mp-taro-kit/core 的 configure）';
+/** 配置槽用 runtime 的跨副本单例，保证「注入一次」对主包 / 分包各副本都生效。 */
+function slot() {
+    return (0, singleton_js_1.createSingleton)('core', () => ({ state: null }));
+}
+/**
+ * 宿主启动时调用一次，注入平台能力与库配置。
+ * 缺字段是开发者契约违例 ⇒ 当场抛错，不静默降级。
+ */
+function configure(faces, options = {}) {
+    if (faces === null || typeof faces !== 'object') {
+        throw new Error('[mp-taro-kit/core] configure() 需要一个 faces 对象；请在 app 入口注入平台能力');
+    }
+    for (const key of REQUIRED_FACES) {
+        if (typeof faces[key] !== 'function') {
+            throw new Error(`[mp-taro-kit/core] configure() 的 faces 缺少 ${key}()；请注入该方法`);
+        }
+    }
+    slot().state = {
+        faces,
+        config: {
+            baseURL: options.baseURL ?? DEFAULT_CONFIG.baseURL,
+            timeout: options.timeout ?? DEFAULT_CONFIG.timeout,
+            storagePrefix: options.storagePrefix ?? DEFAULT_CONFIG.storagePrefix,
+            debug: options.debug ?? DEFAULT_CONFIG.debug,
+            headers: options.headers ?? DEFAULT_CONFIG.headers,
+        },
+    };
+}
+/** 未配置时每次调用都抛，消息直接给修复动作。 */
+function getFaces() {
+    const state = slot().state;
+    if (state === null)
+        throw new Error(NOT_CONFIGURED);
+    return state.faces;
+}
+function getConfig() {
+    const state = slot().state;
+    if (state === null)
+        throw new Error(NOT_CONFIGURED);
+    return state.config;
+}
+/** 仅供单测清空注入状态；产品代码不要调用。 */
+function resetForTests() {
+    slot().state = null;
+}

package/dist/core/configure.d.ts

@@ -0,0 +1,18 @@
+import type { PlatformFaces } from './faces.js';
+export interface CoreConfig {
+    baseURL: string;
+    timeout: number;
+    storagePrefix: string;
+    debug: boolean;
+    headers: Record<string, string>;
+}
+/**
+ * 宿主启动时调用一次，注入平台能力与库配置。
+ * 缺字段是开发者契约违例 ⇒ 当场抛错，不静默降级。
+ */
+export declare function configure(faces: PlatformFaces, options?: Partial<CoreConfig>): void;
+/** 未配置时每次调用都抛，消息直接给修复动作。 */
+export declare function getFaces(): PlatformFaces;
+export declare function getConfig(): CoreConfig;
+/** 仅供单测清空注入状态；产品代码不要调用。 */
+export declare function resetForTests(): void;

package/dist/core/configure.js

@@ -0,0 +1,69 @@
+import { createSingleton } from '../runtime/singleton.js';
+const DEFAULT_CONFIG = {
+    baseURL: '',
+    timeout: 10000,
+    storagePrefix: 'mptk:',
+    debug: false,
+    headers: {},
+};
+const REQUIRED_FACES = [
+    'request',
+    'getStorage',
+    'setStorage',
+    'removeStorage',
+    'clearStorage',
+    'navigateTo',
+    'redirectTo',
+    'switchTab',
+    'navigateBack',
+    'reLaunch',
+    'login',
+    'scanCode',
+    'requestPayment',
+];
+const NOT_CONFIGURED = '[mp-taro-kit/core] 未调用 configure() 注入平台能力；请在 app 入口配置一次（mp-taro-kit/core 的 configure）';
+/** 配置槽用 runtime 的跨副本单例，保证「注入一次」对主包 / 分包各副本都生效。 */
+function slot() {
+    return createSingleton('core', () => ({ state: null }));
+}
+/**
+ * 宿主启动时调用一次，注入平台能力与库配置。
+ * 缺字段是开发者契约违例 ⇒ 当场抛错，不静默降级。
+ */
+export function configure(faces, options = {}) {
+    if (faces === null || typeof faces !== 'object') {
+        throw new Error('[mp-taro-kit/core] configure() 需要一个 faces 对象；请在 app 入口注入平台能力');
+    }
+    for (const key of REQUIRED_FACES) {
+        if (typeof faces[key] !== 'function') {
+            throw new Error(`[mp-taro-kit/core] configure() 的 faces 缺少 ${key}()；请注入该方法`);
+        }
+    }
+    slot().state = {
+        faces,
+        config: {
+            baseURL: options.baseURL ?? DEFAULT_CONFIG.baseURL,
+            timeout: options.timeout ?? DEFAULT_CONFIG.timeout,
+            storagePrefix: options.storagePrefix ?? DEFAULT_CONFIG.storagePrefix,
+            debug: options.debug ?? DEFAULT_CONFIG.debug,
+            headers: options.headers ?? DEFAULT_CONFIG.headers,
+        },
+    };
+}
+/** 未配置时每次调用都抛，消息直接给修复动作。 */
+export function getFaces() {
+    const state = slot().state;
+    if (state === null)
+        throw new Error(NOT_CONFIGURED);
+    return state.faces;
+}
+export function getConfig() {
+    const state = slot().state;
+    if (state === null)
+        throw new Error(NOT_CONFIGURED);
+    return state.config;
+}
+/** 仅供单测清空注入状态；产品代码不要调用。 */
+export function resetForTests() {
+    slot().state = null;
+}

package/dist/core/faces.cjs

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/core/faces.d.ts

@@ -0,0 +1,42 @@
+/**
+ * 平台能力的最小本地接口面：只声明本库真正会调的那几个，不 import @tarojs/taro。
+ * 宿主在 app 入口用 configure() 注入一次；库不与宿主的 Taro 类型版本焊死，也不引入平台类型依赖。
+ */
+export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD';
+export interface PlatformRequestOptions {
+    url: string;
+    method: HttpMethod;
+    data?: unknown;
+    header?: Record<string, string>;
+    timeout?: number;
+}
+export interface PlatformResponse<T> {
+    statusCode: number;
+    data: T;
+}
+export interface NavigateOptions {
+    url: string;
+    params?: Record<string, string | number | boolean | undefined>;
+}
+export interface PaymentOptions {
+    [key: string]: unknown;
+}
+export interface PlatformFaces {
+    request<T>(options: PlatformRequestOptions): Promise<PlatformResponse<T>>;
+    getStorage(key: string): unknown;
+    setStorage(key: string, value: string): void;
+    removeStorage(key: string): void;
+    clearStorage(): void;
+    navigateTo(options: NavigateOptions): Promise<unknown>;
+    redirectTo(options: NavigateOptions): Promise<unknown>;
+    switchTab(options: NavigateOptions): Promise<unknown>;
+    navigateBack(delta?: number): Promise<unknown>;
+    reLaunch(options: NavigateOptions): Promise<unknown>;
+    login(): Promise<{
+        code: string;
+    }>;
+    scanCode(): Promise<{
+        result: string;
+    }>;
+    requestPayment(options: PaymentOptions): Promise<unknown>;
+}

package/dist/core/faces.js

@@ -0,0 +1 @@
+export {};

package/dist/core/index.cjs

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.requestPayment = exports.scanCode = exports.login = exports.storageClear = exports.storageRemove = exports.storageSet = exports.storageGet = exports.buildUrl = exports.navigateBack = exports.reLaunch = exports.switchTab = exports.redirectTo = exports.navigateTo = exports.joinUrl = exports.remove = exports.patch = exports.put = exports.post = exports.get = exports.request = exports.resetForTests = exports.getConfig = exports.getFaces = exports.configure = void 0;
+var configure_js_1 = require("./configure.cjs");
+Object.defineProperty(exports, "configure", { enumerable: true, get: function () { return configure_js_1.configure; } });
+Object.defineProperty(exports, "getFaces", { enumerable: true, get: function () { return configure_js_1.getFaces; } });
+Object.defineProperty(exports, "getConfig", { enumerable: true, get: function () { return configure_js_1.getConfig; } });
+Object.defineProperty(exports, "resetForTests", { enumerable: true, get: function () { return configure_js_1.resetForTests; } });
+var request_js_1 = require("./request.cjs");
+Object.defineProperty(exports, "request", { enumerable: true, get: function () { return request_js_1.request; } });
+Object.defineProperty(exports, "get", { enumerable: true, get: function () { return request_js_1.get; } });
+Object.defineProperty(exports, "post", { enumerable: true, get: function () { return request_js_1.post; } });
+Object.defineProperty(exports, "put", { enumerable: true, get: function () { return request_js_1.put; } });
+Object.defineProperty(exports, "patch", { enumerable: true, get: function () { return request_js_1.patch; } });
+Object.defineProperty(exports, "remove", { enumerable: true, get: function () { return request_js_1.remove; } });
+Object.defineProperty(exports, "joinUrl", { enumerable: true, get: function () { return request_js_1.joinUrl; } });
+var router_js_1 = require("./router.cjs");
+Object.defineProperty(exports, "navigateTo", { enumerable: true, get: function () { return router_js_1.navigateTo; } });
+Object.defineProperty(exports, "redirectTo", { enumerable: true, get: function () { return router_js_1.redirectTo; } });
+Object.defineProperty(exports, "switchTab", { enumerable: true, get: function () { return router_js_1.switchTab; } });
+Object.defineProperty(exports, "reLaunch", { enumerable: true, get: function () { return router_js_1.reLaunch; } });
+Object.defineProperty(exports, "navigateBack", { enumerable: true, get: function () { return router_js_1.navigateBack; } });
+Object.defineProperty(exports, "buildUrl", { enumerable: true, get: function () { return router_js_1.buildUrl; } });
+var storage_js_1 = require("./storage.cjs");
+Object.defineProperty(exports, "storageGet", { enumerable: true, get: function () { return storage_js_1.storageGet; } });
+Object.defineProperty(exports, "storageSet", { enumerable: true, get: function () { return storage_js_1.storageSet; } });
+Object.defineProperty(exports, "storageRemove", { enumerable: true, get: function () { return storage_js_1.storageRemove; } });
+Object.defineProperty(exports, "storageClear", { enumerable: true, get: function () { return storage_js_1.storageClear; } });
+var weapp_js_1 = require("./weapp.cjs");
+Object.defineProperty(exports, "login", { enumerable: true, get: function () { return weapp_js_1.login; } });
+Object.defineProperty(exports, "scanCode", { enumerable: true, get: function () { return weapp_js_1.scanCode; } });
+Object.defineProperty(exports, "requestPayment", { enumerable: true, get: function () { return weapp_js_1.requestPayment; } });

package/dist/core/index.d.ts

@@ -0,0 +1,6 @@
+export type { HttpMethod, NavigateOptions, PaymentOptions, PlatformFaces, PlatformRequestOptions, PlatformResponse, } from './faces.js';
+export { configure, getFaces, getConfig, resetForTests, type CoreConfig, } from './configure.js';
+export { request, get, post, put, patch, remove, joinUrl, type RequestOptions, type HttpResult, } from './request.js';
+export { navigateTo, redirectTo, switchTab, reLaunch, navigateBack, buildUrl, type RouteOptions, } from './router.js';
+export { storageGet, storageSet, storageRemove, storageClear } from './storage.js';
+export { login, scanCode, requestPayment } from './weapp.js';

package/dist/core/index.js

@@ -0,0 +1,5 @@
+export { configure, getFaces, getConfig, resetForTests, } from './configure.js';
+export { request, get, post, put, patch, remove, joinUrl, } from './request.js';
+export { navigateTo, redirectTo, switchTab, reLaunch, navigateBack, buildUrl, } from './router.js';
+export { storageGet, storageSet, storageRemove, storageClear } from './storage.js';
+export { login, scanCode, requestPayment } from './weapp.js';

package/dist/core/request.cjs

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.joinUrl = joinUrl;
+exports.request = request;
+exports.get = get;
+exports.post = post;
+exports.put = put;
+exports.patch = patch;
+exports.remove = remove;
+const configure_js_1 = require("./configure.cjs");
+function joinUrl(baseURL, url) {
+    if (/^https?:\/\//.test(url))
+        return url;
+    if (baseURL === '')
+        return url;
+    return `${baseURL.replace(/\/+$/, '')}/${url.replace(/^\/+/, '')}`;
+}
+/**
+ * 网络失败属于「用户在场」⇒ 返回结果对象而非抛异常；
+ * 未 configure() 属于「开发者在场」⇒ getConfig / getFaces 直接抛。
+ */
+async function request(options) {
+    const config = (0, configure_js_1.getConfig)();
+    const faces = (0, configure_js_1.getFaces)();
+    const outgoing = {
+        url: joinUrl(config.baseURL, options.url),
+        method: options.method ?? 'GET',
+        data: options.data,
+        header: { ...config.headers, ...options.header },
+        timeout: options.timeout ?? config.timeout,
+    };
+    try {
+        const response = await faces.request(outgoing);
+        const statusCode = Number.isFinite(response.statusCode) ? response.statusCode : 0;
+        return {
+            ok: statusCode >= 200 && statusCode < 300,
+            statusCode,
+            data: response.data,
+            error: undefined,
+        };
+    }
+    catch (error) {
+        return { ok: false, statusCode: 0, data: undefined, error: String(error) };
+    }
+}
+function get(url, options = {}) {
+    return request({ ...options, url, method: 'GET' });
+}
+function post(url, options = {}) {
+    return request({ ...options, url, method: 'POST' });
+}
+function put(url, options = {}) {
+    return request({ ...options, url, method: 'PUT' });
+}
+function patch(url, options = {}) {
+    return request({ ...options, url, method: 'PATCH' });
+}
+function remove(url, options = {}) {
+    return request({ ...options, url, method: 'DELETE' });
+}

package/dist/core/request.d.ts

@@ -0,0 +1,27 @@
+import type { HttpMethod } from './faces.js';
+export interface RequestOptions {
+    url: string;
+    method?: HttpMethod;
+    data?: unknown;
+    header?: Record<string, string>;
+    timeout?: number;
+}
+export interface HttpResult<T> {
+    ok: boolean;
+    statusCode: number;
+    data: T | undefined;
+    error: string | undefined;
+}
+export declare function joinUrl(baseURL: string, url: string): string;
+/**
+ * 网络失败属于「用户在场」⇒ 返回结果对象而非抛异常；
+ * 未 configure() 属于「开发者在场」⇒ getConfig / getFaces 直接抛。
+ */
+export declare function request<T = unknown>(options: RequestOptions): Promise<HttpResult<T>>;
+type WithoutUrlMethod = Omit<RequestOptions, 'url' | 'method'>;
+export declare function get<T = unknown>(url: string, options?: WithoutUrlMethod): Promise<HttpResult<T>>;
+export declare function post<T = unknown>(url: string, options?: WithoutUrlMethod): Promise<HttpResult<T>>;
+export declare function put<T = unknown>(url: string, options?: WithoutUrlMethod): Promise<HttpResult<T>>;
+export declare function patch<T = unknown>(url: string, options?: WithoutUrlMethod): Promise<HttpResult<T>>;
+export declare function remove<T = unknown>(url: string, options?: WithoutUrlMethod): Promise<HttpResult<T>>;
+export {};

package/dist/core/request.js

@@ -0,0 +1,51 @@
+import { getConfig, getFaces } from './configure.js';
+export function joinUrl(baseURL, url) {
+    if (/^https?:\/\//.test(url))
+        return url;
+    if (baseURL === '')
+        return url;
+    return `${baseURL.replace(/\/+$/, '')}/${url.replace(/^\/+/, '')}`;
+}
+/**
+ * 网络失败属于「用户在场」⇒ 返回结果对象而非抛异常；
+ * 未 configure() 属于「开发者在场」⇒ getConfig / getFaces 直接抛。
+ */
+export async function request(options) {
+    const config = getConfig();
+    const faces = getFaces();
+    const outgoing = {
+        url: joinUrl(config.baseURL, options.url),
+        method: options.method ?? 'GET',
+        data: options.data,
+        header: { ...config.headers, ...options.header },
+        timeout: options.timeout ?? config.timeout,
+    };
+    try {
+        const response = await faces.request(outgoing);
+        const statusCode = Number.isFinite(response.statusCode) ? response.statusCode : 0;
+        return {
+            ok: statusCode >= 200 && statusCode < 300,
+            statusCode,
+            data: response.data,
+            error: undefined,
+        };
+    }
+    catch (error) {
+        return { ok: false, statusCode: 0, data: undefined, error: String(error) };
+    }
+}
+export function get(url, options = {}) {
+    return request({ ...options, url, method: 'GET' });
+}
+export function post(url, options = {}) {
+    return request({ ...options, url, method: 'POST' });
+}
+export function put(url, options = {}) {
+    return request({ ...options, url, method: 'PUT' });
+}
+export function patch(url, options = {}) {
+    return request({ ...options, url, method: 'PATCH' });
+}
+export function remove(url, options = {}) {
+    return request({ ...options, url, method: 'DELETE' });
+}

package/dist/core/router.cjs

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildUrl = buildUrl;
+exports.navigateTo = navigateTo;
+exports.redirectTo = redirectTo;
+exports.switchTab = switchTab;
+exports.reLaunch = reLaunch;
+exports.navigateBack = navigateBack;
+const singleton_js_1 = require("../runtime/singleton.cjs");
+const configure_js_1 = require("./configure.cjs");
+/** 在途锁跨副本共用一份；释放时机由真实路由事件 settle 决定，不用固定间隔定时器。 */
+function routeLock() {
+    return (0, singleton_js_1.createSingleton)('core/route-lock', () => ({ value: false }));
+}
+function buildUrl(url, params) {
+    if (params === undefined)
+        return url;
+    const query = Object.keys(params)
+        .filter((key) => params[key] !== undefined)
+        .map((key) => `${encodeURIComponent(key)}=${encodeURIComponent(String(params[key]))}`)
+        .join('&');
+    if (query === '')
+        return url;
+    return url.includes('?') ? `${url}&${query}` : `${url}?${query}`;
+}
+async function go(kind, options) {
+    const faces = (0, configure_js_1.getFaces)();
+    const lock = routeLock();
+    if (lock.value && options.force !== true)
+        return false;
+    lock.value = true;
+    try {
+        await faces[kind]({ url: buildUrl(options.url, options.params) });
+        return true;
+    }
+    catch {
+        return false;
+    }
+    finally {
+        lock.value = false;
+    }
+}
+function navigateTo(options) {
+    return go('navigateTo', options);
+}
+function redirectTo(options) {
+    return go('redirectTo', options);
+}
+function switchTab(options) {
+    return go('switchTab', options);
+}
+function reLaunch(options) {
+    return go('reLaunch', options);
+}
+async function navigateBack(delta = 1) {
+    const faces = (0, configure_js_1.getFaces)();
+    const lock = routeLock();
+    if (lock.value)
+        return false;
+    lock.value = true;
+    try {
+        await faces.navigateBack(delta);
+        return true;
+    }
+    catch {
+        return false;
+    }
+    finally {
+        lock.value = false;
+    }
+}

package/dist/core/router.d.ts

@@ -0,0 +1,11 @@
+import type { NavigateOptions } from './faces.js';
+export interface RouteOptions extends NavigateOptions {
+    /** 跳过在途锁，强制发起本次跳转。 */
+    force?: boolean;
+}
+export declare function buildUrl(url: string, params?: NavigateOptions['params']): string;
+export declare function navigateTo(options: RouteOptions): Promise<boolean>;
+export declare function redirectTo(options: RouteOptions): Promise<boolean>;
+export declare function switchTab(options: RouteOptions): Promise<boolean>;
+export declare function reLaunch(options: RouteOptions): Promise<boolean>;
+export declare function navigateBack(delta?: number): Promise<boolean>;

package/dist/core/router.js

@@ -0,0 +1,63 @@
+import { createSingleton } from '../runtime/singleton.js';
+import { getFaces } from './configure.js';
+/** 在途锁跨副本共用一份；释放时机由真实路由事件 settle 决定，不用固定间隔定时器。 */
+function routeLock() {
+    return createSingleton('core/route-lock', () => ({ value: false }));
+}
+export function buildUrl(url, params) {
+    if (params === undefined)
+        return url;
+    const query = Object.keys(params)
+        .filter((key) => params[key] !== undefined)
+        .map((key) => `${encodeURIComponent(key)}=${encodeURIComponent(String(params[key]))}`)
+        .join('&');
+    if (query === '')
+        return url;
+    return url.includes('?') ? `${url}&${query}` : `${url}?${query}`;
+}
+async function go(kind, options) {
+    const faces = getFaces();
+    const lock = routeLock();
+    if (lock.value && options.force !== true)
+        return false;
+    lock.value = true;
+    try {
+        await faces[kind]({ url: buildUrl(options.url, options.params) });
+        return true;
+    }
+    catch {
+        return false;
+    }
+    finally {
+        lock.value = false;
+    }
+}
+export function navigateTo(options) {
+    return go('navigateTo', options);
+}
+export function redirectTo(options) {
+    return go('redirectTo', options);
+}
+export function switchTab(options) {
+    return go('switchTab', options);
+}
+export function reLaunch(options) {
+    return go('reLaunch', options);
+}
+export async function navigateBack(delta = 1) {
+    const faces = getFaces();
+    const lock = routeLock();
+    if (lock.value)
+        return false;
+    lock.value = true;
+    try {
+        await faces.navigateBack(delta);
+        return true;
+    }
+    catch {
+        return false;
+    }
+    finally {
+        lock.value = false;
+    }
+}

package/dist/core/storage.cjs

@@ -0,0 +1,63 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.storageGet = storageGet;
+exports.storageSet = storageSet;
+exports.storageRemove = storageRemove;
+exports.storageClear = storageClear;
+const configure_js_1 = require("./configure.cjs");
+function keyOf(key) {
+    return `${(0, configure_js_1.getConfig)().storagePrefix}${key}`;
+}
+/** 平台异常 / 脏数据 / 过期都按「用户在场」兜底；未 configure() 由 getFaces 抛错。 */
+function storageGet(key) {
+    const faces = (0, configure_js_1.getFaces)();
+    try {
+        const raw = faces.getStorage(keyOf(key));
+        if (raw === undefined || raw === null || raw === '')
+            return undefined;
+        const parsed = typeof raw === 'string' ? JSON.parse(raw) : raw;
+        if (parsed === null || typeof parsed !== 'object' || !('v' in parsed))
+            return undefined;
+        const record = parsed;
+        if (record.e !== null && record.e !== undefined && record.e <= Date.now()) {
+            faces.removeStorage(keyOf(key));
+            return undefined;
+        }
+        return record.v;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** 返回 false 表示平台写入失败，不静默、也不抛。 */
+function storageSet(key, value, ttlMs) {
+    const faces = (0, configure_js_1.getFaces)();
+    const record = { v: value, e: ttlMs === undefined ? null : Date.now() + ttlMs };
+    try {
+        faces.setStorage(keyOf(key), JSON.stringify(record));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function storageRemove(key) {
+    const faces = (0, configure_js_1.getFaces)();
+    try {
+        faces.removeStorage(keyOf(key));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function storageClear() {
+    const faces = (0, configure_js_1.getFaces)();
+    try {
+        faces.clearStorage();
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/core/storage.d.ts

@@ -0,0 +1,6 @@
+/** 平台异常 / 脏数据 / 过期都按「用户在场」兜底；未 configure() 由 getFaces 抛错。 */
+export declare function storageGet<T = unknown>(key: string): T | undefined;
+/** 返回 false 表示平台写入失败，不静默、也不抛。 */
+export declare function storageSet<T>(key: string, value: T, ttlMs?: number): boolean;
+export declare function storageRemove(key: string): boolean;
+export declare function storageClear(): boolean;