rvis-aiui-kit 1.1.1 → 1.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rvis-aiui-kit",
-  "version": "1.1.1",
+  "version": "1.2.1",
   "description": "RVIS AIUI components and Glass3 extension SDK.",
   "type": "module",
   "main": "./sdk/index.js",

package/sdk/README.md

@@ -13,6 +13,7 @@
 - [API 总览](#api-总览)
 - [通用调用约定](#通用调用约定)
 - [Device Context 设备上下文](#device-context-设备上下文)
+- [Status Bar 原生状态栏](#status-bar-原生状态栏)
 - [Screen 屏幕控制](#screen-屏幕控制)
 - [Notification 原生通知](#notification-原生通知)
 - [TTS 语音播报](#tts-语音播报)
@@ -65,6 +66,8 @@ import glass3, {
 
 | 模块 | 方法 | 用途 |
 | --- | --- | --- |
+| `statusBar` | `setTitle({ title })` | 设置或清理当前 AIX 页面的状态栏标题。 |
+| `statusBar` | `setVisible({ visible })` | 显示或重新隐藏 Native 状态栏。 |
 | `deviceContext` | `get(options?)` | 一次性获取设备上下文原子快照。 |
 | `deviceContext` | `observe(options?, callOptions?)` | 订阅设备上下文快照和增量变化。 |
 | `deviceContext` | `stopObserve({ requestId })` | 停止指定的设备上下文订阅。 |
@@ -218,6 +221,25 @@ const result = await glass3.deviceContext.stopObserve({
 
 详见 [`modules/device-context/readme.md`](./modules/device-context/readme.md)。
 
+## Status Bar 原生状态栏
+
+状态栏是 Host 管理的系统 UI，可在屏幕顶部显示标题、时间、网络和电量。该能力只在
+通过 `OPEN_AIX_INK` 外部入口打开的 AIX 页面中注册，页面创建后默认隐藏。
+
+建议先设置标题，再显示：
+
+```js
+await glass3.statusBar.setTitle({ title: '设备巡检' });
+const result = await glass3.statusBar.setVisible({ visible: true });
+// { updated: true, visible: true }
+```
+
+`title` 必须是字符串；空字符串或全空白字符串用于清理标题。`visible` 必须是
+Boolean。两个方法直接解析 Host RPC HTTP response body，不依赖 `onMessage`，并有
+5 秒本地等待上限。
+
+详见 [`modules/status-bar/readme.md`](./modules/status-bar/readme.md)。
+
 ## Screen 屏幕控制
 
 ### `glass3.screen.turnOff()`
@@ -986,8 +1008,8 @@ export default {
 
 ## Native 映射
 
-所有业务调用使用 RPC `version: "2.0.0"`、`namespace: "rokid.tools"`、
-`method: "invoke"`。
+除 `statusBar` 外的 Host RPC 业务调用使用 `version: "2.0.0"`、
+`namespace: "rokid.tools"`、`method: "invoke"`。
 
 | JavaScript API | `toolName` | `toolAction` |
 | --- | --- | --- |
@@ -1014,12 +1036,16 @@ export default {
 | `motion.startDetect` | `motionDetect` | `start` |
 | `motion.stopDetect` | `motionDetect` | `stop` |
 
+`statusBar.setTitle` 和 `statusBar.setVisible` 使用 `namespace: "rokid.statusBar"`，
+Native method 分别为 `setTitle` 和 `setVisible`，业务参数直接放在 `params` 中。
+
 业务代码应调用公开 JavaScript API，不要直接依赖这张 Native 映射表发 RPC。
 
 ## 详细文档与 Demo
 
 ### 模块文档
 
+- [Status Bar](./modules/status-bar/readme.md)
 - [Device Context](./modules/device-context/readme.md)
 - [Screen](./modules/screen/readme.md)
 - [Notification](./modules/notification/readme.md)
@@ -1032,6 +1058,7 @@ export default {
 
 ### 示例页面
 
+- [Status Bar Demo](../pages/sdk-demo/status-bar/index.ink)
 - [Device Context Demo](../pages/sdk-demo/device-context/index.ink)
 - [Screen Demo](../pages/sdk-demo/screen/index.ink)
 - [Notification Demo Suite](../pages/sdk-demo/notification/index.ink)

package/sdk/api-map.js

@@ -6,11 +6,13 @@ import motion from './modules/motion/index.js';
 import notification from './modules/notification/index.js';
 import offlineCommand from './modules/offline-command/index.js';
 import screen from './modules/screen/index.js';
+import statusBar from './modules/status-bar/index.js';
 import tts from './modules/tts/index.js';
 
 // This map is the only mapping between the public JavaScript API and Host RPC.
 // Public names are never inferred from the native namespace or method strings.
 export const API_MAP = [].concat(
+  statusBar,
   deviceContext,
   notification,
   screen,

package/sdk/core/client.js

@@ -43,12 +43,14 @@ export class Glass3Client {
       requestId,
       namespace: definition.namespace,
       method: definition.method,
-      params: {
-        toolName: definition.toolName,
-        toolAction: definition.toolAction,
-        args: nativeArgs,
-        extra: {}
-      }
+      params: typeof definition.buildRequestParams === 'function'
+        ? definition.buildRequestParams(nativeArgs)
+        : {
+            toolName: definition.toolName,
+            toolAction: definition.toolAction,
+            args: nativeArgs,
+            extra: {}
+          }
     };
 
     if (definition.completion === COMPLETION_EVENT) {
@@ -59,7 +61,12 @@ export class Glass3Client {
       return this.invokeUntilReadyEventStream(definition, request, callOptions);
     }
 
-    return this.invokeUntilAccepted(definition, request, callOptions);
+    return this.invokeUntilAccepted(
+      definition,
+      request,
+      callOptions,
+      timeoutMs
+    );
   }
 
   sendRequest(definition, request) {
@@ -104,7 +111,7 @@ export class Glass3Client {
     return true;
   }
 
-  invokeUntilAccepted(definition, request, callOptions) {
+  invokeUntilAccepted(definition, request, callOptions, timeoutMs) {
     if (typeof callOptions.onEvent === 'function') {
       this.activeInvocations.set(request.requestId, {
         requestId: request.requestId,
@@ -113,13 +120,37 @@ export class Glass3Client {
       });
     }
 
-    return this.sendRequest(definition, request).then(response => {
+    let timeoutId = null;
+    const responsePromise = this.sendRequest(definition, request);
+
+    if (timeoutMs !== undefined) {
+      timeoutId = setTimeout(() => {
+        this.rejectPendingResponse(request.requestId, new Glass3Error(
+          `Glass3 call timed out after ${timeoutMs}ms: ${definition.publicModule}.${definition.publicMethod}`,
+          {
+            code: 'CALL_TIMEOUT',
+            stage: 'timeout',
+            requestId: request.requestId,
+            namespace: definition.namespace,
+            method: definition.method,
+            details: { timeout: timeoutMs }
+          }
+        ));
+      }, timeoutMs);
+    }
+
+    return responsePromise.then(response => {
+      if (timeoutId !== null) clearTimeout(timeoutId);
       this.validateAcceptedResponse(definition, request.requestId, response);
+      if (typeof definition.selectAcceptedResult === 'function') {
+        return definition.selectAcceptedResult(response);
+      }
       return {
         requestId: response.requestId,
         ok: response.ok
       };
     }).catch(error => {
+      if (timeoutId !== null) clearTimeout(timeoutId);
       this.activeInvocations.delete(request.requestId);
       throw this.normalizeInvocationError(error, definition, request.requestId);
     });
@@ -235,22 +266,28 @@ export class Glass3Client {
           acceptedResult.toolName === definition.toolName &&
           acceptedResult.toolAction === definition.toolAction
         );
-    const validResponse = response &&
+    const validChannel = !definition.responseChannel || (
+      response && response.channel === definition.responseChannel
+    );
+    const validEnvelope = response &&
+      validChannel &&
       response.version === RPC_VERSION &&
       response.kind === 'response' &&
-      response.requestId === requestId &&
-      response.ok === true &&
-      validAcceptedResult;
+      response.requestId === requestId;
+    const validResponse = validEnvelope &&
+      response.ok === true && validAcceptedResult;
 
     if (validResponse) return;
 
-    const nativeError = response && response.error;
+    const nativeError = validEnvelope && response.ok === false
+      ? response.error
+      : null;
     throw new Glass3Error(
       nativeError && nativeError.message
         ? nativeError.message
         : `Native request was not accepted: ${definition.publicModule}.${definition.publicMethod}`,
       {
-        code: nativeError && nativeError.code
+        code: nativeError && nativeError.code !== undefined
           ? nativeError.code
           : 'NATIVE_REQUEST_NOT_ACCEPTED',
         stage: 'response',

package/sdk/core/constants.js

@@ -1,6 +1,7 @@
 export const RPC_URL = 'https://ink-host-rpc.invalid/rpc';
 export const RPC_ORIGIN = 'rokid://host-rpc';
 export const RPC_VERSION = '2.0.0';
+export const RPC_CHANNEL = 'rokid.host.rpc';
 
 export const RPC_SUCCESS_STATUS_MIN = 200;
 export const RPC_SUCCESS_STATUS_MAX = 299;

package/sdk/core/transport.js

@@ -22,10 +22,20 @@ export class HostRpcTransport {
       JSON.stringify(redactSensitiveDataForLog(request))
     );
 
-    return requestFetch(this.url, {
+    return Promise.resolve().then(() => requestFetch(this.url, {
       method: 'POST',
       headers: { 'content-type': 'application/json' },
       body: requestBody
+    })).catch(error => {
+      if (error instanceof Glass3Error) throw error;
+      throw new Glass3Error('Host RPC transport failed', {
+        code: 'TRANSPORT_ERROR',
+        stage: 'transport',
+        requestId: request.requestId,
+        namespace: request.namespace,
+        method: request.method,
+        cause: error
+      });
     }).then(response => {
       if (
         response.status < RPC_SUCCESS_STATUS_MIN ||
@@ -43,7 +53,16 @@ export class HostRpcTransport {
         );
       }
 
-      return response.json();
+      return Promise.resolve().then(() => response.json()).catch(error => {
+        throw new Glass3Error('Host RPC response is not valid JSON', {
+          code: 'TRANSPORT_INVALID_RESPONSE',
+          stage: 'transport',
+          requestId: request.requestId,
+          namespace: request.namespace,
+          method: request.method,
+          cause: error
+        });
+      });
     }).then(result => {
       console.log(
         '[glass3] Native fetch response:',

package/sdk/modules/status-bar/index.js

@@ -0,0 +1,78 @@
+import { RPC_CHANNEL } from '../../core/constants.js';
+import { Glass3Error } from '../../utils/errors.js';
+
+const STATUS_BAR_NAMESPACE = 'rokid.statusBar';
+const STATUS_BAR_TIMEOUT_MS = 5000;
+
+function createParameterError(message, method) {
+  return new Glass3Error(message, {
+    code: 'INVALID_PARAMS',
+    stage: 'params',
+    namespace: STATUS_BAR_NAMESPACE,
+    method
+  });
+}
+
+function buildSingleFieldArgs(field, type, method) {
+  return args => {
+    if (!args || typeof args !== 'object' || Array.isArray(args)) {
+      throw createParameterError(
+        `statusBar.${method} parameters must be an object`,
+        method
+      );
+    }
+
+    const fields = Object.keys(args);
+    if (fields.length !== 1 || fields[0] !== field) {
+      throw createParameterError(
+        `statusBar.${method} only supports ${field}`,
+        method
+      );
+    }
+
+    if (typeof args[field] !== type) {
+      throw createParameterError(
+        `statusBar.${method} ${field} must be a ${type}`,
+        method
+      );
+    }
+
+    return { [field]: args[field] };
+  };
+}
+
+function directParams(args) {
+  return args;
+}
+
+function selectResult(response) {
+  return response.result;
+}
+
+function createStatusBarDefinition(publicMethod, field, type) {
+  return {
+    publicModule: 'statusBar',
+    publicMethod,
+
+    namespace: STATUS_BAR_NAMESPACE,
+    method: publicMethod,
+    responseChannel: RPC_CHANNEL,
+
+    buildArgs: buildSingleFieldArgs(field, type, publicMethod),
+    buildRequestParams: directParams,
+    getTimeoutMs() {
+      return STATUS_BAR_TIMEOUT_MS;
+    },
+    isAcceptedResponseResult(result) {
+      if (!result || typeof result.updated !== 'boolean') return false;
+      return publicMethod !== 'setVisible' ||
+        typeof result.visible === 'boolean';
+    },
+    selectAcceptedResult: selectResult
+  };
+}
+
+export default [
+  createStatusBarDefinition('setTitle', 'title', 'string'),
+  createStatusBarDefinition('setVisible', 'visible', 'boolean')
+];

package/sdk/modules/status-bar/readme.md

@@ -0,0 +1,66 @@
+# Status Bar 原生状态栏
+
+`glass3.statusBar` 通过同步 HTTP response body 的 Host RPC 控制 AIX 页面顶部的
+系统状态栏。状态栏由 Native 绘制，可显示标题、时间、网络和电量；调用结果不依赖
+页面 `onMessage`。
+
+该能力只在通过外部 `OPEN_AIX_INK` 入口打开的 AIX 页面中注册。页面建立后默认隐藏
+状态栏，普通浏览器、普通 WebView 和普通 AI 卡片中调用会失败。
+
+## API
+
+### `glass3.statusBar.setTitle({ title })`
+
+设置当前页面的状态栏标题：
+
+```js
+const result = await glass3.statusBar.setTitle({
+  title: '设备巡检'
+});
+// { updated: true }
+```
+
+- `title` 必须是字符串，SDK 不会隐式转换类型。
+- Native 会去除首尾空白，当前最多展示前 40 个字符。
+- 空字符串或全空白字符串表示清理标题。
+- 状态栏隐藏时会保存标题，并在下次显示时应用。
+
+### `glass3.statusBar.setVisible({ visible })`
+
+申请显示或重新隐藏状态栏：
+
+```js
+const result = await glass3.statusBar.setVisible({ visible: true });
+// { updated: true, visible: true }
+```
+
+`visible` 必须是 Boolean，字符串 `"true"` 和数字 `1` 均会被 SDK 拒绝。
+
+建议先设置标题，再显示状态栏：
+
+```js
+await glass3.statusBar.setTitle({ title: '设备巡检' });
+await glass3.statusBar.setVisible({ visible: true });
+```
+
+`visible: false` 会隐藏当前状态栏，但不会删除页面保存的标题。再次显示时，Native 会
+恢复此前的标题。
+
+## 返回、超时与错误
+
+两个方法都直接返回 Host RPC `result`，并严格校验响应的 `channel`、`version`、
+`kind` 和 `requestId`。每次调用的本地等待上限为 5 秒；`CALL_TIMEOUT` 只表示 SDK
+停止等待，不能据此判断 Native 一定没有执行。
+
+- 参数错误：`INVALID_PARAMS`，`stage: "params"`。
+- fetch 失败：`TRANSPORT_ERROR`，`stage: "transport"`。
+- HTTP 非 2xx：`TRANSPORT_REJECTED`，`stage: "transport"`。
+- body 不是合法 JSON：`TRANSPORT_INVALID_RESPONSE`，`stage: "transport"`。
+- Native RPC 错误：保留 Native `error.code`，`stage: "response"`。
+- 响应信封不合法：`NATIVE_REQUEST_NOT_ACCEPTED`，`stage: "response"`。
+
+## 生命周期
+
+Native 按 AIX 页面 owner 保存和回收状态栏资源。页面进入后台、释放或进程结束时，
+Native 会清理对其他页面可能产生的影响。页面可以主动调用
+`setVisible({ visible: false })`，但不需要用全局 JavaScript 状态恢复资源。