@synopackageland/cli 0.7.1 → 0.7.2

package/CHANGELOG.md

@@ -1,5 +1,72 @@
 # Changelog
 
+## 0.7.2 (2026-10-11)
+
+Rebuild packages to pick up the new default icon. Packages without `icon` now
+show the SDK default icon instead of a solid blue square.
+
+### Package icon
+
+- `dsm-package.yaml` and `synology-app.yaml` accept `icon`: a square PNG of at
+  least 256×256 inside the project, or a folder of `icon_<size>.png` (16, 24,
+  32, 48, 64, 72, 256; `icon_256.png` required, missing sizes scaled from it).
+  `build` writes `PACKAGE_ICON.PNG` (64×64), `PACKAGE_ICON_256.PNG` and every
+  DSM window size `ui/images/app_<size>.png` from it. SVG is not accepted, so
+  the CLI gains no image dependency. `check` refuses an icon outside the
+  project, a non-PNG, a non-square or smaller image, and one whose Package
+  Center icons exceed the package source's 256 KiB limit
+  (`STANDALONE_ICON_INVALID`, `CONTRACT_ICON_INVALID`).
+
+- A native layout may set `icon` too; `build` then writes both Package Center
+  icons and refuses a metadata folder that also ships them. Without `icon` the
+  layout keeps owning its icons.
+
+- `check` reports which icon a build uses: `圖示：自訂 <path>`, or `圖示：SDK
+  預設圖示` with an info hint about `icon:` (not an error). It warns when an
+  icon is a single colour. `check --json` reports it in `data.icon`.
+
+- `inspect` reports `icon` as `default`, `custom` (with the SHA-256 of
+  `PACKAGE_ICON_256.PNG`) or `none`, and lists a Package Center icon over
+  256 KiB, of the wrong size or not a PNG as a finding.
+
+- The SDK default icon replaces the solid blue square in Package Center, the
+  DSM main menu and the window. Sources are in `assets/default-icon/`.
+
+### Translated DSM title
+
+- With `i18n.info` translations, the DSM main-menu entry and window title
+  follow the DSM language. `ui/config` refers to `synopkgland:app_title` and
+  `app_desc` in `ui/texts/<DSM language>/strings`, written for English and each
+  translated language; a language without its own text shows the English one.
+  Without translations `ui/config` keeps the literal English title.
+
+- `synology-app.yaml` accepts the same `i18n.info` block. It writes INFO
+  `displayname_<lang>` / `description_<lang>` and, with `launch: dsm-window`,
+  localizes the DSM window entry. Once a translation exists, the English
+  `displayname` and `description` must also be one line without `"` or `\`
+  (`CONTRACT_I18N_INVALID`).
+
+### Delegate window
+
+- A DSM window built for a `scope: install-selected` delegate no longer
+  contains the dead `if (panels && false)` check. The window leaves out the
+  approval panel code instead, and other scopes generate `if (panels)`. The
+  behavior is unchanged: this scope is approved only in the app's
+  **Administrator setup** panel, because that approval carries the scope the
+  administrator picks and the window panel has no scope picker. The delegate
+  guide now says so.
+
+### 繁體中文摘要
+
+- 升級後重新建置套件即可換上新的 SDK 預設圖示（不再是純藍方塊）。executor digest 不變，不需重新核准。
+- `dsm-package.yaml`、`synology-app.yaml` 與 native layout 新增 `icon`：專案內至少 256×256 的正方形
+  PNG，或含 `icon_256.png` 的 `icon_<size>.png` 目錄；不接受 SVG。`check` 顯示使用的圖示並檢查格式與
+  256 KiB 上限，`inspect` 回報 `default`／`custom`／`none`。
+- 有 `i18n.info` 翻譯時，DSM 主選單與視窗標題會跟著 DSM 語言切換；缺翻譯的語言顯示英文。
+  `synology-app.yaml` 也支援 `i18n.info`。
+- `scope: install-selected` 的 DSM 視窗不再產生 `if (panels && false)` 死碼；此 scope 仍只在 App 的
+  「管理員設定」核准。
+
 ## 0.7.1 (2026-10-10)
 
 Rebuild packages to pick up template, hook and executor changes. The executor

package/assets/default-icon/README.md

@@ -0,0 +1,19 @@
+# SDK default package icon
+
+Used by `synopkgland build` when `dsm-package.yaml` or `synology-app.yaml`
+sets no `icon`. It marks an App that has not chosen its own icon yet: a
+Package Land parcel on the cream brand tile, not a broken image.
+
+This folder is itself an icon directory (`icon: <dir>`): `icon_<size>.png`
+files are used as drawn and `icon_256.png` is scaled for any missing size.
+
+- `default-icon.svg` draws 48, 64, 72 and 256.
+- `default-icon-small.svg` is a 16 px pixel grid for 16, 24 and 32.
+
+Regenerate after editing an SVG (rsvg-convert is a maintainer tool only;
+the CLI never rasterises SVG):
+
+```sh
+for s in 16 24 32; do rsvg-convert -w $s -h $s default-icon-small.svg -o icon_$s.png; done
+for s in 48 64 72 256; do rsvg-convert -w $s -h $s default-icon.svg -o icon_$s.png; done
+```

package/assets/default-icon/default-icon-small.svg

@@ -0,0 +1,9 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 16 16" shape-rendering="crispEdges">
+  <rect x="0" y="0" width="16" height="16" rx="3.5" fill="#fbf5e8"/>
+  <rect x="3" y="2" width="2" height="2" fill="#1f78e5"/>
+  <rect x="7" y="1" width="2" height="3" fill="#f6b324"/>
+  <rect x="11" y="2" width="2" height="2" fill="#1f78e5"/>
+  <rect x="2" y="4" width="12" height="3" fill="#135bb8"/>
+  <rect x="3" y="7" width="10" height="7" fill="#1f78e5"/>
+  <rect x="6" y="9" width="4" height="1" fill="#fbf5e8"/>
+</svg>

package/assets/default-icon/default-icon.svg

@@ -0,0 +1,10 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="256" height="256" viewBox="0 0 256 256">
+  <rect x="6" y="6" width="244" height="244" rx="56" fill="#fbf5e8" stroke="#e4d8bd" stroke-width="4"/>
+  <path d="M212 22l6 14 14 6-14 6-6 14-6-14-14-6 14-6z" fill="#f6b324"/>
+  <rect x="62" y="58" width="30" height="30" rx="6" fill="#1f78e5"/>
+  <rect x="113" y="50" width="30" height="38" rx="6" fill="#f6b324"/>
+  <rect x="164" y="58" width="30" height="30" rx="6" fill="#1f78e5"/>
+  <rect x="48" y="80" width="160" height="44" rx="12" fill="#135bb8"/>
+  <path d="M58 118h140v66a24 24 0 0 1-24 24H82a24 24 0 0 1-24-24z" fill="#1f78e5"/>
+  <rect x="100" y="140" width="56" height="16" rx="8" fill="#fbf5e8"/>
+</svg>

package/dist/build-spk/dsm-icons.d.ts

@@ -1,2 +1,31 @@
-export declare function writeDsmWindowIcons(uiDir: string): void;
-export declare function writePackageCenterIcons(spkRoot: string): void;
+/** Sizes DSM loads for `images/app_{0}.png` (main menu, desktop, window, taskbar). */
+export declare const WINDOW_ICON_SIZES: readonly [16, 24, 32, 48, 64, 72, 256];
+/** The package source drops a release whose PACKAGE_ICON is larger than this. */
+export declare const MAX_ICON_BYTES: number;
+export interface PackageIcons {
+    source: "custom" | "default";
+    /** Encoded PNG per DSM window size; PACKAGE_ICON.PNG is 64 and PACKAGE_ICON_256.PNG is 256. */
+    window: Map<number, Buffer>;
+    packageIcon: Buffer;
+    packageIcon256: Buffer;
+    /** Every pixel of the 256 px icon is the same colour. */
+    solid: boolean;
+}
+/** Ships next to dist/ and src/ alike: <package>/assets/default-icon. */
+export declare const DEFAULT_ICON_DIR: string;
+/** A project icon: one square PNG of at least 256 px, or a directory of icon_<size>.png. */
+export declare function renderPackageIcons(path: string): PackageIcons;
+/** The SDK default icon, for projects that set no `icon`. */
+export declare function defaultPackageIcons(): PackageIcons;
+/** The project's icon when it sets one, otherwise the SDK default. */
+export declare function packageIcons(icon: string | undefined): PackageIcons;
+/** What check reports: which icon a build would use, relative to the project. */
+export interface IconReport {
+    /** `layout`: a native layout without `icon`, whose metadata owns PACKAGE_ICON*.PNG. */
+    source: PackageIcons["source"] | "layout";
+    path?: string;
+    solid: boolean;
+}
+export declare function iconReport(root: string, icon: string | undefined): IconReport;
+export declare function writeDsmWindowIcons(uiDir: string, icons: PackageIcons): void;
+export declare function writePackageCenterIcons(spkRoot: string, icons: PackageIcons): void;

package/dist/build-spk/dsm-icons.js

@@ -1,67 +1,146 @@
-import { deflateSync } from "node:zlib";
-import { chmodSync, mkdirSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
-const ICON_SIZES = [16, 24, 32, 48, 64, 72, 256];
-const ICON_RGB = [0x1a, 0x73, 0xe8];
-function crc32(data) {
-    let crc = 0xffffffff;
-    for (const byte of data) {
-        crc ^= byte;
-        for (let i = 0; i < 8; i++) {
-            crc = (crc >>> 1) ^ (crc & 1 ? 0xedb88320 : 0);
-        }
+import { chmodSync, existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { basename, dirname, join, relative } from "node:path";
+import { fileURLToPath } from "node:url";
+import { decodePng, encodePng } from "./png.js";
+/** Sizes DSM loads for `images/app_{0}.png` (main menu, desktop, window, taskbar). */
+export const WINDOW_ICON_SIZES = [16, 24, 32, 48, 64, 72, 256];
+/** The package source drops a release whose PACKAGE_ICON is larger than this. */
+export const MAX_ICON_BYTES = 256 * 1024;
+const ICON_FILE = /^icon_(\d+)\.png$/;
+/** Ships next to dist/ and src/ alike: <package>/assets/default-icon. */
+export const DEFAULT_ICON_DIR = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "assets", "default-icon");
+function readPng(path, name) {
+    try {
+        return decodePng(readFileSync(path));
+    }
+    catch (error) {
+        throw new Error(`${name}：${error.message}`);
     }
-    return (crc ^ 0xffffffff) >>> 0;
-}
-function pngChunk(type, data) {
-    const length = Buffer.alloc(4);
-    length.writeUInt32BE(data.length);
-    const typeBuf = Buffer.from(type, "ascii");
-    const crc = Buffer.alloc(4);
-    crc.writeUInt32BE(crc32(Buffer.concat([typeBuf, data])));
-    return Buffer.concat([length, typeBuf, data, crc]);
 }
-function solidPng(size) {
-    const stride = size * 3 + 1;
-    const raw = Buffer.alloc(stride * size);
+/** Area-average downscale in premultiplied alpha, so transparent edges stay clean. */
+function scale(image, size) {
+    if (image.width === size && image.height === size)
+        return image;
+    const { width, height, rgba } = image;
+    const premultiplied = new Float64Array(width * height * 4);
+    for (let i = 0; i < width * height; i++) {
+        const alpha = rgba[i * 4 + 3] / 255;
+        for (let c = 0; c < 3; c++)
+            premultiplied[i * 4 + c] = rgba[i * 4 + c] * alpha;
+        premultiplied[i * 4 + 3] = rgba[i * 4 + 3];
+    }
+    const spans = (from) => Array.from({ length: size }, (_, d) => {
+        const start = (d * from) / size, end = ((d + 1) * from) / size;
+        const weights = [];
+        for (let s = Math.floor(start); s < end; s++)
+            weights.push([s, Math.min(end, s + 1) - Math.max(start, s)]);
+        return weights.map(([s, w]) => [s, w / (end - start)]);
+    });
+    const columns = spans(width), rows = spans(height);
+    const across = new Float64Array(size * height * 4);
+    for (let y = 0; y < height; y++) {
+        for (let x = 0; x < size; x++) {
+            for (const [s, w] of columns[x]) {
+                for (let c = 0; c < 4; c++)
+                    across[(y * size + x) * 4 + c] += premultiplied[(y * width + s) * 4 + c] * w;
+            }
+        }
+    }
+    const out = Buffer.alloc(size * size * 4);
     for (let y = 0; y < size; y++) {
-        const row = y * stride;
-        raw[row] = 0;
         for (let x = 0; x < size; x++) {
-            const i = row + 1 + x * 3;
-            raw[i] = ICON_RGB[0];
-            raw[i + 1] = ICON_RGB[1];
-            raw[i + 2] = ICON_RGB[2];
+            const pixel = [0, 0, 0, 0];
+            for (const [s, w] of rows[y])
+                for (let c = 0; c < 4; c++)
+                    pixel[c] += across[(s * size + x) * 4 + c] * w;
+            const alpha = Math.round(pixel[3]);
+            const at = (y * size + x) * 4;
+            for (let c = 0; c < 3; c++)
+                out[at + c] = alpha ? Math.min(255, Math.round((pixel[c] * 255) / pixel[3])) : 0;
+            out[at + 3] = alpha;
         }
     }
-    const ihdr = Buffer.alloc(13);
-    ihdr.writeUInt32BE(size, 0);
-    ihdr.writeUInt32BE(size, 4);
-    ihdr[8] = 8;
-    ihdr[9] = 2;
-    return Buffer.concat([
-        Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]),
-        pngChunk("IHDR", ihdr),
-        pngChunk("IDAT", deflateSync(raw, { level: 9 })),
-        pngChunk("IEND", Buffer.alloc(0)),
-    ]);
+    return { width: size, height: size, rgba: out };
 }
-export function writeDsmWindowIcons(uiDir) {
-    const imagesDir = join(uiDir, "images");
-    mkdirSync(imagesDir, { recursive: true });
-    for (const size of ICON_SIZES) {
-        const path = join(imagesDir, `app_${size}.png`);
-        writeFileSync(path, solidPng(size));
-        chmodSync(path, 0o644);
+function isSolid(image) {
+    const first = image.rgba.readUInt32BE(0);
+    for (let i = 4; i < image.rgba.length; i += 4)
+        if (image.rgba.readUInt32BE(i) !== first)
+            return false;
+    return true;
+}
+/** `icon_<size>.png` drawn per size; icon_256.png is required and scaled for the rest. */
+function readIconDirectory(dir) {
+    const drawn = new Map();
+    for (const name of readdirSync(dir).sort()) {
+        const match = ICON_FILE.exec(name);
+        if (!match)
+            continue;
+        const size = Number(match[1]);
+        if (!WINDOW_ICON_SIZES.includes(size)) {
+            throw new Error(`${name}：不支援的尺寸；只接受 ${WINDOW_ICON_SIZES.map((s) => `icon_${s}.png`).join("、")}。`);
+        }
+        const image = readPng(join(dir, name), name);
+        if (image.width !== size || image.height !== size) {
+            throw new Error(`${name}：尺寸是 ${image.width}×${image.height}，應為 ${size}×${size}。`);
+        }
+        drawn.set(size, image);
     }
+    if (!drawn.has(256))
+        throw new Error(`圖示目錄 ${basename(dir)}/ 缺少 icon_256.png（256×256 PNG，其他尺寸可省略，由它縮小產生）。`);
+    return drawn;
 }
-export function writePackageCenterIcons(spkRoot) {
-    for (const [name, size] of [
-        ["PACKAGE_ICON.PNG", 64],
-        ["PACKAGE_ICON_256.PNG", 256],
-    ]) {
-        const path = join(spkRoot, name);
-        writeFileSync(path, solidPng(size));
-        chmodSync(path, 0o644);
+function readIconFile(path) {
+    const image = readPng(path, basename(path));
+    if (image.width !== image.height)
+        throw new Error(`${basename(path)}：尺寸 ${image.width}×${image.height} 不是正方形。`);
+    if (image.width < 256)
+        throw new Error(`${basename(path)}：尺寸 ${image.width}×${image.height}，至少 256×256。`);
+    return new Map([[256, scale(image, 256)]]);
+}
+function render(drawn, source) {
+    const big = drawn.get(256);
+    const window = new Map();
+    for (const size of WINDOW_ICON_SIZES) {
+        const png = encodePng(size, size, scale(drawn.get(size) ?? big, size).rgba);
+        if (png.length > MAX_ICON_BYTES) {
+            throw new Error(`${size}×${size} 圖示編碼後 ${png.length} bytes，超過 package source 的 256 KiB 上限；請減少雜訊或細節。`);
+        }
+        window.set(size, png);
     }
+    return { source, window, packageIcon: window.get(64), packageIcon256: window.get(256), solid: isSolid(big) };
+}
+/** A project icon: one square PNG of at least 256 px, or a directory of icon_<size>.png. */
+export function renderPackageIcons(path) {
+    if (!existsSync(path))
+        throw new Error(`找不到圖示 ${basename(path)}。`);
+    return render(statSync(path).isDirectory() ? readIconDirectory(path) : readIconFile(path), "custom");
+}
+let defaults;
+/** The SDK default icon, for projects that set no `icon`. */
+export function defaultPackageIcons() {
+    defaults ??= render(readIconDirectory(DEFAULT_ICON_DIR), "default");
+    return defaults;
+}
+/** The project's icon when it sets one, otherwise the SDK default. */
+export function packageIcons(icon) {
+    return icon ? renderPackageIcons(icon) : defaultPackageIcons();
+}
+export function iconReport(root, icon) {
+    const icons = packageIcons(icon);
+    return { source: icons.source, ...(icon ? { path: relative(root, icon) } : {}), solid: icons.solid };
+}
+function writeIcon(path, png) {
+    writeFileSync(path, png);
+    chmodSync(path, 0o644);
+}
+export function writeDsmWindowIcons(uiDir, icons) {
+    const imagesDir = join(uiDir, "images");
+    mkdirSync(imagesDir, { recursive: true });
+    for (const [size, png] of icons.window)
+        writeIcon(join(imagesDir, `app_${size}.png`), png);
+}
+export function writePackageCenterIcons(spkRoot, icons) {
+    writeIcon(join(spkRoot, "PACKAGE_ICON.PNG"), icons.packageIcon);
+    writeIcon(join(spkRoot, "PACKAGE_ICON_256.PNG"), icons.packageIcon256);
 }

package/dist/build-spk/generator.js

@@ -11,7 +11,8 @@ import { buildGatewayBinary, gatewayConfig, writeGatewayPayload } from "./gatewa
 import { classifyComposeRoute, loadCompose } from "../compose/analyze.js";
 import { scanComposePrivilege } from "../compose/privilege.js";
 import { validateProject } from "../validate.js";
-import { writeDsmWindowIcons, writePackageCenterIcons } from "./dsm-icons.js";
+import { packageIcons, writeDsmWindowIcons, writePackageCenterIcons } from "./dsm-icons.js";
+import { contractIconPath } from "../contract/icon.js";
 import { infoArchValue, isContainerArchFamily } from "./dsm-arch.js";
 import { assertContainerMinDsm, assertPortalMinDsm, resolveMinDsm } from "./dsm-version.js";
 import { createReproducibleTar } from "./reproducible-archive.js";
@@ -22,6 +23,9 @@ import { renderInstallWizardFiles } from "./install-wizard.js";
 import { contractPortal, PORTAL_JSON_RELPATH, PORTAL_MUSTACHE_RELPATH, renderPortalJson, renderPortalLifecycle, renderPortalMustache, renderPortalWizardStep } from "../portal/package.js";
 import { renderWizardFiles, writeWizardUiFiles } from "./wizard-i18n.js";
 import { sharedFolderCombobox } from "./share-combobox.js";
+import { writeUiTexts } from "./ui-texts.js";
+import { DSM_LANGS, LOCALES } from "../standalone/i18n.js";
+import { contractAppTitle } from "../contract/i18n.js";
 import { renderHeadlessResourceMarker, renderResourceConfig, renderResourceWorkerStartStopStatus, } from "./resource-worker.js";
 const FILE_MODE = 0o644;
 const SCRIPT_MODE = 0o755;
@@ -89,6 +93,7 @@ export async function buildSpk(options) {
     const isDynamicRoute = route?.route === "dynamic";
     const isResourceWorkerRoute = route?.route === "static-zero-config" ||
         isDynamicRoute;
+    const icons = packageIcons(contractIconPath(contract, options.project.root));
     const staging = mkdtempSync(join(tmpdir(), "syno-spk-"));
     const gatewayWork = mkdtempSync(join(tmpdir(), "syno-gateway-"));
     try {
@@ -108,7 +113,7 @@ export async function buildSpk(options) {
             gatewayBinary = built.binary;
         }
         writeFileSync(join(staging, "INFO"), renderInfo(contract, options.archFamily, isResourceWorkerRoute), "utf8");
-        writePackageCenterIcons(staging);
+        writePackageCenterIcons(staging, icons);
         mkdirSync(join(staging, "conf"), { recursive: true });
         writeFileSync(join(staging, "conf", "privilege"), renderPrivilege(), "utf8");
         writeFileSync(join(staging, "privilege"), renderPrivilege(), "utf8");
@@ -177,7 +182,8 @@ export async function buildSpk(options) {
             const uiDir = join(staging, "package", "ui");
             mkdirSync(uiDir, { recursive: true });
             writeFileSync(join(uiDir, "config"), renderDsmWindowConfig(contract), "utf8");
-            writeDsmWindowIcons(uiDir);
+            writeDsmWindowIcons(uiDir, icons);
+            writeUiTexts(uiDir, contractAppTitle(contract));
         }
         const portal = contractPortal(contract);
         if (portal) {
@@ -223,6 +229,14 @@ function renderInfo(contract, archFamily, isResourceWorker = false) {
     add("displayname", String(contract.displayname));
     add("description", String(contract.description));
     add("maintainer", String(contract.maintainer));
+    const info = contractAppTitle(contract).info;
+    for (const locale of LOCALES) {
+        const text = info?.[locale];
+        if (text?.displayname)
+            add(`displayname_${DSM_LANGS[locale]}`, text.displayname);
+        if (text?.description)
+            add(`description_${DSM_LANGS[locale]}`, text.description);
+    }
     for (const [key, value] of metadataInfoFields(contract.metadata))
         add(key, value);
     add("arch", archFamily === undefined ? "noarch" : infoArchValue(archFamily));

package/dist/build-spk/png.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Just enough PNG for package icons, without an image dependency: decode any
+ * non-interlaced PNG to 8-bit RGBA, and encode 8-bit RGBA deterministically
+ * with only the critical chunks.
+ */
+export interface RgbaImage {
+    width: number;
+    height: number;
+    /** Row-major, straight (not premultiplied) alpha. */
+    rgba: Buffer;
+}
+export declare function decodePng(bytes: Buffer): RgbaImage;
+/** 8-bit RGBA, adaptive per-row filters, no ancillary chunks: same pixels, same bytes. */
+export declare function encodePng(width: number, height: number, rgba: Buffer): Buffer;

package/dist/build-spk/png.js

@@ -0,0 +1,161 @@
+import { crc32, deflateSync, inflateSync } from "node:zlib";
+const SIGNATURE = Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]);
+const MAX_SIDE = 4096;
+const CHANNELS = { 0: 1, 2: 3, 3: 1, 4: 2, 6: 4 };
+const DEPTHS = { 0: [1, 2, 4, 8, 16], 2: [8, 16], 3: [1, 2, 4, 8], 4: [8, 16], 6: [8, 16] };
+function corrupt(why) {
+    throw new Error(`PNG 損壞：${why}`);
+}
+function chunk(type, data) {
+    const head = Buffer.alloc(8);
+    head.writeUInt32BE(data.length);
+    head.write(type, 4, "ascii");
+    const crc = Buffer.alloc(4);
+    crc.writeUInt32BE(crc32(data, crc32(head.subarray(4))));
+    return Buffer.concat([head, data, crc]);
+}
+function paeth(a, b, c) {
+    const p = a + b - c;
+    const pa = Math.abs(p - a), pb = Math.abs(p - b), pc = Math.abs(p - c);
+    return pa <= pb && pa <= pc ? a : pb <= pc ? b : c;
+}
+export function decodePng(bytes) {
+    if (bytes.length < 8 || !bytes.subarray(0, 8).equals(SIGNATURE))
+        throw new Error("不是 PNG 檔（檔頭簽章不符）。");
+    let offset = 8;
+    let header;
+    let palette, alpha, ended = false;
+    const data = [];
+    while (!ended) {
+        if (offset + 12 > bytes.length)
+            corrupt("檔案被截斷");
+        const length = bytes.readUInt32BE(offset);
+        const type = bytes.toString("latin1", offset + 4, offset + 8);
+        const end = offset + 12 + length;
+        if (end > bytes.length)
+            corrupt("檔案被截斷");
+        const body = bytes.subarray(offset + 8, offset + 8 + length);
+        if (crc32(body, crc32(bytes.subarray(offset + 4, offset + 8))) !== bytes.readUInt32BE(end - 4))
+            corrupt(`${type} CRC 不符`);
+        if (!header && type !== "IHDR")
+            corrupt("第一個 chunk 必須是 IHDR");
+        if (type === "IHDR") {
+            if (header || length !== 13)
+                corrupt("IHDR 無效");
+            header = { width: body.readUInt32BE(0), height: body.readUInt32BE(4), depth: body[8], type: body[9] };
+            if (!DEPTHS[header.type]?.includes(header.depth) || body[10] !== 0 || body[11] !== 0)
+                corrupt("不支援的色彩型態或位元深度");
+            if (body[12] !== 0)
+                throw new Error("不支援交錯（interlaced）PNG；請另存為非交錯 PNG。");
+            if (header.width < 1 || header.height < 1 || header.width > MAX_SIDE || header.height > MAX_SIDE) {
+                throw new Error(`PNG 尺寸 ${header.width}×${header.height} 超出範圍（每邊 1–${MAX_SIDE} px）。`);
+            }
+        }
+        else if (type === "PLTE")
+            palette = body;
+        else if (type === "tRNS")
+            alpha = body;
+        else if (type === "IDAT")
+            data.push(body);
+        else if (type === "IEND")
+            ended = true;
+        offset = end;
+    }
+    if (!header || !data.length)
+        corrupt("缺少影像資料");
+    const { width, height, depth, type } = header;
+    if (type === 3 && (!palette || palette.length % 3 !== 0))
+        corrupt("調色盤影像缺少 PLTE");
+    const bits = CHANNELS[type] * depth;
+    const bpp = Math.max(1, bits >> 3);
+    const stride = Math.ceil((width * bits) / 8);
+    let raw;
+    try {
+        raw = inflateSync(Buffer.concat(data), { maxOutputLength: (stride + 1) * height + 1 });
+    }
+    catch {
+        corrupt("影像資料無法解壓縮");
+    }
+    if (raw.length !== (stride + 1) * height)
+        corrupt("影像資料長度不符");
+    const prev = Buffer.alloc(stride), line = Buffer.alloc(stride);
+    const rgba = Buffer.alloc(width * height * 4);
+    const sample = (x, channel) => {
+        if (depth === 16)
+            return line[(x * CHANNELS[type] + channel) * 2];
+        if (depth === 8)
+            return line[x * CHANNELS[type] + channel];
+        const bit = x * depth;
+        return (line[bit >> 3] >> (8 - depth - (bit & 7))) & ((1 << depth) - 1);
+    };
+    const scale = depth < 8 ? 255 / ((1 << depth) - 1) : 1;
+    for (let y = 0; y < height; y++) {
+        const row = raw.subarray(y * (stride + 1) + 1, (y + 1) * (stride + 1));
+        const filter = raw[y * (stride + 1)];
+        for (let i = 0; i < stride; i++) {
+            const a = i >= bpp ? line[i - bpp] : 0, b = prev[i], c = i >= bpp ? prev[i - bpp] : 0;
+            const predictor = filter === 0 ? 0 : filter === 1 ? a : filter === 2 ? b : filter === 3 ? (a + b) >> 1 : filter === 4 ? paeth(a, b, c) : corrupt("未知的列濾波");
+            line[i] = (row[i] + predictor) & 0xff;
+        }
+        for (let x = 0; x < width; x++) {
+            const out = (y * width + x) * 4;
+            if (type === 3) {
+                const index = sample(x, 0);
+                if (index * 3 + 2 >= palette.length)
+                    corrupt("調色盤索引超出範圍");
+                palette.copy(rgba, out, index * 3, index * 3 + 3);
+                rgba[out + 3] = alpha && index < alpha.length ? alpha[index] : 255;
+            }
+            else if (type === 0 || type === 4) {
+                const grey = Math.round(sample(x, 0) * scale);
+                rgba.fill(grey, out, out + 3);
+                rgba[out + 3] = type === 4 ? sample(x, 1) : 255;
+            }
+            else {
+                for (let channel = 0; channel < 3; channel++)
+                    rgba[out + channel] = sample(x, channel);
+                rgba[out + 3] = type === 6 ? sample(x, 3) : 255;
+            }
+        }
+        line.copy(prev);
+    }
+    return { width, height, rgba };
+}
+/** 8-bit RGBA, adaptive per-row filters, no ancillary chunks: same pixels, same bytes. */
+export function encodePng(width, height, rgba) {
+    const stride = width * 4;
+    const out = Buffer.alloc((stride + 1) * height);
+    const zero = Buffer.alloc(stride);
+    const candidate = Buffer.alloc(stride);
+    for (let y = 0; y < height; y++) {
+        const line = rgba.subarray(y * stride, (y + 1) * stride);
+        const prev = y ? rgba.subarray((y - 1) * stride, y * stride) : zero;
+        let bestScore = Infinity;
+        for (let filter = 0; filter <= 4; filter++) {
+            let score = 0;
+            for (let i = 0; i < stride; i++) {
+                const a = i >= 4 ? line[i - 4] : 0, b = prev[i], c = i >= 4 ? prev[i - 4] : 0;
+                const predictor = filter === 0 ? 0 : filter === 1 ? a : filter === 2 ? b : filter === 3 ? (a + b) >> 1 : paeth(a, b, c);
+                const value = (line[i] - predictor) & 0xff;
+                candidate[i] = value;
+                score += value < 128 ? value : 256 - value;
+            }
+            if (score < bestScore) {
+                bestScore = score;
+                out[y * (stride + 1)] = filter;
+                candidate.copy(out, y * (stride + 1) + 1);
+            }
+        }
+    }
+    const ihdr = Buffer.alloc(13);
+    ihdr.writeUInt32BE(width, 0);
+    ihdr.writeUInt32BE(height, 4);
+    ihdr[8] = 8;
+    ihdr[9] = 6;
+    return Buffer.concat([
+        SIGNATURE,
+        chunk("IHDR", ihdr),
+        chunk("IDAT", deflateSync(out, { level: 9 })),
+        chunk("IEND", Buffer.alloc(0)),
+    ]);
+}

package/dist/build-spk/ui-texts.d.ts

@@ -0,0 +1,20 @@
+import { type InfoTranslations } from "../standalone/i18n.js";
+/** The English INFO text and its translations, which also name the app in DSM. */
+export interface AppTitle {
+    displayname: string;
+    description: string;
+    info?: InfoTranslations;
+}
+/**
+ * `ui/config` title fields. With translations they are `section:key`
+ * references DSM resolves from `ui/texts/<lang>/strings` for the main menu
+ * and the window title; without, the literal English text as before.
+ */
+export declare function uiTitleFields(app: AppTitle): {
+    title: string;
+    desc: string;
+    preloadTexts?: string[];
+};
+/** `ui/texts/<dsm lang>/strings` for English and every translated language; none without translations. */
+export declare function renderUiTexts(app: AppTitle): Map<string, string>;
+export declare function writeUiTexts(uiRoot: string, app: AppTitle): void;