@qilin-agent/client-ui-sidebar-browser 0.0.0-stage → 3.1.3

package/lib/index.js

@@ -0,0 +1,6 @@
+//#region lib/types/index.js
+/** Host companion for the Sidebar Browser Client plugin. */
+/** Mount the browser-only plugin through the Client loader. */
+function apply() {}
+//#endregion
+export { apply };

package/lib/types/client/browser/BrowserController.d.ts

@@ -0,0 +1,76 @@
+/** Per-tab Browser controller. */
+import type { BoundActions } from '@qilin-agent/client-store';
+import type { TabId } from '@qilin-agent/client-ui-dockkit';
+import type { HostObservable } from '@qilin-agent/client-ui-slots';
+import type { BrowserFrame, BrowserFrameState } from './BrowserFrame.ts';
+import type { BrowserTabState } from './BrowserNavigation.ts';
+import type { BrowserStore } from './store.ts';
+/** Construction dependencies for one tab-scoped Browser controller. */
+export interface BrowserControllerOptions {
+    readonly tabId: TabId;
+    readonly signal: AbortSignal;
+    readonly applicationOrigin: string;
+    readonly initial?: BrowserTabState;
+    readonly actions: BoundActions<BrowserStore>;
+}
+/** Owns one Browser tab's URL state, loading lifecycle, and four navigation commands. */
+export declare class BrowserController {
+    private readonly options;
+    /** Renderer-facing iframe and sandbox state. */
+    readonly frame: BrowserFrame;
+    private readonly navigation;
+    private disposed;
+    /**
+     * @param options - tab identity, persistence writer, URL origin, and lifetime.
+     */
+    constructor(options: BrowserControllerOptions);
+    /**
+     * Validate and load one address, replacing a same-address load with Reload.
+     * @param value - address-bar or typed-tab value.
+     */
+    loadUrl(value: string): void;
+    /** Move to the preceding application-known address when Web history remains usable. */
+    goBack(): void;
+    /** Move to the following application-known address when Web history remains usable. */
+    goForward(): void;
+    /** Reload the last application-known address without adding history. */
+    reload(): void;
+    private start;
+    private frameLoaded;
+    private publish;
+    private dispose;
+}
+/** Browser commands and keyed frame state injected into the tab body. */
+export interface BrowserInjected {
+    readonly keyedHooks: {
+        readonly browserFrame: (key: string) => HostObservable<BrowserFrameState> | undefined;
+    };
+    /**
+     * @param tabId - tab occurrence.
+     * @param signal - occurrence lifetime.
+     * @param applicationOrigin - current application origin.
+     * @param initial - persisted tab state.
+     */
+    mount(tabId: TabId, signal: AbortSignal, applicationOrigin: string, initial?: BrowserTabState): void;
+    /** @param tabId - tab occurrence. @param value - address-bar or typed-open value. */
+    loadUrl(tabId: TabId, value: string): void;
+    /** @param tabId - tab occurrence. */
+    goBack(tabId: TabId): void;
+    /** @param tabId - tab occurrence. */
+    goForward(tabId: TabId): void;
+    /** @param tabId - tab occurrence. */
+    reload(tabId: TabId): void;
+    /** @param tabId - tab occurrence. */
+    toggleSandbox(tabId: TabId): void;
+    /** @param tabId - tab occurrence. @param revision - rendered document revision. */
+    reportLoaded(tabId: TabId, revision: number): void;
+    /** @param tabId - tab occurrence. @param revision - rendered document revision that emitted `error`. */
+    reportLoadFailed(tabId: TabId, revision: number): void;
+}
+/**
+ * Bind Browser controllers to one Session and its persistence writer.
+ * @param actions - Browser store mutation face.
+ * @returns a per-tab controller registry exposed as plain Slot callbacks.
+ */
+export declare function createBrowserControllers(actions: BoundActions<BrowserStore>): BrowserInjected;
+//# sourceMappingURL=BrowserController.d.ts.map

package/lib/types/client/browser/BrowserFrame.d.ts

@@ -0,0 +1,60 @@
+import type { HostObservable } from '@qilin-agent/client-ui-slots';
+import type { BrowserTarget } from './url.ts';
+/** One prepared document rendered by a BrowserFrame implementation. */
+export interface BrowserDocument {
+    readonly target: BrowserTarget;
+    readonly src: string;
+    readonly revision: number;
+}
+/** Current renderer-facing state for one Browser tab. */
+export interface BrowserFrameState {
+    readonly document: BrowserDocument | undefined;
+    readonly sandboxed: boolean;
+    readonly loadFailed: boolean;
+}
+/** Browser rendering operations shared by Web and future Electron implementations. */
+export interface BrowserFrame extends HostObservable<BrowserFrameState> {
+    /** Toggle sandbox enforcement for this tab occurrence. */
+    toggleSandbox(): void;
+    /** @param document - current prepared document. */
+    setDocument(document: BrowserDocument): void;
+    /** Remove the current prepared document. */
+    clearDocument(): void;
+    /** @param revision - rendered document revision reported by the carrier. */
+    reportLoaded(revision: number): void;
+    /** @param revision - rendered document revision whose carrier reported an error. */
+    reportLoadFailed(revision: number): void;
+}
+/** Owns transient iframe and sandbox-toggle state independently from URL navigation. */
+export declare class IframeImpl implements BrowserFrame {
+    private readonly sandboxChanged;
+    private readonly documentLoaded;
+    private readonly store;
+    /**
+     * @param sandboxChanged - applies the new policy to the current controlled target.
+     * @param documentLoaded - reports an iframe load to the navigation state machine.
+     */
+    constructor(sandboxChanged: (sandboxed: boolean) => void, documentLoaded: (revision: number) => void);
+    /** @returns the immutable renderer snapshot. */
+    getSnapshot: () => BrowserFrameState;
+    /**
+     * Subscribe to iframe or sandbox-mode changes.
+     * @param listener - invalidation callback.
+     * @returns the unsubscribe function.
+     */
+    subscribe: (listener: () => void) => (() => void);
+    /** Toggle sandbox enforcement for this tab occurrence. */
+    toggleSandbox(): void;
+    /**
+     * Publish a prepared frame from the owning controller.
+     * @param document - current prepared document.
+     */
+    setDocument(document: BrowserDocument): void;
+    /** Remove the current prepared frame and transient load failure. */
+    clearDocument(): void;
+    /** @param revision - rendered document revision reported by the iframe. */
+    reportLoaded(revision: number): void;
+    /** @param revision - rendered document revision whose iframe emitted `error`. */
+    reportLoadFailed(revision: number): void;
+}
+//# sourceMappingURL=BrowserFrame.d.ts.map

package/lib/types/client/browser/BrowserNavigation.d.ts

@@ -0,0 +1,109 @@
+/** URL, history, and observability state for one Browser tab. */
+import type { BrowserAddressFailure, BrowserTarget } from './url.ts';
+/** Maximum retained application-known navigation entries per tab. */
+export declare const MAX_BROWSER_HISTORY = 100;
+/** One canonical address in the application-managed Web history. */
+export type BrowserHistoryEntry = BrowserTarget;
+/** Whether the current carrier document still corresponds to an application-known URL. */
+export type BrowserNavigationStatus = {
+    readonly status: 'empty';
+} | {
+    readonly status: 'loading';
+    readonly revision: number;
+} | {
+    readonly status: 'known';
+    readonly revision: number;
+} | {
+    readonly status: 'unknown';
+    readonly revision: number;
+};
+/** Address-policy or loading failure shown below the toolbar. */
+export type BrowserFailure = {
+    readonly kind: 'address';
+    readonly reason: BrowserAddressFailure;
+};
+/** One Browser tab's serializable URL state. */
+export interface BrowserTabState {
+    readonly entries: readonly BrowserHistoryEntry[];
+    readonly index: number;
+    /** Last application-directed load; carrier observations do not rewrite it. */
+    readonly request: {
+        readonly revision: number;
+        readonly target: BrowserTarget;
+    } | undefined;
+    readonly navigation: BrowserNavigationStatus;
+    readonly failure: BrowserFailure | undefined;
+}
+/**
+ * Owns the application-known URL history and the iframe observation state machine.
+ * The first load for a request keeps its URL authoritative; another load marks it unknown.
+ */
+export declare class BrowserNavigation {
+    private value;
+    /**
+     * @param initial - persisted state restored for this tab, or a fresh empty state.
+     */
+    constructor(initial?: BrowserTabState);
+    /**
+     * Create state before a tab has a controlled navigation target.
+     * @returns empty serializable state.
+     */
+    static empty(): BrowserTabState;
+    /**
+     * Read the selected application-history entry.
+     * @param state - serializable tab state.
+     * @returns the current target, if any.
+     */
+    static current(state: BrowserTabState | undefined): BrowserHistoryEntry | undefined;
+    /**
+     * Test whether the Web carrier can use the preceding application-history entry.
+     * @param state - serializable tab state.
+     * @returns whether Back is available.
+     */
+    static canGoBack(state: BrowserTabState): boolean;
+    /**
+     * Test whether the Web carrier can use the following application-history entry.
+     * @param state - serializable tab state.
+     * @returns whether Forward is available.
+     */
+    static canGoForward(state: BrowserTabState): boolean;
+    /** Current immutable serializable state. */
+    get snapshot(): BrowserTabState;
+    /** Whether the Web iframe can safely use the application-owned Back entry. */
+    get canGoBack(): boolean;
+    /** Whether the Web iframe can safely use the application-owned Forward entry. */
+    get canGoForward(): boolean;
+    /**
+     * Add a controlled target and discard its stale forward branch.
+     * @param target - validated canonical target.
+     * @returns the new load request.
+     */
+    navigate(target: BrowserTarget): NonNullable<BrowserTabState['request']>;
+    /**
+     * Select the preceding application-known target.
+     * @returns a new load request, or undefined when unavailable.
+     */
+    back(): BrowserTabState['request'];
+    /**
+     * Select the following application-known target.
+     * @returns a new load request, or undefined when unavailable.
+     */
+    forward(): BrowserTabState['request'];
+    /**
+     * Start another load of the last application-known target.
+     * @returns a new load request, or undefined before the first target.
+     */
+    reload(): BrowserTabState['request'];
+    /**
+     * Record an invalid address without changing the active document state.
+     * @param reason - parser refusal.
+     */
+    addressFailed(reason: BrowserAddressFailure): void;
+    /**
+     * Record a frame load for its captured revision.
+     * @param revision - revision bound to the rendered frame.
+     */
+    frameLoaded(revision: number): void;
+    private request;
+}
+//# sourceMappingURL=BrowserNavigation.d.ts.map

package/lib/types/client/browser/store.d.ts

@@ -0,0 +1,21 @@
+/** Persisted Browser tab snapshots shared by the body and title slots. */
+import { type EngineStoreHandle } from '@qilin-agent/client-store';
+import type { TabId } from '@qilin-agent/client-ui-dockkit';
+import type { BrowserTabState } from './BrowserNavigation.ts';
+/** All Browser tabs in one Session-scoped store. */
+export interface BrowserState {
+    byTab: Record<TabId, BrowserTabState>;
+}
+type BrowserActions = {
+    replace: (draft: BrowserState, tabId: TabId, state: BrowserTabState) => void;
+    forget: (draft: BrowserState, tabId: TabId) => void;
+};
+/**
+ * Declare the Session-scoped Browser persistence store.
+ * @returns a fresh store handle for Slot registration.
+ */
+export declare function createBrowserStore(): EngineStoreHandle<BrowserState, BrowserActions>;
+/** Browser store handle shared by body and title registrations. */
+export type BrowserStore = ReturnType<typeof createBrowserStore>;
+export {};
+//# sourceMappingURL=store.d.ts.map

package/lib/types/client/browser/url.d.ts

@@ -0,0 +1,31 @@
+/** Address parsing for the Sidebar browser's HTTP(S) allowlist. */
+/** Maximum accepted address length; this bounds persisted navigation state. */
+export declare const MAX_BROWSER_URL_LENGTH: number;
+/** A normalized Browser navigation target. */
+export type BrowserTarget = {
+    readonly kind: 'https';
+    readonly url: string;
+    readonly title: string;
+} | {
+    readonly kind: 'http';
+    readonly url: string;
+    readonly title: string;
+};
+/** Why an address was refused before navigation. */
+export type BrowserAddressFailure = 'empty' | 'invalid' | 'protocol' | 'credentials' | 'application-origin';
+/** Result of parsing an address-bar value. */
+export type BrowserAddressResult = {
+    readonly ok: true;
+    readonly target: BrowserTarget;
+} | {
+    readonly ok: false;
+    readonly reason: BrowserAddressFailure;
+};
+/**
+ * Parse one address-bar value into the fixed protocol allowlist.
+ * @param input - user or typed-open input.
+ * @param applicationOrigin - current QILIN document origin, blocked for HTTPS.
+ * @returns a canonical target or the refusal reason.
+ */
+export declare function parseBrowserAddress(input: string, applicationOrigin?: string): BrowserAddressResult;
+//# sourceMappingURL=url.d.ts.map

package/lib/types/client/definition.d.ts

@@ -0,0 +1,14 @@
+/** Static Browser tab type and guide declaration. */
+import type { TranslateNS } from '@qilin-agent/client-locale/client';
+import type { SidebarRightTabDefinition } from '@qilin-agent/client-ui-sidebar-right/client';
+/** Browser tab kind. */
+export declare const BROWSER_KIND = "browser";
+/** Browser implementation identity and keyed Slot dispatch key. */
+export declare const BROWSER_ID = "@qilin-agent/client-ui-sidebar-browser";
+/**
+ * Build the Browser type with locale-live copy.
+ * @param t - namespace-bound translate, read fresh on every label call.
+ * @returns the definition to register.
+ */
+export declare function browserDefinition(t: TranslateNS<'sidebarBrowser'>): SidebarRightTabDefinition;
+//# sourceMappingURL=definition.d.ts.map

package/lib/types/client/index.d.ts

@@ -0,0 +1,22 @@
+/** Register the HTTP(S) Browser tab type in the right Sidebar. */
+import type { Context } from '@qilin-agent/kylin';
+export type { BrowserBodyProps } from './view/BrowserBody.tsx';
+export type { BrowserInjected } from './browser/BrowserController.ts';
+export type { BrowserDocument, BrowserFrame, BrowserFrameState } from './browser/BrowserFrame.ts';
+export type { BrowserFailure, BrowserHistoryEntry, BrowserNavigationStatus, BrowserTabState } from './browser/BrowserNavigation.ts';
+export type { SidebarBrowserKey } from './locales.ts';
+export type { BrowserState } from './browser/store.ts';
+export type { BrowserAddressFailure, BrowserAddressResult, BrowserTarget } from './browser/url.ts';
+declare module '@qilin-agent/client-ui-sidebar-right/client' {
+    interface SidebarRightTabParamsMap {
+        /** Optional initial Browser URL. */
+        browser: {
+            readonly url?: string;
+        };
+    }
+}
+/** Required Browser services. */
+export declare const inject: string[];
+/** Register the Browser type, localized guide entry, body, and title. */
+export declare function apply(ctx: Context): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/client/locales.d.ts

@@ -0,0 +1,59 @@
+/** Locale-owned Browser tab copy. */
+export declare const zh: {
+    'type.label': string;
+    'guide.title': string;
+    'guide.description': string;
+    'address.placeholder': string;
+    'address.changed': string;
+    back: string;
+    forward: string;
+    reload: string;
+    go: string;
+    external: string;
+    'sandbox.disable': string;
+    'sandbox.enable': string;
+    'sandbox.warning': string;
+    start: string;
+    loading: string;
+    'error.empty': string;
+    'error.invalid': string;
+    'error.protocol': string;
+    'error.credentials': string;
+    'error.application-origin': string;
+    'web.loadFailed': string;
+    'web.unknown': string;
+};
+/** Browser dictionary key union. */
+export type SidebarBrowserKey = keyof typeof zh;
+/** English dictionary with the same keys. */
+export declare const en: {
+    'type.label': string;
+    'guide.title': string;
+    'guide.description': string;
+    'address.placeholder': string;
+    'address.changed': string;
+    back: string;
+    forward: string;
+    reload: string;
+    go: string;
+    external: string;
+    'sandbox.disable': string;
+    'sandbox.enable': string;
+    'sandbox.warning': string;
+    start: string;
+    loading: string;
+    'error.empty': string;
+    'error.invalid': string;
+    'error.protocol': string;
+    'error.credentials': string;
+    'error.application-origin': string;
+    'web.loadFailed': string;
+    'web.unknown': string;
+};
+declare module '@qilin-agent/client-ui-slots' {
+    interface LocaleNamespaceMap {
+        /** Sidebar Browser labels, navigation controls, and failures. */
+        sidebarBrowser: SidebarBrowserKey;
+    }
+}
+//# sourceMappingURL=locales.d.ts.map

package/lib/types/client/view/BrowserBody.d.ts

@@ -0,0 +1,15 @@
+import type { ReactNode } from 'react';
+import type { InjectFace, PropsLocale, PropsRuntime, PropsStore } from '@qilin-agent/client-ui-slots';
+import type { BrowserInjected } from '../browser/BrowserController.ts';
+import type { BrowserStore } from '../browser/store.ts';
+/** Fixed Web iframe sandbox; popups escape the sandbox while top navigation remains absent. */
+export declare const WEB_BROWSER_SANDBOX = "allow-scripts allow-forms allow-same-origin allow-popups allow-popups-to-escape-sandbox";
+/** Browser body props assembled by the tab seat. */
+export type BrowserBodyProps = PropsRuntime<'sidebar.right.pane.tab'> & PropsStore<BrowserStore> & PropsLocale<'sidebarBrowser'> & InjectFace<BrowserInjected>;
+/**
+ * Browser tab renderer for a controller-owned URL state and Web iframe carrier.
+ * @param props - composed slot props for the Browser tab body.
+ * @returns the toolbar and the carrier frame.
+ */
+export declare function BrowserBody(props: BrowserBodyProps): ReactNode;
+//# sourceMappingURL=BrowserBody.d.ts.map

package/lib/types/client/view/BrowserTitle.d.ts

@@ -0,0 +1,13 @@
+/** Live Browser tab title from the Browser store. */
+import type { ReactNode } from 'react';
+import type { PropsRuntime, PropsStore } from '@qilin-agent/client-ui-slots';
+import type { BrowserStore } from '../browser/store.ts';
+/** Browser title props assembled by the Sidebar title seat. */
+export type BrowserTitleProps = PropsRuntime<'sidebar.right.pane.tab.title'> & PropsStore<BrowserStore>;
+/**
+ * Browser icon and current host name.
+ * @param props - composed slot props for the Browser tab title.
+ * @returns the icon and the current host name.
+ */
+export declare function BrowserTitle(props: BrowserTitleProps): ReactNode;
+//# sourceMappingURL=BrowserTitle.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,4 @@
+/** Host companion for the Sidebar Browser Client plugin. */
+/** Mount the browser-only plugin through the Client loader. */
+export declare function apply(): void;
+//# sourceMappingURL=index.d.ts.map

package/package.json

@@ -1,6 +1,69 @@
 {
   "name": "@qilin-agent/client-ui-sidebar-browser",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "description": "Sandboxed Web browser tabs for the right Sidebar",
+  "version": "3.1.3",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kkutysllb/QiLin.git",
+    "directory": "packages/client/ui-sidebar-browser"
+  },
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./client": {
+      "types": "./lib/types/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "qilin": {
+    "client": {
+      "inject": [
+        "@qilin-agent/client-ui-sidebar-right",
+        "@qilin-agent/client-ui-session"
+      ],
+      "platform": "web"
+    }
+  },
+  "license": "MIT",
+  "peerDependencies": {
+    "@qilin-agent/kylin": "~4.0.3"
+  },
+  "devDependencies": {
+    "@testing-library/react": "^16.1.0",
+    "@types/react": "~18.3.1",
+    "@types/react-dom": "~18.3.0",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "@qilin-agent/kylin": "~4.0.3",
+    "@qilin-agent/client-locale": "3.1.3",
+    "@qilin-agent/client-store": "3.1.3",
+    "@qilin-agent/client-ui-dockkit": "3.1.3",
+    "@qilin-agent/client-ui-primitives": "3.1.3",
+    "@qilin-agent/client-ui-renderer": "3.1.3",
+    "@qilin-agent/client-ui-session": "3.1.3",
+    "@qilin-agent/client-ui-slots": "3.1.3",
+    "@qilin-agent/client-ui-sidebar-right": "3.1.3"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/client.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "scripts": {
+    "bundle": "tsdown",
+    "watch": "tsdown --watch"
+  }
 }