@nexia/sdk 0.8.8 → 0.8.9

package/README.md

@@ -8,6 +8,35 @@ Report SDK, setup, CLI, Docker, AI-tool and sandbox problems in the [central dev
 
 SDK·개발환경·CLI·Docker·AI 도구·샌드박스 문제는 [통합 이슈 창구](https://github.com/nexia-cloud-os/developer-support/issues)에 신고하세요. 기존 이슈를 먼저 검색하고 패키지 버전과 최소 재현 단계를 포함하세요. 인증 정보, 비공개 Core 소스와 고객 데이터는 첨부하지 마세요.
 
+## Standalone App frontend tests
+
+Run Vitest in the App repository with `environment: 'jsdom'`, its own setup file,
+and the App's React dependencies. Install `@testing-library/react`,
+`@testing-library/jest-dom`, `jsdom`, `i18next`, `msw`, and `vitest` as App test
+dependencies. No Core checkout or Core test setup is required.
+
+The existing `configureNexiaAppFrontendHost` API accepts a complete explicit host
+fixture. `configureNexiaAppFrontendTestHost` connects the suite's i18n and MSW
+instances to `appTestI18n` and `appTestServer`.
+
+Configure explicit host capabilities through the existing public API in the
+suite's setup file. Supply a real axios instance and explicit public component,
+hook, runtime, and registry fixtures for the capabilities exercised by that suite.
+Missing capabilities should throw instead of supplying automatic UI or permission
+substitutes. No new SDK API or SDK release is needed.
+
+Connect the suite's own i18n and MSW instances with
+`configureNexiaAppFrontendTestHost({ i18n, server })`. Register
+`server.listen({ onUnhandledRequest: 'error' })` in Vitest `beforeAll`, run React
+Testing Library `cleanup()` and `server.resetHandlers()` in `afterEach`, and call
+`server.close()` in `afterAll`. Use one installed SDK instance throughout the
+suite so its main and `/testing` exports share the same configured host.
+
+App fixtures can verify App branching, validation, and request payloads. A DOM
+substitute for a host component does not verify that component's accessibility,
+keyboard behavior, or production rendering; those checks belong to its host.
+Reconfigure mutable fixtures per test to avoid state leaking between cases.
+
 ## Standalone App styles
 
 `nexiaAppConfig(import.meta.url)` generates Tailwind utilities from the App resources, including lazy screens, and records emitted CSS in `nexia-host.json`. The build references the shared `@nexia/sdk/theme.css` token aliases; Core supplies token values and resets. Keep those aliases aligned with the Core theme contract. Do not bundle a second preflight or global theme.

package/changelog/0.8.9/en.md

@@ -0,0 +1,17 @@
+---
+status: published
+version: 0.8.9
+date: 2026-10-16
+title: App frontend compatibility metadata
+description: App frontend compatibility metadata
+---
+
+# App frontend compatibility metadata
+
+The standalone App build records its declared `@nexia/sdk` range, the SDK used to build it, and the shared host exports imported by the generated JavaScript. Platforms supporting this metadata can check compatibility before changing the host or opening a new App bundle. SDK version ranges do not replace behavioral compatibility tests.
+
+Keep the supported SDK range in the App's `package.json` `peerDependencies` or `dependencies` and retain the dependency lock. Peer requirements take precedence when both are present. Rebuild with this SDK to include the metadata; the metadata alone does not require a new App version or change existing published bundles.
+
+Apps without an explicit SDK requirement still build with their existing frontend manifest. Their host compatibility remains unknown and must be verified before a platform update. No automatic App upgrade is introduced.
+
+Standalone builds warn when emitted JavaScript uses the deprecated `allowsManualAppFallback` or `isRetryableHandoffFailure` aliases. Replace them with `permitsManualFallback` or `isRetryableFailure`, respectively. No removal version is scheduled. This import check does not inspect erased TypeScript types or PHP annotations.

package/changelog/0.8.9/ko.md

@@ -0,0 +1,17 @@
+---
+status: published
+version: 0.8.9
+date: 2026-10-16
+title: 앱 프런트엔드 호환성 메타데이터
+description: 앱 프런트엔드 호환성 메타데이터
+---
+
+# 앱 프런트엔드 호환성 정보
+
+독립 앱 빌드에 선언된 `@nexia/sdk` 지원 범위, 빌드에 사용한 SDK 버전, 생성된 JavaScript가 가져오는 공용 호스트 export 목록이 기록됩니다. 이 정보를 지원하는 플랫폼은 호스트를 바꾸거나 새 앱 번들을 열기 전에 호환성을 확인할 수 있습니다. SDK 버전 범위만으로 실제 동작의 호환성 검증을 대신할 수는 없습니다.
+
+앱 `package.json`의 `peerDependencies` 또는 `dependencies`에 지원 SDK 범위를 유지하고 의존성 잠금 파일을 보관하세요. 두 곳에 모두 있으면 peer 요구사항을 우선합니다. 이번 SDK로 다시 빌드하면 정보가 포함되며, 정보 추가만으로 앱 버전을 올릴 필요는 없습니다. 이미 게시된 번들은 바뀌지 않습니다.
+
+명시적인 SDK 요구사항이 없는 앱도 기존 프런트엔드 manifest 형식으로 빌드됩니다. 다만 호스트 호환성이 확인된 것은 아니므로 플랫폼 업데이트 전에 별도 검증이 필요합니다. 앱을 자동으로 업그레이드하지 않습니다.
+
+독립 빌드의 JavaScript에서 deprecated 별칭인 `allowsManualAppFallback` 또는 `isRetryableHandoffFailure`를 사용하면 경고합니다. 각각 `permitsManualFallback`, `isRetryableFailure`로 바꾸세요. 제거 버전은 정해지지 않았습니다. 이 import 검사는 컴파일 후 사라지는 TypeScript 타입이나 PHP 주석을 검사하지 않습니다.

package/dist/testing.d.ts

@@ -6,7 +6,7 @@ export interface NexiaAppFrontendTestHostBindings {
         use: (...handlers: unknown[]) => void;
     };
 }
-/** Core test setup installs its i18n and request-interception harness here. */
+/** App or host test setup installs its own i18n and request-interception harness here. */
 export declare function configureNexiaAppFrontendTestHost(bindings: NexiaAppFrontendTestHostBindings): void;
 export declare const appTestI18n: {
     changeLanguage: (language: string) => unknown;

package/dist/testing.js

@@ -1,11 +1,11 @@
 let activeTestHost = null;
-/** Core test setup installs its i18n and request-interception harness here. */
+/** App or host test setup installs its own i18n and request-interception harness here. */
 export function configureNexiaAppFrontendTestHost(bindings) {
     activeTestHost = bindings;
 }
 function testHost() {
     if (activeTestHost === null) {
-        throw new Error('Nexia App frontend test host is not configured. Core test setup must configure it before App specs run.');
+        throw new Error('Nexia App frontend test host is not configured. Configure it with the test suite’s own i18n and request-interception fixtures before App specs run.');
     }
     return activeTestHost;
 }

package/dist/vite.mjs

@@ -76,10 +76,39 @@ export const { api, openFile, sendUserInvitation, useDataMigrationBackgroundOper
         },
         generateBundle: { order: 'post', handler(_options, bundle) {
             // Standalone App builds expose compatibility before executing their entry.
-            if (owners.length === 1) this.emitFile({
+            if (owners.length !== 1) return;
+            let appPackage = {};
+            try { appPackage = JSON.parse(readFileSync(path.join(owners[0].root, 'package.json'), 'utf8')); }
+            catch (error) { if (error.code !== 'ENOENT') throw error; }
+            const required = appPackage.peerDependencies?.['@nexia/sdk'] ?? appPackage.dependencies?.['@nexia/sdk'];
+            const sdk = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+            const imports = {};
+            for (const chunk of Object.values(bundle)) {
+                if (chunk.type !== 'chunk') continue;
+                for (const [specifier, bindings] of Object.entries(chunk.importedBindings)) {
+                    if (!nexiaHostPeers.includes(specifier)) continue;
+                    imports[specifier] = [...new Set([...(imports[specifier] ?? []), ...bindings])].sort();
+                }
+                for (const specifier of chunk.dynamicImports) {
+                    if (nexiaHostPeers.includes(specifier)) imports[specifier] = ['*'];
+                }
+            }
+            // These aliases are explicitly deprecated in index.ts; no removal release is declared.
+            const deprecated = { allowsManualAppFallback: 'permitsManualFallback', isRetryableHandoffFailure: 'isRetryableFailure' };
+            for (const [name, replacement] of Object.entries(deprecated)) {
+                if (imports['@nexia/sdk']?.includes(name)) {
+                    this.warn(`[NEXIA_SDK_DEPRECATED] ${name}: use ${replacement}. Removal version is not scheduled.`);
+                }
+            }
+            this.emitFile({
                 type: 'asset', fileName: 'nexia-host.json',
                 source: JSON.stringify({ version: 1, development_updates: 1, app_key: owners[0].appKey,
-                    styles: Object.keys(bundle).filter(file => file.endsWith('.css')) }),
+                    styles: Object.keys(bundle).filter(file => file.endsWith('.css')),
+                    // Preserve builds that predate explicit host requirements. Their compatibility
+                    // remains unknown; operators must not infer permission to change the host.
+                    ...(typeof required === 'string' && required.trim() && required.length <= 256
+                        ? { compatibility: { schema_version: 1, host_contract: 1,
+                            sdk: { package: '@nexia/sdk', required, built_with: sdk.version }, imports } } : {}) }),
             });
         } },
     };

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@nexia/sdk",
-    "version": "0.8.8",
+    "version": "0.8.9",
     "description": "Frontend contracts for Nexia App Packages",
     "license": "UNLICENSED",
     "type": "module",