@magicvr/schema-ui-protocol 0.2.0

package/lib/fetch-timeout.d.ts

@@ -0,0 +1,13 @@
+/**
+ * W10 F-002: fetch timeout wrapper.
+ *
+ * Wraps a fetch implementation so a hung request (slow network, stalled
+ * server) aborts after a bounded window instead of pending forever. The
+ * returned function is drop-in compatible with `typeof fetch`; a caller-
+ * provided AbortSignal in `init` is composed with the timeout signal (either
+ * firing aborts the request). Timers are cleared once the request settles, so
+ * no handles leak on the happy path.
+ */
+/** Default ceiling for a single request (30s). */
+export declare const DEFAULT_FETCH_TIMEOUT_MS = 30000;
+export declare function withTimeout(fetchImpl?: typeof fetch, timeoutMs?: number): typeof fetch;

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@magicvr/schema-ui-protocol",
+  "version": "0.2.0",
+  "type": "module",
+  "description": "schema-ui-core 协议面（v0.2.0 · R4 升级演练=normalizePageID additive）",
+  "main": "index.js",
+  "types": "./protocol/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./protocol/index.d.ts",
+      "import": "./index.js"
+    }
+  },
+  "files": [
+    "index.js",
+    "protocol/",
+    "lib/"
+  ],
+  "license": "UNLICENSED",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/protocol/app-manifest.d.ts

@@ -0,0 +1,117 @@
+export declare const DEFAULT_MANIFEST_PATH = "/.well-known/schema-ui/app-manifest.json";
+/**
+ * Host manifest-version support set (strict negotiation, ADR-0009): 2.7 for
+ * existing production manifests, 2.8 for Host/App interoperability manifests
+ * (returnIntentQueryKeys etc.), 2.9 for ADR-0039/ADR-0040 (data.route-binding /
+ * form.controls.readonly). Kept additive — older manifests stay accepted.
+ */
+export declare const APP_MANIFEST_SUPPORTED_PROTOCOL_VERSIONS: readonly ["2.7", "2.8", "2.9"];
+export declare const APP_MANIFEST_PROTOCOL_VERSION: "2.9";
+export declare const MANIFEST_SOURCE_HEADER = "X-Schema-UI-Manifest-Source";
+export declare const APP_MANIFEST_SOURCE = "https://github.com/magicvr/schema-ui-docs/tree/81aa1d8";
+/** True when `expression` matches the frozen $context expression grammar. */
+export declare function isValidExpression(expression: string): boolean;
+export type ManifestErrorCode = "MANIFEST_LOAD_FAILED" | "MISSING_PROTOCOL_VERSION" | "INVALID_PROTOCOL_VERSION" | "UNSUPPORTED_PROTOCOL_VERSION" | "PROTOCOL_VERSION_TOO_LOW" | "MISSING_REQUIRED_CAPABILITY" | "CAPABILITY_REQUIRED" | "UNKNOWN_MANIFEST_FIELD" | "INVALID_MANIFEST" | "INVALID_PATH" | "MANIFEST_HOME_PAGE_UNKNOWN" | "MANIFEST_HOME_ROUTE_PARAMETRIC" | "PAGE_REF_WITH_EMPTY_PAGES" | "MISSING_PATH_BINDING" | "MANIFEST_PAGE_ID_MISMATCH" | "INVALID_LOGO_URL" | "UNKNOWN_NAV_SLOT" | "NAV_LINK_MUTEX" | "NAV_GROUP_NESTED" | "NAV_PAGE_REF_UNKNOWN" | "INVALID_RETURN_INTENT_QUERY_KEYS" | "FORBIDDEN_VARIABLE" | "SYNTAX";
+export declare class ManifestError extends Error {
+    readonly code: ManifestErrorCode;
+    readonly path: string;
+    /** Optional machine detail (e.g. the missing capability id). */
+    readonly detail?: string;
+    constructor(code: ManifestErrorCode, path: string, message: string, detail?: string);
+}
+export interface AppInfo {
+    appId: string;
+    name?: string;
+    nameKey?: string;
+    homePageRef?: string;
+    logo?: {
+        light: string;
+        dark?: string;
+    };
+    description?: string;
+    descriptionKey?: string;
+}
+export interface PageEntry {
+    pageId: string;
+    title?: string;
+    titleKey?: string;
+    schemaUrl: string;
+    route: string;
+    /** v2.8+ (ADR-0036): auth-return intent allowlist extension for this page. */
+    returnIntentQueryKeys?: string[];
+}
+export interface VisibleWhen {
+    when: string;
+}
+export interface NavPermissions {
+    view?: string;
+}
+export interface NavLink {
+    pageRef?: string;
+    url?: string;
+    label?: string;
+    labelKey?: string;
+    icon?: string;
+    visibleWhen?: VisibleWhen;
+    permissions?: NavPermissions;
+}
+export interface NavGroup {
+    label?: string;
+    labelKey?: string;
+    icon?: string;
+    items: NavLink[];
+    visibleWhen?: VisibleWhen;
+    permissions?: NavPermissions;
+}
+export type NavItem = NavLink | NavGroup;
+export interface Navigation {
+    top?: NavItem[];
+    sidebar?: NavItem[];
+    user?: NavItem[];
+}
+export interface AppManifest {
+    protocolVersion: string;
+    requiredCapabilities: string[];
+    app: AppInfo;
+    pages: PageEntry[];
+    navigation?: Navigation;
+}
+export interface RouteMatch {
+    page: PageEntry;
+    index: number;
+    params: Record<string, string>;
+}
+export interface ResolvedRoute extends RouteMatch {
+    path: string;
+    query: Record<string, string>;
+    source: "home" | "deepLink";
+}
+export interface NavigationContext {
+    user?: Record<string, unknown>;
+    features?: Record<string, unknown>;
+}
+export declare function validateAppManifest(value: unknown): AppManifest;
+export declare function matchRoute(pages: PageEntry[], path: string): RouteMatch | undefined;
+export declare function stripPathQuery(path: string): string;
+export declare function resolveInitialRoute(manifest: AppManifest, requestedPath: string): ResolvedRoute | undefined;
+export declare function resolveSchemaUrl(baseURL: string, schemaUrl: string, params: Record<string, string>): string;
+export declare function resolveRoutePath(route: string, params: Record<string, string>): string;
+export declare function resolveLogoUrl(baseURL: string, logoUrl: string): string;
+export declare function pageIdMatches(page: PageEntry, schemaPageId: string): boolean;
+export declare function loadAppManifest(options?: {
+    url?: string;
+    fetcher?: typeof fetch;
+}): Promise<AppManifest>;
+/** Loads the manifest with its raw 200 bytes (bootstrap integrity, ADR-0035 D6). */
+export declare function loadAppManifestBytes(options?: {
+    url?: string;
+    fetcher?: typeof fetch;
+}): Promise<{
+    manifest: AppManifest;
+    bytes: Uint8Array;
+}>;
+export declare function evaluateExpression(expression: string, context: NavigationContext): boolean;
+export declare function isNavigationItemVisible(item: NavLink | NavGroup, context: NavigationContext): boolean;
+/** Normalizes a page identifier for contribution-key matching (trim + lowercase).
+ *  Added in the R4 zero-conflict upgrade drill as a protocol additive sample. */
+export declare function normalizePageID(id: string): string;

package/protocol/conformance/actions-outcome.d.ts

@@ -0,0 +1,4 @@
+/**
+ * actions fixture adapter — transport outcome → host events (non-batch).
+ */
+export declare function runActionOutcome(input: Record<string, unknown>): Record<string, unknown>;

package/protocol/conformance/component-format.d.ts

@@ -0,0 +1,13 @@
+/**
+ * D-COMP component-format fixture adapter (schema-ui-docs v2.7.0).
+ * Validates format wire types without coercion.
+ */
+export type ComponentFormat = "currency" | "percent" | "datetime" | string;
+export type FormatResult = {
+    ok: true;
+    value: unknown;
+} | {
+    ok: false;
+    code: "COMPONENT_DATA_TYPE_MISMATCH";
+};
+export declare function applyComponentFormat(format: ComponentFormat, value: unknown): FormatResult;

package/protocol/conformance/query-serialize.d.ts

@@ -0,0 +1,24 @@
+/**
+ * ADR-0010 query-serialization adapter (schema-ui-docs v2.7.0 fixtures).
+ *
+ * Merges base URL query with ordered source layers; encodes keys/values per
+ * RFC 3986 (unreserved A-Za-z0-9-._~); sorts final keys by Unicode code point.
+ */
+export type QueryScalar = string | number | boolean | null;
+export type QueryPair = [string, unknown];
+export type QuerySource = QueryPair[];
+export type QuerySerializeResult = {
+    ok: true;
+    url: string;
+} | {
+    ok: false;
+    code: "INVALID_BASE_URL_QUERY" | "INVALID_QUERY_KEY" | "INVALID_QUERY_VALUE";
+};
+/** RFC3986 encode: percent-encode everything except unreserved. */
+export declare function encodeRFC3986(value: string): string;
+/**
+ * JCS-style number serialization used by query-serialization fixtures.
+ * Matches JSON number text for typical finite values (1e+21, 1e-7, 0.000001).
+ */
+export declare function serializeQueryNumber(value: number): string;
+export declare function serializeQuery(baseUrl: string, sources: QuerySource[]): QuerySerializeResult;

package/protocol/conformance/request-construction.d.ts

@@ -0,0 +1,42 @@
+/**
+ * request-construction fixture adapter (schema-ui-docs v2.7.0).
+ *
+ * Builds HTTP request / navigation / modal outcomes from declarative mappings.
+ * Batch kinds are out of scope for MVP callers (Q1); this module still implements
+ * non-batch kinds used by stage3 execution.
+ */
+export type RequestConstructionResult = {
+    ok: true;
+    request?: {
+        method: string;
+        url: string;
+        body: unknown;
+        headers?: Record<string, string>;
+    };
+    navigation?: {
+        url: string;
+    };
+    modalOpen?: {
+        modalId: string;
+    };
+    resolvedBase?: string;
+    /** Batch triggers: selection snapshot after a successful reload (ADR-0022 D2). */
+    selectionAfterSuccessReload?: {
+        keys: unknown[];
+        count: number;
+    };
+} | {
+    ok: false;
+    code: string;
+    path: string;
+};
+/** D3 invariants: scalar keys only, dedupe preserving order, count = keys.length. */
+export declare function normalizeSelection(keys: unknown[]): {
+    keys: unknown[];
+    count: number;
+};
+/**
+ * Run one request-construction fixture case.
+ * Batch kinds return a structured error; stage3 excludes them via Q1.
+ */
+export declare function constructRequest(input: Record<string, unknown>): RequestConstructionResult;

package/protocol/conformance/request-lifecycle.d.ts

@@ -0,0 +1,27 @@
+/**
+ * request-lifecycle fixture adapter (latest-wins / hide-drop).
+ */
+type LifecycleEvent = {
+    type: "start";
+} | {
+    type: "response";
+    generation: number;
+    state: unknown;
+} | {
+    type: "hide";
+} | {
+    type: "show";
+} | {
+    type: "unmount";
+};
+export interface LifecycleResult {
+    generation: number;
+    active: boolean;
+    state: unknown;
+    committed: Array<{
+        generation: number;
+        state: unknown;
+    }>;
+}
+export declare function runRequestLifecycle(initialState: unknown, events: LifecycleEvent[]): LifecycleResult;
+export {};

package/protocol/conformance/response-mapping.d.ts

@@ -0,0 +1,4 @@
+/**
+ * response-mapping fixture adapter (schema-ui-docs v2.7.0 / ADR-0005).
+ */
+export declare function mapResponse(input: Record<string, unknown>): Record<string, unknown>;

package/protocol/conformance/runtime-defaults.d.ts

@@ -0,0 +1,5 @@
+/**
+ * runtime-defaults fixture adapter (schema-ui-docs v2.7.0).
+ */
+export type RuntimeDefaultsResult = Record<string, unknown>;
+export declare function applyRuntimeDefaults(input: Record<string, unknown>): RuntimeDefaultsResult;

package/protocol/conformance/runtime-schema-validate.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Browser-safe structural validation for vendored page/node/action/reaction
+ * schemas. Mirrors `protocol/conformance/schema-validate.ts` but imports the
+ * pinned `docs/schemas/*.json` at build time (Vite `@schemas` alias) instead of
+ * reading them from disk, so the runtime loader can enforce D-VAL in the
+ * browser. The schema set is identical, so runtime and test-time validators
+ * stay aligned and neither redefines upstream node/page semantics.
+ */
+export type RuntimeSchemaKind = "node" | "page" | "action" | "reaction";
+export interface RuntimeSchemaValidationResult {
+    ok: boolean;
+    errors: Array<{
+        path: string;
+        message: string;
+        keyword?: string;
+    }>;
+}
+/**
+ * Structural validation of a fetched page document against the pinned page/node
+ * schemas. `ok: false` means the document must fail closed and never reach the
+ * renderer.
+ */
+export declare function validatePageDocument(document: unknown): RuntimeSchemaValidationResult;

package/protocol/conformance/schema-validate.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Structural validation entry for vendored node/page/action/reaction schemas.
+ * Uses Ajv draft-07 against pinned schema-ui-docs@2.7.0 artifacts in docs/schemas/.
+ */
+export type SchemaKind = "node" | "page" | "action" | "reaction";
+export interface SchemaValidationResult {
+    ok: boolean;
+    errors: Array<{
+        path: string;
+        message: string;
+        keyword?: string;
+    }>;
+}
+export declare function validateAgainstSchema(kind: SchemaKind, document: unknown): SchemaValidationResult;
+/** Minimal valid page document using §5 whitelist types (for structural smoke). */
+export declare function sampleWhitelistedPage(): Record<string, unknown>;

package/protocol/conformance/search-table.d.ts

@@ -0,0 +1,14 @@
+/**
+ * search-table fixture adapter — four-layer query merge + selection events.
+ */
+export interface TableState {
+    filters: Record<string, unknown>;
+    page: number;
+    pageSize: number;
+    sort: string | null;
+}
+export interface SelectionState {
+    keys: unknown[];
+    count: number;
+}
+export declare function runSearchTable(input: Record<string, unknown>): Record<string, unknown>;

package/protocol/conformance/static-data.d.ts

@@ -0,0 +1,27 @@
+/**
+ * static-data fixture adapter (schema-ui-docs v2.7.0).
+ */
+type Json = unknown;
+export type StaticDataResult = {
+    ok: true;
+    value: Json;
+    network: false;
+} | {
+    ok: false;
+    code: "STATIC_DATA_SHAPE_MISMATCH" | "STATIC_DATA_REF_INVALID" | "STATIC_RESPONSE_MAPPING_NOT_ALLOWED";
+};
+interface DataRef {
+    source: "static" | "ref" | "api";
+    value?: Json;
+    ref?: string;
+    responseMapping?: unknown;
+}
+export declare function resolveStaticData(input: {
+    component: string;
+    data: DataRef;
+    datasources?: Record<string, unknown>;
+    props?: {
+        valueField?: string;
+    };
+}): StaticDataResult;
+export {};

package/protocol/conformance/table-sort.d.ts

@@ -0,0 +1,4 @@
+/**
+ * table-sort fixture adapter (ADR-0027 three-state sort + L2 validate).
+ */
+export declare function runTableSort(input: Record<string, unknown>): Record<string, unknown>;

package/protocol/conformance/upload-orchestration.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Upload orchestration (schema-ui-docs@2.7.0 · docs/07-actions-contract.md §7
+ * + ADR-0012). I-PROTO-FULL-001 D-UPLOAD include.
+ *
+ * Client contract:
+ *   - one multipart request per file (fieldName default "file"; method POST
+ *     default, PUT allowed)
+ *   - constraints (multiple / maxSize / accept) are checked BEFORE any
+ *     request; any violation rejects the whole batch atomically
+ *   - accept tokens: ".ext" matches the file extension case-insensitively,
+ *     "type/*" matches the MIME main type, other tokens match MIME exactly
+ *     (case-insensitive)
+ *   - serial uploads in selection order; any failure stops the batch and no
+ *     partial field value is committed
+ *   - field value: url (priority) or id; multiple → array in selection order
+ *   - retryPolicy idempotent → Idempotency-Key header "{invocationId}:{index}"
+ */
+export interface UploadFile {
+    name: string;
+    type: string;
+    size: number;
+    contentId: string;
+}
+/** Real-transport file: an UploadFile plus the bytes to send (browser File). */
+export interface UploadableFile extends UploadFile {
+    blob: Blob;
+}
+export interface UploadActionResult {
+    url?: string;
+    id?: string;
+    method?: string;
+    fieldName?: string;
+    accept?: string;
+    maxSize?: number;
+    multiple?: boolean;
+    retryPolicy?: string;
+}
+export interface UploadRequestPart {
+    name: string;
+    fileName: string;
+    contentId: string;
+}
+export interface UploadRequest {
+    method: string;
+    url: string;
+    part: UploadRequestPart;
+    headers?: Record<string, string>;
+}
+export type UploadResult = {
+    type: "success";
+    response: {
+        url?: string;
+        id?: string;
+    };
+} | {
+    type: "failure";
+    status?: number;
+};
+export interface UploadBatchResultOk {
+    ok: true;
+    requests: UploadRequest[];
+    fieldValue: string | string[] | null;
+}
+export interface UploadBatchResultError {
+    ok: false;
+    code: string;
+    fileIndex: number;
+    requests: UploadRequest[];
+    fieldValue: null;
+}
+export type UploadBatchResult = UploadBatchResultOk | UploadBatchResultError;
+/** accept token matching (ADR-0012 D2): ".ext", "type/*", exact MIME. */
+export declare function acceptTokenMatches(token: string, file: UploadFile): boolean;
+/** Client-side constraints (ADR-0012 D2); returns the first violation. */
+export declare function validateUploadSelection(action: UploadActionResult, files: UploadFile[]): {
+    ok: true;
+} | {
+    ok: false;
+    code: string;
+    fileIndex: number;
+};
+/** Builds the per-file multipart request descriptors (pre-request). */
+export declare function buildUploadRequests(action: UploadActionResult, files: UploadFile[], invocationId?: string): UploadBatchResultError | {
+    ok: true;
+    requests: UploadRequest[];
+};
+/**
+ * Fixture-driven orchestration: replays pre-recorded transport results
+ * (`conformance/fixtures/uploads/cases.json` contract).
+ */
+export declare function runUploadBatch(input: {
+    action: UploadActionResult;
+    files: UploadFile[];
+    results?: UploadResult[];
+    invocationId?: string;
+}): UploadBatchResult;
+/**
+ * Real transport orchestration used by the Renderer's upload control: the
+ * same constraints and request shape, executed against a live fetch with
+ * multipart FormData carrying the actual file bytes (ADR-0012 D4).
+ */
+export declare function uploadFilesWithFetch(action: UploadActionResult, files: UploadableFile[], fetcher: typeof fetch, invocationId?: string): Promise<UploadBatchResult>;

package/protocol/conformance/version-negotiate.d.ts

@@ -0,0 +1,4 @@
+/**
+ * version-negotiation fixture adapter (strict version + capability check).
+ */
+export declare function negotiateVersion(input: Record<string, unknown>): Record<string, unknown>;

package/protocol/conformance-claim.json

@@ -0,0 +1,81 @@
+{
+  "claimVersion": "1.0",
+  "host": {
+    "hostId": "schema-ui-web",
+    "hostVersion": "0.1.0",
+    "buildId": "git:9337fd841c4256733acc3856fa518e2af4b4d33f"
+  },
+  "protocolArtifact": {
+    "artifactVersion": "2.9.0",
+    "contentSha256": "c87c22ad2ab4f4f19b93253312d6906b085ae6cd273168cc435d9863809d1c22"
+  },
+  "support": {
+    "pageVersions": [
+      "2.7",
+      "2.9"
+    ],
+    "manifestVersions": [
+      "2.7",
+      "2.8",
+      "2.9"
+    ],
+    "capabilities": [
+      "app.manifest",
+      "app.navigation",
+      "host.bootstrap",
+      "host.failure-recovery",
+      "host.conformance-claim",
+      "data.route-binding",
+      "form.controls.readonly"
+    ]
+  },
+  "conformance": {
+    "fixtureVersion": "1.0",
+    "fixtureSha256": "89baddbc2879b0c183bcb50fbc730257df5786eee316b645e8238876fe0ca3e7",
+    "suites": [
+      {
+        "suiteId": "app-manifest",
+        "suiteVersion": "1.0",
+        "result": "pass"
+      },
+      {
+        "suiteId": "app-navigation",
+        "suiteVersion": "1.0",
+        "result": "pass"
+      },
+      {
+        "suiteId": "host-bootstrap",
+        "suiteVersion": "1.0",
+        "result": "pass"
+      },
+      {
+        "suiteId": "host-failure",
+        "suiteVersion": "1.0",
+        "result": "pass"
+      },
+      {
+        "suiteId": "host-conformance-claim",
+        "suiteVersion": "1.0",
+        "result": "pass"
+      },
+      {
+        "suiteId": "request-construction",
+        "suiteVersion": "1.0",
+        "result": "pass"
+      },
+      {
+        "suiteId": "component-format",
+        "suiteVersion": "1.0",
+        "result": "pass"
+      }
+    ]
+  },
+  "evidence": [
+    {
+      "kind": "local-report",
+      "subjectBuildId": "git:9337fd841c4256733acc3856fa518e2af4b4d33f",
+      "uri": "/protocol/conformance-local-report.json",
+      "sha256": "3823b20137d448a6f43a4601cfacd830f918b83141c043ef3bd5cf64b52132c7"
+    }
+  ]
+}

package/protocol/conformance-claim.json.sha256

@@ -0,0 +1 @@
+3b4c81afa0358e871caacda15ba3d7d93c63b2010a8fef450902516d656e2ad3

package/protocol/conformance-local-report.json

@@ -0,0 +1,60 @@
+{
+  "reportVersion": "1.0",
+  "subjectBuildId": "git:9337fd841c4256733acc3856fa518e2af4b4d33f",
+  "host": {
+    "hostId": "schema-ui-web",
+    "hostVersion": "0.1.0"
+  },
+  "suites": [
+    {
+      "suiteId": "app-manifest",
+      "fixtures": 41,
+      "suiteVersion": "1.0",
+      "result": "pass"
+    },
+    {
+      "suiteId": "app-navigation",
+      "fixtures": 16,
+      "suiteVersion": "1.0",
+      "result": "pass"
+    },
+    {
+      "suiteId": "host-bootstrap",
+      "fixtures": 23,
+      "suiteVersion": "1.0",
+      "result": "pass"
+    },
+    {
+      "suiteId": "host-failure",
+      "fixtures": 43,
+      "suiteVersion": "1.0",
+      "result": "pass"
+    },
+    {
+      "suiteId": "host-conformance-claim",
+      "fixtures": 30,
+      "suiteVersion": "1.0",
+      "result": "pass"
+    },
+    {
+      "suiteId": "request-construction",
+      "fixtures": 81,
+      "suiteVersion": "1.0",
+      "result": "pass"
+    },
+    {
+      "suiteId": "component-format",
+      "fixtures": 5,
+      "suiteVersion": "1.0",
+      "result": "pass"
+    }
+  ],
+  "pinnedUpstream": {
+    "sourceRepo": "https://github.com/magicvr/schema-ui-docs",
+    "sourceCommit": "81aa1d8",
+    "artifactVersion": "2.8.0",
+    "fixtureSha256": "89baddbc2879b0c183bcb50fbc730257df5786eee316b645e8238876fe0ca3e7",
+    "protocolContentSha256": "c87c22ad2ab4f4f19b93253312d6906b085ae6cd273168cc435d9863809d1c22"
+  },
+  "residuals": []
+}

package/protocol/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * @schema-ui/protocol 聚合导出（试点 v0.1.0 · GOAL-004 S2）。
+ *
+ * 协议面：app-manifest 协商/校验/路由 + 页面文档加载/校验管线。
+ * 打包：apps/web Vite lib mode（vite.lib.config.ts）+ tsc declaration。
+ */
+export * from "./app-manifest";
+export * from "./load-page";