@synopackageland/cli 0.13.1 → 0.14.1

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.14.1
+
+- DSM 會改寫 standalone URL，因此沒有 SDK class 的 schema 1 web launcher 使用 url；schema 2 identity_gateway + compose 與原生 new-page 使用 standalone。兩條 Compose 路線共用預設解析。
+
+## 0.14.0
+
+- 原生 App 支援 ui.launch: dsm-window | new-page；new-page 使用 DSM standalone launcher。SDK 原生 App 的內建預設維持 dsm-window；Docker／Web App（含 schema 2 identity_gateway + compose）共用解析邏輯，內建預設改為 new-page，主選單與套件中心皆可開啟既有 gateway／public alias。inspect 驗證 launcher 與 Portal 宣告，完整頁統一設定標題、favicon 與手機 viewport。Web App 省略開啟方式的行為變更，因此採用 0.14.0。
+
 ## 0.13.1 (2026-10-17)
 
 - Use templates 0.13.1, SDK 0.13.1 fixtures and the unchanged executor/lifecycle digests on the 0.13 minor line.

package/README.md

@@ -216,3 +216,36 @@ Call `webapi.call` with `response_type: "raw"`; Go Apps use
 package's private executor-staging folder with size/SHA-256 and immediate cleanup.
 Do not use Attachment.download or follow X-Accel-Redirect. See the SDK raw response
 contract for the complete transport and CGI validation rules.
+
+## App launch mode
+
+Native Apps declare `ui.launch: dsm-window | new-page` in `dsm-package.yaml`.
+Use `dsm-window` for frontends built with `@synopackageland/ui`; use `new-page`
+for every other frontend. Plain/binary scaffolds explicitly choose new-page; Vue uses the native default. An omitted
+native `ui.launch` resolves to `dsm-window`; the CLI does not guess a frontend's
+framework from its build command. `new-page` registers DSM `type: "standalone"`,
+so the main menu and Package Center open a full page on the DSM origin.
+`ctx.fullPage`, `ctx.appIcon`, session/SynoToken, launch parameters and entry
+permissions use the same wrapper in both modes. The wrapper sets the standalone
+page title, favicon and device-width viewport. It retains ExtJS; `pureEnv` is
+not appropriate, and alternate Portal ports are not needed (`allowAltPort` is omitted).
+
+A full page does not need Application Portal. Omit `portal` unless an alias is
+explicitly wanted; only that opt-in adds `defaultAlias`, login styling, Portal
+panels and capabilities. No Portal is a healthy default for inspect/info/doctor.
+
+Web service Apps declare `integration.web.launch`; its built-in default is `new-page`.
+Native SDK Apps default to `dsm-window`; non-UI-SDK native frontends must
+explicitly set `ui.launch: new-page`. Headless Compose Apps have no launcher.
+The new-page main menu uses `type: "url"` with an explicit `url` at the existing trusted entry: the authenticated
+gateway, or a Web Station alias only with explicit `access: public`. DSM rewrites standalone URLs to a launchApp shell, which needs an AppInstance
+and AppWindow JS class. A schema-1 web service has no such class, so it uses url.
+The schema-2 identity_gateway + compose SDK wrapper has the class and uses standalone.
+Authenticated web Apps do not create a Web Station alias or Application Portal.
+`dsm-window` remains an explicit web launch option with its URL launcher.
+
+Schema 2 `dsm-package.yaml` with `identity_gateway` and `compose` is also a web
+service: omitted `ui.launch` resolves to `new-page`, without Application Portal.
+Both Compose routes share `contract/app-launch.ts` for defaults and launcher types.
+An explicit `ui.launch` overrides this default. Native SDK Apps without a web
+service keep `dsm-window` when `ui.launch` is absent.

package/dist/build-spk/generator.js

@@ -184,7 +184,7 @@ export async function buildSpk(options) {
                 cpSync(htmlDir, join(staging, "package", "compose", "html"), { recursive: true });
             }
         }
-        if (contract.adminport !== undefined && resolvedWebLaunch(contract) === "dsm-window") {
+        if (contract.adminport !== undefined && resolvedWebLaunch(contract) !== undefined) {
             const uiDir = join(staging, "package", "ui");
             mkdirSync(uiDir, { recursive: true });
             writeFileSync(join(uiDir, "config"), renderDsmWindowConfig(contract, icons), "utf8");
@@ -198,7 +198,7 @@ export async function buildSpk(options) {
         chmodSync(join(staging, "privilege"), FILE_MODE);
         chmodSync(join(staging, "package", "compose.yaml"), FILE_MODE);
         chmodSync(join(staging, "package", "synology-app.yaml"), FILE_MODE);
-        if (contract.adminport !== undefined && resolvedWebLaunch(contract) === "dsm-window") {
+        if (contract.adminport !== undefined && resolvedWebLaunch(contract) !== undefined) {
             chmodSync(join(staging, "package", "ui", "config"), FILE_MODE);
         }
         const outputPath = options.outputPath ?? join(options.project.root, `${String(contract.package)}.spk`);
@@ -274,14 +274,10 @@ function renderInfo(contract, archFamily, isResourceWorker = false) {
             add("adminurl", String(contract.adminurl));
         }
     }
-    if (launch === "dsm-window") {
+    if (launch === "dsm-window" || launch === "new-page") {
         add("dsmuidir", "ui");
         add("dsmappname", String(contract.package));
     }
-    else if (viaGateway) {
-        // The gateway CGI is served from ui/ even when the App opens in a new page.
-        add("dsmuidir", "ui");
-    }
     return `${lines.join("\n")}\n`;
 }
 function renderPrivilege() {

package/dist/contract/app-launch.d.ts

@@ -0,0 +1,11 @@
+import type { StandaloneManifest } from '../standalone/manifest.js';
+export declare const APP_LAUNCH_MODES: readonly ["dsm-window", "new-page"];
+export type AppLaunchMode = (typeof APP_LAUNCH_MODES)[number];
+export declare const DEFAULT_NATIVE_LAUNCH: AppLaunchMode;
+export declare const DEFAULT_WEB_LAUNCH: AppLaunchMode;
+export declare function isAppLaunchMode(value: unknown): value is AppLaunchMode;
+/** Both Compose routes use the same web default; a valid explicit choice wins. */
+export declare function resolveAppLaunch(value: unknown, webService: boolean): AppLaunchMode | undefined;
+export declare function resolvedSdkLaunch(manifest: Pick<StandaloneManifest, 'ui' | 'compose' | 'identityGateway'>): AppLaunchMode;
+/** DSM rewrites standalone URLs to launchApp; only SDK wrappers provide that class. */
+export declare function dsmLauncherType(launch: AppLaunchMode, sdkWindow: boolean): 'standalone' | 'app' | 'url';

package/dist/contract/app-launch.js

@@ -0,0 +1,18 @@
+export const APP_LAUNCH_MODES = ['dsm-window', 'new-page'];
+export const DEFAULT_NATIVE_LAUNCH = 'dsm-window';
+export const DEFAULT_WEB_LAUNCH = 'new-page';
+export function isAppLaunchMode(value) {
+    return value === 'dsm-window' || value === 'new-page';
+}
+/** Both Compose routes use the same web default; a valid explicit choice wins. */
+export function resolveAppLaunch(value, webService) {
+    return value === undefined ? webService ? DEFAULT_WEB_LAUNCH : DEFAULT_NATIVE_LAUNCH
+        : isAppLaunchMode(value) ? value : undefined;
+}
+export function resolvedSdkLaunch(manifest) {
+    return resolveAppLaunch(manifest.ui.launch, Boolean(manifest.compose || manifest.identityGateway));
+}
+/** DSM rewrites standalone URLs to launchApp; only SDK wrappers provide that class. */
+export function dsmLauncherType(launch, sdkWindow) {
+    return sdkWindow ? launch === 'new-page' ? 'standalone' : 'app' : 'url';
+}

package/dist/contract/web-launch.d.ts

@@ -1,10 +1,11 @@
+import { type AppLaunchMode } from './app-launch.js';
 import { type PackageIcons } from "../build-spk/dsm-icons.js";
 import type { AppContract } from "../types.js";
 /** DSM Web Station portal alias max length (error 1311 above this). */
 export declare const WEB_STATION_ALIAS_MAX = 20;
 export declare const WEB_LAUNCH_MODES: readonly ["dsm-window", "new-page"];
-export type WebLaunchMode = (typeof WEB_LAUNCH_MODES)[number];
-export declare const DEFAULT_WEB_LAUNCH_MODE: WebLaunchMode;
+export type WebLaunchMode = AppLaunchMode;
+export declare const DEFAULT_WEB_LAUNCH_MODE: "dsm-window" | "new-page";
 export interface WebIntegration {
     launch?: unknown;
     cookies?: unknown;

package/dist/contract/web-launch.js

@@ -1,11 +1,12 @@
+import { APP_LAUNCH_MODES, DEFAULT_WEB_LAUNCH, isAppLaunchMode, resolveAppLaunch, dsmLauncherType } from './app-launch.js';
 import { createHash } from "node:crypto";
 import { uiTitleFields } from "../build-spk/ui-texts.js";
 import { windowIconTemplate } from "../build-spk/dsm-icons.js";
 import { contractAppTitle } from "./i18n.js";
 /** DSM Web Station portal alias max length (error 1311 above this). */
 export const WEB_STATION_ALIAS_MAX = 20;
-export const WEB_LAUNCH_MODES = ["dsm-window", "new-page"];
-export const DEFAULT_WEB_LAUNCH_MODE = "dsm-window";
+export const WEB_LAUNCH_MODES = APP_LAUNCH_MODES;
+export const DEFAULT_WEB_LAUNCH_MODE = DEFAULT_WEB_LAUNCH;
 export function readWebIntegration(contract) {
     const integration = contract.integration;
     if (!integration || typeof integration !== "object") {
@@ -18,17 +19,13 @@ export function readWebIntegration(contract) {
     return web;
 }
 export function isWebLaunchMode(value) {
-    return value === "dsm-window" || value === "new-page";
+    return isAppLaunchMode(value);
 }
 export function resolvedWebLaunch(contract) {
     if (contract.adminport === undefined) {
         return undefined;
     }
-    const launch = readWebIntegration(contract)?.launch;
-    if (launch === undefined) {
-        return DEFAULT_WEB_LAUNCH_MODE;
-    }
-    return isWebLaunchMode(launch) ? launch : undefined;
+    return resolveAppLaunch(readWebIntegration(contract)?.launch, true);
 }
 export const WEB_ACCESS_MODES = ["dsm-users", "dsm-admins", "dsm-groups", "public"];
 export const DEFAULT_WEB_ACCESS_MODE = "dsm-users";
@@ -145,7 +142,7 @@ export function renderDsmWindowConfig(contract, icons) {
     return `${JSON.stringify({
         ".url": {
             [packageId]: {
-                type: "url",
+                type: dsmLauncherType(resolvedWebLaunch(contract), false),
                 allUsers: true,
                 ...uiTitleFields(contractAppTitle(contract)),
                 icon: windowIconTemplate(icons),

package/dist/error-registry.js

@@ -1,4 +1,7 @@
 export const ERROR_REGISTRY = {
+    'LAUNCHER_PORTAL_MISMATCH': { code: 'LAUNCHER_PORTAL_MISMATCH', description: 'The launcher has Portal fields without a matching explicit Portal declaration.', suggestion: 'Remove defaultAlias and login fields, or explicitly enable portal and rebuild.' },
+    'LAUNCHER_TYPE_MISMATCH': { code: 'LAUNCHER_TYPE_MISMATCH', description: 'The built launcher or INFO entry differs from the declared launch mode.', suggestion: 'Rebuild with synopkgland build; native new-page uses standalone, and schema-1 web uses url at the trusted entry; schema-2 SDK wrappers use standalone.' },
+    'STANDALONE_UI_LAUNCH_INVALID': { code: 'STANDALONE_UI_LAUNCH_INVALID', description: 'The native ui.launch value is invalid.', suggestion: 'Set ui.launch to dsm-window (UI SDK) or new-page (other frontends). Portal is a separate opt-in.' },
     "NATIVE_LAYOUT_INVALID": {
         code: "NATIVE_LAYOUT_INVALID",
         description: "The native layout's manifest, hooks, toolkit or artifacts violate the package-only contract.",
@@ -52,7 +55,7 @@ export const ERROR_REGISTRY = {
     "CONTRACT_LAUNCH_INVALID": {
         "code": "CONTRACT_LAUNCH_INVALID",
         "description": "The integration.web.launch mode is invalid.",
-        "suggestion": "Use dsm-window (DSM window, the default) or new-page (new tab); omit this field for a headless App."
+        "suggestion": "Use dsm-window (DSM window) or new-page (new tab, the default); omit this field for a headless App."
     },
     "CONTRACT_LAUNCH_REQUIRES_WEB": {
         "code": "CONTRACT_LAUNCH_REQUIRES_WEB",

package/dist/init.js

@@ -191,7 +191,7 @@ export function initFromTemplate(template, targetDir, options = {}) {
     }
     if (ui === "vue") {
         const manifest = join(targetDir, "dsm-package.yaml");
-        writeFileSync(manifest, readFileSync(manifest, "utf8").replace("  dir: ui", "  dir: frontend/dist\n  build: {cwd: frontend, command: [npm, run, build]}"));
+        writeFileSync(manifest, readFileSync(manifest, "utf8").replace("  dir: ui", "  dir: frontend/dist\n  build: {cwd: frontend, command: [npm, run, build]}").replace("  launch: new-page\n", "").replace("Non-UI-SDK frontends open a full page", "UI SDK frontends open a DSM window"));
         rmSync(join(targetDir, "ui"), { recursive: true });
     }
     if (ui !== "vue")

package/dist/inspect.js

@@ -31,7 +31,7 @@ export function inspectProject(project) {
         const primary = publishedPorts[0];
         webHints.push(`Detected published port ${primary.port}; consider setting adminport: ${primary.port} in synology-app.yaml.`);
         webHints.push("A Web App usually also needs adminprotocol and adminurl.");
-        webHints.push("Launch Mode: integration.web.launch is dsm-window (default, DSM window) or new-page (new tab).");
+        webHints.push("Launch Mode: integration.web.launch is dsm-window (DSM window) or new-page (default, new tab).");
     }
     const exposedPorts = listPortExposures(compose).filter((exposure) => !exposure.loopbackOnly);
     return { services, publishedPorts, dataMounts, risks, webHints, exposedPorts };

package/dist/runtime/executor-digests.json

@@ -1,5 +1,5 @@
 {
-    "0.13.0": {
+    "0.14.1": {
         "x86_64": "efe409287770f6b70e7f8465e8767eeb2413b9ab8775020cf4dffb1555d7bf1f",
         "aarch64": "d68c9889ed2391e918b9c278679ea0a01cd04425528c11090700a3b6341fc543",
         "armv7": "9149a05efb9f2d7d86a400707099b3d657382b1c0dbad6588be8c500e90445cc",
@@ -10,7 +10,7 @@
         },
         "goToolchain": "go1.26.9"
     },
-    "0.13.1": {
+    "0.14.0": {
         "x86_64": "efe409287770f6b70e7f8465e8767eeb2413b9ab8775020cf4dffb1555d7bf1f",
         "aarch64": "d68c9889ed2391e918b9c278679ea0a01cd04425528c11090700a3b6341fc543",
         "armv7": "9149a05efb9f2d7d86a400707099b3d657382b1c0dbad6588be8c500e90445cc",

package/dist/standalone/dsm-window.js

@@ -1,3 +1,4 @@
+import { resolvedSdkLaunch, dsmLauncherType } from "../contract/app-launch.js";
 import { REOPEN_EVENTS_RUNTIME } from "./reopen-events.js";
 import { LAUNCH_PARAMS_RUNTIME } from "./launch-params.js";
 import { DSM_LANGS } from "./i18n.js";
@@ -99,7 +100,8 @@ export function renderUiConfig(manifest, icons = packageIcons(manifest.icon), lo
     return `${JSON.stringify({
         [windowScriptName(manifest)]: {
             [`${ns}.Instance`]: {
-                type: "app",
+                type: dsmLauncherType(resolvedSdkLaunch(manifest), true),
+                ...(manifest.portal ? { defaultAlias: manifest.portal.alias } : {}),
                 ...titleFields,
                 icon,
                 appWindow: `${ns}.MainWindow`,
@@ -316,6 +318,18 @@ ${ns}.fullPage = function () {
 };
 ${ns}.appIcon = ${JSON.stringify(`webman/3rdparty/${pkg}/${windowIconFile(icons, 64)}`)};
 
+// Standalone pages own their title, favicon and device viewport, for any UI.
+${ns}.prepareFullPage = function (title) {
+  if (!${ns}.fullPage()) return;
+  document.title = title;
+  var viewport = document.querySelector && document.querySelector('meta[name="viewport"]');
+  if (!viewport) { viewport = document.createElement("meta"); viewport.name = "viewport"; document.head.appendChild(viewport); }
+  viewport.content = "width=device-width, initial-scale=1, viewport-fit=cover";
+  var favicon = document.querySelector && document.querySelector('link[rel="icon"]');
+  if (!favicon) { favicon = document.createElement("link"); favicon.rel = "icon"; document.head.appendChild(favicon); }
+  favicon.href = ${ns}.appIcon;
+};
+
 // DSM reopens a window at the size it was last left at, even one saved on a
 // larger screen, and only moves a window that does not fit: keep it inside.
 ${ns}.fitDesktop = function (size) {
@@ -367,6 +381,7 @@ ${root ? root.mount : ""}    ${ns}.loadApp(function (app) {
         var i18n = ${ns}.createI18n(lang, ${ns}.messages);
         me.hostAccess = ${ns}.createHost({ appWindow: me, locale: i18n.locale });
         root.lang = i18n.locale;
+        ${ns}.prepareFullPage(${ns}.createI18n(lang, ${JSON.stringify(displayNameCatalogs(manifest))}).t("app_title"));
         try {
           me.mounted = app.mount(root, Ext.apply(ctx, {
           displayName: ${ns}.createI18n(lang, ${JSON.stringify(displayNameCatalogs(manifest))}).t("app_title"),

package/dist/standalone/inspect-spk.d.ts

@@ -1,3 +1,4 @@
+import { type WebLaunchMode } from "../contract/web-launch.js";
 import { type ExecutorInspection } from "../runtime/executor-inspect.js";
 import { type AppScriptName } from "./app-scripts.js";
 import type { EntryMode } from "./manifest.js";
@@ -31,6 +32,8 @@ export interface SpkInspection {
     };
     /** Declared `entry` mode; `admin-only` is the administrator floor of every route. */
     entry?: EntryMode;
+    /** The declared launch mode verified against the built launcher. */
+    launch?: WebLaunchMode;
     /** The App's own scripts/app/<DSM script name>, each called from the generated script of that name. */
     appScripts?: AppScriptName[];
     /** PACKAGE_ICON_256.PNG: the SDK default, a custom icon (by digest) or none. */

package/dist/standalone/inspect-spk.js

@@ -1,3 +1,6 @@
+import { dsmLauncherType } from "../contract/app-launch.js";
+import { isWebLaunchMode, resolvedWebLaunch, trustedAppEntryPath, usesAuthGateway } from "../contract/web-launch.js";
+import { loadContract } from "../contract/load.js";
 import { readComposeApp } from "./compose.js";
 import { createHash } from "node:crypto";
 import { inspectNativeLayout } from "./native-layout.js";
@@ -63,7 +66,7 @@ export async function inspectSpk(spkPath, expectedKind) {
         if (metadataText !== undefined) {
             try {
                 const raw = JSON.parse(metadataText);
-                if (raw.schema !== 2 || !["go", "python", "node", "rust", "binary"].includes(raw.backend) || !Array.isArray(raw.capabilities) || raw.capabilities.some((name) => !["files", "jobs", "identity", "rootOps", "delegate", "webapi"].includes(String(name))) || new Set(raw.capabilities).size !== raw.capabilities.length || (raw.entry !== undefined && !["admin-only", "app-privilege"].includes(raw.entry)))
+                if ((raw.launch !== undefined && !isWebLaunchMode(raw.launch)) || raw.schema !== 2 || !["go", "python", "node", "rust", "binary"].includes(raw.backend) || !Array.isArray(raw.capabilities) || raw.capabilities.some((name) => !["files", "jobs", "identity", "rootOps", "delegate", "webapi"].includes(String(name))) || new Set(raw.capabilities).size !== raw.capabilities.length || (raw.entry !== undefined && !["admin-only", "app-privilege"].includes(raw.entry)))
                     throw new Error();
                 metadata = raw;
             }
@@ -144,6 +147,7 @@ export async function inspectSpk(spkPath, expectedKind) {
         }
         if (metadata.entry)
             await checkEntryLauncher(dir, info.package, metadata.entry, findings);
+        const launch = await checkLaunchConfiguration(dir, info, standalone, metadata.launch, portal?.alias ?? executor?.policy.portal?.alias, findings);
         const loginStyle = standalone ? await inspectLoginStyle(dir, info.package, Boolean(portal || executor?.policy.portal), findings) : undefined;
         if (standalone)
             checkSharedFolder(dir, findings, info.package, sharedFolder, executor?.policy.scope === 'install-selected', portal, hasExecutor);
@@ -157,6 +161,7 @@ export async function inspectSpk(spkPath, expectedKind) {
         }
         return {
             kind,
+            ...(launch ? { launch } : {}),
             icon,
             ...(executor ? { executor } : {}),
             ...(portal ? { portal: { appId: portal.appId, alias: portal.alias } } : {}),
@@ -179,6 +184,57 @@ export async function inspectSpk(spkPath, expectedKind) {
         rmSync(dir, { recursive: true, force: true });
     }
 }
+const LAUNCHER_TYPE_MISMATCH = "LAUNCHER_TYPE_MISMATCH";
+const LAUNCHER_PORTAL_MISMATCH = "LAUNCHER_PORTAL_MISMATCH";
+/** Compare the actual launcher and Portal fields to the packaged declaration. */
+async function checkLaunchConfiguration(dir, info, native, declared, alias, findings) {
+    const target = join(dir, "launch-inspection");
+    mkdirSync(target);
+    await tar.x({ file: join(dir, "package.tgz"), cwd: target, filter: path => ["ui/config", "synology-app.yaml"].includes(path.replace(/^\.\//, "")) });
+    let launch = declared ?? "dsm-window";
+    let url;
+    if (!native) {
+        let contract;
+        try {
+            contract = loadContract(join(target, "synology-app.yaml")).contract;
+        }
+        catch {
+            findings.push(`${LAUNCHER_TYPE_MISMATCH} cannot read the packaged web launch declaration; rebuild with synopkgland build`);
+            return undefined;
+        }
+        const resolved = resolvedWebLaunch(contract);
+        if (!resolved) {
+            if (contract.adminport !== undefined)
+                findings.push(`${LAUNCHER_TYPE_MISMATCH} invalid packaged web launch mode; use dsm-window or new-page and rebuild`);
+            return undefined; // A headless service has no launcher.
+        }
+        launch = resolved;
+        url = trustedAppEntryPath(contract);
+        try {
+            const resource = JSON.parse(readFileSync(join(dir, "conf/resource"), "utf8"));
+            const portals = resource.webservice?.portals ?? [];
+            if (usesAuthGateway(contract) ? portals.length > 0 : portals.some((p) => p.app !== (launch === "dsm-window" ? info.package : undefined))) {
+                findings.push(`${LAUNCHER_PORTAL_MISMATCH} Web Station entries differ from the declared access and launch mode; rebuild with synopkgland build`);
+            }
+        }
+        catch { /* checkConf reports invalid resources */ }
+    }
+    const appId = native ? `SYNO.SDS.${info.package}.Instance` : info.package;
+    let launcher;
+    try {
+        const config = JSON.parse(readFileSync(join(target, "ui/config"), "utf8"));
+        launcher = Object.values(config).map((entries) => entries[appId]).find(Boolean);
+    }
+    catch { /* report the missing or malformed launcher below */ }
+    const type = dsmLauncherType(launch, native);
+    if (!launcher || launcher.type !== type || info.dsmuidir !== "ui" || info.dsmappname !== appId || (native ? launcher.appWindow !== `SYNO.SDS.${info.package}.MainWindow` : launcher.url !== url || info.adminurl !== url)) {
+        findings.push(`${LAUNCHER_TYPE_MISMATCH} ${launch} requires a ${type} launcher at ${appId} and matching INFO entry; rebuild with synopkgland build`);
+    }
+    if (launcher && (launcher.defaultAlias !== alias || (!alias && (launcher.loginStyle !== undefined || launcher.loginIcon !== undefined)))) {
+        findings.push(`${LAUNCHER_PORTAL_MISMATCH} defaultAlias and login fields require an explicit matching portal declaration; remove them or opt in to portal and rebuild`);
+    }
+    return launch;
+}
 /** The launcher in ui/config must carry exactly the access the declared entry mode fixes. */
 async function checkEntryLauncher(dir, pkg, entry, findings) {
     const target = join(dir, "entry-inspection");

package/dist/standalone/manifest.d.ts

@@ -1,3 +1,4 @@
+import { type WebLaunchMode } from "../contract/web-launch.js";
 import { type WebAPIProfiles } from '../runtime/webapi-profile.js';
 import { type PackageMetadata } from "../package-metadata.js";
 import { type DelegateCapability } from "../runtime/executor-policy.js";
@@ -61,6 +62,7 @@ export interface StandaloneManifest {
     /** `ui.window`: the DSM window's size over the defaults; absent keeps 960×640, at least 700×420. */
     ui: {
         dir: string;
+        launch?: WebLaunchMode;
         build?: {
             cwd: string;
             command: string[];

package/dist/standalone/manifest.js

@@ -1,3 +1,4 @@
+import { isWebLaunchMode } from "../contract/web-launch.js";
 import { validWebAPIProfiles } from '../runtime/webapi-profile.js';
 import { validateMetadata } from "../package-metadata.js";
 import { validDelegate } from "../runtime/executor-policy.js";
@@ -487,13 +488,16 @@ function readUi(value, c) {
     if (!isRecord(value)) {
         return c.fail("STANDALONE_UI_INVALID", "ui must contain dir.");
     }
+    if (value.launch !== undefined && !isWebLaunchMode(value.launch))
+        return c.fail("STANDALONE_UI_LAUNCH_INVALID", "ui.launch must be dsm-window or new-page. Application Portal is a separate opt-in.");
+    const launch = value.launch === undefined ? {} : { launch: value.launch };
     const dir = c.path(value.dir, "ui.dir");
     const read = value.window === undefined ? undefined : readWindowSize(value.window);
     if (read && "error" in read)
         return c.fail("STANDALONE_UI_WINDOW_INVALID", read.error);
     const window = read ? { window: read.size } : {};
     if (value.build === undefined) {
-        return dir ? { dir, ...window } : undefined;
+        return dir ? { dir, ...launch, ...window } : undefined;
     }
     const build = value.build;
     const command = isRecord(build) ? build.command : undefined;
@@ -501,7 +505,7 @@ function readUi(value, c) {
         return c.fail("STANDALONE_UI_BUILD_INVALID", "ui.build.command must be an argv string array (not going through a shell), for example [npm, run, build].");
     }
     const cwd = c.path(build.cwd, "ui.build.cwd");
-    return dir && cwd ? { dir, build: { cwd, command: command }, ...window } : undefined;
+    return dir && cwd ? { dir, build: { cwd, command: command }, ...launch, ...window } : undefined;
 }
 function readI18n(value, c) {
     const invalid = (why) => c.fail("STANDALONE_I18N_INVALID", `i18n ${why}`);

package/dist/standalone/spk.js

@@ -1,3 +1,4 @@
+import { resolvedSdkLaunch } from "../contract/app-launch.js";
 import { metadataInfoFields } from "../package-metadata.js";
 import { createHash } from "node:crypto";
 import { chmodSync, copyFileSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync, } from "node:fs";
@@ -146,7 +147,7 @@ export async function assembleStandaloneSpk(options) {
         await createReproducibleTar(join(staging, "package"), packageTgz, { gzip: true });
         rmSync(join(staging, "package"), { recursive: true, force: true });
         const checksum = createHash("md5").update(readFileSync(packageTgz)).digest("hex");
-        writeFile(join(staging, "sdk-package.json"), JSON.stringify({ schema: 2, backend: manifest.backend.kind, capabilities: Object.keys(manifest.capabilities).sort(), ...(manifest.compose ? { compose: { services: manifest.compose.services } } : {}), ...(manifest.entry ? { entry: manifest.entry } : {}), ...(manifest.uninstall ? { uninstall: uninstallRecord(manifest.uninstall, manifest.i18n?.catalogs) } : {}) }));
+        writeFile(join(staging, "sdk-package.json"), JSON.stringify({ schema: 2, backend: manifest.backend.kind, launch: resolvedSdkLaunch(manifest), capabilities: Object.keys(manifest.capabilities).sort(), ...(manifest.compose ? { compose: { services: manifest.compose.services } } : {}), ...(manifest.entry ? { entry: manifest.entry } : {}), ...(manifest.uninstall ? { uninstall: uninstallRecord(manifest.uninstall, manifest.i18n?.catalogs) } : {}) }));
         writeFile(join(staging, "INFO"), renderInfo(manifest, options.arch, checksum, options.executor?.executorDigest));
         mkdirSync(join(staging, "conf"));
         writeFile(join(staging, "conf", "privilege"), renderNativePrivilege());

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synopackageland/cli",
-  "version": "0.13.1",
+  "version": "0.14.1",
   "description": "Syno Package Land Developer Kit CLI",
   "type": "module",
   "bin": {
@@ -25,7 +25,7 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@synopackageland/templates": "0.13.1",
+    "@synopackageland/templates": "0.14.1",
     "ajv": "^8.17.1",
     "commander": "^13.1.0",
     "tar": "^7.4.3",

package/schema/synology-app.schema.json

@@ -122,7 +122,7 @@
                 "dsm-window",
                 "new-page"
               ],
-              "description": "Web App Launch Mode. dsm-window opens a DSM Application Window at the Trusted App Entry; new-page uses Package Center Open. Omit for dsm-window. Headless apps omit this field."
+              "description": "Web App Launch Mode. dsm-window opens a DSM Application Window at the Trusted App Entry; new-page opens a new tab from the main menu and Package Center. Omit for new-page. Headless apps omit this field."
             },
             "cookies": {
               "type": "array",

package/skills/SKILL.md

@@ -131,3 +131,34 @@ sweep forward the cancel instead of admitting it.
   adapt a real producer; show Saved only from a protected committed receipt.
 - Wizard support is measured on vt-nas DSM 7.4 via a session-only SSH local
   forward. This is not proof of other DSM releases or full writer/reboot behavior.
+
+## 開啟方式
+
+原生 App 在 `dsm-package.yaml` 設定 `ui.launch: dsm-window | new-page`。
+SDK 原生 App 的內建預設為 `dsm-window`。使用 `@synopackageland/ui` 的前端維持視窗；
+其他前端必須明確設定 `new-page`，不宣告 Application Portal。
+Scaffold 明確寫入此選擇，plain／binary 使用 `new-page`，Vue UI SDK 使用
+預設的 `dsm-window`（省略 `ui.launch`）。原生 manifest 省略 `ui.launch` 時解析為 `dsm-window`，CLI 不猜測前端依賴。
+
+`new-page` 產生 DSM `type: "standalone"` launcher，主選單及套件中心皆在 DSM
+本身的 origin 開啟全頁。`ctx.fullPage`、`ctx.appIcon`、SynoToken／session、
+`ctx.launchParams`／`onLaunch`、`entry` 權限沿用共用 wrapper；全頁的標題、
+favicon 與手機 viewport 由 wrapper 設定。不需要 `pureEnv` 或 `allowAltPort`。
+
+Application Portal 是獨立 opt-in：不想要別名就省略 `portal`，不生成
+`defaultAlias`、Portal 面板／capability 或 Web Station alias；沒有 Portal
+不是 inspect／info／doctor 問題。明確啟用 `portal` 時才將其 alias 作為 `defaultAlias`。
+
+Docker／web service App 設定 `integration.web.launch`，內建預設是 `new-page`；
+省略開啟方式時直接開新分頁，不宣告 Application Portal。SDK 原生 App
+省略時使用 `dsm-window`；非 UI SDK 原生 App 必須明確寫 `ui.launch: new-page`。
+Web service 主選單使用
+`type: "url"` 與明確的 `url` 指向既有 DSM gateway。明確 `access: public` 才保留 Web Station
+alias；這是服務入口，不是 SDK Application Portal。DSM 會將 standalone URL 改寫成 launchApp 頁面，
+需要 AppInstance／AppWindow JS class；schema 1 web service 沒有該 class，因此使用 url。需要 DSM 視窗時明寫 `dsm-window`。
+
+Schema 2 的 `dsm-package.yaml` + `identity_gateway` + `compose` 同樣視為
+web service：省略 `ui.launch` 時預設 `new-page`，使用 standalone launcher，
+不帶 Application Portal。兩條 Compose 路線共用 `contract/app-launch.ts`
+解析開啟方式與選擇 launcher 型別；明確的 `ui.launch` 可覆寫預設。
+只有沒有 web service 的 SDK 原生 App 省略時才預設 `dsm-window`。

package/skills/reference/create.md

@@ -39,8 +39,8 @@ rootOps 與 delegate 已共用管理員 PasswordConfirm 核准的 protected exec
 backend 寫 `runtime: python|node|rust`（`runtime: go` 等同 `kind: go`）。CGI 是 SDK 的 Go runtime（`bridge/cmd/runtime`），它驗證 DSM session、entry 與 `permissions.json` 後，以套件帳號（不是 root）每個請求啟動一次 App。App 放在 ui 以外的目錄，打包成 `target/app/`，build 寫入 `bridge.json`（spec/bridge/v1）並把它與 `permissions.json` 的 sha256 編進 runtime。
 
 ```yaml
-backend: {runtime: python, dir: app, entry: main.py, sdk: 0.13.1}
-backend: {runtime: node, dir: app, entry: main.mjs, sdk: 0.13.1, node: {package: Node.js_v20}}
+backend: {runtime: python, dir: app, entry: main.py, sdk: 0.14.1}
+backend: {runtime: node, dir: app, entry: main.mjs, sdk: 0.14.1, node: {package: Node.js_v20}}
 backend: {runtime: rust, dir: app, entry: hello, methods: [hello.greet]}
 ```
 
@@ -214,3 +214,34 @@ sweep forward the cancel instead of admitting it.
   adapt a real producer; show Saved only from a protected committed receipt.
 - Wizard support is measured on vt-nas DSM 7.4 via a session-only SSH local
   forward. This is not proof of other DSM releases or full writer/reboot behavior.
+
+## 開啟方式
+
+原生 App 在 `dsm-package.yaml` 設定 `ui.launch: dsm-window | new-page`。
+SDK 原生內建預設為 `dsm-window`；使用 `@synopackageland/ui` 維持視窗，
+其他原生前端必須明確寫 `ui.launch: new-page`。
+Scaffold 明確寫入此選擇，plain／binary 使用 `new-page`，Vue UI SDK 使用
+預設的 `dsm-window`（省略 `ui.launch`）。原生 manifest 省略 `ui.launch` 時解析為 `dsm-window`，CLI 不猜測前端依賴。
+
+`new-page` 產生 DSM `type: "standalone"` launcher，主選單及套件中心皆在 DSM
+本身的 origin 開啟全頁。`ctx.fullPage`、`ctx.appIcon`、SynoToken／session、
+`ctx.launchParams`／`onLaunch`、`entry` 權限沿用共用 wrapper；全頁的標題、
+favicon 與手機 viewport 由 wrapper 設定。不需要 `pureEnv` 或 `allowAltPort`。
+
+Application Portal 是獨立 opt-in：不想要別名就省略 `portal`，不生成
+`defaultAlias`、Portal 面板／capability 或 Web Station alias；沒有 Portal
+不是 inspect／info／doctor 問題。明確啟用 `portal` 時才將其 alias 作為 `defaultAlias`。
+
+Docker／web service App 設定 `integration.web.launch`，內建預設是 `new-page`；
+省略開啟方式時直接開新分頁，不宣告 Application Portal。SDK 原生 App
+省略時使用 `dsm-window`；非 UI SDK 原生 App 必須明確寫 `ui.launch: new-page`。
+Web service 主選單使用
+`type: "url"` 與明確的 `url` 指向既有 DSM gateway。明確 `access: public` 才保留 Web Station
+alias；這是服務入口，不是 SDK Application Portal。DSM 會將 standalone URL 改寫成 launchApp 頁面，
+需要 AppInstance／AppWindow JS class；schema 1 web service 沒有該 class，因此使用 url。需要 DSM 視窗時明寫 `dsm-window`。
+
+Schema 2 的 `dsm-package.yaml` + `identity_gateway` + `compose` 同樣視為
+web service：省略 `ui.launch` 時預設 `new-page`，使用 standalone launcher，
+不帶 Application Portal。兩條 Compose 路線共用 `contract/app-launch.ts`
+解析開啟方式與選擇 launcher 型別；明確的 `ui.launch` 可覆寫預設。
+只有沒有 web service 的 SDK 原生 App 省略時才預設 `dsm-window`。

package/skills/reference/identity-gateway.md

@@ -37,7 +37,7 @@ Start with a schema-2 native-go or binary project for the native CGI and package
 UI. Add `compose` to **dsm-package.yaml**; do not combine the legacy
 `synology-app.yaml` Compose contract with it. Omit `daemon`. Set `os_min_ver` to
 at least `7.2.1-69057`, `capabilities: {}`, and supply one helper payload directory
-per architecture. The examples below pin released SDK 0.13.1, which contains the gateway/account APIs.
+per architecture. The examples below pin released SDK 0.14.1, which contains the gateway/account APIs.
 
 ```yaml
 compose:
@@ -46,7 +46,7 @@ compose:
   services:
     openlist: {address_env: ADDR, port: 25244}
 identity_gateway:
-  sdk: 0.13.1
+  sdk: 0.14.1
   mode: oidc
   upstream: 25244
   listen: {http: 25240, https: 25241}
@@ -114,7 +114,7 @@ as a firewall: correct bindings must be established before deployment.
 Use the existing native `daemon` route. A project-owned `absglue run` launches
 the unmodified ABS binary, binds it to loopback with the supported host/base
 path settings, configures OIDC through its API, and supervises it. The same
-helper implements idempotent deletion. The example pins released SDK 0.13.1.
+helper implements idempotent deletion. The example pins released SDK 0.14.1.
 
 ```yaml
 daemon:
@@ -122,7 +122,7 @@ daemon:
   targets: {x86_64: payload}
   args: [run]
 identity_gateway:
-  sdk: 0.13.1
+  sdk: 0.14.1
   mode: oidc
   upstream: 13378
   listen: {http: 13380, https: 13443}
@@ -172,3 +172,9 @@ deleting audio files. A minimal fixture directory is not proof of full purge.
 - Clean up only task-owned users, package/project/containers/images, private
   fixtures and test resources. Read back absence. Keep DSM-retained package
   identities unless their deletion was authorized, and report their names.
+
+Schema 2 的 `dsm-package.yaml` + `identity_gateway` + `compose` 同樣視為
+web service：省略 `ui.launch` 時預設 `new-page`，使用 standalone launcher，
+不帶 Application Portal。兩條 Compose 路線共用 `contract/app-launch.ts`
+解析開啟方式與選擇 launcher 型別；明確的 `ui.launch` 可覆寫預設。
+只有沒有 web service 的 SDK 原生 App 省略時才預設 `dsm-window`。

package/skills/reference/portal.md

@@ -35,3 +35,34 @@ Never: write `AppPortal.json`, `@appconf/<package>` or `/usr/syno/etc/www/app.d`
 Uninstall: the root executor's purge deletes the rules of `SYNO.SDS.<package>.Instance` through the Application Privileges API and, once DSM has removed the alias files, reloads nginx (`synosystemctl reload nginx`), so the alias stops at once. Failures are only logged to the system log entry `synopkgland-executor`; then an administrator saves an alias in Control Panel > Login Portal > Applications (which reloads nginx) or restarts the NAS, and removes the rules in Control Panel > Application Privileges. The uninstall wizard and the `status`/`inspect` cleanup list say this in that order: automatic first, manual only as the fallback.
 
 Executor mode uninstall: the purge reads the retained policy and unregisters the entry. If the executor is not running or was never approved, uninstall does not remove the entry; the wizard and cleanup list say so and give the root commands (`rm -f /usr/syno/etc/www/app.d/<package>.json /usr/syno/etc/www/app.d/<package>.mustache /usr/syno/etc/packages/<package>/AppPortal.json`, `synow3tool --disable-nginx-confd/--unreg-nginx-confd` for `dsm www alias .alias`, `--disable-nginx-sites/--unreg-nginx-sites` for `server .server` on `<c>.syno-app-portal.<package>.conf`, then `nginx -t && synow3tool --nginx=reload`).
+
+## 開啟方式
+
+原生 App 在 `dsm-package.yaml` 設定 `ui.launch: dsm-window | new-page`。
+SDK 原生內建預設為 `dsm-window`；使用 `@synopackageland/ui` 維持視窗，
+其他原生前端必須明確寫 `ui.launch: new-page`。
+Scaffold 明確寫入此選擇，plain／binary 使用 `new-page`，Vue UI SDK 使用
+預設的 `dsm-window`（省略 `ui.launch`）。原生 manifest 省略 `ui.launch` 時解析為 `dsm-window`，CLI 不猜測前端依賴。
+
+`new-page` 產生 DSM `type: "standalone"` launcher，主選單及套件中心皆在 DSM
+本身的 origin 開啟全頁。`ctx.fullPage`、`ctx.appIcon`、SynoToken／session、
+`ctx.launchParams`／`onLaunch`、`entry` 權限沿用共用 wrapper；全頁的標題、
+favicon 與手機 viewport 由 wrapper 設定。不需要 `pureEnv` 或 `allowAltPort`。
+
+Application Portal 是獨立 opt-in：不想要別名就省略 `portal`，不生成
+`defaultAlias`、Portal 面板／capability 或 Web Station alias；沒有 Portal
+不是 inspect／info／doctor 問題。明確啟用 `portal` 時才將其 alias 作為 `defaultAlias`。
+
+Docker／web service App 設定 `integration.web.launch`，內建預設是 `new-page`；
+省略開啟方式時直接開新分頁，不宣告 Application Portal。SDK 原生 App
+省略時使用 `dsm-window`；非 UI SDK 原生 App 必須明確寫 `ui.launch: new-page`。
+Web service 主選單使用
+`type: "url"` 與明確的 `url` 指向既有 DSM gateway。明確 `access: public` 才保留 Web Station
+alias；這是服務入口，不是 SDK Application Portal。DSM 會將 standalone URL 改寫成 launchApp 頁面，
+需要 AppInstance／AppWindow JS class；schema 1 web service 沒有該 class，因此使用 url。需要 DSM 視窗時明寫 `dsm-window`。
+
+Schema 2 的 `dsm-package.yaml` + `identity_gateway` + `compose` 同樣視為
+web service：省略 `ui.launch` 時預設 `new-page`，使用 standalone launcher，
+不帶 Application Portal。兩條 Compose 路線共用 `contract/app-launch.ts`
+解析開啟方式與選擇 launcher 型別；明確的 `ui.launch` 可覆寫預設。
+只有沒有 web service 的 SDK 原生 App 省略時才預設 `dsm-window`。

package/skills/reference/ui-vue.md

@@ -94,3 +94,34 @@ with the same PasswordConfirm form and no extra dialog. Mismatch must be explici
 Restrict the existing NasPicker to `selection.root`; do not grant via cached paths.
 The default facade includes typed `destination(key)` and `exportExample({key,job_id})`;
 use original operation references and display Saved only for protected receipts.
+
+## 開啟方式
+
+原生 App 在 `dsm-package.yaml` 設定 `ui.launch: dsm-window | new-page`。
+SDK 原生內建預設為 `dsm-window`；使用 `@synopackageland/ui` 維持視窗，
+其他原生前端必須明確寫 `ui.launch: new-page`。
+Scaffold 明確寫入此選擇，plain／binary 使用 `new-page`，Vue UI SDK 使用
+預設的 `dsm-window`（省略 `ui.launch`）。原生 manifest 省略 `ui.launch` 時解析為 `dsm-window`，CLI 不猜測前端依賴。
+
+`new-page` 產生 DSM `type: "standalone"` launcher，主選單及套件中心皆在 DSM
+本身的 origin 開啟全頁。`ctx.fullPage`、`ctx.appIcon`、SynoToken／session、
+`ctx.launchParams`／`onLaunch`、`entry` 權限沿用共用 wrapper；全頁的標題、
+favicon 與手機 viewport 由 wrapper 設定。不需要 `pureEnv` 或 `allowAltPort`。
+
+Application Portal 是獨立 opt-in：不想要別名就省略 `portal`，不生成
+`defaultAlias`、Portal 面板／capability 或 Web Station alias；沒有 Portal
+不是 inspect／info／doctor 問題。明確啟用 `portal` 時才將其 alias 作為 `defaultAlias`。
+
+Docker／web service App 設定 `integration.web.launch`，內建預設是 `new-page`；
+省略開啟方式時直接開新分頁，不宣告 Application Portal。SDK 原生 App
+省略時使用 `dsm-window`；非 UI SDK 原生 App 必須明確寫 `ui.launch: new-page`。
+Web service 主選單使用
+`type: "url"` 與明確的 `url` 指向既有 DSM gateway。明確 `access: public` 才保留 Web Station
+alias；這是服務入口，不是 SDK Application Portal。DSM 會將 standalone URL 改寫成 launchApp 頁面，
+需要 AppInstance／AppWindow JS class；schema 1 web service 沒有該 class，因此使用 url。需要 DSM 視窗時明寫 `dsm-window`。
+
+Schema 2 的 `dsm-package.yaml` + `identity_gateway` + `compose` 同樣視為
+web service：省略 `ui.launch` 時預設 `new-page`，使用 standalone launcher，
+不帶 Application Portal。兩條 Compose 路線共用 `contract/app-launch.ts`
+解析開啟方式與選擇 launcher 型別；明確的 `ui.launch` 可覆寫預設。
+只有沒有 web service 的 SDK 原生 App 省略時才預設 `dsm-window`。

package/skills/reference/wrap.md

@@ -34,3 +34,12 @@ the legacy Compose route below retains its restrictions.
 
 - 要身分／檔案整合 → `identity.md`／`files.md`
 - 要上 NAS → `deploy.md`
+
+## 開啟方式
+
+Docker／web service App 的 `integration.web.launch` 內建預設為 `new-page`。
+主選單與套件中心開啟既有 gateway，不產生 Application Portal。
+schema 1 新分頁 launcher 使用 `type: "url"` 與明確 `url`；DSM 的 standalone
+會改寫成需要 AppWindow JS class 的 launchApp 頁面。schema 2 SDK wrapper
+有此 class，因此使用 standalone。只有 `access: public` 需要 Web Station alias。
+SDK 原生 App 的 `ui.launch` 內建預設是 `dsm-window`；非 UI SDK 前端明寫 `new-page`。