@lingxia/elements 0.17.0 → 0.18.0

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 export { registerVideoComponent, LxVideoElement, type LxVideoAttributes, type LxVideoEventPayloads, type LxVideoEventHandlers, } from "./video.js";
 export { registerMediaSwiperComponent, LxMediaSwiperElement, type LxMediaSwiperAttributes, type LxMediaSwiperItem, type LxMediaSwiperChangeEvent, type LxMediaSwiperChangeEventDetail, type LxMediaSwiperTransitionEndEvent, type LxMediaSwiperTransitionEndEventDetail, type LxMediaSwiperItemEvent, type LxMediaSwiperEventDetail, type LxMediaSwiperEndReachedEvent, type LxMediaSwiperEndReachedEventDetail, type LxMediaSwiperErrorEvent, type LxMediaSwiperErrorEventDetail, type LxMediaSwiperChangeSource, type LxMediaSwiperErrorCode, } from "./media_swiper.js";
 export { registerPickerComponent, LxPickerElement, type LxPickerAttributes, type LxPickerColumn, type LxPickerCascadingColumns, type LxPickerEvent, type LxPickerEventDetail, } from "./picker.js";
-export { LxNavigatorElement, type LxNavigatorAttributes, type LxNavigatorEvent, type NavigatorChannel, type NavigatorOpenType, type NavigatorQuery, type NavigatorQueryValue, type NavigatorTarget, } from "./navigator.js";
+export { LxNavigatorElement, type LxNavigatorAttributes, type LxNavigatorEvent, type NavigatorChannel, type NavigatorEdge, type NavigatorFloatPosition, type NavigatorInteraction, type NavigatorPagePlacement, type NavigatorPlacement, type NavigatorSize, type NavigatorSizeValue, type NavigatorUrlPlacement, type NavigatorWindowChrome, type NavigatorOpenType, type NavigatorQuery, type NavigatorQueryValue, type NavigatorTarget, } from "./navigator.js";
 export { buildVideoNativeAttrs, buildMediaSwiperNativeAttrs, buildNavigatorNativeAttrs, buildPickerNativeAttrs, getPickerDisplayText, getPickerValueFromIndex, VIDEO_DOM_EVENT_MAP, MEDIA_SWIPER_DOM_EVENT_MAP, } from "./native_component_wrapper_shared.js";
 export { isHarmony, isIOS, isAndroid, isMacOS, isDesktop, getOS, } from "./platform.js";
 export { ensureComponentId, rectEquals, NativeComponentUpdateState, type Rect, } from "./component.js";

package/dist/native_component_wrapper_shared.d.ts

@@ -1,4 +1,4 @@
-import type { NavigatorChannel, NavigatorOpenType, NavigatorTarget } from "./navigator.js";
+import type { NavigatorChannel, NavigatorEdge, NavigatorFloatPosition, NavigatorInteraction, NavigatorOpenType, NavigatorPlacement, NavigatorSize, NavigatorTarget, NavigatorWindowChrome } from "./navigator.js";
 import type { NavigatorQuery } from "./navigator.js";
 import type { LxMediaSwiperItem } from "./media_swiper.js";
 import type { LxVideoQuality } from "./video.js";
@@ -10,6 +10,12 @@ export interface NavigatorNativeAttrOptions {
     openType?: NavigatorOpenType;
     target?: NavigatorTarget;
     delta?: number;
+    as?: NavigatorPlacement;
+    edge?: NavigatorEdge;
+    position?: NavigatorFloatPosition;
+    chrome?: NavigatorWindowChrome;
+    size?: NavigatorSize;
+    interaction?: NavigatorInteraction;
     appId?: string;
     query?: NavigatorQuery;
     channel?: NavigatorChannel;

package/dist/native_component_wrapper_shared.js

@@ -39,6 +39,18 @@ export function buildNavigatorNativeAttrs(options, extraAttrs = {}) {
         result.page = options.page;
     if (options.target)
         result.target = options.target;
+    if (options.as)
+        result.as = options.as;
+    if (options.edge)
+        result.edge = options.edge;
+    if (options.position)
+        result.position = options.position;
+    if (options.chrome)
+        result.chrome = options.chrome;
+    if (options.size)
+        result.size = JSON.stringify(options.size);
+    if (options.interaction)
+        result.interaction = JSON.stringify(options.interaction);
     if (options.appId)
         result["app-id"] = options.appId;
     if (options.query)

package/dist/navigator.d.ts

@@ -1,5 +1,21 @@
-export type NavigatorOpenType = 'navigate' | 'redirect' | 'navigateBack' | 'reLaunch' | 'switchTab' | 'exit' | 'openUrl' | 'tel';
-export type NavigatorTarget = 'self' | 'lxapp' | 'browser';
+export type NavigatorOpenType = 'navigate' | 'redirect' | 'navigateBack' | 'reLaunch' | 'switchTab' | 'exit' | 'tel';
+export type NavigatorTarget = 'page' | 'lxapp' | 'url';
+export type NavigatorUrlPlacement = 'external' | 'tab' | 'aside';
+export type NavigatorPagePlacement = 'float' | 'window';
+export type NavigatorPlacement = NavigatorUrlPlacement | NavigatorPagePlacement;
+export type NavigatorEdge = 'left' | 'right' | 'top' | 'bottom';
+export type NavigatorFloatPosition = 'center' | 'top' | 'bottom' | 'left' | 'right';
+export type NavigatorWindowChrome = 'system' | 'full';
+export type NavigatorSizeValue = number | `${number}%`;
+export type NavigatorSize = {
+    width?: NavigatorSizeValue;
+    height?: NavigatorSizeValue;
+};
+export type NavigatorInteraction = {
+    closeButton?: boolean;
+    dismiss?: 'tapOutside' | 'manual';
+    modal?: boolean;
+};
 export type NavigatorQueryValue = string | number | boolean | null | undefined;
 export type NavigatorQuery = Record<string, NavigatorQueryValue>;
 export type NavigatorChannel = 'release' | 'draft';
@@ -17,6 +33,12 @@ export type LxNavigatorAttributes = {
     'open-type'?: NavigatorOpenType;
     target?: NavigatorTarget;
     delta?: number;
+    as?: NavigatorPlacement;
+    edge?: NavigatorEdge;
+    position?: NavigatorFloatPosition;
+    chrome?: NavigatorWindowChrome;
+    size?: string;
+    interaction?: string;
     'app-id'?: string;
     channel?: NavigatorChannel;
     'target-version'?: string;
@@ -75,17 +97,15 @@ export declare class LxNavigatorElement extends HTMLElement {
     private removeHoverClass;
     private clearHoverTimer;
     private handleClick;
-    /**
-     * Auto-infer navigation target based on context
-     * Priority: explicit target > appId > HTTPS URL > default (self)
-     */
-    private inferTarget;
     private navigate;
     private dispatchSuccess;
     private resolveErrorMessage;
     private dispatchFail;
+    private bridge;
     private callHost;
+    private callSurface;
     private performNavigation;
+    private readJsonObject;
     private readQuery;
     private buildPageTarget;
     private buildLxAppTarget;

package/dist/navigator.js

@@ -43,6 +43,12 @@ export class LxNavigatorElement extends HTMLElement {
             "open-type",
             "target",
             "delta",
+            "as",
+            "edge",
+            "position",
+            "chrome",
+            "size",
+            "interaction",
             "app-id",
             "channel",
             "target-version",
@@ -158,55 +164,33 @@ export class LxNavigatorElement extends HTMLElement {
         }
     }
     handleClick(e) {
+        var _a;
         e.preventDefault();
-        const url = this.getAttribute('url') || '';
-        const page = this.getAttribute('page');
-        // Read the removed attribute only to provide a forward-only runtime error
-        // for untyped HTML callers instead of silently ignoring it.
-        const path = this.getAttribute('path');
-        const query = this.getAttribute('query');
-        const openType = (this.getAttribute('open-type') || 'navigate');
-        const explicitTarget = this.getAttribute('target');
-        const delta = parseInt(this.getAttribute('delta') || '1', 10);
-        const appId = this.getAttribute('app-id');
-        const channel = this.getAttribute('channel');
-        const targetVersion = this.getAttribute('target-version');
-        const phoneNumber = this.getAttribute('phone-number');
-        // Auto-infer target if not explicitly specified
-        const target = this.inferTarget(explicitTarget, url, appId);
-        void this.navigate({
+        const attr = (name) => this.getAttribute(name);
+        const url = attr('url') || '';
+        const appId = attr('app-id');
+        const options = {
             url,
-            page,
-            path,
-            query,
-            openType,
-            target,
-            delta,
+            page: attr('page'),
+            // Read the removed attribute only to provide a forward-only runtime error
+            // for untyped HTML callers instead of silently ignoring it.
+            path: attr('path'),
+            query: attr('query'),
+            openType: (attr('open-type') || 'navigate'),
+            target: (_a = attr('target')) !== null && _a !== void 0 ? _a : (appId ? 'lxapp' : url ? 'url' : 'page'),
+            delta: parseInt(attr('delta') || '1', 10),
+            placement: attr('as'),
+            edge: attr('edge'),
+            position: attr('position'),
+            chrome: attr('chrome'),
+            size: attr('size'),
+            interaction: attr('interaction'),
             appId,
-            channel,
-            targetVersion,
-            phoneNumber
-        });
-    }
-    /**
-     * Auto-infer navigation target based on context
-     * Priority: explicit target > appId > HTTPS URL > default (self)
-     */
-    inferTarget(explicitTarget, url, appId) {
-        // 1. Explicit target has highest priority
-        if (explicitTarget) {
-            return explicitTarget;
-        }
-        // 2. If appId is specified, target is another lxapp
-        if (appId) {
-            return 'lxapp';
-        }
-        // 3. If URL starts with http:// or https://, open in browser
-        if (/^https?:\/\//i.test(url)) {
-            return 'browser';
-        }
-        // 4. Default: navigate within current lxapp
-        return 'self';
+            channel: attr('channel'),
+            targetVersion: attr('target-version'),
+            phoneNumber: attr('phone-number'),
+        };
+        void this.navigate(options);
     }
     async navigate(options) {
         try {
@@ -273,17 +257,24 @@ export class LxNavigatorElement extends HTMLElement {
         });
         this.dispatchEvent(completeEvent);
     }
-    callHost(route, params) {
+    bridge() {
         const bridge = window.LingXiaBridge;
         if (!bridge || typeof bridge.invoke !== 'function') {
-            return Promise.reject(new Error('LingXiaBridge is not available'));
+            throw new Error('LingXiaBridge is not available');
         }
-        return bridge.invoke(route, params).then(() => undefined);
+        return bridge;
+    }
+    async callHost(route, params) {
+        await this.bridge().invoke(route, params);
+    }
+    // Placements run through Logic's lx.surface, which owns surface handles.
+    async callSurface(method, params) {
+        await this.bridge().raw.call(`surface.${method}`, params);
     }
     async performNavigation(options) {
-        const url = options.url || '';
+        const { url, placement } = options;
         const delta = Number.isFinite(options.delta) && options.delta > 0 ? options.delta : 1;
-        if (options.path !== null && options.path !== undefined) {
+        if (options.path !== null) {
             throw new Error('path is not supported; pass the configured page name in page');
         }
         if (options.openType === 'tel') {
@@ -300,39 +291,71 @@ export class LxNavigatorElement extends HTMLElement {
         if (options.openType === 'navigateBack') {
             if (options.target === 'lxapp') {
                 await this.callHost('navigator.navigateBackApp');
-                return;
             }
-            if (options.target === 'browser') {
-                throw new Error('navigateBack is not supported for browser target');
+            else {
+                await this.callHost('navigation.navigateBack', { delta });
             }
-            await this.callHost('navigation.navigateBack', { delta });
             return;
         }
-        if (options.target === 'browser') {
-            if (!url) {
-                throw new Error('openUrl requires url');
-            }
-            await this.callHost('device.openUrl', { url, target: 'external' });
-            return;
-        }
-        if (options.target === 'lxapp') {
-            if (!options.appId) {
-                throw new Error('navigateToApp requires app-id');
-            }
-            await this.callHost('navigator.navigateToApp', this.buildLxAppTarget(options));
-            return;
-        }
-        if (options.target === 'self' && /^https?:\/\//i.test(url)) {
-            if (!url) {
-                throw new Error('openUrl requires url');
+        switch (options.target) {
+            case 'url': {
+                if (!url) {
+                    throw new Error('target url requires url');
+                }
+                if (!placement || placement === 'external') {
+                    await this.callHost('device.openUrl', { url, target: 'external' });
+                    return;
+                }
+                if (placement !== 'tab' && placement !== 'aside') {
+                    throw new Error(`a url opens as external, tab, or aside; got ${placement}`);
+                }
+                const surfaceOptions = { as: placement };
+                if (options.edge)
+                    surfaceOptions.edge = options.edge;
+                const size = this.readJsonObject('size', options.size);
+                if (size)
+                    surfaceOptions.size = size;
+                await this.callSurface('openUrl', { url, options: surfaceOptions });
+                return;
             }
-            await this.callHost('device.openUrl', { url, target: 'self' });
-            return;
+            case 'lxapp':
+                if (!options.appId) {
+                    throw new Error('target lxapp requires app-id');
+                }
+                if (placement) {
+                    throw new Error('as is not supported for target lxapp');
+                }
+                await this.callHost('navigator.navigateToApp', this.buildLxAppTarget(options));
+                return;
+            case 'page':
+                break;
+            default:
+                throw new Error(`Unsupported target: ${options.target}`);
         }
         const target = this.buildPageTarget(options);
         if (!target) {
             throw new Error(`${options.openType} requires page`);
         }
+        if (placement) {
+            if (placement !== 'float' && placement !== 'window') {
+                throw new Error(`a page opens as float or window; got ${placement}`);
+            }
+            const surfaceOptions = { as: placement };
+            if (target.query)
+                surfaceOptions.query = target.query;
+            if (options.position)
+                surfaceOptions.position = options.position;
+            if (options.chrome)
+                surfaceOptions.chrome = options.chrome;
+            const size = this.readJsonObject('size', options.size);
+            if (size)
+                surfaceOptions.size = size;
+            const interaction = this.readJsonObject('interaction', options.interaction);
+            if (interaction)
+                surfaceOptions.interaction = interaction;
+            await this.callSurface('openPage', { page: target.page, options: surfaceOptions });
+            return;
+        }
         switch (options.openType) {
             case 'navigate':
                 await this.callHost('navigation.navigateTo', target);
@@ -346,25 +369,22 @@ export class LxNavigatorElement extends HTMLElement {
             case 'reLaunch':
                 await this.callHost('navigation.reLaunch', target);
                 break;
-            case 'openUrl':
-                await this.callHost('device.openUrl', {
-                    url,
-                    target: options.target === 'self' ? 'self' : 'external'
-                });
-                break;
             default:
                 throw new Error(`Unsupported openType: ${options.openType}`);
         }
     }
-    readQuery(raw) {
+    readJsonObject(name, raw) {
         if (!raw)
             return undefined;
         const parsed = JSON.parse(raw);
         if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
-            throw new Error('query must be an object');
+            throw new Error(`${name} must be an object`);
         }
         return parsed;
     }
+    readQuery(raw) {
+        return this.readJsonObject('query', raw);
+    }
     buildPageTarget(options) {
         var _a;
         const page = (_a = options.page) === null || _a === void 0 ? void 0 : _a.trim();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lingxia/elements",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "private": false,
   "description": "LingXia custom elements — native-backed web components for LxApp pages",
   "type": "module",
@@ -15,7 +15,7 @@
   },
   "scripts": {
     "build": "npm --prefix ../lingxia-bridge run build:types && tsc -p tsconfig.json",
-    "test:inline-native": "npm run build && node tests/inline-native-structure.mjs && node tests/inline-native-unwrap.mjs && node tests/inline-native-runtime.mjs && node tests/inline-native-events.mjs && node tests/inline-native-style.mjs && node tests/video-events.mjs && node tests/inline-native-identity.mjs && node tests/inline-native-contract.mjs",
+    "test:inline-native": "npm run build && node tests/inline-native-structure.mjs && node tests/inline-native-unwrap.mjs && node tests/inline-native-runtime.mjs && node tests/inline-native-events.mjs && node tests/inline-native-style.mjs && node tests/video-events.mjs && node tests/navigator-routing.mjs && node tests/inline-native-identity.mjs && node tests/inline-native-contract.mjs",
     "clean": "rm -rf dist",
     "prepublishOnly": "npm run build"
   },

package/src/index.ts

@@ -41,6 +41,15 @@ export {
   type LxNavigatorAttributes,
   type LxNavigatorEvent,
   type NavigatorChannel,
+  type NavigatorEdge,
+  type NavigatorFloatPosition,
+  type NavigatorInteraction,
+  type NavigatorPagePlacement,
+  type NavigatorPlacement,
+  type NavigatorSize,
+  type NavigatorSizeValue,
+  type NavigatorUrlPlacement,
+  type NavigatorWindowChrome,
   type NavigatorOpenType,
   type NavigatorQuery,
   type NavigatorQueryValue,

package/src/native_component_wrapper_shared.ts

@@ -1,4 +1,14 @@
-import type { NavigatorChannel, NavigatorOpenType, NavigatorTarget } from "./navigator.js";
+import type {
+  NavigatorChannel,
+  NavigatorEdge,
+  NavigatorFloatPosition,
+  NavigatorInteraction,
+  NavigatorOpenType,
+  NavigatorPlacement,
+  NavigatorSize,
+  NavigatorTarget,
+  NavigatorWindowChrome,
+} from "./navigator.js";
 import type { NavigatorQuery } from "./navigator.js";
 import type { LxMediaSwiperItem } from "./media_swiper.js";
 import type { LxVideoQuality, LxVideoEventPayloads } from "./video.js";
@@ -37,6 +47,12 @@ export interface NavigatorNativeAttrOptions {
   openType?: NavigatorOpenType;
   target?: NavigatorTarget;
   delta?: number;
+  as?: NavigatorPlacement;
+  edge?: NavigatorEdge;
+  position?: NavigatorFloatPosition;
+  chrome?: NavigatorWindowChrome;
+  size?: NavigatorSize;
+  interaction?: NavigatorInteraction;
   appId?: string;
   query?: NavigatorQuery;
   channel?: NavigatorChannel;
@@ -64,6 +80,12 @@ export function buildNavigatorNativeAttrs(
   if (options.url) result.url = options.url;
   if (options.page) result.page = options.page;
   if (options.target) result.target = options.target;
+  if (options.as) result.as = options.as;
+  if (options.edge) result.edge = options.edge;
+  if (options.position) result.position = options.position;
+  if (options.chrome) result.chrome = options.chrome;
+  if (options.size) result.size = JSON.stringify(options.size);
+  if (options.interaction) result.interaction = JSON.stringify(options.interaction);
   if (options.appId) result["app-id"] = options.appId;
   if (options.query) result.query = JSON.stringify(options.query);
   if (options.channel) result.channel = options.channel;

package/src/navigator.ts

@@ -8,13 +8,26 @@ export type NavigatorOpenType =
   | 'reLaunch'      // Restart app with new page
   | 'switchTab'     // Switch to tab page
   | 'exit'          // Exit current lxapp
-  | 'openUrl'       // Open external URL or lxapp
   | 'tel';          // Make a phone call
 
-export type NavigatorTarget =
-  | 'self'          // Navigate within current lxapp (default)
-  | 'lxapp'         // Open another lxapp
-  | 'browser';      // Open in external browser
+// What to open. Inferred when omitted: app-id → lxapp, url → url, else page.
+export type NavigatorTarget = 'page' | 'lxapp' | 'url';
+
+// Where to open it; mirrors `as` of lx.surface.openUrl / openPage.
+// A url defaults to `external`; a page without `as` follows open-type.
+export type NavigatorUrlPlacement = 'external' | 'tab' | 'aside';
+export type NavigatorPagePlacement = 'float' | 'window';
+export type NavigatorPlacement = NavigatorUrlPlacement | NavigatorPagePlacement;
+export type NavigatorEdge = 'left' | 'right' | 'top' | 'bottom';
+export type NavigatorFloatPosition = 'center' | 'top' | 'bottom' | 'left' | 'right';
+export type NavigatorWindowChrome = 'system' | 'full';
+export type NavigatorSizeValue = number | `${number}%`;
+export type NavigatorSize = { width?: NavigatorSizeValue; height?: NavigatorSizeValue };
+export type NavigatorInteraction = {
+  closeButton?: boolean;
+  dismiss?: 'tapOutside' | 'manual';
+  modal?: boolean;
+};
 
 export type NavigatorQueryValue = string | number | boolean | null | undefined;
 export type NavigatorQuery = Record<string, NavigatorQueryValue>;
@@ -31,17 +44,46 @@ export interface LxNavigatorEvent extends CustomEvent<LxNavigatorEventDetail> {
 
 type LingXiaBridgeCall = {
   invoke(route: string, params?: unknown): Promise<unknown>;
+  raw: { call(method: string, params?: unknown): Promise<unknown> };
+};
+
+type NavigateOptions = {
+  url: string;
+  page: string | null;
+  path: string | null;
+  query: string | null;
+  openType: NavigatorOpenType;
+  target: NavigatorTarget;
+  delta: number;
+  placement: NavigatorPlacement | null;
+  edge: string | null;
+  position: string | null;
+  chrome: string | null;
+  size: string | null;
+  interaction: string | null;
+  appId: string | null;
+  channel: NavigatorChannel | null;
+  targetVersion: string | null;
+  phoneNumber: string | null;
 };
 
 export type LxNavigatorAttributes = {
   // Navigation
-  url?: string;                    // Browser URL for openUrl/browser target
+  url?: string;                    // http(s) URL
   page?: string;                   // Configured page name from lxapp.json; routes are unsupported
   query?: string;                  // JSON-encoded page query params
   'open-type'?: NavigatorOpenType; // Navigation type
-  target?: NavigatorTarget;        // Navigation target (auto-inferred if not specified)
+  target?: NavigatorTarget;        // What to open (inferred if not specified)
   delta?: number;                  // Pages to go back (for navigateBack)
 
+  // Placement
+  as?: NavigatorPlacement;
+  edge?: NavigatorEdge;                // as="aside"
+  position?: NavigatorFloatPosition;   // as="float"
+  chrome?: NavigatorWindowChrome;      // as="window"
+  size?: string;                       // JSON-encoded NavigatorSize
+  interaction?: string;                // JSON-encoded NavigatorInteraction (float/window)
+
   // Open external lxapp
   'app-id'?: string;              // Target lxapp ID
   channel?: NavigatorChannel; // Target lxapp channel
@@ -88,6 +130,12 @@ export class LxNavigatorElement extends HTMLElement {
       "open-type",
       "target",
       "delta",
+      "as",
+      "edge",
+      "position",
+      "chrome",
+      "size",
+      "interaction",
       "app-id",
       "channel",
       "target-version",
@@ -252,80 +300,34 @@ export class LxNavigatorElement extends HTMLElement {
 
   private handleClick(e: MouseEvent) {
     e.preventDefault();
-
-    const url = this.getAttribute('url') || '';
-    const page = this.getAttribute('page');
-    // Read the removed attribute only to provide a forward-only runtime error
-    // for untyped HTML callers instead of silently ignoring it.
-    const path = this.getAttribute('path');
-    const query = this.getAttribute('query');
-    const openType = (this.getAttribute('open-type') || 'navigate') as NavigatorOpenType;
-    const explicitTarget = this.getAttribute('target') as NavigatorTarget | null;
-    const delta = parseInt(this.getAttribute('delta') || '1', 10);
-    const appId = this.getAttribute('app-id');
-    const channel = this.getAttribute('channel') as NavigatorChannel | null;
-    const targetVersion = this.getAttribute('target-version');
-    const phoneNumber = this.getAttribute('phone-number');
-
-    // Auto-infer target if not explicitly specified
-    const target = this.inferTarget(explicitTarget, url, appId);
-
-    void this.navigate({
+    const attr = (name: string) => this.getAttribute(name);
+    const url = attr('url') || '';
+    const appId = attr('app-id');
+    const options: NavigateOptions = {
       url,
-      page,
-      path,
-      query,
-      openType,
-      target,
-      delta,
+      page: attr('page'),
+      // Read the removed attribute only to provide a forward-only runtime error
+      // for untyped HTML callers instead of silently ignoring it.
+      path: attr('path'),
+      query: attr('query'),
+      openType: (attr('open-type') || 'navigate') as NavigatorOpenType,
+      target: (attr('target') as NavigatorTarget | null) ?? (appId ? 'lxapp' : url ? 'url' : 'page'),
+      delta: parseInt(attr('delta') || '1', 10),
+      placement: attr('as') as NavigatorPlacement | null,
+      edge: attr('edge'),
+      position: attr('position'),
+      chrome: attr('chrome'),
+      size: attr('size'),
+      interaction: attr('interaction'),
       appId,
-      channel,
-      targetVersion,
-      phoneNumber
-    });
-  }
-
-  /**
-   * Auto-infer navigation target based on context
-   * Priority: explicit target > appId > HTTPS URL > default (self)
-   */
-  private inferTarget(
-    explicitTarget: NavigatorTarget | null,
-    url: string,
-    appId: string | null
-  ): NavigatorTarget {
-    // 1. Explicit target has highest priority
-    if (explicitTarget) {
-      return explicitTarget;
-    }
-
-    // 2. If appId is specified, target is another lxapp
-    if (appId) {
-      return 'lxapp';
-    }
-
-    // 3. If URL starts with http:// or https://, open in browser
-    if (/^https?:\/\//i.test(url)) {
-      return 'browser';
-    }
-
-    // 4. Default: navigate within current lxapp
-    return 'self';
+      channel: attr('channel') as NavigatorChannel | null,
+      targetVersion: attr('target-version'),
+      phoneNumber: attr('phone-number'),
+    };
+    void this.navigate(options);
   }
 
-  private async navigate(options: {
-    url: string;
-    page?: string | null;
-    path?: string | null;
-    query?: string | null;
-    openType: NavigatorOpenType;
-    target: NavigatorTarget;
-    delta: number;
-    appId?: string | null;
-    channel?: NavigatorChannel | null;
-    targetVersion?: string | null;
-    phoneNumber?: string | null;
-  }) {
+  private async navigate(options: NavigateOptions) {
     try {
       await this.performNavigation(options);
       this.dispatchSuccess();
@@ -398,31 +400,28 @@ export class LxNavigatorElement extends HTMLElement {
     this.dispatchEvent(completeEvent);
   }
 
-  private callHost(route: string, params?: unknown): Promise<void> {
+  private bridge(): LingXiaBridgeCall {
     const bridge = (window as unknown as { LingXiaBridge?: LingXiaBridgeCall }).LingXiaBridge;
     if (!bridge || typeof bridge.invoke !== 'function') {
-      return Promise.reject(new Error('LingXiaBridge is not available'));
+      throw new Error('LingXiaBridge is not available');
     }
-    return bridge.invoke(route, params).then(() => undefined);
+    return bridge;
   }
 
-  private async performNavigation(options: {
-    url: string;
-    page?: string | null;
-    path?: string | null;
-    query?: string | null;
-    openType: NavigatorOpenType;
-    target: NavigatorTarget;
-    delta: number;
-    appId?: string | null;
-    channel?: NavigatorChannel | null;
-    targetVersion?: string | null;
-    phoneNumber?: string | null;
-  }) {
-    const url = options.url || '';
+  private async callHost(route: string, params?: unknown): Promise<void> {
+    await this.bridge().invoke(route, params);
+  }
+
+  // Placements run through Logic's lx.surface, which owns surface handles.
+  private async callSurface(method: 'openPage' | 'openUrl', params: unknown): Promise<void> {
+    await this.bridge().raw.call(`surface.${method}`, params);
+  }
+
+  private async performNavigation(options: NavigateOptions) {
+    const { url, placement } = options;
     const delta = Number.isFinite(options.delta) && options.delta > 0 ? options.delta : 1;
 
-    if (options.path !== null && options.path !== undefined) {
+    if (options.path !== null) {
       throw new Error('path is not supported; pass the configured page name in page');
     }
 
@@ -442,44 +441,67 @@ export class LxNavigatorElement extends HTMLElement {
     if (options.openType === 'navigateBack') {
       if (options.target === 'lxapp') {
         await this.callHost('navigator.navigateBackApp');
-        return;
-      }
-      if (options.target === 'browser') {
-        throw new Error('navigateBack is not supported for browser target');
+      } else {
+        await this.callHost('navigation.navigateBack', { delta });
       }
-      await this.callHost('navigation.navigateBack', { delta });
       return;
     }
 
-    if (options.target === 'browser') {
-      if (!url) {
-        throw new Error('openUrl requires url');
+    switch (options.target) {
+      case 'url': {
+        if (!url) {
+          throw new Error('target url requires url');
+        }
+        if (!placement || placement === 'external') {
+          await this.callHost('device.openUrl', { url, target: 'external' });
+          return;
+        }
+        if (placement !== 'tab' && placement !== 'aside') {
+          throw new Error(`a url opens as external, tab, or aside; got ${placement}`);
+        }
+        const surfaceOptions: Record<string, unknown> = { as: placement };
+        if (options.edge) surfaceOptions.edge = options.edge;
+        const size = this.readJsonObject('size', options.size);
+        if (size) surfaceOptions.size = size;
+        await this.callSurface('openUrl', { url, options: surfaceOptions });
+        return;
       }
-      await this.callHost('device.openUrl', { url, target: 'external' });
-      return;
+      case 'lxapp':
+        if (!options.appId) {
+          throw new Error('target lxapp requires app-id');
+        }
+        if (placement) {
+          throw new Error('as is not supported for target lxapp');
+        }
+        await this.callHost('navigator.navigateToApp', this.buildLxAppTarget(options));
+        return;
+      case 'page':
+        break;
+      default:
+        throw new Error(`Unsupported target: ${options.target}`);
     }
 
-    if (options.target === 'lxapp') {
-      if (!options.appId) {
-        throw new Error('navigateToApp requires app-id');
-      }
-      await this.callHost('navigator.navigateToApp', this.buildLxAppTarget(options));
-      return;
+    const target = this.buildPageTarget(options);
+    if (!target) {
+      throw new Error(`${options.openType} requires page`);
     }
 
-    if (options.target === 'self' && /^https?:\/\//i.test(url)) {
-      if (!url) {
-        throw new Error('openUrl requires url');
+    if (placement) {
+      if (placement !== 'float' && placement !== 'window') {
+        throw new Error(`a page opens as float or window; got ${placement}`);
       }
-      await this.callHost('device.openUrl', { url, target: 'self' });
+      const surfaceOptions: Record<string, unknown> = { as: placement };
+      if (target.query) surfaceOptions.query = target.query;
+      if (options.position) surfaceOptions.position = options.position;
+      if (options.chrome) surfaceOptions.chrome = options.chrome;
+      const size = this.readJsonObject('size', options.size);
+      if (size) surfaceOptions.size = size;
+      const interaction = this.readJsonObject('interaction', options.interaction);
+      if (interaction) surfaceOptions.interaction = interaction;
+      await this.callSurface('openPage', { page: target.page, options: surfaceOptions });
       return;
     }
 
-    const target = this.buildPageTarget(options);
-    if (!target) {
-      throw new Error(`${options.openType} requires page`);
-    }
-
     switch (options.openType) {
       case 'navigate':
         await this.callHost('navigation.navigateTo', target);
@@ -493,24 +515,22 @@ export class LxNavigatorElement extends HTMLElement {
       case 'reLaunch':
         await this.callHost('navigation.reLaunch', target);
         break;
-      case 'openUrl':
-        await this.callHost('device.openUrl', {
-          url,
-          target: options.target === 'self' ? 'self' : 'external'
-        });
-        break;
       default:
         throw new Error(`Unsupported openType: ${options.openType}`);
     }
   }
 
-  private readQuery(raw?: string | null): NavigatorQuery | undefined {
+  private readJsonObject(name: string, raw?: string | null): Record<string, unknown> | undefined {
     if (!raw) return undefined;
     const parsed = JSON.parse(raw) as unknown;
     if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
-      throw new Error('query must be an object');
+      throw new Error(`${name} must be an object`);
     }
-    return parsed as NavigatorQuery;
+    return parsed as Record<string, unknown>;
+  }
+
+  private readQuery(raw?: string | null): NavigatorQuery | undefined {
+    return this.readJsonObject('query', raw) as NavigatorQuery | undefined;
   }
 
   private buildPageTarget(options: {