@aiot-nexus/plugin-sdk 2.1.0 → 2.1.1

package/README.md

@@ -1,6 +1,6 @@
 # @aiot-nexus/plugin-sdk
 
-> 版本适用性：当前包版本为 `2.1.0`，面向 Framework API `2.1.0` 的 v2 worker/RPC 模型，并兼容仍声明 `2.0.x` 的插件。1.x SDK 和同步 Host API 已停止适用，但其历史语义保留在本文末尾和 [v1 到 v2 迁移说明](../docs/plugin-framework-v1-v2-migration.md)；2.x 不提供 1.x 运行模型兼容层。
+> 版本适用性：当前包版本为 `2.1.1`，面向 Framework API `2.1.0` 的 v2 worker/RPC 模型，并兼容仍声明 `2.0.x` 的插件。1.x SDK 和同步 Host API 已停止适用，但其历史语义保留在本文末尾和 [v1 到 v2 迁移说明](../docs/plugin-framework-v1-v2-migration.md)；2.x 不提供 1.x 运行模型兼容层。
 
 AIoT Nexus 独立插件开发包，包含公开 TypeScript 契约、PluginFrame 浏览器客户端和 `nexus-plugin` 命令行工具。
 
@@ -39,7 +39,7 @@ SDK 提供两层非阻塞版本检查：
 - `nexus-plugin` 启动时先读取缓存。缓存新鲜期为 24 小时；缓存缺失或过期时在后台检查，不等待网络，不改变命令退出码。检测到普通更新时会显示：
 
   ```text
-  npm notice Update available for @aiot-nexus/plugin-sdk: 2.1.0 -> 2.2.0
+  npm notice Update available for @aiot-nexus/plugin-sdk: 2.1.1 -> 2.2.0
   npm notice Run npm install --save-dev @aiot-nexus/plugin-sdk@latest
   ```
 
@@ -68,7 +68,7 @@ nexus-plugin create my-frame-plugin \
 - 目标目录非空时命令以返回码 `2` 拒绝覆盖。生成或安装失败返回 `1`。
 - 两套模板均读取宿主 `PluginRendererContext.language` 和 `themeMode`，通过 `onContextChanged` 在同一 iframe 内响应运行时语言与主题切换，并内置 `zh-CN` / `en-US` renderer 文案；manifest 使用相同文化资源本地化宿主入口。模板页面自身不提供语言或主题选择控件。
 
-默认来源从 npm registry 安装。离线开发时先执行 `npm run pack:sdk`，再通过 `--sdk-source /path/to/aiot-nexus-plugin-sdk-2.1.0.tgz` 指定本地包；CLI 会把本地包一并放入生成工程。
+默认来源从 npm registry 安装。离线开发时先执行 `npm run pack:sdk`，再通过 `--sdk-source /path/to/aiot-nexus-plugin-sdk-2.1.1.tgz` 指定本地包；CLI 会把本地包一并放入生成工程。
 
 ### SQLite 数据库浏览器模板
 
@@ -76,7 +76,7 @@ nexus-plugin create my-frame-plugin \
 
 最近选择的外部路径会原子写入插件数据目录的 `sqlite-browser-state.json`。下次启动会先尝试恢复；文件缺失、损坏或不再是 SQLite 时清除记录、回退 `plugin.db`，并在页面显示恢复提示。外部数据库不会执行示例表建表或 journal pragma。
 
-模板按 `table_list` / `table_xinfo` 动态显示普通用户表、列类型、SQLite affinity、主键、NULL、默认值和生成列。新增字段可选“使用默认值 / NULL / 输入值”，编辑字段可选“不修改 / NULL / 输入值”；INTEGER 使用精确十进制整数，REAL 必须有限，NUMERIC 可输入整数、浮点或文本，BLOB 输入偶数长度十六进制并按解码后的实际字节数计入 1 MiB/4 MiB 限制。普通 rowid 表优先用内建 rowid 定位；`WITHOUT ROWID` 表或 rowid 别名全部被遮蔽的表只回退到全部非空的单/复合主键。没有唯一 locator 的表仍可浏览和新增，但禁用编辑、删除；更新和删除在事务内要求恰好命中一行。表格中的 TEXT 预览最多 16 KiB，BLOB 只显示字节数和前 32 字节。
+模板按 `table_list` / `table_xinfo` 动态显示普通用户表、列类型、SQLite affinity、主键、NULL、默认值和生成列。新增字段可选“使用默认值 / NULL / 输入值”，编辑字段可选“不修改 / NULL / 输入值”；INTEGER 使用精确十进制整数，REAL 必须有限，NUMERIC 可输入整数、浮点或文本，BLOB 输入偶数长度十六进制并按解码后的实际字节数计入 1 MiB/4 MiB 限制。普通 rowid 表优先用内建 rowid 定位；`WITHOUT ROWID` 表或 rowid 别名全部被遮蔽的表只回退到全部非空的单/复合主键。没有唯一 locator 的表仍可浏览和新增，超过 16 KiB 的主键 locator 也按只读行处理；更新和删除在事务内要求恰好命中一行。表格中的 TEXT 预览最多读取 16 KiB UTF-8 数据，BLOB 只读取总字节数和前 32 字节，避免把完整大字段复制进插件 worker 和 iframe。
 
 该模板刻意不依赖 Quasar，以保持独立插件依赖最小化，因此数据库网格使用原生 `<table>`，这是宿主默认 `QTable` 规则之外的 SDK 模板例外。页面仍包含分页、横向表格滚动、中英文、亮暗主题、busy/empty/error 状态和窄窗口布局。
 
@@ -113,7 +113,7 @@ nexus-plugin dev [plugin-project-directory]
   [--no-devtools]
 ```
 
-调试宿主工具栏中的语言和主题选择器用于模拟 Nexus 主框架 context，不属于插件页面。切换后调试宿主向同一 iframe 重发框架 `2.1.0` 的 `init` 消息；SDK 将后续 `init` 作为 context 更新并原地刷新语言和主题，同时仍接受可选的 `context-changed` 消息。调试宿主还复用正式的 `nexus-plugin://` 资源协议、iframe sandbox、CSP、消息结构、operation 校验、Electron Facade 和当前 Host API 权限语义，但不包含 Nexus 的完整页面路由、Pinia 状态和应用级功能。`mainEntry` 的激活、deactivate、Host API 请求和 renderer operation 调用都通过异步 RPC 连接 worker；交付前仍需把 `dist/<plugin-id>/` 放入正式 Nexus 完成集成验证。
+调试宿主工具栏中的语言和主题选择器用于模拟 Nexus 主框架 context，不属于插件页面。除该工具栏外，插件 iframe 无边距、无边框地填满窗口剩余区域；宿主不根据插件上报的内容尺寸限制 iframe 宽高，Electron 调试窗口也不设置最小宽高。切换 context 后调试宿主向同一 iframe 重发框架 `2.1.0` 的 `init` 消息；SDK 将后续 `init` 作为 context 更新并原地刷新语言和主题，同时仍接受可选的 `context-changed` 消息。调试宿主还复用正式的 `nexus-plugin://` 资源协议、iframe sandbox、CSP、消息结构、operation 校验、Electron Facade 和当前 Host API 权限语义，但不包含 Nexus 的完整页面路由、Pinia 状态和应用级功能。`mainEntry` 的激活、deactivate、Host API 请求和 renderer operation 调用都通过异步 RPC 连接 worker；交付前仍需把 `dist/<plugin-id>/` 放入正式 Nexus 完成集成验证。
 
 浏览器 UI 命令支持 `--no-build`、`--no-open`、`--port <port>`，以及与 Electron 调试宿主相同的 `--language`、`--theme`、`--surface` 和 `--contribution-id` 参数。它使用普通 `http://127.0.0.1` iframe，不模拟 `nexus-plugin://` 协议或 Electron sandbox，因此只作为 UI 开发入口。Renderer-only 输出不会覆盖正式插件制品。
 

package/dev-host/host.html

@@ -34,9 +34,11 @@
       html,
       body {
         width: 100%;
+        height: 100%;
         min-width: 0;
-        min-height: 100%;
+        min-height: 0;
         margin: 0;
+        overflow: hidden;
         background: var(--page);
         color: var(--text);
       }
@@ -51,6 +53,7 @@
         top: 0;
         z-index: 1;
         display: flex;
+        flex: 0 0 auto;
         align-items: center;
         min-height: 48px;
         gap: 12px;
@@ -117,18 +120,21 @@
       .frame-shell {
         display: flex;
         flex-direction: column;
-        flex: 1 1 auto;
+        flex: 1 1 0;
         min-width: 0;
-        padding: 12px;
-        overflow: auto;
+        min-height: 0;
+        padding: 0;
+        overflow: hidden;
       }
 
       iframe {
         display: block;
-        flex: 1 1 auto;
+        flex: 1 1 0;
         width: 100%;
-        min-height: 360px;
-        border: 1px solid var(--border);
+        height: 100%;
+        min-width: 0;
+        min-height: 0;
+        border: 0;
         background: var(--surface);
       }
 
@@ -146,10 +152,6 @@
         .status {
           margin-left: auto;
         }
-
-        .frame-shell {
-          padding: 8px;
-        }
       }
     </style>
   </head>
@@ -255,7 +257,6 @@
           return;
         }
         if (message.type === "nexus-plugin:resize" && typeof message.height === "number") {
-          iframe.style.height = Math.min(6000, Math.max(160, Math.ceil(message.height))) + "px";
           resizeSeen = true;
           scheduleSmokeReport();
           return;

package/dev-host/main.js

@@ -832,8 +832,6 @@ function createWindow() {
   mainWindow = new BrowserWindow({
     width: 1200,
     height: 800,
-    minWidth: 640,
-    minHeight: 480,
     show: !configuration.smoke,
     backgroundColor: configuration.themeMode === "dark" ? "#181a1d" : "#f4f5f7",
     webPreferences: {

package/dist/src/index.d.ts

@@ -1,5 +1,5 @@
 import pluginManifestSchema from "../.generated/plugin-manifest.schema.json";
-export declare const PLUGIN_SDK_VERSION = "2.1.0";
+export declare const PLUGIN_SDK_VERSION = "2.1.1";
 export { pluginManifestSchema };
 export * from "../.generated/plugin-framework-version";
 export * from "./types";

package/dist/src/index.js

@@ -20,7 +20,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.pluginManifestSchema = exports.PLUGIN_SDK_VERSION = void 0;
 const plugin_manifest_schema_json_1 = __importDefault(require("../.generated/plugin-manifest.schema.json"));
 exports.pluginManifestSchema = plugin_manifest_schema_json_1.default;
-exports.PLUGIN_SDK_VERSION = "2.1.0";
+exports.PLUGIN_SDK_VERSION = "2.1.1";
 __exportStar(require("../.generated/plugin-framework-version"), exports);
 __exportStar(require("./types"), exports);
 __exportStar(require("./electron-facade"), exports);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiot-nexus/plugin-sdk",
-  "version": "2.1.0",
+  "version": "2.1.1",
   "description": "Types, PluginFrame client, and CLI for AIoT Nexus independent plugins.",
   "license": "UNLICENSED",
   "publishConfig": {

package/templates/minimal/README.md.tmpl

@@ -23,16 +23,64 @@ The deployable plugin package is `dist/__PLUGIN_ID__/`. For a manual installatio
 
 ```ts
 import * as fs from "fs/promises";
-import type { PluginMainActivationContext } from "@aiot-nexus/plugin-sdk";
+import type { NexusResult, PluginMainActivationContext } from "@aiot-nexus/plugin-sdk";
 
-export async function chooseAndReadText(context: PluginMainActivationContext): Promise<string | undefined> {
+const maximumTextFileBytes = 1024 * 1024;
+
+export async function chooseAndReadText(
+  context: PluginMainActivationContext
+): Promise<NexusResult<string | undefined>> {
   const result = await context.host.electron.dialog.showOpenDialog({
     properties: ["openFile"],
     filters: [{ name: "Text", extensions: ["txt", "md", "json"] }]
   });
-  return result.canceled || !result.filePaths[0]
-    ? undefined
-    : fs.readFile(result.filePaths[0], "utf8");
+  if (result.canceled || !result.filePaths[0]) {
+    return { ok: true, value: undefined };
+  }
+  return readTextFileBounded(result.filePaths[0]);
+}
+
+async function readTextFileBounded(filePath: string): Promise<NexusResult<string>> {
+  try {
+    const file = await fs.open(filePath, "r");
+    try {
+      const stat = await file.stat();
+      if (!stat.isFile()) {
+        return failure("FileNotReadable", "The selected path is not a regular file.");
+      }
+      if (stat.size > maximumTextFileBytes) {
+        return failure("FileTooLarge", "The selected text file exceeds the 1 MiB limit.");
+      }
+
+      // The extra byte detects a file that grows after stat without an unbounded allocation.
+      const buffer = Buffer.alloc(maximumTextFileBytes + 1);
+      let totalBytes = 0;
+      while (totalBytes < buffer.length) {
+        const { bytesRead } = await file.read(
+          buffer,
+          totalBytes,
+          buffer.length - totalBytes,
+          totalBytes
+        );
+        if (bytesRead === 0) {
+          break;
+        }
+        totalBytes += bytesRead;
+      }
+      if (totalBytes > maximumTextFileBytes) {
+        return failure("FileTooLarge", "The selected text file exceeds the 1 MiB limit.");
+      }
+      return { ok: true, value: buffer.subarray(0, totalBytes).toString("utf8") };
+    } finally {
+      await file.close();
+    }
+  } catch {
+    return failure("FileReadFailed", "The selected text file could not be read.");
+  }
+}
+
+function failure(code: string, message: string): NexusResult<never> {
+  return { ok: false, error: { code, message } };
 }
 
 export async function chooseFolder(context: PluginMainActivationContext): Promise<string | undefined> {
@@ -48,11 +96,11 @@ export async function chooseSavePath(context: PluginMainActivationContext): Prom
 }
 ```
 
-Call these helpers from an operation registered with `context.host.registerRendererMethod`, then let the renderer invoke that narrow operation through `client.invokeMain()`. Do not expose the Facade or unrestricted file paths to the iframe. `npm run dev:web` is renderer-only and deliberately has no `mainEntry`, Node filesystem, or Electron Facade; use `npm run dev` or a formal Nexus host to test these dialogs.
+Call these helpers from an operation registered with `context.host.registerRendererMethod`, then let the renderer invoke that narrow operation through `client.invokeMain()`. Return the `NexusResult` from `chooseAndReadText` directly so the renderer receives the stable `FileNotReadable`, `FileTooLarge`, or `FileReadFailed` code. Do not expose the Facade or unrestricted file paths to the iframe. For larger files, stream or paginate in `mainEntry` and return only bounded chunks or summaries instead of the whole file. `npm run dev:web` is renderer-only and deliberately has no `mainEntry`, Node filesystem, or Electron Facade; use `npm run dev` or a formal Nexus host to test these dialogs.
 
 The renderer calls the plugin-worker `demo.echo` operation through `@aiot-nexus/plugin-sdk`. The worker also calls `context.host.electron.app.getName()` during activation, so `npm run dev` verifies the real asynchronous Electron Facade path. Run `npm run validate` after changing the manifest or output layout.
 
-The renderer follows `context.language` and `context.themeMode` from Nexus, subscribes to in-place context updates without reloading the iframe, and includes `en-US` and `zh-CN` message catalogs. The plugin page has no language or theme selector; the controls shown by `npm run dev` belong to the debug host and simulate Nexus context changes. Add or edit renderer messages in `src/renderer/app.ts`; edit host-shell titles and descriptions in `src/manifest.json` resources.
+The renderer follows `context.language` and `context.themeMode` from Nexus, subscribes to in-place context updates without reloading the iframe, and includes `en-US` and `zh-CN` message catalogs. The plugin page has no language or theme selector; the controls shown by `npm run dev` belong to the debug host and simulate Nexus context changes. Below that toolbar, the iframe has no host padding, border, minimum size, or content-driven height and fills the remaining host viewport. Add or edit renderer messages in `src/renderer/app.ts`; edit host-shell titles and descriptions in `src/manifest.json` resources.
 
 The current SDK has no generic business-event subscription API. For a long-running operation, register a fast `job.start` operation that returns a `taskId`, then expose `job.getStatus` and optional `job.cancel` for renderer polling. See the Nexus repository's plugin IPC and event notification example for the full contract and code.
 

package/templates/sqlite/README.md.tmpl

@@ -45,9 +45,9 @@ For related workflows, use `properties: ["openDirectory", "createDirectory"]` to
 
 External files are opened read/write only after a separate candidate connection can query `sqlite_schema`. Canceling the dialog or selecting a corrupt, locked, or inaccessible file keeps the current connection. The latest external path is atomically stored as `sqlite-browser-state.json` in the plugin data directory. Startup restores it when valid; otherwise the template clears the saved selection, falls back to `plugin.db`, and returns a visible notice. External databases do not receive the sample schema or journal pragma.
 
-The table selector lists ordinary user tables from the `main` schema. Dynamic headers show declared type, SQLite affinity, primary-key order, NULL, default, and generated-column metadata. The editor supports default/NULL/value modes for inserts and unchanged/NULL/value modes for updates. INTEGER input uses exact decimal integers, REAL must be finite, NUMERIC accepts integer, real, or text values, and BLOB input uses even-length hexadecimal text. The 1 MiB field and 4 MiB row limits count decoded BLOB bytes rather than hexadecimal characters. Ordinary rowid tables prefer an unshadowed built-in rowid; `WITHOUT ROWID` tables, or tables that shadow every rowid alias, fall back only to primary-key columns that are all non-NULL. A table without a unique locator remains browsable and insertable, but update and delete are unavailable. Update and delete run in a transaction and must affect exactly one row. TEXT previews are capped at 16 KiB; BLOB previews show the byte length and first 32 bytes.
+The table selector lists ordinary user tables from the `main` schema. Dynamic headers show declared type, SQLite affinity, primary-key order, NULL, default, and generated-column metadata. The editor supports default/NULL/value modes for inserts and unchanged/NULL/value modes for updates. INTEGER input uses exact decimal integers, REAL must be finite, NUMERIC accepts integer, real, or text values, and BLOB input uses even-length hexadecimal text. The 1 MiB field and 4 MiB row limits count decoded BLOB bytes rather than hexadecimal characters. Ordinary rowid tables prefer an unshadowed built-in rowid; `WITHOUT ROWID` tables, or tables that shadow every rowid alias, fall back only to primary-key columns that are all non-NULL. A table without a unique locator remains browsable and insertable, but update and delete are unavailable. Primary-key locators larger than 16 KiB are also treated as browse-only so a page cannot copy unbounded keys into the plugin worker and iframe. Update and delete run in a transaction and must affect exactly one row. TEXT previews are capped at 16 KiB of UTF-8 data; BLOB previews show the byte length and first 32 bytes.
 
-The renderer follows `context.language` and `context.themeMode` from Nexus and preserves unfinished editor values during in-place context updates. The plugin page has no language or theme selector; the controls shown by `npm run dev` belong to the debug host. This SDK template deliberately has no Quasar dependency, so its data grid uses a native `<table>` as a dependency-minimized template exception. It still provides pagination, contained horizontal scrolling, light/dark themes, `en-US` / `zh-CN`, and busy/empty/error states. Edit renderer messages in `src/renderer/app.ts`; edit host-shell titles and descriptions in `src/manifest.json` resources.
+The renderer follows `context.language` and `context.themeMode` from Nexus and preserves unfinished editor values during in-place context updates. The plugin page has no language or theme selector; the controls shown by `npm run dev` belong to the debug host. Below that toolbar, the iframe has no host padding, border, minimum size, or content-driven height and fills the remaining host viewport. This SDK template deliberately has no Quasar dependency, so its data grid uses a native `<table>` as a dependency-minimized template exception. It still provides pagination, contained horizontal scrolling, light/dark themes, `en-US` / `zh-CN`, and busy/empty/error states. Edit renderer messages in `src/renderer/app.ts`; edit host-shell titles and descriptions in `src/manifest.json` resources.
 
 The current SDK has no generic business-event subscription API. For a long-running operation, register a fast `job.start` operation that returns a `taskId`, then expose `job.getStatus` and optional `job.cancel` for renderer polling. See the Nexus repository's plugin IPC and event notification example for the full contract and code.
 

package/templates/sqlite/src/main.ts.tmpl

@@ -131,10 +131,14 @@ const defaultDatabaseName = "plugin.db";
 const stateFileName = "sqlite-browser-state.json";
 const defaultTableName = "plugin_records";
 const allowedPageSizes = new Set([25, 50, 100]);
-const maximumTextPreviewLength = 16 * 1024;
+const maximumTextPreviewBytes = 16 * 1024;
 const maximumBlobPreviewBytes = 32;
 const maximumFieldBytes = 1024 * 1024;
 const maximumRequestBytes = 4 * 1024 * 1024;
+const maximumBlobInputCharacters = maximumFieldBytes * 2 + 4096;
+const maximumLocatorBytes = 16 * 1024;
+const maximumSqliteIntegerCharacters = 20;
+const projectedValuesPerColumn = 4;
 const minimumSqliteInteger = -(1n << 63n);
 const maximumSqliteInteger = (1n << 63n) - 1n;
 
@@ -365,11 +369,9 @@ function readTable(request: PluginRendererOperationRequest): {
   const connection = requireDatabase().connection;
   const schema = readTableSchema(connection, tableName);
   const totalRows = readCount(connection, schema.summary.name);
-  const selectColumns = schema.visibleColumns.map((column) => quoteIdentifier(column.name));
-  const hasRowidLocator = schema.locator?.kind === "rowid" && schema.locator.rowidAlias;
   const selectList = [
-    ...(hasRowidLocator ? [schema.locator?.rowidAlias as string] : []),
-    ...selectColumns
+    ...locatorProjection(schema),
+    ...schema.visibleColumns.flatMap(previewProjection)
   ].join(", ");
   const orderBy = orderByClause(schema.locator);
   const rawRows = requireArrayRows(
@@ -544,32 +546,71 @@ function createLocatorSpec(summary: TableSummary, columns: ColumnInfo[]): Locato
   return undefined;
 }
 
+function locatorProjection(schema: TableSchema): string[] {
+  const spec = schema.locator;
+  if (!spec) {
+    return [];
+  }
+  if (spec.kind === "rowid") {
+    return [spec.rowidAlias as string];
+  }
+  return spec.columns.map((column) => {
+    const identifier = quoteIdentifier(column);
+    return "CASE WHEN typeof(" + identifier + ") IN ('text', 'blob')"
+      + " AND length(CAST(" + identifier + " AS BLOB)) > " + String(maximumLocatorBytes)
+      + " THEN NULL ELSE " + identifier + " END";
+  });
+}
+
+function previewProjection(column: ColumnInfo): string[] {
+  const identifier = quoteIdentifier(column.name);
+  const storageType = "typeof(" + identifier + ")";
+  return [
+    storageType,
+    "CASE WHEN " + storageType + " = 'text' THEN length(" + identifier + ") ELSE NULL END",
+    "CASE WHEN " + storageType + " IN ('text', 'blob') THEN length(CAST(" + identifier + " AS BLOB)) ELSE NULL END",
+    "CASE " + storageType
+      + " WHEN 'text' THEN substr(" + identifier + ", 1, " + String(maximumTextPreviewBytes) + ")"
+      + " WHEN 'blob' THEN substr(" + identifier + ", 1, " + String(maximumBlobPreviewBytes) + ")"
+      + " ELSE " + identifier + " END"
+  ];
+}
+
 function readTableRow(schema: TableSchema, rawRow: unknown[]): TableRow {
-  const rowidOffset = schema.locator?.kind === "rowid" ? 1 : 0;
-  if (rawRow.length !== schema.visibleColumns.length + rowidOffset) {
+  const locatorValueCount = schema.locator?.columns.length || 0;
+  const expectedValueCount = locatorValueCount + schema.visibleColumns.length * projectedValuesPerColumn;
+  if (rawRow.length !== expectedValueCount) {
     throw new Error("SQLite table row has an unexpected column count.");
   }
-  const cells = schema.visibleColumns.map((column, index) => ({
-    column: column.name,
-    value: serializePreviewValue(rawRow[index + rowidOffset])
-  }));
-  const locator = createRowLocator(schema, rawRow, rowidOffset);
+  const cells = schema.visibleColumns.map((column, index) => {
+    const valueOffset = locatorValueCount + index * projectedValuesPerColumn;
+    return {
+      column: column.name,
+      value: serializeProjectedValue(
+        rawRow[valueOffset],
+        rawRow[valueOffset + 1],
+        rawRow[valueOffset + 2],
+        rawRow[valueOffset + 3]
+      )
+    };
+  });
+  const locator = createRowLocator(schema, rawRow.slice(0, locatorValueCount));
   return { cells, ...(locator ? { locator } : {}) };
 }
 
-function createRowLocator(schema: TableSchema, rawRow: unknown[], rowidOffset: number): RowLocator | undefined {
+function createRowLocator(schema: TableSchema, rawLocatorValues: unknown[]): RowLocator | undefined {
   const spec = schema.locator;
   if (!spec) {
     return undefined;
   }
   if (spec.kind === "rowid") {
-    const value = serializeLocatorValue(rawRow[0]);
+    const value = serializeLocatorValue(rawLocatorValues[0]);
     return value ? { kind: "rowid", values: [{ column: spec.columns[0], value }] } : undefined;
   }
   const values: LocatorValue[] = [];
-  for (const columnName of spec.columns) {
-    const index = schema.visibleColumns.findIndex((column) => column.name === columnName);
-    const value = index < 0 ? undefined : serializeLocatorValue(rawRow[index + rowidOffset]);
+  for (let index = 0; index < spec.columns.length; index += 1) {
+    const columnName = spec.columns[index];
+    const value = serializeLocatorValue(rawLocatorValues[index]);
     if (!value) {
       return undefined;
     }
@@ -578,42 +619,73 @@ function createRowLocator(schema: TableSchema, rawRow: unknown[], rowidOffset: n
   return { kind: "primaryKey", values };
 }
 
-function serializePreviewValue(value: unknown): WireValue {
-  if (value === null || value === undefined) {
+function serializeProjectedValue(
+  storageType: unknown,
+  characterLength: unknown,
+  byteLength: unknown,
+  preview: unknown
+): WireValue {
+  if (storageType === "null" && (preview === null || preview === undefined)) {
     return { kind: "null" };
   }
-  if (typeof value === "bigint") {
-    return { kind: "integer", value: value.toString() };
+  if (storageType === "integer" && typeof preview === "bigint") {
+    return { kind: "integer", value: preview.toString() };
   }
-  if (typeof value === "number") {
-    return Number.isInteger(value)
-      ? { kind: "integer", value: String(value) }
-      : { kind: "real", value };
+  if (storageType === "integer" && typeof preview === "number" && Number.isSafeInteger(preview)) {
+    return { kind: "integer", value: String(preview) };
   }
-  if (typeof value === "string") {
+  if (storageType === "real" && typeof preview === "number" && Number.isFinite(preview)) {
+    return { kind: "real", value: preview };
+  }
+  if (storageType === "text" && typeof preview === "string") {
+    const totalCharacters = integerNumber(characterLength, "text character length");
+    const totalBytes = integerNumber(byteLength, "text byte length");
+    const boundedPreview = truncateUtf8(preview, maximumTextPreviewBytes);
     return {
       kind: "text",
-      value: value.slice(0, maximumTextPreviewLength),
-      length: value.length,
-      truncated: value.length > maximumTextPreviewLength
+      value: boundedPreview,
+      length: totalCharacters,
+      truncated: Buffer.byteLength(boundedPreview, "utf8") < totalBytes
     };
   }
-  if (Buffer.isBuffer(value)) {
+  if (storageType === "blob" && Buffer.isBuffer(preview)) {
+    const totalBytes = integerNumber(byteLength, "BLOB byte length");
     return {
       kind: "blob",
-      hex: value.subarray(0, maximumBlobPreviewBytes).toString("hex"),
-      byteLength: value.length,
-      truncated: value.length > maximumBlobPreviewBytes
+      hex: preview.toString("hex"),
+      byteLength: totalBytes,
+      truncated: preview.length < totalBytes
     };
   }
-  throw new Error("SQLite returned an unsupported cell value.");
+  throw new Error("SQLite returned malformed projected cell data.");
+}
+
+function truncateUtf8(value: string, maximumBytes: number): string {
+  if (Buffer.byteLength(value, "utf8") <= maximumBytes) {
+    return value;
+  }
+  const characters: string[] = [];
+  let byteLength = 0;
+  for (const character of value) {
+    const characterBytes = Buffer.byteLength(character, "utf8");
+    if (byteLength + characterBytes > maximumBytes) {
+      break;
+    }
+    characters.push(character);
+    byteLength += characterBytes;
+  }
+  return characters.join("");
 }
 
 function serializeLocatorValue(value: unknown): WireValue | undefined {
-  if (typeof value === "string" && Buffer.byteLength(value, "utf8") > maximumFieldBytes) {
+  if (value === null || value === undefined) {
+    return undefined;
+  }
+  if (typeof value === "string" && (value.length > maximumLocatorBytes
+    || Buffer.byteLength(value, "utf8") > maximumLocatorBytes)) {
     return undefined;
   }
-  if (Buffer.isBuffer(value) && value.length > maximumFieldBytes) {
+  if (Buffer.isBuffer(value) && value.length > maximumLocatorBytes) {
     return undefined;
   }
   if (typeof value === "string") {
@@ -622,7 +694,15 @@ function serializeLocatorValue(value: unknown): WireValue | undefined {
   if (Buffer.isBuffer(value)) {
     return { kind: "blob", hex: value.toString("hex"), byteLength: value.length, truncated: false };
   }
-  return serializePreviewValue(value);
+  if (typeof value === "bigint") {
+    return { kind: "integer", value: value.toString() };
+  }
+  if (typeof value === "number" && Number.isFinite(value)) {
+    return Number.isInteger(value)
+      ? { kind: "integer", value: String(value) }
+      : { kind: "real", value };
+  }
+  return undefined;
 }
 
 function parseMutations(schema: TableSchema, value: unknown, mode: "insert" | "update"): ParsedMutations {
@@ -687,12 +767,23 @@ function readMutationValue(value: unknown, columnName: string): MutationValue {
 }
 
 function convertInputValue(column: ColumnInfo, source: string): ConvertedInputValue {
-  const sourceBytes = Buffer.byteLength(source, "utf8");
-  if (column.affinity === "integer") {
-    if (!/^[+-]?\d+$/.test(source)) {
-      throw codedError("InvalidRequest", "Column requires an integer: " + column.name);
+  if (column.affinity === "blob") {
+    if (source.length > maximumBlobInputCharacters) {
+      throw codedError("InvalidRequest", "BLOB value exceeds the accepted encoded input size: " + column.name);
     }
-    return { value: parseSqliteInteger(source, column.name), byteLength: sourceBytes };
+    const normalized = source.replace(/\s+/g, "");
+    if (normalized.length > maximumFieldBytes * 2) {
+      throw codedError("InvalidRequest", "BLOB value exceeds the 1 MiB limit: " + column.name);
+    }
+    if (normalized.length % 2 !== 0 || !/^[0-9a-fA-F]*$/.test(normalized)) {
+      throw codedError("InvalidRequest", "BLOB columns require an even-length hexadecimal value: " + column.name);
+    }
+    const buffer = Buffer.from(normalized, "hex");
+    return { value: buffer, byteLength: buffer.length };
+  }
+  const sourceBytes = boundedUtf8ByteLength(source, maximumFieldBytes, "Column value exceeds the 1 MiB limit: " + column.name);
+  if (column.affinity === "integer") {
+    return { value: parseSqliteInteger(source, "Column " + column.name), byteLength: sourceBytes };
   }
   if (column.affinity === "real") {
     const parsed = Number(source);
@@ -703,7 +794,7 @@ function convertInputValue(column: ColumnInfo, source: string): ConvertedInputVa
   }
   if (column.affinity === "numeric") {
     if (/^[+-]?\d+$/.test(source)) {
-      return { value: parseSqliteInteger(source, column.name), byteLength: sourceBytes };
+      return { value: parseSqliteInteger(source, "Column " + column.name), byteLength: sourceBytes };
     }
     const parsed = Number(source);
     return {
@@ -711,24 +802,27 @@ function convertInputValue(column: ColumnInfo, source: string): ConvertedInputVa
       byteLength: sourceBytes
     };
   }
-  if (column.affinity === "blob") {
-    const normalized = source.replace(/\s+/g, "");
-    if (normalized.length % 2 !== 0 || !/^[0-9a-fA-F]*$/.test(normalized)) {
-      throw codedError("InvalidRequest", "BLOB columns require an even-length hexadecimal value: " + column.name);
-    }
-    if (normalized.length > maximumFieldBytes * 2) {
-      throw codedError("InvalidRequest", "BLOB value exceeds the 1 MiB limit: " + column.name);
-    }
-    const buffer = Buffer.from(normalized, "hex");
-    return { value: buffer, byteLength: buffer.length };
-  }
   return { value: source, byteLength: sourceBytes };
 }
 
-function parseSqliteInteger(source: string, columnName: string): bigint {
+function boundedUtf8ByteLength(source: string, maximumBytes: number, message: string): number {
+  if (source.length > maximumBytes) {
+    throw codedError("InvalidRequest", message);
+  }
+  const byteLength = Buffer.byteLength(source, "utf8");
+  if (byteLength > maximumBytes) {
+    throw codedError("InvalidRequest", message);
+  }
+  return byteLength;
+}
+
+function parseSqliteInteger(source: string, label: string): bigint {
+  if (source.length > maximumSqliteIntegerCharacters || !/^[+-]?\d+$/.test(source)) {
+    throw codedError("InvalidRequest", label + " requires a signed 64-bit integer.");
+  }
   const value = BigInt(source);
   if (value < minimumSqliteInteger || value > maximumSqliteInteger) {
-    throw codedError("InvalidRequest", "Column integer is outside SQLite's signed 64-bit range: " + columnName);
+    throw codedError("InvalidRequest", label + " is outside SQLite's signed 64-bit range.");
   }
   return value;
 }
@@ -758,19 +852,20 @@ function readWireValue(value: unknown): WireValue {
   if (record.kind === "null") {
     return { kind: "null" };
   }
-  if (record.kind === "integer" && typeof record.value === "string" && /^[+-]?\d+$/.test(record.value)) {
-    return { kind: "integer", value: record.value };
+  if (record.kind === "integer" && typeof record.value === "string") {
+    return { kind: "integer", value: parseSqliteInteger(record.value, "Row locator").toString() };
   }
   if (record.kind === "real" && typeof record.value === "number" && Number.isFinite(record.value)) {
     return { kind: "real", value: record.value };
   }
   if (record.kind === "text" && typeof record.value === "string" && record.truncated === false
-    && Buffer.byteLength(record.value, "utf8") <= maximumFieldBytes) {
+    && record.value.length <= maximumLocatorBytes
+    && Buffer.byteLength(record.value, "utf8") <= maximumLocatorBytes) {
     return { kind: "text", value: record.value, length: record.value.length, truncated: false };
   }
   if (record.kind === "blob" && typeof record.hex === "string" && record.truncated === false
-    && record.hex.length % 2 === 0 && /^[0-9a-fA-F]*$/.test(record.hex)
-    && record.hex.length / 2 <= maximumFieldBytes) {
+    && record.hex.length <= maximumLocatorBytes * 2
+    && record.hex.length % 2 === 0 && /^[0-9a-fA-F]*$/.test(record.hex)) {
     return { kind: "blob", hex: record.hex, byteLength: record.hex.length / 2, truncated: false };
   }
   throw codedError("InvalidRequest", "Row locator contains an invalid value.");

package/templates/sqlite/src/renderer/app.ts.tmpl

@@ -327,7 +327,7 @@ void client.waitForContext().then((context) => {
   writeStatusMessage("error.initializationFailed", { message: errorMessage(error) });
 });
 
-async function refreshDatabase(preserveSelection: boolean): Promise<void> {
+async function refreshDatabase(preserveSelection: boolean): Promise<boolean> {
   setBusy(true, "status.loading");
   try {
     const [info, tableList] = await Promise.all([
@@ -351,10 +351,12 @@ async function refreshDatabase(preserveSelection: boolean): Promise<void> {
     } else {
       writeStatusMessage("status.ready");
     }
+    return true;
   } catch (error: unknown) {
     tableData = undefined;
     renderTableData();
     writeStatusMessage("error.refreshFailed", { message: errorMessage(error) });
+    return false;
   } finally {
     setBusy(false, "status.idle");
   }
@@ -371,8 +373,9 @@ async function openDatabase(): Promise<void> {
     closeEditor();
     selectedTable = "";
     offset = 0;
-    await refreshDatabase(false);
-    writeStatusMessage("status.databaseOpened", { name: result.database.databaseName });
+    if (await refreshDatabase(false)) {
+      writeStatusMessage("status.databaseOpened", { name: result.database.databaseName });
+    }
   } catch (error: unknown) {
     writeStatusMessage("error.operationFailed", { message: errorMessage(error) });
   } finally {
@@ -387,8 +390,9 @@ async function useDefaultDatabase(): Promise<void> {
     closeEditor();
     selectedTable = "plugin_records";
     offset = 0;
-    await refreshDatabase(true);
-    writeStatusMessage("status.defaultOpened");
+    if (await refreshDatabase(true)) {
+      writeStatusMessage("status.defaultOpened");
+    }
   } catch (error: unknown) {
     writeStatusMessage("error.operationFailed", { message: errorMessage(error) });
   } finally {