@moldable-ai/ui 0.2.20 → 0.2.22

package/dist/lib/frame-lifecycle.js

@@ -1,4 +1,29 @@
 let frameLifecycleInstalled = false;
+let advertisedHostServices;
+function normalizeHostServices(value) {
+    if (typeof value !== 'object' ||
+        value === null ||
+        !('version' in value) ||
+        value.version !== 1 ||
+        !('services' in value) ||
+        typeof value.services !== 'object' ||
+        value.services === null ||
+        Array.isArray(value.services)) {
+        return undefined;
+    }
+    const services = {};
+    for (const [name, details] of Object.entries(value.services)) {
+        if (typeof details === 'object' &&
+            details !== null &&
+            !Array.isArray(details)) {
+            services[name] = { ...details };
+        }
+    }
+    return { version: 1, services };
+}
+export function getMoldableHostServices() {
+    return advertisedHostServices;
+}
 export function applyMoldableChatSafePadding(safePadding) {
     if (typeof document === 'undefined')
         return false;
@@ -25,9 +50,11 @@ function applyMoldableChatState(message) {
             : 'docked';
     document.documentElement.dataset.moldableChat = presentation;
 }
-function applyMoldableHostContext(message) {
+export function applyMoldableHostContext(message) {
     const root = document.documentElement;
+    advertisedHostServices = normalizeHostServices(message.hostServices);
     root.dataset.moldableDisplayMode = message.displayMode;
+    root.dataset.moldableWindowTitlebar = message.titlebar ?? 'host';
     if (message.platform)
         root.dataset.moldablePlatform = message.platform;
     if (message.windowId)
@@ -55,6 +82,7 @@ function installHostStateLifecycle() {
     const root = document.documentElement;
     root.dataset.moldableDisplayMode =
         window.parent === window ? 'window' : 'embedded';
+    root.dataset.moldableWindowTitlebar = 'host';
     // Standalone windows do not reserve space for the desktop chat dock.
     if (window.parent === window) {
         applyMoldableChatSafePadding(0);
@@ -75,8 +103,7 @@ function installHostStateLifecycle() {
         else if (event.data.type === 'moldable:host-context') {
             const message = event.data;
             if (message.version === 1 &&
-                (message.displayMode === 'embedded' ||
-                    message.displayMode === 'window')) {
+                (message.displayMode === 'embedded' || message.displayMode === 'window')) {
                 applyMoldableHostContext(message);
             }
         }

package/dist/lib/host-date-time-picker.d.ts

@@ -0,0 +1,36 @@
+import { type HostServiceRequestOptions } from './host-services';
+export type HostDateTimePickerMode = 'date' | 'time' | 'datetime';
+export interface HostDateTimePickerAnchorRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface HostDateTimePickerOptions extends HostServiceRequestOptions {
+    value?: string;
+    min?: string;
+    max?: string;
+    anchor?: Element | HostDateTimePickerAnchorRect;
+}
+export type HostDateTimePickerResult = {
+    status: 'completed';
+    method: 'native';
+    value: string;
+} | {
+    status: 'cancelled';
+    method: 'native';
+} | {
+    status: 'fallback';
+    method: 'portable';
+    mode: HostDateTimePickerMode;
+    value?: string;
+    min?: string;
+    max?: string;
+};
+export interface HostDateTimePicker {
+    available: boolean;
+    pick: (mode: HostDateTimePickerMode, options?: HostDateTimePickerOptions) => Promise<HostDateTimePickerResult>;
+}
+export declare function pickDateTimeWithHost(mode: HostDateTimePickerMode, options?: HostDateTimePickerOptions): Promise<HostDateTimePickerResult>;
+export declare function useHostDateTimePicker(): HostDateTimePicker;
+//# sourceMappingURL=host-date-time-picker.d.ts.map

package/dist/lib/host-date-time-picker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-date-time-picker.d.ts","sourceRoot":"","sources":["../../src/lib/host-date-time-picker.ts"],"names":[],"mappings":"AACA,OAAO,EAEL,KAAK,yBAAyB,EAG/B,MAAM,iBAAiB,CAAA;AAMxB,MAAM,MAAM,sBAAsB,GAAG,MAAM,GAAG,MAAM,GAAG,UAAU,CAAA;AAEjE,MAAM,WAAW,4BAA4B;IAC3C,CAAC,EAAE,MAAM,CAAA;IACT,CAAC,EAAE,MAAM,CAAA;IACT,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;CACf;AAED,MAAM,WAAW,yBAA0B,SAAQ,yBAAyB;IAC1E,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,MAAM,CAAC,EAAE,OAAO,GAAG,4BAA4B,CAAA;CAChD;AAED,MAAM,MAAM,wBAAwB,GAChC;IACE,MAAM,EAAE,WAAW,CAAA;IACnB,MAAM,EAAE,QAAQ,CAAA;IAChB,KAAK,EAAE,MAAM,CAAA;CACd,GACD;IACE,MAAM,EAAE,WAAW,CAAA;IACnB,MAAM,EAAE,QAAQ,CAAA;CACjB,GACD;IACE,MAAM,EAAE,UAAU,CAAA;IAClB,MAAM,EAAE,UAAU,CAAA;IAClB,IAAI,EAAE,sBAAsB,CAAA;IAC5B,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,GAAG,CAAC,EAAE,MAAM,CAAA;CACb,CAAA;AAEL,MAAM,WAAW,kBAAkB;IACjC,SAAS,EAAE,OAAO,CAAA;IAClB,IAAI,EAAE,CACJ,IAAI,EAAE,sBAAsB,EAC5B,OAAO,CAAC,EAAE,yBAAyB,KAChC,OAAO,CAAC,wBAAwB,CAAC,CAAA;CACvC;AAgJD,wBAAsB,oBAAoB,CACxC,IAAI,EAAE,sBAAsB,EAC5B,OAAO,GAAE,yBAA8B,GACtC,OAAO,CAAC,wBAAwB,CAAC,CAgDnC;AAED,wBAAgB,qBAAqB,IAAI,kBAAkB,CAoB1D"}

package/dist/lib/host-date-time-picker.js

@@ -0,0 +1,162 @@
+import { useCallback, useEffect, useState } from 'react';
+import { HostServiceRequestError, isHostServiceAvailable, requestHostService, } from './host-services';
+const HOST_CONTEXT_CHANGE_EVENT = 'moldable:host-context-change';
+const DATE_TIME_PICKER_SERVICE_NAME = 'dateTimePicker';
+const MAX_ISO_VALUE_LENGTH = 128;
+function validateMode(mode) {
+    if (mode !== 'date' && mode !== 'time' && mode !== 'datetime') {
+        throw new TypeError('Date/time picker mode must be date, time, or datetime.');
+    }
+}
+function isoValueNumber(mode, value) {
+    if (typeof value !== 'string' ||
+        value.length === 0 ||
+        value.length > MAX_ISO_VALUE_LENGTH) {
+        return null;
+    }
+    const [datePart, timePart, extraPart] = mode === 'time' ? [undefined, value, undefined] : value.split('T');
+    if (extraPart !== undefined)
+        return null;
+    let date;
+    if (mode !== 'time') {
+        const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(datePart ?? '');
+        if (!match)
+            return null;
+        const year = Number(match[1]);
+        const month = Number(match[2]);
+        const day = Number(match[3]);
+        date = new Date(0);
+        date.setHours(0, 0, 0, 0);
+        date.setFullYear(year, month - 1, day);
+        if (date.getFullYear() !== year ||
+            date.getMonth() !== month - 1 ||
+            date.getDate() !== day) {
+            return null;
+        }
+        if (mode === 'date')
+            return date.getTime();
+    }
+    const match = /^(\d{2}):(\d{2})(?::(\d{2})(?:\.(\d{1,9}))?)?$/.exec(timePart ?? '');
+    if (!match)
+        return null;
+    const hour = Number(match[1]);
+    const minute = Number(match[2]);
+    const second = Number(match[3] ?? 0);
+    const millisecond = Math.floor(Number(`0.${match[4] ?? 0}`) * 1000);
+    if (hour > 23 || minute > 59 || second > 59)
+        return null;
+    if (mode === 'time') {
+        return ((hour * 60 + minute) * 60 + second) * 1000 + millisecond;
+    }
+    if (!date)
+        return null;
+    date.setHours(hour, minute, second, millisecond);
+    return date.getHours() === hour &&
+        date.getMinutes() === minute &&
+        date.getSeconds() === second
+        ? date.getTime()
+        : null;
+}
+function validateIsoValue(mode, name, value) {
+    if (value !== undefined && isoValueNumber(mode, value) === null) {
+        throw new TypeError(`${name} must be a valid ISO ${mode} value.`);
+    }
+}
+function validateRange(mode, options) {
+    validateIsoValue(mode, 'value', options.value);
+    validateIsoValue(mode, 'min', options.min);
+    validateIsoValue(mode, 'max', options.max);
+    if (options.min !== undefined &&
+        options.max !== undefined &&
+        isoValueNumber(mode, options.min) >
+            isoValueNumber(mode, options.max)) {
+        throw new TypeError('Date/time picker min must not be after max.');
+    }
+    if (options.value !== undefined) {
+        const value = isoValueNumber(mode, options.value);
+        if ((options.min !== undefined &&
+            value < isoValueNumber(mode, options.min)) ||
+            (options.max !== undefined &&
+                value > isoValueNumber(mode, options.max))) {
+            throw new TypeError('Date/time picker value must be inside the min/max range.');
+        }
+    }
+}
+function anchorRect(anchor) {
+    if (!anchor)
+        return undefined;
+    const rect = typeof Element !== 'undefined' && anchor instanceof Element
+        ? anchor.getBoundingClientRect()
+        : anchor;
+    if (!Number.isFinite(rect.x) ||
+        !Number.isFinite(rect.y) ||
+        !Number.isFinite(rect.width) ||
+        !Number.isFinite(rect.height) ||
+        rect.width < 0 ||
+        rect.height < 0) {
+        throw new TypeError('Date/time picker anchors require a finite, non-negative rect.');
+    }
+    return {
+        x: rect.x,
+        y: rect.y,
+        width: rect.width,
+        height: rect.height,
+    };
+}
+function abortError() {
+    return new DOMException('The date/time picker request was aborted.', 'AbortError');
+}
+export async function pickDateTimeWithHost(mode, options = {}) {
+    validateMode(mode);
+    validateRange(mode, options);
+    if (options.signal?.aborted)
+        throw abortError();
+    if (!isHostServiceAvailable(DATE_TIME_PICKER_SERVICE_NAME)) {
+        return {
+            status: 'fallback',
+            method: 'portable',
+            mode,
+            ...(options.value === undefined ? {} : { value: options.value }),
+            ...(options.min === undefined ? {} : { min: options.min }),
+            ...(options.max === undefined ? {} : { max: options.max }),
+        };
+    }
+    try {
+        const result = await requestHostService(DATE_TIME_PICKER_SERVICE_NAME, {
+            mode,
+            ...(options.value === undefined ? {} : { value: options.value }),
+            ...(options.min === undefined ? {} : { min: options.min }),
+            ...(options.max === undefined ? {} : { max: options.max }),
+            ...(options.anchor ? { anchor: anchorRect(options.anchor) } : {}),
+        }, {
+            signal: options.signal,
+            timeoutMs: options.timeoutMs,
+        });
+        if (typeof result !== 'string' || isoValueNumber(mode, result) === null) {
+            throw new Error('The native date/time picker returned an invalid result.');
+        }
+        return {
+            status: 'completed',
+            method: 'native',
+            value: result,
+        };
+    }
+    catch (error) {
+        if (error instanceof HostServiceRequestError &&
+            error.status === 'cancelled') {
+            return { status: 'cancelled', method: 'native' };
+        }
+        throw error;
+    }
+}
+export function useHostDateTimePicker() {
+    const [available, setAvailable] = useState(() => isHostServiceAvailable(DATE_TIME_PICKER_SERVICE_NAME));
+    useEffect(() => {
+        const update = () => setAvailable(isHostServiceAvailable(DATE_TIME_PICKER_SERVICE_NAME));
+        update();
+        window.addEventListener(HOST_CONTEXT_CHANGE_EVENT, update);
+        return () => window.removeEventListener(HOST_CONTEXT_CHANGE_EVENT, update);
+    }, []);
+    const pick = useCallback((mode, options) => pickDateTimeWithHost(mode, options), []);
+    return { available, pick };
+}

package/dist/lib/host-file-dialog.d.ts

@@ -0,0 +1,66 @@
+import { type HostServiceRequestOptions } from './host-services';
+export type HostFileDialogDefaultLocation = 'documents' | 'downloads' | 'desktop' | 'home' | 'appData';
+export interface HostFileDialogFilter {
+    name: string;
+    extensions: string[];
+}
+export interface HostOpenFileDialogProperties {
+    /**
+     * Allow more than one selection. Defaults to false.
+     */
+    multiple?: boolean;
+    /**
+     * Choose directories instead of files. Defaults to false.
+     */
+    directories?: boolean;
+    /**
+     * Show the New Folder control. Defaults to false.
+     */
+    createDirectories?: boolean;
+    /**
+     * Initially reveal hidden entries. Defaults to false.
+     */
+    showHidden?: boolean;
+}
+interface HostFileDialogCommonOptions extends HostServiceRequestOptions {
+    title?: string;
+    buttonLabel?: string;
+    filters?: HostFileDialogFilter[];
+    defaultLocation?: HostFileDialogDefaultLocation;
+}
+export interface HostOpenFileDialogOptions extends HostFileDialogCommonOptions {
+    properties?: HostOpenFileDialogProperties;
+}
+export interface HostSaveFileDialogOptions extends HostFileDialogCommonOptions {
+    defaultName?: string;
+    /**
+     * Show the New Folder control. Defaults to false.
+     */
+    createDirectories?: boolean;
+}
+export type HostOpenFileDialogResult = {
+    status: 'completed';
+    paths: string[];
+} | {
+    status: 'cancelled';
+} | {
+    status: 'fallback';
+};
+export type HostSaveFileDialogResult = {
+    status: 'completed';
+    path: string;
+} | {
+    status: 'cancelled';
+} | {
+    status: 'fallback';
+};
+export interface HostFileDialog {
+    available: boolean;
+    open: (options?: HostOpenFileDialogOptions) => Promise<HostOpenFileDialogResult>;
+    save: (options?: HostSaveFileDialogOptions) => Promise<HostSaveFileDialogResult>;
+}
+export declare function openFileDialogWithHost(options?: HostOpenFileDialogOptions): Promise<HostOpenFileDialogResult>;
+export declare function saveFileDialogWithHost(options?: HostSaveFileDialogOptions): Promise<HostSaveFileDialogResult>;
+export declare function useHostFileDialog(): HostFileDialog;
+export {};
+//# sourceMappingURL=host-file-dialog.d.ts.map

package/dist/lib/host-file-dialog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-file-dialog.d.ts","sourceRoot":"","sources":["../../src/lib/host-file-dialog.ts"],"names":[],"mappings":"AACA,OAAO,EAEL,KAAK,yBAAyB,EAG/B,MAAM,iBAAiB,CAAA;AAWxB,MAAM,MAAM,6BAA6B,GACrC,WAAW,GACX,WAAW,GACX,SAAS,GACT,MAAM,GACN,SAAS,CAAA;AAEb,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAA;IACZ,UAAU,EAAE,MAAM,EAAE,CAAA;CACrB;AAED,MAAM,WAAW,4BAA4B;IAC3C;;OAEG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB;;OAEG;IACH,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB;;OAEG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAA;IAC3B;;OAEG;IACH,UAAU,CAAC,EAAE,OAAO,CAAA;CACrB;AAED,UAAU,2BAA4B,SAAQ,yBAAyB;IACrE,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,OAAO,CAAC,EAAE,oBAAoB,EAAE,CAAA;IAChC,eAAe,CAAC,EAAE,6BAA6B,CAAA;CAChD;AAED,MAAM,WAAW,yBAA0B,SAAQ,2BAA2B;IAC5E,UAAU,CAAC,EAAE,4BAA4B,CAAA;CAC1C;AAED,MAAM,WAAW,yBAA0B,SAAQ,2BAA2B;IAC5E,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;OAEG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAA;CAC5B;AAED,MAAM,MAAM,wBAAwB,GAChC;IAAE,MAAM,EAAE,WAAW,CAAC;IAAC,KAAK,EAAE,MAAM,EAAE,CAAA;CAAE,GACxC;IAAE,MAAM,EAAE,WAAW,CAAA;CAAE,GACvB;IAAE,MAAM,EAAE,UAAU,CAAA;CAAE,CAAA;AAE1B,MAAM,MAAM,wBAAwB,GAChC;IAAE,MAAM,EAAE,WAAW,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACrC;IAAE,MAAM,EAAE,WAAW,CAAA;CAAE,GACvB;IAAE,MAAM,EAAE,UAAU,CAAA;CAAE,CAAA;AAE1B,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,OAAO,CAAA;IAClB,IAAI,EAAE,CACJ,OAAO,CAAC,EAAE,yBAAyB,KAChC,OAAO,CAAC,wBAAwB,CAAC,CAAA;IACtC,IAAI,EAAE,CACJ,OAAO,CAAC,EAAE,yBAAyB,KAChC,OAAO,CAAC,wBAAwB,CAAC,CAAA;CACvC;AAmLD,wBAAsB,sBAAsB,CAC1C,OAAO,GAAE,yBAA8B,GACtC,OAAO,CAAC,wBAAwB,CAAC,CA4CnC;AAED,wBAAsB,sBAAsB,CAC1C,OAAO,GAAE,yBAA8B,GACtC,OAAO,CAAC,wBAAwB,CAAC,CA0CnC;AAED,wBAAgB,iBAAiB,IAAI,cAAc,CAuBlD"}

package/dist/lib/host-file-dialog.js

@@ -0,0 +1,221 @@
+import { useCallback, useEffect, useState } from 'react';
+import { HostServiceRequestError, isHostServiceAvailable, requestHostService, } from './host-services';
+const HOST_CONTEXT_CHANGE_EVENT = 'moldable:host-context-change';
+const FILE_DIALOG_SERVICE_NAME = 'fileDialog';
+const MAX_TEXT_LENGTH = 512;
+const MAX_DEFAULT_NAME_LENGTH = 255;
+const MAX_FILTERS = 32;
+const MAX_FILTER_NAME_LENGTH = 128;
+const MAX_EXTENSIONS_PER_FILTER = 64;
+const MAX_EXTENSION_LENGTH = 64;
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function assertOnlyKeys(value, allowed, label) {
+    if (!Object.keys(value).every((key) => allowed.has(key))) {
+        throw new TypeError(`${label} contain an unknown property.`);
+    }
+}
+function validateOptionalText(label, value) {
+    if (value !== undefined &&
+        (typeof value !== 'string' ||
+            value.trim().length === 0 ||
+            value.length > MAX_TEXT_LENGTH ||
+            value.includes('\0'))) {
+        throw new TypeError(`${label} must contain 1–${MAX_TEXT_LENGTH} characters.`);
+    }
+}
+function validateDefaultLocation(value) {
+    if (value !== undefined &&
+        value !== 'documents' &&
+        value !== 'downloads' &&
+        value !== 'desktop' &&
+        value !== 'home' &&
+        value !== 'appData') {
+        throw new TypeError('File-dialog defaultLocation is not supported.');
+    }
+}
+function validateFilters(filters) {
+    if (filters === undefined)
+        return;
+    if (!Array.isArray(filters) || filters.length > MAX_FILTERS) {
+        throw new TypeError(`File dialogs support at most ${MAX_FILTERS} filters.`);
+    }
+    for (const filter of filters) {
+        if (!isRecord(filter)) {
+            throw new TypeError('File-dialog filters must be objects.');
+        }
+        assertOnlyKeys(filter, new Set(['name', 'extensions']), 'File-dialog filters');
+        if (typeof filter.name !== 'string' ||
+            filter.name.trim().length === 0 ||
+            filter.name.length > MAX_FILTER_NAME_LENGTH ||
+            filter.name.includes('\0') ||
+            !Array.isArray(filter.extensions) ||
+            filter.extensions.length === 0 ||
+            filter.extensions.length > MAX_EXTENSIONS_PER_FILTER) {
+            throw new TypeError('Each file-dialog filter requires a bounded name and extension list.');
+        }
+        if (!filter.extensions.every((extension) => typeof extension === 'string' &&
+            extension.length > 0 &&
+            extension.length <= MAX_EXTENSION_LENGTH &&
+            !extension.startsWith('.') &&
+            !/[\s/\\:*\0]/u.test(extension))) {
+            throw new TypeError('File-dialog extensions must omit dots, wildcards, whitespace, and path separators.');
+        }
+    }
+}
+const COMMON_KEYS = [
+    'title',
+    'buttonLabel',
+    'filters',
+    'defaultLocation',
+    'signal',
+    'timeoutMs',
+];
+const OPEN_KEYS = new Set([...COMMON_KEYS, 'properties']);
+const SAVE_KEYS = new Set([...COMMON_KEYS, 'defaultName', 'createDirectories']);
+const OPEN_PROPERTY_KEYS = new Set([
+    'multiple',
+    'directories',
+    'createDirectories',
+    'showHidden',
+]);
+function validateCommonOptions(options, keys) {
+    assertOnlyKeys(options, keys, 'File-dialog options');
+    validateOptionalText('File-dialog title', options.title);
+    validateOptionalText('File-dialog buttonLabel', options.buttonLabel);
+    validateDefaultLocation(options.defaultLocation);
+    validateFilters(options.filters);
+}
+function validateOpenOptions(options) {
+    if (!isRecord(options)) {
+        throw new TypeError('Open file-dialog options must be an object.');
+    }
+    validateCommonOptions(options, OPEN_KEYS);
+    if (options.properties === undefined)
+        return;
+    if (!isRecord(options.properties)) {
+        throw new TypeError('Open file-dialog properties must be an object.');
+    }
+    assertOnlyKeys(options.properties, OPEN_PROPERTY_KEYS, 'Open file-dialog properties');
+    if (!Object.values(options.properties).every((value) => typeof value === 'boolean')) {
+        throw new TypeError('Open file-dialog properties must be booleans.');
+    }
+}
+function validateSaveOptions(options) {
+    if (!isRecord(options)) {
+        throw new TypeError('Save file-dialog options must be an object.');
+    }
+    validateCommonOptions(options, SAVE_KEYS);
+    if (options.defaultName !== undefined &&
+        (typeof options.defaultName !== 'string' ||
+            options.defaultName.trim().length === 0 ||
+            options.defaultName.length > MAX_DEFAULT_NAME_LENGTH ||
+            /[/\\\0]/u.test(options.defaultName))) {
+        throw new TypeError(`Save-dialog defaultName must be a filename of 1–${MAX_DEFAULT_NAME_LENGTH} characters.`);
+    }
+    if (options.createDirectories !== undefined &&
+        typeof options.createDirectories !== 'boolean') {
+        throw new TypeError('Save-dialog createDirectories must be a boolean.');
+    }
+}
+function requestOptions(options) {
+    return {
+        signal: options.signal,
+        timeoutMs: options.timeoutMs,
+    };
+}
+function abortError() {
+    return new DOMException('The file-dialog request was aborted.', 'AbortError');
+}
+function isPath(value) {
+    return typeof value === 'string' && value.length > 0;
+}
+export async function openFileDialogWithHost(options = {}) {
+    validateOpenOptions(options);
+    if (options.signal?.aborted)
+        throw abortError();
+    if (!isHostServiceAvailable(FILE_DIALOG_SERVICE_NAME)) {
+        return { status: 'fallback' };
+    }
+    try {
+        const result = await requestHostService(FILE_DIALOG_SERVICE_NAME, {
+            mode: 'open',
+            ...(options.title === undefined ? {} : { title: options.title }),
+            ...(options.buttonLabel === undefined
+                ? {}
+                : { buttonLabel: options.buttonLabel }),
+            ...(options.filters === undefined ? {} : { filters: options.filters }),
+            ...(options.defaultLocation === undefined
+                ? {}
+                : { defaultLocation: options.defaultLocation }),
+            ...(options.properties === undefined
+                ? {}
+                : { properties: options.properties }),
+        }, requestOptions(options));
+        if (!isRecord(result) ||
+            !Array.isArray(result.paths) ||
+            result.paths.length === 0 ||
+            !result.paths.every(isPath)) {
+            throw new Error('The native open dialog returned an invalid result.');
+        }
+        return { status: 'completed', paths: result.paths };
+    }
+    catch (error) {
+        if (error instanceof HostServiceRequestError &&
+            error.status === 'cancelled') {
+            return { status: 'cancelled' };
+        }
+        throw error;
+    }
+}
+export async function saveFileDialogWithHost(options = {}) {
+    validateSaveOptions(options);
+    if (options.signal?.aborted)
+        throw abortError();
+    if (!isHostServiceAvailable(FILE_DIALOG_SERVICE_NAME)) {
+        return { status: 'fallback' };
+    }
+    try {
+        const result = await requestHostService(FILE_DIALOG_SERVICE_NAME, {
+            mode: 'save',
+            ...(options.title === undefined ? {} : { title: options.title }),
+            ...(options.buttonLabel === undefined
+                ? {}
+                : { buttonLabel: options.buttonLabel }),
+            ...(options.filters === undefined ? {} : { filters: options.filters }),
+            ...(options.defaultLocation === undefined
+                ? {}
+                : { defaultLocation: options.defaultLocation }),
+            ...(options.defaultName === undefined
+                ? {}
+                : { defaultName: options.defaultName }),
+            ...(options.createDirectories === undefined
+                ? {}
+                : { createDirectories: options.createDirectories }),
+        }, requestOptions(options));
+        if (!isRecord(result) || !isPath(result.path)) {
+            throw new Error('The native save dialog returned an invalid result.');
+        }
+        return { status: 'completed', path: result.path };
+    }
+    catch (error) {
+        if (error instanceof HostServiceRequestError &&
+            error.status === 'cancelled') {
+            return { status: 'cancelled' };
+        }
+        throw error;
+    }
+}
+export function useHostFileDialog() {
+    const [available, setAvailable] = useState(() => isHostServiceAvailable(FILE_DIALOG_SERVICE_NAME));
+    useEffect(() => {
+        const update = () => setAvailable(isHostServiceAvailable(FILE_DIALOG_SERVICE_NAME));
+        update();
+        window.addEventListener(HOST_CONTEXT_CHANGE_EVENT, update);
+        return () => window.removeEventListener(HOST_CONTEXT_CHANGE_EVENT, update);
+    }, []);
+    const open = useCallback((options) => openFileDialogWithHost(options), []);
+    const save = useCallback((options) => saveFileDialogWithHost(options), []);
+    return { available, open, save };
+}

package/dist/lib/host-native-menu.d.ts

@@ -0,0 +1,75 @@
+import { type HostServiceRequestOptions } from './host-services';
+export declare const HOST_NATIVE_MENU_MAX_DEPTH = 3;
+export declare const HOST_NATIVE_MENU_MAX_ITEMS = 200;
+export declare const HOST_NATIVE_MENU_MAX_TITLE_LENGTH = 256;
+export declare const HOST_NATIVE_MENU_MAX_SUBLABEL_LENGTH = 512;
+export type NativeMenuItemKind = 'normal' | 'separator' | 'checkbox' | 'radio';
+export interface NativeMenuShortcut {
+    key: string;
+    modifiers?: Array<'cmd' | 'shift' | 'alt' | 'ctrl'>;
+}
+interface NativeMenuItemBase {
+    sublabel?: string;
+    enabled?: boolean;
+    shortcut?: NativeMenuShortcut;
+    /**
+     * Reserved for a future native destructive appearance. It is validated and
+     * carried through the v1 service but intentionally not rendered by AppKit.
+     */
+    destructive?: boolean;
+}
+export type NativeMenuItem = (NativeMenuItemBase & {
+    id: string;
+    kind?: 'normal';
+    title: string;
+    checked?: never;
+    submenu?: NativeMenuItem[];
+}) | (NativeMenuItemBase & {
+    id?: string;
+    kind: 'separator';
+    title?: string;
+    checked?: never;
+    submenu?: never;
+}) | (NativeMenuItemBase & {
+    id: string;
+    kind: 'checkbox';
+    title: string;
+    checked?: boolean | 'mixed';
+    submenu?: never;
+}) | (NativeMenuItemBase & {
+    id: string;
+    kind: 'radio';
+    title: string;
+    checked?: boolean;
+    submenu?: never;
+});
+export interface HostNativeMenuAnchorRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface HostNativeMenuPoint {
+    x: number;
+    y: number;
+}
+export interface HostNativeMenuOptions extends HostServiceRequestOptions {
+    anchor?: Element | HostNativeMenuAnchorRect;
+    position?: HostNativeMenuPoint;
+}
+export type HostNativeMenuResult = {
+    status: 'completed';
+    selectedId: string;
+} | {
+    status: 'cancelled';
+} | {
+    status: 'fallback';
+};
+export interface HostNativeMenu {
+    available: boolean;
+    open: (items: NativeMenuItem[], options: HostNativeMenuOptions) => Promise<HostNativeMenuResult>;
+}
+export declare function openNativeMenuWithHost(items: NativeMenuItem[], options: HostNativeMenuOptions): Promise<HostNativeMenuResult>;
+export declare function useHostNativeMenu(): HostNativeMenu;
+export {};
+//# sourceMappingURL=host-native-menu.d.ts.map

package/dist/lib/host-native-menu.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-native-menu.d.ts","sourceRoot":"","sources":["../../src/lib/host-native-menu.ts"],"names":[],"mappings":"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"}