@lvce-editor/api 9.29.1 → 9.31.0

package/README.md

@@ -50,3 +50,20 @@ await storeSecret('access-token', token)
 const savedToken = await getSecret('access-token')
 await deleteSecret('access-token')
 ```
+
+## Workspace ports
+
+Declare `"onPorts:codespaces"` in the extension's `activation` array and register a provider after activating the API:
+
+```ts
+import { registerPortProvider } from '@lvce-editor/api'
+
+const registration = registerPortProvider({
+  scheme: 'codespaces',
+  async providePorts(workspaceUri) {
+    return [{ port: 3000, forwardedAddress: 'https://my-codespace-3000.app.github.dev/', origin: 'devcontainer.json' }]
+  },
+})
+```
+
+Ports queries matching extensions with the current workspace URI. Each extension may register one provider per scheme. Return an empty array when no ports are available, and dispose the registration when deactivating. The provider supplies addresses; the API does not create tunnels or change their visibility. Results from disposed registrations are discarded.

package/dist/index.d.ts

@@ -62,3 +62,6 @@ export type { ShowQuickPickOptions } from './parts/ShowQuickPickOptions/ShowQuic
 export type { StatusBarItem, StatusBarItemProvider, StatusBarItemProviderHandle, StatusBarItemProviderRegistrySnapshot, } from './parts/StatusBar/StatusBar.ts';
 export { setRemoteDescription, startWebRtcAudioStream, stopWebRtcAudioStream, readMicLevels } from './parts/WebRtc/WebRtc.ts';
 export type { MicLevelsResult, ReadMicLevelOptions, SetRemoteDescriptionOptions, StartWebRpcAudioStreamOptions, WebRtcAudioConstraints, } from './parts/WebRtc/WebRtc.ts';
+export { registerPortProvider } from './parts/PortProviderRegistry/PortProviderRegistry.ts';
+export type { PortProvider } from './parts/PortProvider/PortProvider.ts';
+export type { ForwardedPort } from './parts/ForwardedPort/ForwardedPort.ts';

package/dist/index.js

@@ -33,3 +33,4 @@ export { getStatusBarItemProviderRegistrySnapshot, registerStatusBarItemProvider
 export { handleExtensionManagementMessagePort } from "./parts/HandleExtensionManagementMessagePort/HandleExtensionManagementMessagePort.js";
 export { createNodeRpc, createRpc } from "./parts/Rpc/Rpc.js";
 export { setRemoteDescription, startWebRtcAudioStream, stopWebRtcAudioStream, readMicLevels } from "./parts/WebRtc/WebRtc.js";
+export { registerPortProvider } from "./parts/PortProviderRegistry/PortProviderRegistry.js";

package/dist/parts/ForwardedPort/ForwardedPort.d.ts

@@ -0,0 +1,7 @@
+export interface ForwardedPort {
+    readonly active?: boolean;
+    readonly forwardedAddress: string;
+    readonly origin?: string;
+    readonly port: number;
+    readonly runningProcess?: string;
+}

package/dist/parts/ForwardedPort/ForwardedPort.js

@@ -0,0 +1 @@
+export {};

package/dist/parts/PortProvider/PortProvider.d.ts

@@ -0,0 +1,5 @@
+import type { ForwardedPort } from '../ForwardedPort/ForwardedPort.ts';
+export interface PortProvider {
+    readonly providePorts: (workspaceUri: string) => readonly ForwardedPort[] | Promise<readonly ForwardedPort[]>;
+    readonly scheme: string;
+}

package/dist/parts/PortProvider/PortProvider.js

@@ -0,0 +1 @@
+export {};

package/dist/parts/PortProviderRegistry/PortProviderRegistry.d.ts

@@ -0,0 +1,5 @@
+import type { Disposable } from '../Disposable/Disposable.ts';
+import type { ForwardedPort } from '../ForwardedPort/ForwardedPort.ts';
+import type { PortProvider } from '../PortProvider/PortProvider.ts';
+export declare const providePorts: (workspaceUri: string) => Promise<readonly ForwardedPort[]>;
+export declare const registerPortProvider: (provider: PortProvider) => Disposable;

package/dist/parts/PortProviderRegistry/PortProviderRegistry.js

@@ -0,0 +1,37 @@
+import * as ExtensionApiCommandRegistry from "../ExtensionApiCommandRegistry/ExtensionApiCommandRegistry.js";
+import { ExtensionApiError } from "../ExtensionApiError/ExtensionApiError.js";
+const providers = new Map();
+export const providePorts = async (workspaceUri) => {
+    const scheme = /^([a-z][a-z0-9+.-]*):/i.exec(workspaceUri)?.[1].toLowerCase();
+    const provider = scheme ? providers.get(scheme) : undefined;
+    if (!provider) {
+        return [];
+    }
+    const ports = await provider.providePorts(workspaceUri);
+    if (!Array.isArray(ports) ||
+        ports.some((port) => !port || !Number.isSafeInteger(port.port) || port.port < 1 || port.port > 65_535 || typeof port.forwardedAddress !== 'string')) {
+        throw new ExtensionApiError('port provider returned invalid ports');
+    }
+    return providers.get(scheme) === provider ? ports : [];
+};
+export const registerPortProvider = (provider) => {
+    if (!provider ||
+        typeof provider.scheme !== 'string' ||
+        !/^[a-z][a-z0-9+.-]*$/.test(provider.scheme) ||
+        typeof provider.providePorts !== 'function') {
+        throw new ExtensionApiError('port provider requires a URI scheme and providePorts function');
+    }
+    const { scheme } = provider;
+    if (providers.has(scheme)) {
+        throw new ExtensionApiError(`port provider for ${scheme} is already registered`);
+    }
+    providers.set(scheme, provider);
+    ExtensionApiCommandRegistry.registerCommandMap({ 'ExtensionApi.providePorts': providePorts });
+    return {
+        dispose() {
+            if (providers.get(scheme) === provider) {
+                providers.delete(scheme);
+            }
+        },
+    };
+};

package/dist/parts/View/View.d.ts

@@ -73,9 +73,11 @@ interface ViewBase<State> {
     readonly preferredLocation?: ViewPreferredLocation;
     readonly title?: string;
 }
-export interface InstanceView<State = unknown> extends ViewBase<State> {
+export interface InstanceView<State = unknown, ComponentState = unknown> extends ViewBase<State> {
     readonly create: (context?: ViewContext) => State | Promise<State>;
     readonly createInitialState?: never;
+    readonly getComponentState?: (instance: State) => ComponentState | Promise<ComponentState>;
+    readonly setComponentState?: (instance: State, state: ComponentState) => void | Promise<void>;
 }
 export interface StatefulView<State = unknown> extends ViewBase<State> {
     readonly create?: never;
@@ -95,7 +97,7 @@ export interface StatefulView<State = unknown> extends ViewBase<State> {
     readonly renderTitle?: (state: State) => string | Promise<string>;
     readonly saveState?: (state: State) => unknown;
 }
-export type View<State = unknown> = InstanceView<State> | StatefulView<State>;
+export type View<State = unknown, ComponentState = unknown> = InstanceView<State, ComponentState> | StatefulView<State>;
 export interface RegisteredView {
     readonly displayName?: string;
     readonly eventListeners?: readonly DomEventListener[];

package/dist/parts/ViewRegistry/ViewRegistry.d.ts

@@ -1,7 +1,7 @@
 import { type VirtualDomNode } from '@lvce-editor/virtual-dom-worker';
 import type { Disposable } from '../Disposable/Disposable.ts';
 import type { MenuEntry, View, ViewAction, ViewContext, ViewEvent, ViewRegistrySnapshot, ViewRenderResult } from '../View/View.ts';
-export declare const registerView: <State>(view: View<State>) => Disposable;
+export declare const registerView: <State, ComponentState = unknown>(view: View<State, ComponentState>) => Disposable;
 export declare const executeViewProvider: (id: string) => unknown;
 export declare const createViewInstance: (viewId: string, uid: number, context?: ViewContext) => Promise<ViewRenderResult>;
 export declare const dispatchViewEvent: (uid: number, event: ViewEvent) => Promise<ViewRenderResult>;

package/dist/parts/ViewRegistry/ViewRegistry.js

@@ -91,6 +91,11 @@ const assertView = (view) => {
     if (typeof candidate.createInitialState === 'function' && typeof candidate.render !== 'function') {
         throw new ExtensionApiError(`view ${view.id} is missing render function`);
     }
+    if (!isStatefulView(view) &&
+        (view.getComponentState !== undefined || view.setComponentState !== undefined) &&
+        (typeof view.getComponentState !== 'function' || typeof view.setComponentState !== 'function')) {
+        throw new ExtensionApiError(`view ${view.id} component state requires getComponentState and setComponentState`);
+    }
     if (view.id in views) {
         throw new ExtensionApiError(`view ${view.id} is already registered`);
     }
@@ -109,7 +114,7 @@ const toRegisteredView = (view) => {
         id: view.id,
         name: view.name,
         preferredLocation: view.preferredLocation || 'sideBar',
-        ...(isStatefulView(view) && { stateful: true }),
+        ...((isStatefulView(view) || typeof view.getComponentState === 'function') && { stateful: true }),
         title: displayName,
     };
     if (view.kind) {
@@ -625,13 +630,29 @@ export const saveViewInstanceState = async (uid) => {
     return instance.saveState();
 };
 export const getViewInstanceState = (uid) => {
-    getVirtualDomInstance(uid);
+    const instance = getVirtualDomInstance(uid);
+    const view = views[contextViewIds[uid]];
+    if (!isStatefulView(view) && view.getComponentState) {
+        return view.getComponentState(instance);
+    }
     return ViewletStates.get(uid);
 };
 export const setViewInstanceState = async (uid, newState) => {
-    getVirtualDomInstance(uid);
+    const instance = getVirtualDomInstance(uid);
     const viewId = contextViewIds[uid];
+    const view = views[viewId];
     assertViewState(viewId, newState);
+    if (!isStatefulView(view) && view.getComponentState && view.setComponentState) {
+        const oldState = structuredClone(await view.getComponentState(instance));
+        try {
+            await view.setComponentState(instance, newState);
+            return await renderViewInstance(uid);
+        }
+        catch (error) {
+            await view.setComponentState(instance, oldState);
+            throw error;
+        }
+    }
     const oldState = ViewletStates.get(uid);
     ViewletStates.replace(uid, newState);
     try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lvce-editor/api",
-  "version": "9.29.1",
+  "version": "9.31.0",
   "description": "Tree-shakeable extension API for Lvce Editor extensions.",
   "keywords": [
     "lvce-editor",