markedit-api 0.0.0-stage → 0.39.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 MarkEdit.app
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,138 @@
-# Temporary Holding Version
+# MarkEdit-api
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Type definitions for the latest [MarkEdit](https://github.com/MarkEdit-app/MarkEdit) API.
+
+## References
+
+- [MarkEdit Customization Guide](https://github.com/MarkEdit-app/MarkEdit/wiki/Customization)
+- [MarkEdit Extensions](https://markedit-app.github.io/extensions/)
+- [Example: Markdown Table Editor](https://github.com/MarkEdit-app/MarkEdit-mte)
+- [Example: Text Highlight](https://github.com/MarkEdit-app/MarkEdit-highlight)
+- [Example: Vue Language Package](https://github.com/MarkEdit-app/MarkEdit-lang-vue)
+
+## Usage
+
+> The general workflow for creating a MarkEdit script involves leveraging [CodeMirror extensions](https://codemirror.net/docs/extensions/) or [Lezer parsers](https://lezer.codemirror.net/) to modify the app's behavior.
+
+Add `markedit-api` to your (TypeScript) project's devDependencies:
+
+```json
+{
+  "devDependencies": {
+    "markedit-api": "0.39.0"
+  }
+}
+```
+
+Import type declarations with:
+
+```ts
+import { MarkEdit } from 'markedit-api';
+```
+
+Refer to the [index.d.ts](index.d.ts) file for all available interfaces and type definitions.
+
+Also, you can import and use [CodeMirror](https://codemirror.net/) and [Lezer](https://lezer.codemirror.net/) dependencies like this:
+
+```ts
+import { keymap } from '@codemirror/view';
+import { Prec } from '@codemirror/state';
+import { Tag } from '@lezer/highlight';
+import { MarkdownConfig } from '@lezer/markdown';
+```
+
+Build [CodeMirror extension](https://codemirror.net/docs/extensions/) with these dependencies, and add it to MarkEdit with:
+
+```ts
+MarkEdit.addExtension(extension); // Can also add an array of extensions
+```
+
+Build [MarkdownConfig](https://github.com/lezer-parser/markdown?tab=readme-ov-file#user-content-markdownconfig) with these dependencies, and add it to MarkEdit with:
+
+```ts
+MarkEdit.addMarkdownConfig(config);
+```
+
+MarkEdit supports syntax highlighting for code blocks, you can also build your own [Language Package](https://codemirror.net/examples/lang-package/), and add it to MarkEdit with:
+
+```ts
+MarkEdit.addCodeLanguage(language);
+```
+
+> While extensions and configs can theoretically be added at any time, it is recommended that they be added immediately after loading the script.
+
+## Handling User Input
+
+While you can certainly build user interfaces with JavaScript and CSS, leveraging native UI components might be a better option.
+
+To create UI entries for your features, use `addMainMenuItem`, which adds an item to the "Extensions" submenu of the main menu, with keyboard shortcuts support.
+
+To request user input, try using `showContextMenu`, `showAlert`, and `showTextBox`.
+
+## Building
+
+In your build configuration, mark used MarkEdit and CodeMirror dependencies as `external`.
+
+Here is an example of [vite](https://vitejs.dev/) config:
+
+```ts
+import { defineConfig } from 'vite';
+
+export default defineConfig({
+  build: {
+    rollupOptions: {
+      external: [
+        'markedit-api',
+        '@codemirror/view',
+        '@codemirror/state',
+        // ...
+      ],
+    },
+    lib: {
+      entry: 'main.ts',
+      formats: ['cjs'], // CommonJS
+    },
+  },
+});
+```
+
+> Note: If you're using packages that are **not** supported in MarkEdit, such as leveraging [@codemirror/lang-vue](https://github.com/codemirror/lang-vue) to add syntax highlighting for Vue, they should **not** be marked as external.
+
+It is recommended to build as [cjs](https://commonjs.org/), building as [umd](https://github.com/umdjs/umd) should work too. If you build it as an [iife](https://developer.mozilla.org/en-US/docs/Glossary/IIFE), make sure to replace imports as globals like this:
+
+```
+rollupOptions: {
+  external: [
+    'markedit-api',
+    '@codemirror/view',
+    '@codemirror/state',
+  ],
+  output: {
+    globals: {
+      'markedit-api': 'MarkEdit',
+      '@codemirror/view': 'MarkEdit.codemirror.view',
+      '@codemirror/state': 'MarkEdit.codemirror.state',
+    },
+  },
+},
+```
+
+The reason is to ensure that user scripts and MarkEdit use the same modules, rather than being separately bundled from different projects.
+
+The final step is to copy the built script to `~/Library/Containers/app.cyan.markedit/Data/Documents/scripts/`, and restart the app.
+
+Ensure the build system produces a single JavaScript file. If the build generates multiple chunks, you can use [vite-plugin-singlefile](https://github.com/richardtallent/vite-plugin-singlefile) to bundle everything into one file.
+
+> [!TIP]
+> You can also use [MarkEdit-vite](https://github.com/MarkEdit-app/MarkEdit-vite) to simplify the workflow.
+
+## Using JavaScript
+
+You can directly access CodeMirror and MarkEdit interfaces through objects assigned to the `MarkEdit` object. For example:
+
+```js
+const keymap = MarkEdit.codemirror.view.keymap;
+const editorAPI = MarkEdit.editorAPI;
+```
+
+This is useful when you simply want to prototype something quickly.

package/index.cjs

@@ -0,0 +1,2 @@
+const MarkEdit = Object.freeze({ /* stub */ });
+exports.MarkEdit = MarkEdit;

package/index.d.cts

@@ -0,0 +1 @@
+export * from './index.js';

package/index.d.ts

@@ -0,0 +1,982 @@
+/**
+ * https://github.com/MarkEdit-app/MarkEdit-api
+ *
+ * - [MarkEdit Customization Guide](https://github.com/MarkEdit-app/MarkEdit/wiki/Customization)
+ * - [Example: Markdown Table Editor](https://github.com/MarkEdit-app/MarkEdit-mte)
+ * - [Example: Text Highlight](https://github.com/MarkEdit-app/MarkEdit-highlight)
+ * - [Example: Vue Language Package](https://github.com/MarkEdit-app/MarkEdit-lang-vue)
+ */
+
+import type { EditorView } from '@codemirror/view';
+import type { Extension } from '@codemirror/state';
+import type { LanguageDescription, LanguageSupport } from '@codemirror/language';
+import type { MarkdownConfig } from '@lezer/markdown';
+
+import type * as cmView from '@codemirror/view';
+import type * as cmState from '@codemirror/state';
+import type * as cmLanguage from '@codemirror/language';
+import type * as cmLangMarkdown from '@codemirror/lang-markdown';
+import type * as cmCommands from '@codemirror/commands';
+import type * as cmSearch from '@codemirror/search';
+import type * as cmAutocomplete from '@codemirror/autocomplete';
+
+import type * as lezerCommon from '@lezer/common';
+import type * as lezerHighlight from '@lezer/highlight';
+import type * as lezerMarkdown from '@lezer/markdown';
+import type * as lezerLr from '@lezer/lr';
+
+declare global {
+  /**
+   * File path of the current user script, or undefined if not applicable (e.g., in the DevTools console, which is not a user script context).
+   */
+  const __FILE_PATH__: string | undefined;
+}
+
+export const MarkEdit: Readonly<MarkEdit>;
+
+export interface MarkEdit {
+  /**
+   * Configuration of the current editor.
+   */
+  editorConfig: EditorConfig;
+
+  /**
+   * User-defined settings loaded from the [settings.json](https://github.com/MarkEdit-app/MarkEdit/wiki/Customization#advanced-settings) file.
+   *
+   * For example, user-defined scripts can use this to provide additional configurations.
+   */
+  userSettings: JSONObject;
+
+  /**
+   * CodeMirror EditorView instance of the current editor.
+   */
+  editorView: EditorView;
+
+  /**
+   * Convenient text editing interfaces.
+   */
+  editorAPI: TextEditable;
+
+  /**
+   * Keychain-backed secret storage for the current script.
+   */
+  secretStorage: SecretStorage;
+
+  /**
+   * Retrieves a generative language model by name.
+   */
+  languageModel(name: LanguageModelName): LanguageModel;
+
+  /**
+   * Retrieves the system translation service.
+   */
+  translationService: TranslationService;
+
+  /**
+   * CodeMirror modules used by MarkEdit.
+   */
+  codemirror: {
+    /**
+     * The `@codemirror/view` module.
+     */
+    view: typeof cmView;
+
+    /**
+     * The `@codemirror/state` module.
+     */
+    state: typeof cmState;
+
+    /**
+     * The `@codemirror/language` module.
+     */
+    language: typeof cmLanguage;
+
+    /**
+     * The `@codemirror/lang-markdown` module.
+     */
+    langMarkdown: typeof cmLangMarkdown;
+
+    /**
+     * The `@codemirror/commands` module.
+     */
+    commands: typeof cmCommands;
+
+    /**
+     * The `@codemirror/search` module.
+     */
+    search: typeof cmSearch;
+
+    /**
+     * The `@codemirror/autocomplete` module.
+     */
+    autocomplete: typeof cmAutocomplete;
+  };
+
+  /**
+   * Lezer modules used by MarkEdit.
+   */
+  lezer: {
+    /**
+     * The `@lezer/common` module.
+     */
+    common: typeof lezerCommon;
+
+    /**
+     * The `@lezer/highlight` module.
+     */
+    highlight: typeof lezerHighlight;
+
+    /**
+     * The `@lezer/markdown` module.
+     */
+    markdown: typeof lezerMarkdown;
+
+    /**
+     * The `@lezer/lr` module.
+     */
+    lr: typeof lezerLr;
+  };
+
+  /**
+   * Get information about the runtime.
+   */
+  runtimeInfo(): RuntimeInfo;
+
+  /**
+   * Terminate the application. Unsaved changes will prompt for confirmation.
+   */
+  terminateApp(): void;
+
+  /**
+   * Relaunch the application. Unsaved changes will prompt for confirmation.
+   */
+  relaunchApp(): void;
+
+  /**
+   * Play the system beep.
+   */
+  playSystemBeep(): void;
+
+  /**
+   * Get notified when the app is ready.
+   *
+   * For a user script, this is ensured to be called only once during the app lifecycle.
+   * @param listener The callback function to be called when the app is ready.
+   */
+  onAppReady(listener: () => void): void;
+
+  /**
+   * Get notified when the editor is initialized.
+   * @param listener The callback function with the initialized editor instance.
+   */
+  onEditorReady(listener: (editorView: EditorView) => void): void;
+
+  /**
+   * Get notified when the editor configuration changes.
+   * @param listener The callback function with the changed key and new value.
+   */
+  onEditorConfigChange(listener: (key: EditorConfigChange[0], value: EditorConfigChange[1]) => void): void;
+
+  /**
+   * Open a plain text file in MarkEdit, or focus it if already open.
+   * @param path The file path.
+   * @param options Where to open the document.
+   * @returns True on success; false on failure, without external fallback.
+   */
+  openDocument(path: string, options?: { target?: 'automatic' | 'window' | 'tab' }): Promise<boolean>;
+
+  /**
+   * Save the current document to disk.
+   * @returns True if the document was successfully saved.
+   */
+  saveDocument(): Promise<boolean>;
+
+  /**
+   * Close the current document.
+   * @returns True if the document was successfully closed.
+   */
+  closeDocument(): Promise<boolean>;
+
+  /**
+   * Get the paths of recently opened documents, sorted most recent first.
+   * @returns The file-system paths, or an empty array if there are no recent documents.
+   */
+  recentDocumentPaths(): Promise<string[]>;
+
+  /**
+   * Open a file in the file system.
+   * @param path The file path.
+   * @returns True if the file was successfully opened.
+   */
+  openFile(path: string): Promise<boolean>;
+
+  /**
+   * Create a file in the file system.
+   * @param options The options, including path and content.
+   * @returns True if the file was successfully created.
+   */
+  createFile(options: CreateFileOptions): Promise<boolean>;
+
+  /**
+   * Delete a file from the file system.
+   * @param path The file path.
+   * @returns True if the file was successfully deleted.
+   */
+  deleteFile(path: string): Promise<boolean>;
+
+  /**
+   * Move a file in the file system.
+   * @param options The source and destination paths.
+   * @returns True if the file was successfully moved.
+   */
+  moveFile(options: MoveFileOptions): Promise<boolean>;
+
+  /**
+   * Reveal a file in Finder.
+   * @param path The file path. The current file is used as a fallback.
+   * @returns True if the file was successfully revealed.
+   */
+  revealFile(path?: string): Promise<boolean>;
+
+  /**
+   * List all files under a directory.
+   * @param path The directory path.
+   * @returns All file names as a string array, or undefined if failed.
+   */
+  listFiles(path: string): Promise<string[] | undefined>;
+
+  /**
+   * Get the content of a file.
+   * @param path The file path. The current file is used as a fallback.
+   * @returns The file content as a string, or undefined if failed.
+   */
+  getFileContent(path?: string): Promise<string | undefined>;
+
+  /**
+   * Get the binary data and type information of a file.
+   * @param path The file path. The current file is used as a fallback.
+   * @returns The file object, or undefined if failed.
+   */
+  getFileObject(path?: string): Promise<FileObject | undefined>;
+
+  /**
+   * Get the information of a file.
+   * @param path The file path. The current file is used as a fallback.
+   * @returns The file information, or undefined if not found.
+   */
+  getFileInfo(path?: string): Promise<FileInfo | undefined>;
+
+  /**
+   * Get the path of a standard directory.
+   * @param type The directory type.
+   * @returns The directory path.
+   */
+  getDirectoryPath(type: DirectoryType): string;
+
+  /**
+   * Get all available versions of the current document, sorted newest to oldest.
+   * @returns The list of file versions, or an empty array if no versions are available.
+   */
+  getFileVersions(): Promise<FileVersion[]>;
+
+  /**
+   * Get the text content of a specific file version.
+   * @param id The unique identifier of the version.
+   * @returns The text content, or undefined if the version is not found.
+   */
+  getFileVersionContent(id: string): Promise<string | undefined>;
+
+  /**
+   * Restore the document to a specific file version.
+   * @param id The unique identifier of the version.
+   * @returns True if the version was successfully restored.
+   */
+  restoreFileVersion(id: string): Promise<boolean>;
+
+  /**
+   * Delete specific file versions, this works for local versions only.
+   * @param ids The unique identifiers of the versions to delete.
+   * @returns True if the versions were successfully deleted.
+   */
+  deleteLocalFileVersions(ids: string[]): Promise<boolean>;
+
+  /**
+   * Get all items from the native pasteboard.
+   * @returns The items from the native (general) pasteboard.
+   */
+  getPasteboardItems(): Promise<PasteboardItem[]>;
+
+  /**
+   * Get the string from the native pasteboard.
+   * @returns The string from the native (general) pasteboard, if applicable.
+   */
+  getPasteboardString(): Promise<string | undefined>;
+
+  /**
+   * Add an extension to MarkEdit.
+   * @param extension CodeMirror extension.
+   */
+  addExtension(extension: Extension): void;
+
+  /**
+   * Add a Markdown config to MarkEdit.
+   * @param config Markdown config.
+   */
+  addMarkdownConfig(config: MarkdownConfig | MarkdownConfig[]): void;
+
+  /**
+   * Add a language to be highlighted (in code blocks) to MarkEdit.
+   * @param language The language description.
+   */
+  addCodeLanguage(language: LanguageDescription | LanguageDescription[]): void;
+
+  /**
+   * Override the built-in HTML language.
+   * @param provider A function that returns a LanguageSupport instance for HTML.
+   */
+  overrideHTMLLanguage(provider: (config?: { matchClosingTags?: boolean }) => LanguageSupport): void;
+
+  /**
+   * Add a menu item to the status bar.
+   * @param item The menu item to add, which will be placed under the "Extensions" submenu. It can either perform an action or contain a submenu.
+   */
+  addMainMenuItem(item: MenuItem | MenuItem[]): void;
+
+  /**
+   * Present a contextual menu to receive user input.
+   * @param items The items in the menu.
+   * @param location The location to show the menu, with the default value set to the caret position.
+   * @param options The menu's presentation behavior.
+   */
+  showContextMenu(items: MenuItem[], location?: Point, options?: ContextMenuOptions): void;
+
+  /**
+   * Present an alert to receive user input.
+   * @param alert The alert to present.
+   * @returns The index of the chosen button, 0-indexed.
+   */
+  showAlert(alert: Alert): Promise<number>;
+
+  /**
+   * Present a text box to receive user input.
+   * @param textBox The text box to present.
+   * @returns The input string, or undefined if no value is provided.
+   */
+  showTextBox(textBox?: TextBox): Promise<string | undefined>;
+
+  /**
+   * Present an open panel for selecting files or folders without opening them.
+   * @param options The panel information and selection behavior.
+   * @returns A nonempty array of absolute file paths, or undefined if cancelled or failed.
+   */
+  showOpenPanel(options?: OpenPanelOptions): Promise<string[] | undefined>;
+
+  /**
+   * Present a save panel for saving the file.
+   * @param options The panel information, including the data and optionally a default file name.
+   * @returns True if the file was successfully saved.
+   */
+  showSavePanel(options: SavePanelOptions): Promise<boolean>;
+
+  /**
+   * Present the print panel for content of a supported type.
+   * @param options The content to print and optionally a job title.
+   * @returns True if the print operation was accepted.
+   */
+  showPrintPanel(options: PrintPanelOptions): Promise<boolean>;
+
+  /**
+   * Run a [system service](https://support.apple.com/guide/mac-help/mchlp1012/mac) with input.
+   * @param name The name of the system service.
+   * @param input The input to pass to the service.
+   * @returns True if the service performed successfully.
+   */
+  runService(name: string, input?: string): Promise<boolean>;
+}
+
+export interface EditorConfig {
+  theme: string;
+  fontFace: { family: string; weight?: string; style?: string; };
+  fontSize: number;
+  showLineNumbers: boolean;
+  showActiveLineIndicator: boolean;
+  invisiblesBehavior: 'never' | 'selection' | 'trailing' | 'always';
+  readOnlyMode: boolean;
+  typewriterMode: boolean;
+  focusMode: boolean;
+  lineWrapping: boolean;
+  lineHeight: number;
+  suggestWhileTyping: boolean;
+  standardDirectories: { [key: string]: string };
+  runtimeInfo?: RuntimeInfo;
+  defaultLineBreak?: string;
+  tabKeyBehavior?: number;
+  indentUnit?: string;
+  smartQuotesEnabled: boolean;
+}
+
+export type EditorConfigChange = {
+  [Key in keyof EditorConfig]-?: [key: Key, value: EditorConfig[Key]];
+}[keyof EditorConfig];
+
+/**
+ * Information about the runtime.
+ */
+export type RuntimeInfo = {
+  /**
+   * Application version, such as `1.0`.
+   */
+  appVersion: string;
+
+  /**
+   * Application build number, such as `100`.
+   */
+  appBuild: string;
+
+  /**
+   * Operating system version, such as `15.0`.
+   */
+  osVersion: string;
+
+  /**
+   * WebKit version, such as `620.1.16`.
+   */
+  webkitVersion: string;
+};
+
+/**
+ * Abstract editor to provide convenient text editing interfaces.
+ */
+export interface TextEditable {
+  /**
+   * Get text of the document.
+   * @param range The range of the text. If no range is provided, the entire document is returned.
+   */
+  getText(range?: TextRange): string;
+
+  /**
+   * Set text for the document.
+   * @param text The text to set.
+   * @param range The range of the text. If no range is provided, the entire document is overwritten.
+   */
+  setText(text: string, range?: TextRange): void;
+
+  /**
+   * Get text selections.
+   */
+  getSelections(): TextRange[];
+
+  /**
+   * Set text selections.
+   * @param ranges Text ranges to set.
+   */
+  setSelections(ranges: TextRange[]): void;
+
+  /**
+   * Get the line number (0-indexed) of given text position.
+   * @param position The text position.
+   */
+  getLineNumber(position: number): number;
+
+  /**
+   * Get line range of given row (0-indexed).
+   * @param row The line number.
+   */
+  getLineRange(row: number): TextRange;
+
+  /**
+   * Get number of lines.
+   */
+  getLineCount(): number;
+
+  /**
+   * Get line separator.
+   */
+  getLineBreak(): string;
+
+  /**
+   * Get CodeMirror syntax node name of given position.
+   * @param position The text position.
+   */
+  getNodeName(position: number): string;
+
+  /**
+   * Undo a change.
+   */
+  undo(): void;
+
+  /**
+   * Redo a change.
+   */
+  redo(): void;
+}
+
+/**
+ * Secret storage in macOS Keychain, each extension has its own store.
+ *
+ * Reading a secret requires MarkEdit confirmation to provide context to the user.
+ * macOS may separately require authentication for any operation.
+ *
+ * Operations reject if the user denies or cancels access, no script context is available, or storage fails.
+ */
+export interface SecretStorage {
+  /**
+   * Check whether a secret exists without retrieving its value or showing MarkEdit confirmation.
+   * @returns True if the secret exists, or false only if it does not exist.
+   */
+  has(key: string): Promise<boolean>;
+
+  /**
+   * Get a secret after native confirmation showing its key, script identity, and script path.
+   *
+   * Each call requires approval before accessing Keychain.
+   * @returns The secret, or undefined only if it does not exist.
+   */
+  get(key: string): Promise<string | undefined>;
+
+  /**
+   * Store or replace a secret.
+   */
+  set(key: string, value: string): Promise<void>;
+
+  /**
+   * Delete a secret.
+   * @returns True if deleted, or false only if the secret did not exist.
+   */
+  delete(key: string): Promise<boolean>;
+}
+
+/**
+ * Unique identifier of a generative language model.
+ *
+ * `Private-Cloud-Compute` works in macOS 27.0 and later.
+ */
+export type LanguageModelName = 'Apple-Foundation-Models' | 'Private-Cloud-Compute';
+
+/**
+ * Response of a language model content generation.
+ *
+ * For non-streaming scenarios, `done` is always true.
+ */
+export type LanguageModelResponse = {
+  content?: string;
+  error?: string;
+  done: boolean;
+};
+
+/**
+ * Response notifier for language model streaming responses.
+ */
+export type LanguageModelStream = (response: LanguageModelResponse) => void;
+
+/**
+ * Interfaces for a generative language model.
+ */
+export interface LanguageModel {
+  /**
+   * Check the language model availability.
+   */
+  availability(): Promise<LanguageModelAvailability>;
+
+  /**
+   * Create a new language model session.
+   */
+  createSession(options?: { instructions?: string }): Promise<LanguageModelSession>;
+}
+
+/**
+ * Generative language model session.
+ */
+export interface LanguageModelSession {
+  /**
+   * Indicates a response is being generated.
+   */
+  isResponding(): Promise<boolean>;
+
+  /**
+   * Produces a response to a prompt.
+   */
+  respondTo(prompt: string, options?: LanguageModelGenerationOptions): Promise<LanguageModelResponse>;
+
+  /**
+   * Produces a response stream to a prompt.
+   *
+   * Each update delivers the latest snapshot of the content, not partial chunks.
+   */
+  streamResponseTo(
+    prompt: string,
+    options: LanguageModelGenerationOptions | LanguageModelStream,
+    stream?: LanguageModelStream,
+  ): void;
+}
+
+export type LanguageModelAvailability = {
+  isAvailable: boolean;
+  unavailableReason?: string;
+};
+
+export type LanguageModelGenerationOptions = {
+  /**
+   * In macOS 27.0 and later, provide attachments to the language model.
+   */
+  attachments?: FileObject[];
+  sampling?: LanguageModelSampling;
+  temperature?: number;
+  maximumResponseTokens?: number;
+};
+
+export type LanguageModelSampling =
+  | { mode: 'greedy' }
+  | { mode: 'top-k' | 'top-p'; value: number; seed?: number };
+
+/**
+ * The system translation service.
+ */
+export interface TranslationService {
+  /**
+   * Translate the text with language pair.
+   *
+   * Use BCP-47 language tags, such as `en-US`, `zh-CN`.
+   */
+  translate(text: string, languages?: { from?: string; to?: string }): Promise<TranslationResponse>;
+}
+
+export type TranslationResponse =
+  | { succeeded: true; text: string }
+  | { succeeded: false; error: string };
+
+/**
+ * Represents a file object with data and type information.
+ */
+export type FileObject = {
+  /**
+   * Base64 representation of the file.
+   */
+  data: string;
+
+  /**
+   * Uniform Type Identifier (UTI) of the file.
+   */
+  typeIdentifier?: string;
+
+  /**
+   * MIME type of the file.
+   */
+  mimeType?: string;
+
+  /**
+   * File extension of the file.
+   */
+  filenameExtension?: string;
+}
+
+/**
+ * Information of a file in the file system.
+ */
+export type FileInfo = {
+  filePath: string;
+  fileSize: number;
+  creationDate: Date;
+  modificationDate: Date;
+  parentPath: string;
+  isDirectory: boolean;
+};
+
+/**
+ * Represents a native pasteboard item.
+ */
+export type PasteboardItem = {
+  /**
+   * Type name, such as `public.utf8-plain-text`.
+   */
+  type: string;
+
+  /**
+   * Base64 representation of the pasteboard data.
+   */
+  data: string;
+
+  /**
+   * String representation of the pasteboard data, if applicable.
+   */
+  string?: string;
+};
+
+/**
+ * Represents a portion of text.
+ */
+export type TextRange = {
+  from: number;
+  to: number;
+};
+
+/**
+ * Represents a menu item in native menus.
+ */
+export type MenuItem = {
+  title?: string;
+  action?: () => void;
+  state?: () => MenuItemState;
+
+  /**
+   * Icon for the item.
+   *
+   * This can be either a base64 string or a SF Symbol name.
+   */
+  icon?: string;
+
+  /**
+   * Whether an item is a separator used to logically group other items.
+   */
+  separator?: boolean;
+
+  /**
+   * Key equivalent of the action.
+   */
+  key?: string;
+
+  /**
+   * Key modifiers of the action. Valid values are `Shift`, `Control`, `Command`, and `Option`.
+   *
+   * The order does not matter but they are case sensitive.
+   *
+   * When `key` is uppercase, `Shift` is automatically enabled.
+   */
+  modifiers?: ('Shift' | 'Control' | 'Command' | 'Option')[];
+
+  /**
+   * Child items to build a submenu.
+   */
+  children?: MenuItem[];
+};
+
+/**
+ * Represents the state of a menu item.
+ */
+export type MenuItemState = {
+  /**
+   * Whether enabled; defaults to true.
+   */
+  isEnabled?: boolean;
+  /**
+   * Whether selected; defaults to false.
+   */
+  isSelected?: boolean;
+};
+
+/**
+ * Represents a location on the screen.
+ */
+export type Point = {
+  x: number;
+  y: number;
+};
+
+/**
+ * Represents options to present a contextual menu.
+ */
+export type ContextMenuOptions = {
+  /**
+   * Index of the item to highlight when the menu opens (zero-based).
+   *
+   * If omitted, invalid, or pointing to a separator or disabled item,
+   * the menu opens without an initial highlight.
+   */
+  highlightedIndex?: number;
+};
+
+/**
+ * Represents a native alert to present.
+ *
+ * If it's a string, it will be used as the title.
+ */
+export type Alert = {
+  /**
+   * The title that is displayed prominently in the alert.
+   */
+  title?: string;
+
+  /**
+   * The informative message for more details.
+   */
+  message?: string;
+
+  /**
+   * The button titles.
+   */
+  buttons?: string[];
+} | string;
+
+/**
+ * Represents a text box to receive input.
+ *
+ * If it's a string, it will be used as the title.
+ */
+export type TextBox = {
+  title?: string;
+  placeholder?: string;
+  defaultValue?: string;
+} | string;
+
+/**
+ * Represents options to create a file.
+ */
+export type CreateFileOptions = {
+  /**
+   * File path.
+   */
+  path: string;
+
+  /**
+   * If set to true, a directory will be created instead.
+   */
+  isDirectory?: boolean;
+
+  /**
+   * If set to true, existing files with the same path will be overwritten.
+   */
+  overwrites?: boolean;
+
+  /**
+   * String representation of the file, if applicable.
+   */
+  string?: string;
+
+  /**
+   * Base64 representation of the file, if applicable.
+   */
+  data?: string;
+};
+
+/**
+ * Represents options to move a file.
+ */
+export type MoveFileOptions = {
+  /**
+   * Source file path.
+   */
+  source: string;
+
+  /**
+   * Destination file path.
+   */
+  destination: string;
+
+  /**
+   * If set to true, existing files at the destination will be overwritten.
+   */
+  overwrites?: boolean;
+};
+
+/**
+ * Represents standard directory types.
+ */
+export type DirectoryType = 'home' | 'documents' | 'library' | 'caches' | 'temporary' | 'sharedContainer';
+
+/**
+ * Represents options to show the open panel.
+ */
+export type OpenPanelOptions = {
+  /**
+   * Panel title. Uses the system default if omitted.
+   */
+  title?: string;
+
+  /**
+   * Instructions displayed in the panel.
+   */
+  message?: string;
+
+  /**
+   * Confirmation button label. Uses the system default if omitted.
+   */
+  prompt?: string;
+
+  /**
+   * Types of items that can be selected. Defaults to 'files'.
+   */
+  selectionType?: 'files' | 'directories' | 'both';
+
+  /**
+   * Allow selecting multiple items. Defaults to false.
+   */
+  allowsMultipleSelection?: boolean;
+};
+
+/**
+ * Represents options to show the save panel.
+ */
+export type SavePanelOptions = {
+  /**
+   * String representation of the file, if applicable.
+   */
+  string?: string;
+
+  /**
+   * Base64 representation of the file, if applicable.
+   */
+  data?: string;
+
+  /**
+   * Default file name.
+   */
+  fileName?: string;
+};
+
+/**
+ * Represents options to show the print panel for content of a supported type.
+ */
+export type PrintPanelOptions = {
+  /**
+   * Content type to print. Currently only PDF is supported.
+   */
+  type: 'pdf';
+
+  /**
+   * Base64 representation of the content to print. For 'pdf', this is PDF data.
+   */
+  data: string;
+
+  /**
+   * Job title shown in the print panel and print queue.
+   */
+  title?: string;
+};
+
+/**
+ * Represents a historical version of the current document.
+ */
+export type FileVersion = {
+  /**
+   * Unique identifier for this version, valid for the current session.
+   */
+  id: string;
+
+  /**
+   * Modification date of this version.
+   */
+  modificationDate: Date;
+
+  /**
+   * Whether this version is stored locally or in iCloud.
+   */
+  isLocal: boolean;
+};
+
+/**
+ * Typed JSON value.
+ */
+type JSONValue =
+  | string
+  | number
+  | boolean
+  | null
+  | JSONObject
+  | JSONValue[];
+
+/**
+ * Typed JSON Object.
+ */
+type JSONObject = {
+  [key: string]: JSONValue;
+};

package/index.js

@@ -0,0 +1,2 @@
+const MarkEdit = Object.freeze({ /* stub */ });
+export { MarkEdit };

package/package.json

@@ -1,6 +1,49 @@
 {
   "name": "markedit-api",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.39.0",
+  "description": "Type definitions for the latest MarkEdit API.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MarkEdit-app/MarkEdit-api.git"
+  },
+  "files": [
+    "index.js",
+    "index.cjs",
+    "index.d.ts",
+    "index.d.cts"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "type": "module",
+  "main": "./index.cjs",
+  "module": "./index.js",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./index.d.ts",
+        "default": "./index.js"
+      },
+      "require": {
+        "types": "./index.d.cts",
+        "default": "./index.cjs"
+      }
+    }
+  },
+  "license": "MIT",
+  "peerDependencies": {
+    "@codemirror/autocomplete": "^6.0.0",
+    "@codemirror/commands": "^6.0.0",
+    "@codemirror/lang-markdown": "^6.0.0",
+    "@codemirror/language": "^6.0.0",
+    "@codemirror/search": "^6.0.0",
+    "@codemirror/state": "^6.0.0",
+    "@codemirror/view": "^6.0.0",
+    "@lezer/common": "^1.0.0",
+    "@lezer/highlight": "^1.0.0",
+    "@lezer/lr": "^1.0.0",
+    "@lezer/markdown": "^1.0.0"
+  }
+}