@octostar/platform-types 0.5.37 → 1.0.0

package/dist/desktop.d.ts

@@ -1,15 +1,13 @@
 import type { TabNode } from 'flexlayout-react';
 import type { ButtonProps } from 'antd';
 import type { AddListener, Unsubscribe } from './callback';
-import type { WorkspaceItem, Entity, WorkspaceItemModel, WorkspaceRecordIdentifier, OsWorkspaceEntity, Relationship, OsTag, TagAttributes, ConceptFilter, FocusListItem, Concept, EntityBase } from './model';
-import type { TagWithRelationship, Workspace, WorkspaceChangeEmitter, WorkspaceIdentifier, WorkspacePermission, WorkspacePermissionValue, WorkspaceRecordWithRelationships } from './workspace';
+import type { WorkspaceItem, Entity, WorkspaceItemModel, WorkspaceRecordIdentifier, OsWorkspaceEntity, Relationship, OsTag, TagAttributes, FocusListItem, Concept, EntityBase } from './model';
+import type { RuntimeAppUrlWorkspaceItem, TagWithRelationship, WorkspaceChangeEmitter, WorkspaceIdentifier, WorkspacePermission, WorkspacePermissionValue, WorkspaceRecordWithRelationships } from './workspace';
 import type { EventEmitterType } from './event';
 import type { ActionContext, ContextMenuGroup, ContextMenuOptions, ContextMenuRequest } from './action';
-import type { ModalTemplateProps, SavedTemplate } from './templates';
+import type { ModalTemplateProps, RenderableTemplate, SavedTemplate } from './templates';
 import type { App, AppServiceCallProps } from './app';
-import type { SearchOptions, SearchProps, SearchXperienceProps } from './search';
-import type { Styler, StylerConfig, StylerOption } from './styling';
-import type { GraphSpec } from './graph';
+import type { SearchOptions, SearchProps, SearchQueryResult, SearchXperienceProps } from './search';
 import type { UserProfile } from './user';
 import type { ReactCssProperties, ReactRef, ReactNode } from './react-types';
 import type { Ontology } from './ontology';
@@ -46,48 +44,6 @@ export type IconProps = {
      */
     iconRef?: ReactRef<HTMLSpanElement>;
 };
-export type Watcher = {
-    /**
-     * Application ID.
-     */
-    app_id: string;
-    /**
-     * Application name.
-     */
-    app_name: string;
-    /**
-     * Watcher name.
-     */
-    watcher_name: string;
-    /**
-     * Constants for the watcher.
-     */
-    const: [key: string, value: any][];
-    /**
-     * Description of the watcher.
-     */
-    description: string;
-    /**
-     * File associated with the watcher.
-     */
-    file: string;
-    /**
-     * Interval for the watcher.
-     */
-    interval: string;
-    /**
-     * Name of the watcher.
-     */
-    name: string;
-    /**
-     * Parameters for the watcher.
-     */
-    params: [key: string, value: any][];
-    /**
-     * Semantically bound items.
-     */
-    semantically_bound: string[];
-};
 /**
  * Options for saving a file.
  * @beta
@@ -103,10 +59,6 @@ export type SaveFileOptions = {
  * @beta
  */
 export type SaveOptions = SaveFileOptions & {
-    /**
-     * Whether to save as a draft.
-     */
-    draft?: boolean;
     /**
      * Whether to save as a new file.
      */
@@ -147,10 +99,6 @@ export interface DeveloperSettings {
      * Override URL for the API server.
      */
     octostarAPIServer?: string;
-    /**
-     * Override URL for the search app.
-     */
-    searchAppUrl?: string;
 }
 /**
  * Interface for desktop settings.
@@ -224,6 +172,23 @@ export type DesktopActionOptions = {
      * Open tab in a new tabset
      */
     newTabset?: boolean;
+    /**
+     * Open the tab in a new tabset docked on one side of this tabset, e.g. a view beside the tab it follows.
+     * Falls back to the default placement when the tabset no longer exists.
+     */
+    dockBeside?: {
+        tabsetId: string;
+        side: 'left' | 'right';
+    };
+    /**
+     * When `tabId` matches an existing tab, swap the tab's
+     * `component`/`config`/`name` in place instead of just focusing it.
+     * No delete + re-add, so the tab node stays alive at its current
+     * position and flexlayout re-runs the factory with the new entity —
+     * flicker-free content swap inside a single persistent tab.
+     * Ignored when the tab doesn't exist (falls through to normal open).
+     */
+    replaceContent?: boolean;
     /**
      * Wait for the tab to open
      */
@@ -232,6 +197,38 @@ export type DesktopActionOptions = {
      * Custom name of the tab.
      */
     tabName?: string;
+    /**
+     * When the open is requested from a global surface with NO active workspace (Home,
+     * Workspaces, …), host the record in the workspace it belongs to — opening that
+     * workspace — instead of the last-active / personal workspace. Set by
+     * entity deep links (`#entity/...`) so a pasted link lands the record in its
+     * own workspace. Ignored when a workspace is already active (the active workspace hosts
+     * it) or when the record carries no concrete workspace (draft / personal).
+     */
+    hostInOwnWorkspace?: boolean;
+};
+/**
+ * Options for {@link Desktop.openNewAIChat}.
+ * @beta
+ */
+export type OpenNewAIChatOptions = {
+    /**
+     * How the prompt seeds the new chat:
+     * - `'send'` (default): the prompt is auto-sent as the chat's first message
+     *   on first mount.
+     * - `'draft'`: the prompt only prefills the chat input, leaving the user to
+     *   review and hit send.
+     */
+    mode?: 'send' | 'draft';
+    /**
+     * Where the new chat opens:
+     * - `'tab'` (default): as a workbench tab, via the AI Chat app.
+     * - `'sidebar'`: in the host's AI panel (making it visible and
+     *   switching it to AI Chats). Requires the v3 app to be present — a host
+     *   without an AI panel ignores it. The chat is seeded identically either
+     *   way (same one-shot `os_item_content` prompt/context fields).
+     */
+    target?: 'tab' | 'sidebar';
 };
 /**
  * Context for desktop actions.
@@ -303,6 +300,10 @@ export type DesktopActionMenuItem = {
      * Key for the menu item.
      */
     key: string;
+    /**
+     * Test id for the rendered menu item. Defaults to `menuitem-<key>`.
+     */
+    testId?: string;
     /**
      * Icon for the menu item.
      */
@@ -335,6 +336,12 @@ export type DesktopActionMenuItem = {
      * Filter for accepting the menu item.
      */
     accepts: DesktopActionFilter;
+    /**
+     * Render the item greyed-out and non-clickable. Use for an action that is
+     * deliberately shown-but-inert in some state (so the user learns it exists and
+     * why it's unavailable) rather than hidden.
+     */
+    disabled?: boolean;
     /**
      * Function to invoke the action.
      */
@@ -356,6 +363,40 @@ export type DesktopActionMenuItem = {
      */
     aiDescription?: string;
 };
+/**
+ * Serializable descriptor of a host-registered context-menu action — the
+ * subset of {@link DesktopActionMenuItem} that survives a structured-clone
+ * round-trip across the event-emitter bridge. Returned by
+ * {@link Desktop.getRegisteredActions} so micro-frontends can render their
+ * own group submenus ("Open with…", "Add to…", …) without taking a
+ * dependency on the host's registry.
+ *
+ * The `invoke` callback lives only in the host — call
+ * {@link Desktop.invokeRegisteredAction} with `key` to fire it.
+ * @beta
+ */
+export type RegisteredActionInfo = {
+    /** Stable identifier of the underlying registered action. Pass back
+     * to {@link Desktop.invokeRegisteredAction} to invoke. */
+    key: string;
+    /** Display label as registered. Always coerced to a string here
+     * (React-node labels are not serialisable across the bridge). */
+    label: string;
+    /** Icon hint — either a font-icon name or the full {@link IconProps}. */
+    icon?: Icon;
+    /** Group the action was registered under. Callers narrow by passing a
+     * specific group list to {@link Desktop.getRegisteredActions}. */
+    group: ContextMenuGroup;
+    /** Lower order = first in the rendered list. */
+    order?: number;
+    /** Builtin opener key when the action declares one (mirrors the host's
+     * `DesktopActionOptions.with` matching). Optional. */
+    with?: string;
+    /** App-service identifier when the action was registered by an app. */
+    service?: string;
+    /** AI description from the app manifest, when present. */
+    aiDescription?: string;
+};
 /**
  * Type for notifications.
  * @beta
@@ -459,6 +500,26 @@ export type OsProgress = {
      * Persist until complete for the progress item.
      */
     persistUntilComplete?: boolean;
+    /**
+     * Milliseconds after which a finished row clears. 0 removes it outright
+     * (its outcome is narrated elsewhere). Unset falls back to the
+     * persistUntilComplete behavior.
+     */
+    clearAfterMs?: number;
+    /**
+     * Why a job stopped before finishing, where `status` alone cannot tell: an
+     * upload batch reports `exception` whether it was cancelled, failed, or
+     * stopped by its failure breaker.
+     */
+    outcome?: 'cancelled' | 'failed' | 'stopped';
+    /**
+     * How many of a batch's items failed so far, where the label only says it in prose.
+     */
+    failedCount?: number;
+    /**
+     * How many of a batch's items have finished so far, where the label only says it in prose.
+     */
+    doneCount?: number;
 };
 /**
  * Affirmative option for the confirmation modal.
@@ -535,6 +596,11 @@ export type CreateEntityFormProps = {
      * Concept related to the form.
      */
     concept?: string;
+    /**
+     * Root concept for the concept selector tree. When set, the concept selector
+     * only shows this concept and its subtypes. Defaults to 'os_workspace_item'.
+     */
+    conceptTreeRoot?: string;
 };
 /**
  * Properties for creating relations dialog.
@@ -683,20 +749,6 @@ export type WithProgressBarOptions = {
      */
     persistUntilComplete?: boolean;
 };
-/**
- * Context for desktop styler.
- * @beta
- */
-export type DesktopStylerContext = {
-    /**
-     * Graph specification.
-     */
-    graph: GraphSpec;
-    /**
-     * Selected graph specification.
-     */
-    selected?: GraphSpec;
-};
 /**
  * Options for exporting items.
  * @beta
@@ -725,85 +777,37 @@ export type ImportFoldersOptions = {
      */
     include_content?: boolean;
 };
+export type SetsSortBy = {
+    field: string;
+    direction: 'asc' | 'desc';
+};
 export type SetsOptions = {
-    /**
-     * Workspace items for the context.
-     */
     workspace_items?: WorkspaceItem[];
-    /**
-     * Limit for the context.
-     */
     limit?: number;
-    /**
-     * Offset for the context.
-     */
     offset?: number;
+    datasource?: 'timbr' | 'opensearch';
     /**
-     * Datasource for the context.
-     */
-    datasource?: string;
-    /**
-     * Recursive for the context.
-     */
-    recursive?: boolean;
-    /**
-     * Include count for the context.
+     * Controls recursion depth for hierarchical expansion.
+     * true = flatten mode (bulk query, all descendants at once).
+     * false = direct children only.
+     * number(N) = incremental expansion up to N levels deep.
      */
+    recursive?: boolean | number;
     include_count?: boolean;
-    /**
-     * Include root for the context.
-     */
     include_root?: boolean;
-    /**
-     * Include all fields for the context.
-     */
     include_all_fields?: boolean;
-    /**
-     * OS exact concept filter for the context.
-     */
-    os_exact_concept_filter?: string[];
-    /**
-     * When limit1 and limit2 are provided,
-     * the user will be prompted to choose the number of records to add
-     * if the count is greater than limit1.
-     */
+    include_types?: string[];
+    exclude_types?: string[];
+    expand_types?: string[];
+    no_expand_types?: string[];
+    /** UI-only prompt threshold. */
     limit1?: number;
-    /**
-     * When limit1 and limit2 are provided,
-     * the user will be prompted to choose the number of records to add
-     * if the count is greater than limit1.
-     */
+    /** UI-only prompt threshold. */
     limit2?: number;
-};
-/**
- * Options for pasting context.
- * @beta
- */
-export type PasteContextOptions = {
-    /**
-     * First limit for the context.
-     */
-    limit1?: number;
-    /**
-     * Second limit for the context.
-     */
-    limit2?: number;
-    /**
-     * Record for the context.
-     */
-    record?: Entity;
-    /**
-     * Records for the context.
-     */
-    records?: Entity[];
-    /**
-     * Query for the context.
-     */
-    query?: ConceptFilter;
-    /**
-     * Whether to return a SavedSet entity when a folder is dropped.
-     */
-    preferSavedSet?: boolean;
+    workspace_sidebar_set?: boolean;
+    expand_abstract_sets_recursively?: boolean;
+    deduplicate?: boolean;
+    sort_by?: SetsSortBy[];
 };
 /**
  * Parameters for drag start.
@@ -851,22 +855,34 @@ export type DragEndParams = {
  */
 export type FetchEntityOptions = {};
 /**
- * Options for pasting folders.
+ * Metadata fields extracted from a fragment entity.
  * @beta
  */
-export type FolderPasteOptions = {
-    /**
-     * Whether to include folders in the paste.
-     */
-    folders?: boolean;
-    /**
-     * Whether to include files in the paste.
-     */
-    files?: boolean;
-    /**
-     * Whether to paste recursively.
-     */
-    recursive?: boolean;
+export type FragmentInfo = {
+    fragment_page_number?: number;
+    /** Seconds for audio/video collections, a page for `document_*`, a row for `table_*`; the pipeline writes numbers, older indexes strings. */
+    fragment_start?: string | number;
+    fragment_end?: string | number;
+    fragment_index?: number;
+    fragment_count?: number;
+    fragment_collection_type?: string;
+    /** `[x1, y1, x2, y2]` in the parent image's pixels, as an array of numeric strings or comma-joined. */
+    fragment_image_bbox?: string | string[];
+    fragment_x_offset?: number;
+    fragment_y_offset?: number;
+    fragment_z_offset?: number;
+    fragment_keyframe_number?: number;
+    fragment_path_expression?: string;
+    /** Content type of the original file the fragment chain starts from, not of the direct parent. */
+    parent_os_item_content_type?: string;
+};
+/**
+ * Result of resolving a fragment entity to its source entity.
+ * @beta
+ */
+export type FragmentResolution = {
+    entity: Entity;
+    fragment: FragmentInfo | undefined;
 };
 /**
  * Options for file tree.
@@ -894,6 +910,34 @@ export type FileTreeOptions = {
      */
     structure?: boolean;
 };
+/**
+ * Filtered listing of `os_wsfs_object` rows via ontology (not from hydrated workspace.items).
+ * Supply at least one of `contentTypes`, `nameLikeLower`, `labelLikeLower` or `itemTypes`; with
+ * none it returns `[]`.
+ */
+export type QueryFilesystemItemsParams = {
+    workspaceIds: string[];
+    /** OR: os_item_content_type equals one of these */
+    contentTypes?: string[];
+    /** OR: lower(os_item_name) LIKE pattern (SQL LIKE, e.g. '%.odoc') */
+    nameLikeLower?: string[];
+    /** OR: lower(entity_label) LIKE pattern, for the name a row displays when it has a label */
+    labelLikeLower?: string[];
+    /** AND: os_item_type is one of these (`['os_file']` leaves folders out); enough on its own.
+     * Applied before `limit`, so excluded rows don't use up the cap. */
+    itemTypes?: string[];
+    /**
+     * Cap the rows returned, most-recently-updated first (the listing is always
+     * `ORDER BY os_last_updated_at DESC`).
+     *
+     * Unbounded by default because the pickers want the whole set. Pass it for any
+     * high-cardinality listing — the query selects every concept field and the
+     * workspace list is a fan-out, so an uncapped Files or Records section would
+     * pull every matching row of every workspace into memory. A caller that caps
+     * is showing a subset and should say so in its UI.
+     */
+    limit?: number;
+};
 /**
  * Represents information about the current user.
  * @beta
@@ -915,6 +959,7 @@ export type Whoami = {
      * Username of the user.
      */
     username: string;
+    roles?: string[];
     /**
      * Roles of the user.
      */
@@ -968,9 +1013,14 @@ export type WorkspaceConfig = Partial<{
      */
     color: string;
     /**
-     * ID of the workspace.
+     * ID of the workspace. The server accepts only the caller's own personal
+     * workspace id; omit it and the server mints the id.
      */
     entity_id?: string;
+    /**
+     * Ontology concept to create. Defaults to 'os_workspace'.
+     */
+    entity_type?: string;
     /**
      * Whether to create the workspace quietly, without opening it.
      */
@@ -996,8 +1046,38 @@ export type GetSystemSettingResponse<T extends string | boolean = string | boole
     security: boolean;
     type: string;
     value: T;
+    /**
+     * Set when `value` is the caller's default because the setting could not be
+     * fetched. `DesktopAPI.getSystemSetting` swallows the error, so callers that
+     * must tell "unset" from "unreadable" check this instead.
+     */
+    unavailable?: boolean;
 };
+/**
+ * Result from a geocoding query.
+ */
+export interface GeocodingResult {
+    latitude: number;
+    longitude: number;
+    address: string;
+    name: string;
+    country: string;
+    city: string;
+    type: string;
+}
 export declare const ORIGINAL_OS_PARENT_FOLDER = "#original_os_parent_folder";
+/**
+ * Which per-source bucket of a workspace's records to act on.
+ *
+ * `source_name` is the exact import origin; `null` targets the records that
+ * carry none (the "(No source)" bucket). Absent is not a value here — an
+ * unscoped bulk delete is a different call.
+ */
+export interface RecordsSourceScope {
+    source_name: string | null;
+    /** Narrow to one concept hierarchy inside the bucket, e.g. `Person`. */
+    concept?: string;
+}
 /**
  * Interface for desktop actions.
  * @beta
@@ -1048,9 +1128,9 @@ export interface Desktop extends DesktopSettings, WorkspaceChangeEmitter {
     listAllWorkspaces: (permissions?: WorkspacePermissionValue) => Promise<WorkspaceItem[]>;
     /**
      * This might not be enough, add a listener to {@link WorkspaceChangeEmitter.onOpenWorkspacesChanged} to keep getting updated.
-     * In react components, prefer useDesktopWorkspaces hook.
+     * In react components, prefer the `useOpenWorkspaces` hook for ids and `getEntity` for per-workspace data.
      */
-    getOpenWorkspaces: () => Promise<Workspace[]>;
+    getOpenWorkspaces: () => Promise<WorkspaceItem[]>;
     /**
      * Gets the OntologyAPI.
      * @returns a promise that resolves to the current ontology
@@ -1068,22 +1148,12 @@ export interface Desktop extends DesktopSettings, WorkspaceChangeEmitter {
      * @returns A promise that resolves to the attachment of type T.
      */
     getAttachment: <T extends AttachmentType>(entity: Entity, options?: GetAttachmentOptions<T>) => Promise<T>;
-    /**
-     * @beta
-     * Gets options for stylers.
-     */
-    getStylerOptions: () => Promise<StylerOption[]>;
-    /**
-     * @beta
-     * Gets a styler by name and context.
-     */
-    getStyler: (name: string, context: DesktopStylerContext) => Promise<Styler>;
     /**
      * Gets a workspace by identifier.
      */
     getWorkspace: (ws: WorkspaceIdentifier, options?: {
         shouldRetry?: boolean;
-    }) => Promise<Workspace | undefined>;
+    }) => Promise<WorkspaceItem | undefined>;
     /**
      * Gets items in a workspace by name.
      */
@@ -1137,15 +1207,36 @@ export interface Desktop extends DesktopSettings, WorkspaceChangeEmitter {
     /**
      * Gets templates by layout or filter
      */
-    getTemplates: (layout?: string | ((template: SavedTemplate) => boolean)) => Promise<SavedTemplate[]>;
+    getTemplates: (layout?: string | ((template: SavedTemplate) => boolean)) => Promise<RenderableTemplate[]>;
     /**
      * Gets a template by name or entity or filter with an optional default template.
      */
-    getTemplate: (name: string | Entity | ((template: SavedTemplate) => boolean), defaultTemplate?: string) => Promise<SavedTemplate>;
+    getTemplate: (name: string | Entity | ((template: SavedTemplate) => boolean), defaultTemplate?: string) => Promise<RenderableTemplate>;
     /**
      * Gets the named app if it is on the desktop and in a running state.
+     *
+     * MIGRATION (app authors): the app's iframe URL is no longer on
+     * `os_item_content.app_url` — that field is gone. The resolved URL is now
+     * exposed on the runtime-only `#appUrl` field of the returned item (see
+     * {@link RuntimeAppUrlWorkspaceItem}). It is hydrated from the K8s apps API
+     * and is NOT persisted, so don't read it off a stored/restored item.
+     */
+    getApp: (name: string) => Promise<RuntimeAppUrlWorkspaceItem | undefined>;
+    /**
+     * Resolve app folders by name within the given workspaces. Match is on
+     * `os_item_name`, case-insensitive. Use this instead of hardcoding app
+     * `entity_id`s on a home page or launcher — those ids are regenerated per
+     * environment, whereas the app name is stable across them.
+     *
+     * Returns one {@link App} per requested name that exists, in the order the
+     * names were given (unknown names are skipped). Each App carries its `folder`
+     * (open it via `desktop.open(app.folder)`) and, when found, its
+     * `manifest_entity` for loading the app's icon/description.
+     *
+     * @param names - App folder names to look up.
+     * @param workspace_ids - Workspaces to search; defaults to the currently open workspaces.
      */
-    getApp: (name: string) => Promise<WorkspaceItem | undefined>;
+    getApps: (names: string[], workspace_ids?: string[]) => Promise<App[]>;
     /**
      * Gets the context of an app by its octostar channel id.
      * @param octostarChannelId the id assigned to the app by the octostar platform
@@ -1153,12 +1244,10 @@ export interface Desktop extends DesktopSettings, WorkspaceChangeEmitter {
      */
     getAppContext: (octostarChannelId: string) => Promise<Record<string, any>>;
     /**
-     * Query workspace items by content type directly from the database.
-     * This ensures all items are retrieved, not just those loaded in memory.
+     * Workspace items matching `os_item_content_type`.
+     * Hydrated-in-memory types use Redux; others are loaded via an ontology query on the filesystem concept.
      *
-     * @param os_item_content_type - The content type to filter by
-     * @param workspace_ids - Optional list of workspace IDs to filter by. If not provided, searches across all open workspaces
-     * @returns Promise resolving to array of workspace items matching the content type
+     * @param workspace_ids - Optional workspace filter; if omitted, uses currently open workspaces for ontology fallback.
      */
     getItemsByContentType: (os_item_content_type: string, workspace_ids?: string[]) => Promise<WorkspaceItem[]>;
     /**
@@ -1199,6 +1288,11 @@ export interface Desktop extends DesktopSettings, WorkspaceChangeEmitter {
      * Fetches an entity from the index, or from the ontology if not found in the index.
      */
     fetchEntity: (entity: EntityBase, options?: FetchEntityOptions) => Promise<Entity>;
+    /**
+     * Resolves a fragment to the root file its `source_entity_uid` names.
+     * Returns null if the source cannot be found.
+     */
+    fetchFragmentSource: (fragment: Entity) => Promise<(Entity & Partial<WorkspaceItem>) | null>;
     /**
      * Extracts entities from some text which may be json or a list of urls.
      */
@@ -1207,14 +1301,87 @@ export interface Desktop extends DesktopSettings, WorkspaceChangeEmitter {
      * Gets a file tree for a workspace or folder with optional file tree options.
      */
     getFilesTree: (workspace_or_folder: WorkspaceItem, options?: FileTreeOptions) => Promise<WorkspaceItem[]>;
+    /**
+     * Query workspace filesystem entities by content type / name patterns (ontology SQL).
+     */
+    queryFilesystemItemsInWorkspaces: (params: QueryFilesystemItemsParams) => Promise<WorkspaceItem[]>;
     /**
      * Show the search modal and return the selected results.
      */
     getSearchResults: (params: undefined | string | SearchProps, enableSelection?: boolean) => Promise<Entity[] | undefined>;
+    /**
+     * Show the search modal in query-return mode.
+     * The user refines the search and clicks "Return current search (N) results".
+     * Resolves with the underlying Elasticsearch query and total result count.
+     */
+    getSearchQuery: (params: undefined | string | SearchProps) => Promise<SearchQueryResult | undefined>;
     /**
      * Opens records with default action or as specified in the optional desktop action options.
      */
     open: (records: Entity | Entity[], options?: DesktopActionOptions) => Promise<void>;
+    /**
+     * Opens a fresh AI Chat seeded with a prompt and, optionally, context
+     * entities — the supported way to launch AI Chat from another application.
+     *
+     * Encapsulates building the chat workspace item (content type
+     * `application/vnd.octostar.chat+json`) in the active workspace and opening
+     * it with the AI Chat app, so callers don't hand-roll that flow. Every call
+     * mints a fresh chat, so the prompt always seeds; seeding is one-shot per
+     * chat, so a browser refresh won't re-send it.
+     *
+     * By default the prompt is auto-sent as the chat's first message (no skill
+     * armed). Pass `{ mode: 'draft' }` to only prefill the chat input and let
+     * the user hit send. Omitting `initialPrompt` (or passing an empty string)
+     * opens the chat unseeded and does not auto-send — useful to just start a
+     * chat over some context entities.
+     *
+     * By default the chat opens as a workbench tab. Pass `{ target: 'sidebar' }`
+     * to open it in the host's AI panel instead (making the panel
+     * visible and switching it to AI Chats); this requires the v3 app.
+     *
+     * @example
+     * ```ts
+     * await desktop.openNewAIChat('Summarize this document', [document]);
+     * await desktop.openNewAIChat('Draft to review', [entity], { mode: 'draft' });
+     * await desktop.openNewAIChat(undefined, [entity]); // unseeded chat over context
+     * await desktop.openNewAIChat('About this record', [entity], { mode: 'draft', target: 'sidebar' });
+     * ```
+     *
+     * @param initialPrompt - The prompt to seed the new chat with; omit to open unseeded.
+     * @param contextEntities - Entities to seed the chat's context.
+     * @param options - Seeding behavior; see {@link OpenNewAIChatOptions}.
+     */
+    openNewAIChat: (initialPrompt?: string, contextEntities?: Entity[], options?: OpenNewAIChatOptions) => Promise<void>;
+    /**
+     * Enumerates the host-registered context-menu actions whose group is in
+     * `groups` AND which accept the given record(s) — i.e. the same set the
+     * host would put under those group sub-menus of the right-click context
+     * menu, returned as plain data so a micro-frontend can render its own
+     * menu instead of triggering the host popup. Pass a single record or
+     * an array; for arrays the host applies the same `accepts({ items })`
+     * filter the context-menu builder uses.
+     *
+     * Typical groupings:
+     *   - `['open', 'edit']` — "Open with…" submenu (openers / editors).
+     *   - `['addto']`         — "Add to…" submenu (link chart, map, set, …).
+     *   - `['transform']`     — "Transform" submenu (slower; consider lazy).
+     *
+     * The returned items are not executable directly — invoke them with
+     * {@link invokeRegisteredAction} using the `key`. Keys are stable
+     * across registrations of the same action.
+     */
+    getRegisteredActions: (items: WorkspaceItem | WorkspaceItem[], groups: ContextMenuGroup[]) => Promise<RegisteredActionInfo[]>;
+    /**
+     * Invokes a previously-enumerated action (from
+     * {@link getRegisteredActions}) by its `key`, with the records the user
+     * wants to act on. The host resolves the registered action and runs its
+     * `invoke` callback with the same context shape the right-click flow
+     * would have built.
+     *
+     * Rejects when no registered action matches the key OR when the
+     * action's `accepts(...)` filter refuses the given items.
+     */
+    invokeRegisteredAction: (key: string, items: WorkspaceItem | WorkspaceItem[], options?: DesktopActionOptions) => Promise<void>;
     /**
      * Deletes an item or items recursively.
      */
@@ -1227,6 +1394,12 @@ export interface Desktop extends DesktopSettings, WorkspaceChangeEmitter {
      * Deletes local concept records in a workspace by base concept.
      */
     delete_local_concept_records: (workspace_id: string, base_concept: string) => Promise<void>;
+    /**
+     * Deletes the records of ONE import source in a workspace (the per-source
+     * buckets the Content Browser shows under Records). Rejects with a 404 on an
+     * API that predates the endpoint, rather than deleting anything wider.
+     */
+    delete_workspace_records_by_source: (workspace_id: string, scope: RecordsSourceScope) => Promise<void>;
     /**
      * Searches the index using the query string
      * @param query OpenSearch qeuery string.
@@ -1245,7 +1418,7 @@ export interface Desktop extends DesktopSettings, WorkspaceChangeEmitter {
     /**
      * Renames a tab by its id.
      */
-    renameTab: (tabId: string, newName: string) => Promise<void>;
+    renameTab: (props: RenameTabProps) => Promise<void>;
     /**
      * Closes a tab with given properties.
      */
@@ -1274,10 +1447,17 @@ export interface Desktop extends DesktopSettings, WorkspaceChangeEmitter {
      * Gets a system setting.
      */
     getSystemSetting: <T extends string | boolean>(key: string, defaultValue: T, show_protected?: boolean) => Promise<GetSystemSettingResponse<T>>;
+    /**
+     * Forward geocodes a query string into geographic coordinates.
+     * @param query - Free-text location query (address, place name, etc.)
+     * @param limit - Maximum number of results to return (default: 5)
+     * @returns Array of geocoding results
+     */
+    geocode: (query: string, limit?: number) => Promise<GeocodingResult[]>;
     /**
      * Wraps a promise with a progress bar.
      */
-    withProgressBar: <T>(promise: Promise<T>, options?: WithProgressBarOptions) => Promise<T>;
+    withProgressBar: <T>(promise: Promise<T>, options?: WithProgressBarOptions) => Promise<T | undefined>;
     /**
      * Shows a confirmation modal.
      */
@@ -1286,6 +1466,13 @@ export interface Desktop extends DesktopSettings, WorkspaceChangeEmitter {
      * Shows a file upload dialog.
      */
     showFileUpload: (folder: WorkspaceItem) => Promise<WorkspaceItem[]>;
+    /**
+     * Shows the "Add to Files" dialog scoped to a workspace: the user picks a
+     * target folder via a tree selector (defaulting to the workspace root),
+     * then uploads files into it. Fire-and-forget — the dialog handles the
+     * upload itself.
+     */
+    showUploadToFolder: (workspace: WorkspaceItem) => Promise<void>;
     /**
      * Shows a form for creating an entity.
      */
@@ -1298,10 +1485,6 @@ export interface Desktop extends DesktopSettings, WorkspaceChangeEmitter {
      * Shows a modal for saving as.
      */
     showSaveAsModal: (props: SaveAsModalProps) => Promise<WorkspaceItem | undefined>;
-    /**
-     * @deprecated This method is deprecated and will be removed in a future version. Use {@link createSetsFromItems} or {@link expandSet} instead.
-     */
-    getPasteContext: (options: PasteContextOptions) => Promise<Entity[]>;
     /**
      * Expands a set with optional options.
      */
@@ -1326,14 +1509,6 @@ export interface Desktop extends DesktopSettings, WorkspaceChangeEmitter {
      * Adds a comment to an entity.
      */
     addComment: (about: Entity, comment: AddCommentParams) => Promise<Entity>;
-    /**
-     * Adds a watch intent to an entity.
-     */
-    addWatchIntent: (entity: Entity, watcher: Watcher) => Promise<Entity>;
-    /**
-     * Removes a watch intent by workspace and intent ID.
-     */
-    removeWatchIntent: (os_workspace: string, intent_id: string) => Promise<void>;
     /**
      * Gets workspace permissions by IDs.
      */
@@ -1347,9 +1522,9 @@ export interface Desktop extends DesktopSettings, WorkspaceChangeEmitter {
      */
     deployApp: (app: WorkspaceItem | App, initialSecrets?: Record<string, string>) => Promise<WorkspaceItem>;
     /**
-     * Undeploys an application.
+     * Undeploys an application. `appId` is the k8s app id; without it the id is looked up from the apps API.
      */
-    undeployApp: (app: WorkspaceItem | App) => Promise<WorkspaceItem>;
+    undeployApp: (app: WorkspaceItem | App, appId?: string) => Promise<WorkspaceItem>;
     /**
      * Gets information about the current user.
      */
@@ -1371,13 +1546,25 @@ export interface Desktop extends DesktopSettings, WorkspaceChangeEmitter {
      */
     removeFromFocusList: (entities: Entity[], type?: 'single' | 'group', tabName?: string) => Promise<FocusListItem[]>;
     /**
-     * Gets the image URL for an entity.
+     * Gets the image URL for an entity: its own bytes when it is an image file,
+     * else its attached image, else its concept icon. With `maxWidth`, image
+     * bytes come as a downscaled server thumbnail (snapped to 512 or 2048 px)
+     * instead of the original.
      */
-    getImageUrl: (entity: EntityBase) => Promise<string>;
+    getImageUrl: (entity: EntityBase, options?: {
+        maxWidth?: number;
+    }) => Promise<string>;
     /**
      * Gets images for an entity.
      */
     getImages: (entity: Entity) => Promise<Entity[]>;
+    /**
+     * Gets batch images for an entity.
+     */
+    getBatchImages: (entities: Entity[]) => Promise<{
+        entity: Entity;
+        images: Entity[];
+    }[]>;
     /**
      * Gets icon code for an entity, concept, or string.
      */
@@ -1401,10 +1588,6 @@ export interface Desktop extends DesktopSettings, WorkspaceChangeEmitter {
      * Get config files
      */
     getConfigFiles: (name: string) => Promise<WorkspaceItem[]>;
-    /**
-     * "Cache" for workspaces, avoiding to return a modal error, if this workspace was fetched before
-     */
-    workspaceStore: Record<string, Workspace>;
     getWhitelabelingInfo: () => Promise<{
         OCTOSTAR_MAIN_LOGO: string;
         OCTOSTAR_FAVICON: string;
@@ -1427,11 +1610,6 @@ export type AppRegistry = {
      * Registers an action.
      */
     registerAction: (action: DesktopActionMenuItem) => void;
-    /**
-     * @beta
-     * Registers a styler.
-     */
-    registerStyler: (styler: StylerConfig) => () => void;
 };
 /**
  * Properties for workspace item title.
@@ -1445,9 +1623,7 @@ export type WorkspaceItemTitleProps = DesktopActionContext & {
     /**
      * Menu options with extra action items.
      */
-    menuOptions?: ContextMenuOptions & {
-        extraActionItems?: DesktopActionMenuItem[];
-    };
+    menuOptions?: ContextMenuOptions;
     /**
      * Whether the item is expanded.
      */