kirby-types 1.3.0 → 1.4.0

package/README.md

@@ -297,18 +297,25 @@ type Parsed = ParseKirbyQuery<'page.children.filterBy("status", "published")'>;
 For ProseMirror-based Writer extensions (requires optional ProseMirror peer dependencies):
 
 ```ts
-import type { WriterMarkContext } from "kirby-types";
+import type { WriterMarkExtension } from "kirby-types";
 
-// In a Writer mark extension
-class Bold {
-  commands({ type, utils }: WriterMarkContext) {
+// Define a custom mark extension
+const highlight: WriterMarkExtension = {
+  button: {
+    icon: "highlight",
+    label: "Highlight",
+  },
+  commands({ type, utils }) {
     return () => utils.toggleMark(type);
-  }
-
-  inputRules({ type, utils }: WriterMarkContext) {
+  },
+  inputRules({ type, utils }) {
     return [utils.markInputRule(/\*\*([^*]+)\*\*$/, type)];
-  }
-}
+  },
+  schema: {
+    parseDOM: [{ tag: "mark" }],
+    toDOM: () => ["mark", 0],
+  },
+};
 ```
 
 ## API Reference
@@ -329,10 +336,15 @@ class Bold {
 
 | Type                                                | Description                        |
 | --------------------------------------------------- | ---------------------------------- |
-| [`WriterUtils`](./src/panel/writer.d.ts)            | ProseMirror commands and utilities |
+| [`WriterEditor`](./src/panel/writer.d.ts)           | Main editor instance               |
+| [`WriterExtensions`](./src/panel/writer.d.ts)       | Extensions manager                 |
+| [`WriterExtension`](./src/panel/writer.d.ts)        | Generic extension interface        |
+| [`WriterMarkExtension`](./src/panel/writer.d.ts)    | Mark extension interface           |
+| [`WriterNodeExtension`](./src/panel/writer.d.ts)    | Node extension interface           |
 | [`WriterMarkContext`](./src/panel/writer.d.ts)      | Context for mark extensions        |
 | [`WriterNodeContext`](./src/panel/writer.d.ts)      | Context for node extensions        |
 | [`WriterExtensionContext`](./src/panel/writer.d.ts) | Context for generic extensions     |
+| [`WriterUtils`](./src/panel/writer.d.ts)            | ProseMirror commands and utilities |
 
 ### API
 

package/index.d.ts

@@ -10,26 +10,7 @@ export type {
 } from "./src/blocks";
 
 // Blueprint types
-export type {
-  KirbyAnyFieldProps,
-  KirbyBlocksFieldProps,
-  KirbyDateFieldProps,
-  KirbyFieldProps,
-  KirbyFieldsetGroup,
-  KirbyFieldsetProps,
-  KirbyFieldsetTab,
-  KirbyFilesFieldProps,
-  KirbyLayoutFieldProps,
-  KirbyNumberFieldProps,
-  KirbyObjectFieldProps,
-  KirbyOption,
-  KirbyOptionsFieldProps,
-  KirbyStructureColumn,
-  KirbyStructureFieldProps,
-  KirbyTextFieldProps,
-  KirbyToggleFieldProps,
-  KirbyWriterFieldProps,
-} from "./src/blueprint";
+export type * from "./src/blueprint";
 
 // KQL types
 export type {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "kirby-types",
   "type": "module",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "packageManager": "pnpm@10.27.0",
   "description": "TypeScript types for Kirby Panel plugins and headless CMS usage",
   "author": "Johann Schopplich <hello@johannschopplich.com>",

package/src/blueprint.d.ts

@@ -110,12 +110,12 @@ export interface KirbyFieldProps {
 // =============================================================================
 
 /**
- * Props for text and textarea fields.
+ * Props for text fields.
  *
  * @see https://getkirby.com/docs/reference/panel/fields/text
  */
 export interface KirbyTextFieldProps extends KirbyFieldProps {
-  type: "text" | "textarea" | "slug" | "url" | "email" | "tel";
+  type: "text" | "slug" | "url" | "email" | "tel";
   /** Value converter: `lower`, `upper`, `ucfirst`, `slug` */
   converter?: "lower" | "upper" | "ucfirst" | "slug";
   /** Whether to show character counter */
@@ -133,6 +133,34 @@ export interface KirbyTextFieldProps extends KirbyFieldProps {
   value?: string;
 }
 
+/**
+ * Props for textarea fields.
+ *
+ * @see https://getkirby.com/docs/reference/panel/fields/textarea
+ */
+export interface KirbyTextareaFieldProps extends KirbyFieldProps {
+  type: "textarea";
+  /** Format buttons: true/false or array of allowed buttons (headlines, italic, bold, link, email, file, code, ul, ol) */
+  buttons?: boolean | string[];
+  /** Whether to show character counter */
+  counter: boolean;
+  /** File picker options (query string or config object) */
+  files?: string | Record<string, any>;
+  /** Font family: `sans-serif` or `monospace` */
+  font: "sans-serif" | "monospace";
+  /** Maximum character length */
+  maxlength?: number;
+  /** Minimum character length */
+  minlength?: number;
+  /** Textarea size */
+  size?: "small" | "medium" | "large" | "huge";
+  /** Whether spellcheck is enabled */
+  spellcheck: boolean;
+  /** Upload configuration */
+  uploads?: false | string | Record<string, any>;
+  value?: string;
+}
+
 /**
  * Props for number fields.
  *
@@ -200,6 +228,8 @@ export interface KirbyDateFieldProps extends KirbyFieldProps {
   calendar?: boolean;
   /** Date/time display format (dayjs tokens) */
   display?: string;
+  /** Storage format for the value (from datetime mixin) */
+  format?: string;
   /** Maximum date/time */
   max?: string;
   /** Minimum date/time */
@@ -243,6 +273,8 @@ export interface KirbyFilesFieldProps extends KirbyFieldProps {
   image?: Record<string, any>;
   /** Info text template for each item */
   info?: string;
+  /** Display layout for selected items */
+  layout?: "list" | "cardlets" | "cards";
   /** Whether each item should be clickable */
   link?: boolean;
   /** Maximum number of items */
@@ -255,10 +287,16 @@ export interface KirbyFilesFieldProps extends KirbyFieldProps {
   query?: string;
   /** Whether to show search field in picker */
   search?: boolean;
+  /** Layout size for cards */
+  size?: "tiny" | "small" | "medium" | "large" | "huge" | "full" | "auto";
   /** Whether to store `"uuid"` or `"id"` in content file */
   store?: "uuid" | "id";
+  /** Include subpages in picker (pages field only) */
+  subpages?: boolean;
   /** Text template for each item */
   text?: string;
+  /** Upload configuration (files field only) */
+  uploads?: false | string | Record<string, any>;
   /** Selected items (transformed picker data, not raw IDs) */
   value?: KirbyPickerItem[];
 }
@@ -446,6 +484,8 @@ export interface KirbyBlocksFieldProps extends KirbyFieldProps {
   max?: number;
   /** Minimum number of blocks */
   min?: number;
+  /** Format JSON output with indentation */
+  pretty?: boolean;
   value?: KirbyBlockValue[];
 }
 
@@ -488,7 +528,7 @@ export interface KirbyLayoutFieldProps extends KirbyFieldProps {
 export interface KirbyWriterFieldProps extends KirbyFieldProps {
   type: "writer";
   /** Whether to show character counter */
-  counter?: boolean;
+  counter: boolean;
   /** Available heading levels (1-6) */
   headings?: number[];
   /** Whether only inline formatting is allowed */
@@ -506,6 +546,61 @@ export interface KirbyWriterFieldProps extends KirbyFieldProps {
   value?: string;
 }
 
+/**
+ * Props for entries fields.
+ * A simplified structure field for single-field entries.
+ *
+ * @since Kirby 5.0.0
+ * @see https://getkirby.com/docs/reference/panel/fields/entries
+ */
+export interface KirbyEntriesFieldProps extends KirbyFieldProps {
+  type: "entries";
+  /** Placeholder text when no entries exist */
+  empty?: string;
+  /** Single field definition for entry items */
+  field: KirbyFieldProps;
+  /** Maximum number of entries */
+  max?: number;
+  /** Minimum number of entries */
+  min?: number;
+  /** Whether entries are sortable via drag & drop */
+  sortable?: boolean;
+  value?: any[];
+}
+
+/**
+ * Stats report item for the stats field.
+ */
+export interface KirbyStatsReport {
+  /** Report label */
+  label: string;
+  /** Report value */
+  value: string | number;
+  /** Additional info text */
+  info?: string;
+  /** Link URL */
+  link?: string;
+  /** Icon identifier */
+  icon?: string;
+  /** Color theme */
+  theme?: string;
+}
+
+/**
+ * Props for stats fields.
+ * Display stats/metrics as cards.
+ *
+ * @since Kirby 5.1.0
+ * @see https://getkirby.com/docs/reference/panel/fields/stats
+ */
+export interface KirbyStatsFieldProps extends KirbyFieldProps {
+  type: "stats";
+  /** Array of report objects or query string */
+  reports: KirbyStatsReport[] | string;
+  /** Card size */
+  size?: "tiny" | "small" | "medium" | "large";
+}
+
 // =============================================================================
 // Block & Layout Values
 // =============================================================================
@@ -644,6 +739,7 @@ export interface KirbyFieldsetGroup {
 export type KirbyAnyFieldProps =
   | KirbyFieldProps
   | KirbyTextFieldProps
+  | KirbyTextareaFieldProps
   | KirbyNumberFieldProps
   | KirbyOptionsFieldProps
   | KirbyToggleFieldProps
@@ -655,6 +751,8 @@ export type KirbyAnyFieldProps =
   | KirbyLinkFieldProps
   | KirbyStructureFieldProps
   | KirbyObjectFieldProps
+  | KirbyEntriesFieldProps
   | KirbyBlocksFieldProps
   | KirbyLayoutFieldProps
-  | KirbyWriterFieldProps;
+  | KirbyWriterFieldProps
+  | KirbyStatsFieldProps;

package/src/panel/index.d.ts

@@ -18,7 +18,15 @@
  * @since 4.0.0
  */
 
-import type { ComponentPublicInstance, VueConstructor } from "vue";
+import type {
+  ComponentOptions,
+  ComponentPublicInstance,
+  PluginFunction,
+  PluginObject,
+  VNode,
+  VueConstructor,
+  h as VueH,
+} from "vue";
 import type { PanelApi } from "./api";
 import type {
   PanelContext,
@@ -191,10 +199,8 @@ export type {
   WriterMarkContext,
   WriterNodeContext,
   WriterExtensionContext,
-  // Writer Schemas
-  WriterMarkSchema,
-  WriterNodeSchema,
   // Writer Extensions
+  WriterExtension,
   WriterMarkExtension,
   WriterNodeExtension,
 } from "./writer";
@@ -224,6 +230,32 @@ export type PanelApp = InstanceType<VueConstructor> & {
   $esc: (string: string) => string;
 };
 
+// =============================================================================
+// Plugin Component Types
+// =============================================================================
+
+/**
+ * Vue component options for Panel plugin extensions.
+ *
+ * Components can be defined as:
+ * - Vue component options object with template or render function
+ * - Component that extends another component by name
+ */
+export type PanelComponentExtension =
+  | ComponentPublicInstance
+  | ComponentOptions<any>
+  | {
+      /** Extend another component by name (e.g., `"k-text-field"`) */
+      extends?: string | ComponentPublicInstance;
+      /** Named mixins (e.g., `"dialog"`, `"drawer"`, `"section"`) or component objects */
+      mixins?: (string | ComponentOptions<any>)[];
+      /** Template string */
+      template?: string;
+      /** Render function */
+      render?: (h: typeof VueH) => VNode;
+      [key: string]: any;
+    };
+
 // =============================================================================
 // Panel Configuration
 // =============================================================================
@@ -423,6 +455,175 @@ export interface PanelRequestResponse {
   };
 }
 
+// =============================================================================
+// Panel Plugin Extensions (window.panel.plugin)
+// =============================================================================
+
+/**
+ * Extensions object passed to `window.panel.plugin()`.
+ *
+ * @example
+ * ```ts
+ * window.panel.plugin("my-plugin", {
+ *   // Custom block types
+ *   blocks: {
+ *     video: `<k-block-video :source="content.source" />`
+ *   },
+ *
+ *   // Custom field types
+ *   fields: {
+ *     "color-picker": {
+ *       extends: "k-text-field",
+ *       template: `<k-field v-bind="$props">...</k-field>`
+ *     }
+ *   },
+ *
+ *   // Custom sections
+ *   sections: {
+ *     stats: {
+ *       template: `<div>{{ data }}</div>`
+ *     }
+ *   },
+ *
+ *   // Textarea toolbar buttons
+ *   textareaButtons: {
+ *     timestamp: {
+ *       label: "Insert Timestamp",
+ *       icon: "clock",
+ *       click() {
+ *         this.command("insert", () => new Date().toISOString());
+ *       }
+ *     }
+ *   },
+ *
+ *   // Writer marks and nodes
+ *   writerMarks: {
+ *     highlight: {
+ *       button: { icon: "highlight", label: "Highlight" },
+ *       schema: {
+ *         parseDOM: [{ tag: "mark" }],
+ *         toDOM: () => ["mark", 0]
+ *       }
+ *     }
+ *   }
+ * });
+ * ```
+ *
+ * @see https://getkirby.com/docs/reference/plugins/extensions
+ */
+export interface PanelPluginExtensions {
+  /**
+   * Custom block types for the blocks field.
+   *
+   * Can be either a template string (shorthand) or a component options object.
+   * Registered as `k-block-type-${name}` components that automatically
+   * extend `k-block-type-default`.
+   *
+   * @see https://getkirby.com/docs/reference/plugins/extensions/blocks
+   */
+  blocks?: Record<string, string | PanelComponentExtension>;
+
+  /**
+   * Vue components to register globally in the Panel.
+   *
+   * @see https://getkirby.com/docs/reference/plugins/extensions/components
+   */
+  components?: Record<string, PanelComponentExtension>;
+
+  /**
+   * Custom field types.
+   *
+   * Registered as `k-${name}-field` components.
+   *
+   * @see https://getkirby.com/docs/reference/plugins/extensions/fields
+   */
+  fields?: Record<string, PanelComponentExtension>;
+
+  /**
+   * SVG icon definitions.
+   *
+   * @see https://getkirby.com/docs/reference/plugins/extensions/icons
+   */
+  icons?: Record<string, string>;
+
+  /**
+   * Custom section types.
+   *
+   * Registered as `k-${name}-section` components.
+   * The `section` mixin is automatically prepended to the mixins array.
+   *
+   * @see https://getkirby.com/docs/reference/plugins/extensions/sections
+   */
+  sections?: Record<string, PanelComponentExtension>;
+
+  /**
+   * View button components.
+   *
+   * Registered as `k-${name}-view-button` components.
+   *
+   * @see https://getkirby.com/docs/reference/plugins/extensions/view-buttons
+   */
+  viewButtons?: Record<string, PanelComponentExtension>;
+
+  /**
+   * Vue plugins to install via `Vue.use()`.
+   *
+   * Can be used to add global methods, directives, or mixins.
+   */
+  use?: Record<string, PluginObject<any> | PluginFunction<any>>;
+
+  /**
+   * Callback executed after the Panel Vue app is created.
+   *
+   * Receives the Vue app instance as parameter.
+   *
+   * @example
+   * ```ts
+   * window.panel.plugin("my-plugin", {
+   *   created(app) {
+   *     console.log("Panel app created", app);
+   *   }
+   * });
+   * ```
+   */
+  created?: (app: PanelApp) => void;
+
+  /**
+   * Custom login form component.
+   *
+   * Replaces the default login form with a custom implementation.
+   */
+  login?: PanelComponentExtension;
+
+  /**
+   * Custom textarea toolbar buttons.
+   *
+   * @see https://getkirby.com/docs/reference/plugins/extensions/textarea-buttons
+   */
+  textareaButtons?: Record<string, TextareaButton>;
+
+  /**
+   * Arbitrary third-party plugin data.
+   *
+   * Can be used to pass configuration to other plugins.
+   */
+  thirdParty?: Record<string, any>;
+
+  /**
+   * Custom Writer inline formatting marks.
+   *
+   * @see https://getkirby.com/docs/reference/plugins/extensions/writer-marks
+   */
+  writerMarks?: Record<string, WriterMarkExtension>;
+
+  /**
+   * Custom Writer block-level nodes.
+   *
+   * @see https://getkirby.com/docs/reference/plugins/extensions/writer-nodes
+   */
+  writerNodes?: Record<string, WriterNodeExtension>;
+}
+
 // =============================================================================
 // Panel Plugins
 // =============================================================================
@@ -771,6 +972,37 @@ export interface Panel {
    */
   overlays: () => ("drawer" | "dialog")[];
 
+  /**
+   * Registers a Panel plugin with its extensions.
+   *
+   * @param name - Unique plugin identifier (typically vendor/plugin-name)
+   * @param extensions - Plugin extensions to register
+   *
+   * @example
+   * ```ts
+   * window.panel.plugin("my-plugin", {
+   *   fields: {
+   *     "color-picker": {
+   *       extends: "k-text-field",
+   *       template: `<k-field v-bind="$props">...</k-field>`
+   *     }
+   *   },
+   *   textareaButtons: {
+   *     timestamp: {
+   *       label: "Insert Timestamp",
+   *       icon: "clock",
+   *       click() {
+   *         this.command("insert", () => new Date().toISOString());
+   *       }
+   *     }
+   *   }
+   * });
+   * ```
+   *
+   * @see https://getkirby.com/docs/reference/plugins/extensions
+   */
+  plugin: (name: string, extensions: PanelPluginExtensions) => void;
+
   /**
    * Sends a POST request through the Panel router.
    *

package/src/panel/textarea.d.ts

@@ -149,12 +149,48 @@ export interface TextareaButton {
    */
   shortcut?: string;
 
+  /**
+   * Keyboard event handler for the button.
+   *
+   * Called when a key is pressed while the button is focused.
+   * This is different from `shortcut`, which is triggered globally
+   * with Cmd/Ctrl modifier.
+   *
+   * @param event - The native keyboard event
+   */
+  key?: (event: KeyboardEvent) => void;
+
   /**
    * Dropdown menu items.
    *
    * If provided, the button shows a dropdown instead of executing click directly.
    */
   dropdown?: TextareaDropdownItem[];
+
+  /**
+   * Conditional rendering. If false, the button won't be shown.
+   */
+  when?: boolean;
+
+  /**
+   * Disables the button.
+   */
+  disabled?: boolean;
+
+  /**
+   * Sets the aria-current attribute for active state styling.
+   */
+  current?: boolean | string;
+
+  /**
+   * Alternative tooltip text (defaults to label).
+   */
+  title?: string;
+
+  /**
+   * Custom CSS class for the button.
+   */
+  class?: string;
 }
 
 // =============================================================================
@@ -164,14 +200,23 @@ export interface TextareaButton {
 /**
  * A dropdown menu item for textarea toolbar buttons.
  *
+ * **Important:** Unlike the main button's `click` handler, dropdown item clicks
+ * are NOT called with the toolbar context as `this`. The `this` context is
+ * bound to the DropdownContent component which doesn't have `command()`.
+ *
+ * For this reason, dropdown items should use arrow functions and access
+ * the toolbar's functionality through closures or other means.
+ *
  * @example
  * ```js
+ * // Built-in buttons use arrow functions to capture toolbar's `this`
  * dropdown: [
  *   {
  *     label: "Option 1",
  *     icon: "check",
- *     click() {
- *       this.command("insert", "text");
+ *     click: () => {
+ *       // Access toolbar methods through closure
+ *       toolbar.command("insert", "text");
  *     }
  *   }
  * ]
@@ -182,11 +227,28 @@ export interface TextareaDropdownItem {
   label: string;
 
   /** Icon name */
-  icon: string;
+  icon?: string;
 
   /**
-   * Click handler. Called with `this` bound to the toolbar context.
-   * Use a regular function (not arrow function) to access `this.command()`.
+   * Click handler.
+   *
+   * Note: Unlike main button clicks, `this` is NOT bound to the toolbar context.
+   * Use arrow functions and capture any needed references through closures.
    */
-  click: (this: TextareaToolbarContext) => void;
+  click: () => void;
+
+  /**
+   * Conditional rendering. If false, the item won't be shown.
+   */
+  when?: boolean;
+
+  /**
+   * Disables the dropdown item.
+   */
+  disabled?: boolean;
+
+  /**
+   * Sets the aria-current attribute for active state styling.
+   */
+  current?: boolean | string;
 }

package/src/panel/writer.d.ts

@@ -4,7 +4,6 @@
  * This module provides types for the Writer component, including:
  * - Editor instance and options
  * - Mark and node extensions for plugins
- * - ProseMirror schema wrappers
  * - Utility functions and contexts
  *
  * @see https://getkirby.com/docs/reference/plugins/extensions/writer-marks-nodes
@@ -14,7 +13,6 @@
 
 import type { InputRule } from "prosemirror-inputrules";
 import type {
-  DOMOutputSpec,
   Fragment,
   Mark,
   MarkSpec,
@@ -51,6 +49,10 @@ import type {
  * @see https://github.com/getkirby/kirby/blob/main/panel/src/components/Forms/Writer/Editor.js
  */
 export interface WriterEditor {
+  // ---------------------------------------------------------------------------
+  // Properties
+  // ---------------------------------------------------------------------------
+
   /** Currently active mark names */
   activeMarks: string[];
   /** Currently active mark attributes by mark name */
@@ -61,19 +63,41 @@ export interface WriterEditor {
   activeNodeAttrs: Record<string, Record<string, any>>;
   /** Available commands */
   commands: Record<string, (attrs?: any) => any>;
+  /** The DOM element the editor is mounted to */
+  element: HTMLElement | null;
+  /** Registered event handlers */
+  events: Record<string, (...args: any[]) => any>;
+  /** The extensions manager instance */
+  extensions: WriterExtensions;
   /** Whether the editor is focused */
   focused: boolean;
-  /** Check if a mark or node is active, returns functions that accept optional attrs */
+  /** Active input rules */
+  inputRules: InputRule[];
+  /** Check if a mark or node is active */
   isActive: Record<string, (attrs?: Record<string, any>) => boolean>;
-  /** ProseMirror marks registered in the schema */
-  marks: Record<string, MarkType>;
-  /** ProseMirror nodes registered in the schema */
-  nodes: Record<string, NodeType>;
+  /** Keymap plugins */
+  keymaps: Plugin[];
+  /**
+   * Raw mark schema definitions.
+   *
+   * For ProseMirror MarkType instances, use `schema.marks` instead.
+   */
+  marks: Record<string, MarkSpec>;
+  /**
+   * Raw node schema definitions.
+   *
+   * For ProseMirror NodeType instances, use `schema.nodes` instead.
+   */
+  nodes: Record<string, NodeSpec>;
   /** Editor options */
   options: WriterEditorOptions;
+  /** Paste rule plugins */
+  pasteRules: Plugin[];
+  /** Custom ProseMirror plugins */
+  plugins: Plugin[];
   /** ProseMirror schema */
   schema: Schema;
-  /** Current editor selection (ProseMirror Selection object) */
+  /** Current editor selection */
   selection: ProseMirrorSelection;
   /** Selection at the end of the document */
   selectionAtEnd: ProseMirrorSelection;
@@ -88,22 +112,41 @@ export interface WriterEditor {
   /** ProseMirror editor view */
   view: EditorView;
 
+  // ---------------------------------------------------------------------------
+  // Methods
+  // ---------------------------------------------------------------------------
+
   /** Removes focus from the editor */
   blur: () => void;
-  /** Get available toolbar buttons */
+  /** Returns available toolbar buttons for the given type */
   buttons: (type: "mark" | "node") => Record<string, WriterToolbarButton>;
   /** Clears the editor content */
   clearContent: (emitUpdate?: boolean) => void;
   /** Executes a command by name */
   command: (command: string, ...args: any[]) => void;
+  /**
+   * Creates a ProseMirror document from content.
+   *
+   * @param content - HTML string, JSON object, or null for empty document
+   * @param parseOptions - Optional ProseMirror parse options
+   * @returns The created document node, or false if content type is unsupported
+   */
+  createDocument: (
+    content: string | Record<string, any> | null,
+    parseOptions?: Record<string, any>,
+  ) => ProseMirrorNode | false;
   /** Destroys the editor instance */
   destroy: () => void;
-  /** Emits an event */
-  emit: (event: string, ...args: any[]) => void;
-  /** Focuses the editor */
+  /** Emits an event to all registered listeners */
+  emit: (event: string, ...args: any[]) => this;
+  /** Focuses the editor at the given position */
   focus: (position?: "start" | "end" | number | boolean | null) => void;
-  /** Returns the current content as HTML */
-  getHTML: () => string;
+  /**
+   * Returns content as HTML.
+   *
+   * @param fragment - Optional fragment to serialize (defaults to full document)
+   */
+  getHTML: (fragment?: Fragment) => string;
   /** Returns HTML content from start to current selection */
   getHTMLStartToSelection: () => string;
   /** Returns HTML content from current selection to end */
@@ -124,17 +167,39 @@ export interface WriterEditor {
   /** Checks if the editor is editable */
   isEditable: () => boolean;
   /** Checks if the editor is empty */
-  isEmpty: () => boolean;
+  isEmpty: () => boolean | undefined;
+  /**
+   * Unsubscribes from events.
+   *
+   * @param event - Event name (omit to remove all listeners)
+   * @param fn - Specific handler to remove (omit to remove all for event)
+   */
+  off: (event?: string, fn?: (...args: any[]) => any) => this;
+  /**
+   * Subscribes to an event.
+   *
+   * @param event - Event name (e.g., "update", "focus", "blur", "transaction")
+   * @param fn - Event handler function
+   */
+  on: (event: string, fn: (...args: any[]) => any) => this;
   /** Removes a mark from the current selection */
-  removeMark: (mark: string) => boolean;
+  removeMark: (mark: string) => boolean | undefined;
+  /**
+   * Returns selection at the given position.
+   *
+   * @param position - Position indicator or numeric position
+   */
+  selectionAtPosition: (
+    position?: "start" | "end" | number | boolean | null,
+  ) => ProseMirrorSelection | { from: number; to: number };
   /** Sets the editor content */
   setContent: (content?: any, emitUpdate?: boolean, parseOptions?: any) => void;
   /** Sets the selection range */
   setSelection: (from?: number, to?: number) => void;
   /** Toggles a mark on the current selection */
-  toggleMark: (mark: string) => boolean;
+  toggleMark: (mark: string) => boolean | undefined;
   /** Updates a mark's attributes */
-  updateMark: (mark: string, attrs: Record<string, any>) => boolean;
+  updateMark: (mark: string, attrs: Record<string, any>) => boolean | undefined;
 }
 
 /**
@@ -143,8 +208,8 @@ export interface WriterEditor {
  * @see https://github.com/getkirby/kirby/blob/main/panel/src/components/Forms/Writer/Editor.js
  */
 export interface WriterEditorOptions {
-  autofocus?: boolean | "start" | "end";
-  content?: string | Record<string, any>;
+  autofocus?: boolean | "start" | "end" | number;
+  content?: string | Record<string, any> | null;
   disableInputRules?: boolean | string[];
   disablePasteRules?: boolean | string[];
   editable?: boolean;
@@ -158,6 +223,33 @@ export interface WriterEditorOptions {
   useBuiltInExtensions?: boolean;
 }
 
+/**
+ * The extensions manager for the Writer editor.
+ *
+ * Manages all registered mark, node, and generic extensions.
+ *
+ * @see https://github.com/getkirby/kirby/blob/main/panel/src/components/Forms/Writer/Extensions.js
+ */
+export interface WriterExtensions {
+  /** All registered extension instances */
+  extensions: (WriterExtension | WriterMarkExtension | WriterNodeExtension)[];
+  /** ProseMirror EditorView (set after editor initialization) */
+  view: EditorView;
+
+  /** Returns toolbar buttons for the given type */
+  buttons: (type: "mark" | "node") => Record<string, WriterToolbarButton>;
+  /** Raw mark schema definitions from all mark extensions */
+  marks: Record<string, MarkSpec>;
+  /** Mark view constructors */
+  markViews: Record<string, WriterMarkExtension["view"]>;
+  /** Raw node schema definitions from all node extensions */
+  nodes: Record<string, NodeSpec>;
+  /** Node view constructors */
+  nodeViews: Record<string, WriterNodeExtension["view"]>;
+  /** Extension options with reactive proxy */
+  options: Record<string, Record<string, any>>;
+}
+
 // =============================================================================
 // Writer Toolbar
 // =============================================================================
@@ -176,7 +268,7 @@ export interface WriterToolbarButton {
   command?: string;
   /** Icon name from Kirby's icon set */
   icon: string;
-  /** Display label (usually translated via `window.panel.$t()`) */
+  /** Display label (usually translated via `window.panel.t()`) */
   label: string;
   /** Extension name this button belongs to */
   name?: string;
@@ -184,6 +276,8 @@ export interface WriterToolbarButton {
   attrs?: Record<string, any>;
   /** Show separator line after this button */
   separator?: boolean;
+  /** Whether this is an inline node button (shown inline, not in dropdown) */
+  inline?: boolean;
   /** Node types when this button should be visible */
   when?: string[];
 }
@@ -490,63 +584,106 @@ export interface WriterExtensionContext {
 }
 
 // =============================================================================
-// ProseMirror Schema Types
+// Writer Generic Extension
 // =============================================================================
 
 /**
- * Mark schema specification for ProseMirror.
+ * A generic Writer extension (non-mark, non-node).
  *
- * @see https://prosemirror.net/docs/ref/#model.MarkSpec
- */
-export interface WriterMarkSchema extends Omit<MarkSpec, "parseDOM" | "toDOM"> {
-  /** Attribute definitions with defaults */
-  attrs?: Record<
-    string,
-    {
-      default?: any;
-    }
-  >;
-  /** DOM parsing rules */
-  parseDOM?: {
-    tag?: string;
-    style?: string;
-    priority?: number;
-    consuming?: boolean;
-    context?: string;
-    getAttrs?: (
-      node: HTMLElement | string,
-    ) => Record<string, any> | false | null;
-  }[];
-  /** DOM serialization */
-  toDOM?: (mark: Mark) => DOMOutputSpec;
-}
-
-/**
- * Node schema specification for ProseMirror.
+ * Generic extensions provide functionality like history (undo/redo),
+ * custom keyboard shortcuts, or other editor-wide features.
+ * They are registered via `window.panel.plugin("name", { writerExtensions: { ... } })`.
+ *
+ * @example
+ * ```js
+ * window.panel.plugin("my-plugin", {
+ *   writerExtensions: {
+ *     customKeys: {
+ *       keys() {
+ *         return {
+ *           "Ctrl-s": () => {
+ *             // Custom save handler
+ *             return true;
+ *           }
+ *         };
+ *       }
+ *     }
+ *   }
+ * });
+ * ```
  *
- * @see https://prosemirror.net/docs/ref/#model.NodeSpec
+ * @see https://github.com/getkirby/kirby/blob/main/panel/src/components/Forms/Writer/Extension.js
  */
-export interface WriterNodeSchema extends Omit<NodeSpec, "parseDOM" | "toDOM"> {
-  /** Attribute definitions with defaults */
-  attrs?: Record<
-    string,
-    {
-      default?: any;
-    }
-  >;
-  /** DOM parsing rules */
-  parseDOM?: {
-    tag?: string;
-    priority?: number;
-    consuming?: boolean;
-    context?: string;
-    attrs?: Record<string, any>;
-    getAttrs?: (node: HTMLElement) => Record<string, any> | false | null;
-    getContent?: (node: HTMLElement, schema: Schema) => Fragment;
-    preserveWhitespace?: boolean | "full";
-  }[];
-  /** DOM serialization */
-  toDOM?: (node: ProseMirrorNode) => DOMOutputSpec;
+export interface WriterExtension {
+  /**
+   * Unique name of the extension.
+   */
+  name?: string;
+
+  /** Extension type identifier */
+  type?: string;
+
+  /**
+   * The editor instance, available after `bindEditor()` is called.
+   */
+  editor?: WriterEditor;
+
+  /**
+   * Merged extension options from `defaults` and constructor options.
+   */
+  options?: Record<string, any>;
+
+  /**
+   * Default options for the extension.
+   */
+  defaults?: Record<string, any>;
+
+  /**
+   * Called after the editor is bound to the extension.
+   */
+  init?: () => null | void;
+
+  /**
+   * Commands provided by this extension.
+   *
+   * @param context - Context with schema and utils (no type for generic extensions)
+   * @returns A command function, or an object mapping command names to functions.
+   */
+  commands?: (
+    context: WriterExtensionContext,
+  ) => (() => any) | Record<string, (attrs?: any) => any>;
+
+  /**
+   * Additional ProseMirror plugins.
+   *
+   * @param context - Context with schema and utils
+   * @returns Array of ProseMirror plugins or plugin specs
+   */
+  plugins?: (context: WriterExtensionContext) => (Plugin | PluginSpec<any>)[];
+
+  /**
+   * Input rules for automatic formatting.
+   *
+   * @param context - Context with schema and utils
+   * @returns Array of ProseMirror input rules
+   */
+  inputRules?: (context: WriterExtensionContext) => InputRule[];
+
+  /**
+   * Paste rules for processing pasted content.
+   *
+   * @param context - Context with schema and utils
+   * @returns Array of ProseMirror plugins
+   */
+  pasteRules?: (context: WriterExtensionContext) => Plugin[];
+
+  /**
+   * Keyboard shortcuts.
+   *
+   * @param context - Context with schema and utils
+   * @returns Object mapping key combinations to command functions
+   */
+  keys?: (context: WriterExtensionContext) => Record<string, () => any>;
 }
 
 // =============================================================================
@@ -587,6 +724,39 @@ export interface WriterNodeSchema extends Omit<NodeSpec, "parseDOM" | "toDOM"> {
  * @see https://getkirby.com/docs/reference/plugins/extensions/writer-marks-nodes
  */
 export interface WriterMarkExtension {
+  // ---------------------------------------------------------------------------
+  // Instance Properties (available via `this` in extension methods)
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Unique name of the mark extension.
+   *
+   * When using object literals with `window.panel.plugin()`, this is
+   * typically derived from the object key in `writerMarks`.
+   */
+  name?: string;
+
+  /** Extension type identifier */
+  type?: "mark";
+
+  /**
+   * The editor instance, available after `bindEditor()` is called.
+   *
+   * Use this to access editor methods like `emit()`, `toggleMark()`, etc.
+   */
+  editor?: WriterEditor;
+
+  /**
+   * Merged extension options from `defaults` and constructor options.
+   *
+   * Available at runtime after the extension is instantiated.
+   */
+  options?: Record<string, any>;
+
+  // ---------------------------------------------------------------------------
+  // Configuration
+  // ---------------------------------------------------------------------------
+
   /**
    * Toolbar button configuration.
    *
@@ -606,7 +776,7 @@ export interface WriterMarkExtension {
    *
    * Defines how the mark is parsed from and serialized to DOM.
    */
-  schema?: WriterMarkSchema;
+  schema?: MarkSpec;
 
   /**
    * Commands provided by this extension.
@@ -719,6 +889,42 @@ export interface WriterMarkExtension {
     view: EditorView,
     inline: boolean,
   ) => { dom: HTMLElement; contentDOM?: HTMLElement };
+
+  // ---------------------------------------------------------------------------
+  // Lifecycle
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Called after the editor is bound to the extension.
+   *
+   * Use this for initialization logic that requires access to `this.editor`.
+   */
+  init?: () => null | void;
+
+  // ---------------------------------------------------------------------------
+  // Mark Helper Methods (inherited from Mark base class)
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Toggles this mark on the current selection.
+   *
+   * Shorthand for `this.editor.toggleMark(this.name)`.
+   */
+  toggle?: () => boolean | undefined;
+
+  /**
+   * Removes this mark from the current selection.
+   *
+   * Shorthand for `this.editor.removeMark(this.name)`.
+   */
+  remove?: () => void;
+
+  /**
+   * Updates the attributes of this mark.
+   *
+   * Shorthand for `this.editor.updateMark(this.name, attrs)`.
+   */
+  update?: (attrs: Record<string, any>) => void;
 }
 
 // =============================================================================
@@ -761,6 +967,39 @@ export interface WriterMarkExtension {
  * @see https://getkirby.com/docs/reference/plugins/extensions/writer-marks-nodes
  */
 export interface WriterNodeExtension {
+  // ---------------------------------------------------------------------------
+  // Instance Properties (available via `this` in extension methods)
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Unique name of the node extension.
+   *
+   * When using object literals with `window.panel.plugin()`, this is
+   * typically derived from the object key in `writerNodes`.
+   */
+  name?: string;
+
+  /** Extension type identifier */
+  type?: "node";
+
+  /**
+   * The editor instance, available after `bindEditor()` is called.
+   *
+   * Use this to access editor methods like `emit()`, `command()`, etc.
+   */
+  editor?: WriterEditor;
+
+  /**
+   * Merged extension options from `defaults` and constructor options.
+   *
+   * Available at runtime after the extension is instantiated.
+   */
+  options?: Record<string, any>;
+
+  // ---------------------------------------------------------------------------
+  // Configuration
+  // ---------------------------------------------------------------------------
+
   /**
    * Toolbar button configuration.
    *
@@ -776,7 +1015,7 @@ export interface WriterNodeExtension {
   /**
    * ProseMirror node schema definition.
    */
-  schema?: WriterNodeSchema;
+  schema?: NodeSpec;
 
   /**
    * Commands provided by this extension.
@@ -834,4 +1073,15 @@ export interface WriterNodeExtension {
     decorations: Decoration[],
     innerDecorations: DecorationSource,
   ) => NodeView;
+
+  // ---------------------------------------------------------------------------
+  // Lifecycle
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Called after the editor is bound to the extension.
+   *
+   * Use this for initialization logic that requires access to `this.editor`.
+   */
+  init?: () => null | void;
 }