# Instance and configuration reference

Look up public Classic creation settings, updates, instance methods and UI controls.

Use this page to look up types, the [quick start](/en/classic/quick-start) to integrate, and [configuration and lifetime](/en/classic/configuration) to choose an update strategy. Import types from `@quirekit/classic-editor`; Vue hosts create the runtime through `/vue`.

## Creation options

`preset` selects the model and defaults, `plugins` installs product capabilities, and `extensions` adds content extensions. `media` and `host` establish instance services at creation and cannot be replaced through updates.

### ClassicEditorOptions

`@quirekit/classic-editor` · AGPL-3.0-only

Options accepted when creating a Classic Editor product instance.

```ts
export interface ClassicEditorOptions {
    readonly element?: HTMLElement | null | undefined;
    readonly document?: QuireEditorContent | undefined;
    readonly preset?: ClassicEditorPreset | undefined;
    readonly locale?: ClassicEditorLocale | undefined;
    readonly surfaceMode?: ClassicEditorSurfaceMode | undefined;
    readonly features?: ClassicEditorFeatureOptions | undefined;
    readonly plugins?: readonly ClassicEditorPlugin[] | undefined;
    readonly extensions?: readonly QuireAnyExtension[] | undefined;
    readonly editable?: boolean | undefined;
    readonly view?: ClassicEditorViewOptions | undefined;
    readonly canvasRuntime?: Readonly<Partial<CanvasMountedViewRuntimeOptions>> | undefined;
    readonly svgRuntime?: Readonly<Partial<SvgMountedViewRuntimeOptions>> | undefined;
    readonly theme?: QuireKitTheme | undefined;
    readonly shell?: ClassicEditorShellOptions | undefined;
    readonly ui?: ClassicEditorUiProfileOptions | undefined;
    readonly webFonts?: ClassicEditorWebFontOptions | false | undefined;
    readonly media?: ClassicEditorMediaServices | undefined;
    readonly host?: ClassicEditorHostServices | undefined;
}
```

**element** — Optional mount element. Omit or pass null to create an initially unmounted instance.

**document** — Initial ProseMirror-compatible document content.

**preset** — Product preset. Defaults to `classicEditorPreset`.

**locale** — Product-interface locale. Defaults to Simplified Chinese.

**surfaceMode** — Create-time product surface mode. Defaults to the user-facing product.

**features** — Feature overrides merged with the selected preset.

**plugins** — Product plugins installed after preset plugins.

**extensions** — Ordinary QuireKit extensions appended after preset extensions.

**editable** — Whether the document accepts editing input.

**view** — Product view backend selection.

**canvasRuntime** — Canvas runtime overrides. Product page-stack values remain authoritative.

**svgRuntime** — SVG mounted-runtime overrides.

**theme** — Complete QuireKit theme taking precedence over the preset theme.

**shell** — Product shell overrides merged with the preset shell.

**ui** — Updated final composition for action-backed product surfaces.

**webFonts** — External font library policy, or `false` to disable acquisition.

**media** — Instance-scoped media registration and resolution authorities.

Omit this for the in-memory authoring repository. Hosts that persist
canonical JSON must provide matching durable media persistence.

**host** — Create-time Host resource adapter boundary. It cannot be replaced by update().

## Update options

Locale, editability and built-in preset theme updates retain the session; structural settings still rebuild Core. `plugins` / `extensions` replace arrays; options such as `features` / `shell` merge by field. Updating an array does not append entries. See [configuration rules](/en/classic/configuration).

### ClassicEditorUpdateOptions

`@quirekit/classic-editor` · AGPL-3.0-only

Runtime options accepted by `ClassicEditorInstance.update()`.

```ts
export interface ClassicEditorUpdateOptions {
    readonly document?: QuireEditorContent | undefined;
    readonly preset?: ClassicEditorPreset | undefined;
    readonly locale?: ClassicEditorLocale | undefined;
    readonly features?: ClassicEditorFeatureOptions | undefined;
    readonly plugins?: readonly ClassicEditorPlugin[] | undefined;
    readonly extensions?: readonly QuireAnyExtension[] | undefined;
    readonly editable?: boolean | undefined;
    readonly view?: ClassicEditorViewOptions | undefined;
    readonly canvasRuntime?: Readonly<Partial<CanvasMountedViewRuntimeOptions>> | undefined;
    readonly svgRuntime?: Readonly<Partial<SvgMountedViewRuntimeOptions>> | undefined;
    readonly theme?: QuireKitTheme | undefined;
    readonly shell?: ClassicEditorShellOptions | undefined;
    readonly ui?: ClassicEditorUiProfileOptions | undefined;
    readonly webFonts?: ClassicEditorWebFontOptions | false | undefined;
}
```

**document** — Optional replacement document.

**preset** — Optional replacement preset.

**locale** — Updated product-interface locale.

**features** — Feature overrides to merge into current options.

**plugins** — Replacement instance-level product plugins.

**extensions** — Replacement instance-level QuireKit extensions.

**editable** — Updated editability.

**view** — Updated product view backend selection.

**canvasRuntime** — Canvas runtime overrides to merge into current options.

**svgRuntime** — SVG runtime overrides to merge into current options.

**theme** — Complete QuireKit theme replacing the current instance theme.

**shell** — Shell options to merge into current options.

**ui** — Updated final composition for action-backed product surfaces.

**webFonts** — Replacement external font library policy, or `false` to disable acquisition.

## Product instance

Read `instance.editor` again after `update()` or `unmount()`, rather than sending commands to a cached old Core. `getJSON()` returns canonical content; the application separately manages product names, document IDs, media bytes and storage acknowledgements.

### ClassicEditorInstance

`@quirekit/classic-editor` · AGPL-3.0-only

Public lifecycle and integration surface returned by `createClassicEditor`.

```ts
export interface ClassicEditorInstance {
    readonly isMounted: boolean;
    readonly isDestroyed: boolean;
    readonly editor: QuireEditor | undefined;
    readonly root: HTMLElement | undefined;
    readonly features: ClassicEditorResolvedFeatures;
    readonly locale: ClassicEditorLocale;
    readonly documentName: string;
    readonly backend: ClassicEditorViewBackend;
    readonly registry: ClassicEditorRegistrySnapshot;
    readonly ui: ClassicEditorUiController;
    readonly documentFontStatus: ClassicEditorDocumentFontStatus;
    readPageLayout?(document: PMNode): readonly ClassicEditorPageLayout[] | null;
    readonly fontLibrary: ClassicEditorFontLibrary | undefined;
    readonly media: ClassicEditorMediaServices;
    readonly hostResources: ClassicEditorHostResourceController;
    readonly tasks: ClassicEditorTaskFeedbackController;
    readonly resourceTasks: ClassicEditorHostResourceTaskController;
    setDocumentName(name: string): void;
    mount(element: HTMLElement): void;
    unmount(): void;
    update(options: ClassicEditorUpdateOptions): void;
    isContributionAvailable(behavior: ClassicEditorBehavior, payload?: unknown): boolean;
    canExecuteContribution(behavior: ClassicEditorBehavior, payload?: unknown): boolean;
    executeContribution(behavior: ClassicEditorBehavior, payload?: unknown, trigger?: ClassicEditorBehaviorTrigger): boolean | Promise<boolean>;
    refreshProductUi(): void;
    createReadOnlySnapshot(document: PMNode): QuireEditor;
    importDocument(serviceId: string, input: ClassicEditorImportArtifact, options?: ClassicEditorImportOptions): Promise<void>;
    exportDocument(serviceId: string): Promise<ClassicEditorExportArtifact>;
    getJSON(): QuireJSONContent;
    destroy(): void;
}
```

**isMounted** — Whether the product currently owns a mounted shell and Core editor.

**isDestroyed** — Whether final destruction has completed.

**editor** — Mounted Core editor, or undefined while unmounted.

**root** — Mounted product root, or undefined while unmounted.

**features** — Current resolved feature switches.

**locale** — Current product-interface locale.

**documentName** — Current product-level document name shown by chrome and used for exports.

**backend** — Active rendering backend.

**registry** — Current normalized product registry.

**ui** — Typed runtime authority for non-document product UI state.

**documentFontStatus** — Logical and rendered body-font facts for the mounted host.

**readPageLayout** — Reads where each page of the latest rendered layout starts and how much of its body is used.
@param document - Document the layout must belong to; a layout of an older document is not returned.
@returns Pages in order, or null before the current document is laid out.

**fontLibrary** — Mounted explicit external font library, or undefined while unmounted.

**media** — Instance-scoped media registration, identity, and resolution authorities.

**hostResources** — Stable Host resource coordinator retained across remounts.

**tasks** — Instance-scoped task feedback authority retained across remounts.

**resourceTasks** — Concurrent end-to-end resource workflow authority retained across remounts.

**setDocumentName** — Updates the product-level document name without changing editor content.
@param name - New name; empty text restores the localized untitled label.

**mount** — Mounts or remounts the product into a host element.
@param element - Host element that receives the product root.

**unmount** — Reusably unmounts the shell and owned Core/View runtime.

**update** — Updates product configuration, preserving content unless replaced.
@param options - Partial product updates.

**isContributionAvailable** — Reports whether one directly bound contribution behavior is installed.
@param behavior - Typed contribution behavior.
@param payload - Optional behavior payload.
@returns Whether the behavior is available.

**canExecuteContribution** — Reports whether one directly bound contribution behavior can execute.
@param behavior - Typed contribution behavior.
@param payload - Optional behavior payload.
@returns Whether the behavior is executable.

**executeContribution** — Executes one directly bound contribution behavior and refreshes product UI.
@param behavior - Typed contribution behavior.
@param payload - Optional behavior payload.
@param trigger - Normalized source and surface detail.
@returns Whether the behavior handled the request.

**refreshProductUi** — Re-evaluates product chrome after external non-document state changes.

**createReadOnlySnapshot** — Creates an isolated read-only snapshot using this product's rendering settings.
@param document - Same-schema immutable result to present.
@returns Unmounted caller-owned editor; destroy it when the preview closes.

**importDocument** — Imports external input through a named service.
@param serviceId - Registered service id.
@param input - File artifact consumed by the service.
@param options - Optional host cancellation signal.
@returns Asynchronous completion.

**exportDocument** — Exports the document through a named service.
@param serviceId - Registered service id.
@returns Downloadable export artifact.

**getJSON** — Returns the current canonical document JSON.

**destroy** — Final, idempotent destruction of the product instance.

## UI controller

Use `instance.ui` for zoom, ruler and sidebar changes while retaining document and history. `subscribe()` returns a cleanup function. Panel IDs refer to installed sidebar contributions; opening a panel does not create a missing contribution.

### ClassicEditorUiController

`@quirekit/classic-editor` · AGPL-3.0-only

Typed runtime authority for non-document product UI state.

```ts
export interface ClassicEditorUiController {
    readonly state: ClassicEditorUiState;
    setZoom(percent: number): void;
    setZoomMode(mode: ClassicEditorZoomMode): void;
    setRulerVisible(visible: boolean): void;
    setInvisibleCharactersVisible(visible: boolean): void;
    setHiddenTextVisible(visible: boolean): void;
    subscribe(listener: ClassicEditorUiStateListener): () => void;
    setSidebarVisible(side: "left" | "right", visible: boolean): void;
    toggleSidebar(side: "left" | "right"): void;
    openSidebarPanel(side: "left" | "right", panelId: string, options?: ClassicEditorSidebarOpenOptions): void;
    closeSidebar(side: "left" | "right"): void;
    setSemanticSnapshot(snapshot: ClassicEditorUiSemanticSnapshot): void;
}
```

**state** — Current immutable product UI state.

**setZoom** — Sets a fixed percentage and exits automatic fit without changing document history.
@param percent - Finite reading percentage, clamped to 25–400.

**setZoomMode** — @param mode - Automatic page fit or fixed reading percentage; never changes document history.

**setRulerVisible** — Shows or hides the ruler without recreating the document view.
@param visible - Requested ruler visibility.

**setInvisibleCharactersVisible** — @param visible - View-only hint visibility; does not change document history.

**setHiddenTextVisible** — @param visible - View-only hidden-text visibility, independent of document formatting and history.

**subscribe** — Subscribes to product UI state changes.
@param listener - Listener called with each new immutable snapshot.
@returns Cleanup that removes the listener.

**setSidebarVisible** — Sets one sidebar's visibility.
@param side - Product sidebar side.
@param visible - Requested visibility.

**toggleSidebar** — Toggles one sidebar's visibility.
@param side - Product sidebar side.

**openSidebarPanel** — Opens one panel and its owning sidebar.
@param side - Product sidebar side.
@param panelId - Stable sidebar-panel contribution id.
@param options - Optional semantic target inside the panel.

**closeSidebar** — Closes one sidebar without discarding its active panel selection.
@param side - Product sidebar side.

**setSemanticSnapshot** — Replaces the product semantic snapshot with an immutable value.
@param snapshot - Current selection, target, command, and geometry semantics.

## Import cancellation and commit

Hosts cancel preparation through a signal. Custom services execute one synchronous document command inside `context.commit()`; invalid targets are rejected before writing. See [files](/en/classic/files) for usage and migration.

### ClassicEditorImportOptions

`@quirekit/classic-editor` · AGPL-3.0-only

Optional cancellation owned by the host that opens a document.

```ts
export interface ClassicEditorImportOptions {
    readonly signal?: AbortSignal | undefined;
}
```

**signal** — Cancels preparation and rejects any later commit from this operation.

### ClassicEditorImportContext

`@quirekit/classic-editor` · AGPL-3.0-only

Instance-owned final write boundary supplied only to document import services.

```ts
export interface ClassicEditorImportContext extends ClassicEditorServiceContext {
    readonly signal: AbortSignal;
    commit(write: () => boolean): void;
}
```

**signal** — Cancels when the operation, target session or host request becomes invalid.

**commit** — Validates the original target and executes one synchronous document command.
@param write - Synchronous typed-command call; return true only after acceptance.

**blockInsertion** — Ephemeral target supplied only to captured block insertion presenters.

**instance** — Product instance that owns the contribution.

**editor** — Mounted Core editor.

**root** — Product root element.

**workspaceToolbarHost** — Stable shell-owned host for companion controls beside the ruler; absent in headless/custom shells.

**ownerDocument** — Document used to create contribution DOM.

**theme** — Immutable current instance theme; optional for older hand-authored contexts.

**features** — Resolved product feature switches.

**locale** — Resolved product-interface locale.

**backend** — Active rendering backend.

**ui** — Typed authority for non-document product UI state.

## Preset presentation updates

This context refreshes an existing session's presentation. It cannot install extensions or change models. Explicit host color overrides should retain precedence.

### ClassicEditorPresetPresentationContext

`@quirekit/classic-editor` · AGPL-3.0-only

Existing session facts supplied while a preset refreshes its presentation.

```ts
export interface ClassicEditorPresetPresentationContext {
    readonly editor: QuireEditor;
    readonly theme: QuireKitTheme;
    readonly locale: ClassicEditorLocale;
    readonly canvasRuntime: Readonly<Partial<CanvasMountedViewRuntimeOptions>>;
    readonly svgRuntime: Readonly<Partial<SvgMountedViewRuntimeOptions>>;
}
```

**editor** — Retained Core whose schema, commands and history must remain unchanged.

**theme** — Current complete product theme.

**locale** — Current interface language.

**canvasRuntime** — Host overrides that must retain precedence over theme defaults.

**svgRuntime** — Host SVG overrides that must retain precedence over theme defaults.

## Media and fonts

Follow [durable media](/en/classic/media) and [fonts](/en/classic/fonts). Binary assets, browser font resources and logical document identities have separate owners.

### ClassicEditorMediaServices

`@quirekit/classic-editor` · AGPL-3.0-only

Media authorities shared by one Classic Editor instance and its mounted views.

```ts
export interface ClassicEditorMediaServices {
    readonly sink: QuireMediaAssetSink;
    readonly registrar?: QuireMediaAssetRegistrar | undefined;
    readonly resolver: QuireMediaAssetResolver;
    createAssetId(kind: QuireMediaAssetKind): string;
}
```

**sink** — Registration boundary used by authoring actions before document insertion.

**registrar** — Lease-based registration boundary for fallible authoring workflows.

**resolver** — Resolution boundary injected into every mounted rendering backend.

**createAssetId** — Allocates one stable host-scoped media identity.
@param kind - Media family receiving the identity.
@returns A non-empty identity that is unique within the backing repository.

### ClassicEditorWebFontOptions

`@quirekit/classic-editor` · AGPL-3.0-only

Host policy and provider boundaries for Classic's external font library.

```ts
export interface ClassicEditorWebFontOptions {
    readonly families: readonly ClassicEditorWebFontFamily[];
    readonly mountedFamilies?: readonly ClassicEditorMountedFontFamily[] | undefined;
    readonly sources?: readonly ClassicEditorWebFontSource[] | undefined;
    readonly persistence?: ClassicEditorFontLibraryPersistence | undefined;
    readonly catalogs: readonly QuireWebFontCatalog[];
    readonly cache?: QuireWebFontCache | undefined;
    readonly fetch?: QuireWebFontFetch | undefined;
    readonly maxAssetBytes?: number | undefined;
    readonly maxConcurrentAssets?: number | undefined;
}
```

**families** — Families disclosed to users as explicitly downloadable.

**mountedFamilies** — Families already registered by application-owned stylesheets.

**sources** — Searchable provider adapters displayed by the font Hub.

**persistence** — Optional local Hub persistence override.

**catalogs** — Ordered provider catalogs enabled by the host.

**cache** — Optional persistent cache override.

**fetch** — Optional font-asset fetch implementation.

**maxAssetBytes** — Maximum accepted bytes for one provider asset.

**maxConcurrentAssets** — Maximum provider assets fetched concurrently.

### ClassicEditorFontLibrary

`@quirekit/classic-editor` · AGPL-3.0-only

Mounted Classic authority for explicit external font installation.

```ts
export interface ClassicEditorFontLibrary {
    readonly families: readonly ClassicEditorWebFontFamily[];
    readonly sources: readonly ClassicEditorWebFontSource[];
    readonly importedFamilies: readonly ClassicEditorImportedWebFontFamily[];
    readonly mountedFamilies: readonly ClassicEditorMountedFontFamily[];
    readonly recentFamilies: readonly string[];
    rememberRecentFamily(family: string): void;
    getInstallations(): readonly QuireWebFontInstallation[];
    subscribe(listener: () => void): () => void;
    getSourceSettings(sourceId: string): ClassicEditorWebFontSourceSettings;
    configureSource(sourceId: string, settings: ClassicEditorWebFontSourceSettings): void;
    search(sourceId: string, query: string, subsets?: readonly string[]): Promise<readonly ClassicEditorWebFontFamily[]>;
    browse?(sourceId: string, query: string, limit: number, cursor?: string, subsets?: readonly string[]): Promise<ClassicEditorWebFontCatalogPage>;
    inspectCustomSource?(descriptorUrl: string): Promise<ClassicEditorCustomWebFontSourceRecord>;
    enableCustomSource?(record: ClassicEditorCustomWebFontSourceRecord): void;
    inspectStylesheetSource?(url: string, name?: string): Promise<ClassicEditorStylesheetFontSourceRecord>;
    enableStylesheetSource?(record: ClassicEditorStylesheetFontSourceRecord): void;
    removeCustomSource?(sourceId: string): void;
    previewFamily(family: ClassicEditorWebFontFamily): Promise<void>;
    importFamily(family: ClassicEditorWebFontFamily, download?: boolean): Promise<void>;
    removeFamily(family: ClassicEditorWebFontFamily | string): Promise<void>;
    getStatus(family: string): QuireWebFontStatus;
    install(family: string): Promise<void>;
}
```

**families** — Host-disclosed families available from the current mount.

**sources** — Searchable configured sources.

**importedFamilies** — Families explicitly imported into this browser product.

**mountedFamilies** — Families already registered by application-owned stylesheets.

**recentFamilies** — Most recently selected visible families, newest first.

**rememberRecentFamily** — Remembers one explicit font choice in origin-local product state.
@param family - Exact logical family selected by the user.

**getInstallations** — Reads completed byte-backed, local, or registered installation results.

Consumers must treat the returned records as read-only runtime resources.
Local-only records intentionally contain no embeddable font bytes.
@returns Immutable installation snapshot in readiness order.

**subscribe** — Observes source, import, and loader lifecycle changes.
@param listener - Product-chrome invalidation callback.
@returns Unsubscribe callback.

**getSourceSettings** — Reads current local settings for one source.
@param sourceId - Stable source identity.
@returns Source-local setting values.

**configureSource** — Saves complete local settings for one source.
@param sourceId - Stable source identity.
@param settings - Source-local values.

**search** — Searches one configured source.
@param sourceId - Stable source identity.
@param query - User-entered family query.
@param subsets - Optional accepted provider subset tokens.
@returns Matching provider families.

**browse** — Browses one bounded page from a configured source.
@param sourceId - Stable source identity.
@param query - User-entered family query or an empty browse-all query.
@param limit - Maximum requested result count.
@param cursor - Optional cursor returned by the preceding page.
@param subsets - Optional accepted provider subset tokens applied before paging.
@returns One provider catalog page.

**inspectCustomSource** — Validates one declarative source without enabling it.
@param descriptorUrl - User-supplied HTTPS descriptor URL.
@returns Persistable validated source record.

**enableCustomSource** — Enables one previously inspected declarative source.
@param record - Validated persistable source record.

**inspectStylesheetSource** — Reads a static font-face stylesheet without downloading fonts or enabling it.
@param url - Direct HTTP(S) CSS URL, including localhost services.
@param name - Optional user-visible source name.
@returns Validated persistable CSS snapshot.

**enableStylesheetSource** — Enables or updates a previously inspected static directory.
@param record - Validated CSS snapshot.

**removeCustomSource** — Removes one declarative source while retaining already imported families.
@param sourceId - Stable custom source identity.

**previewFamily** — Downloads and registers one disclosed family for an explicit visual preview.

Previewing may populate the external-font byte cache but does not add an
imported-family record to product persistence.
@param family - Exact provider search or curated family result.
@returns Completion after the browser can render the real family.

**importFamily** — Imports one provider family and optionally installs its bytes now.
@param family - Provider search or curated family result.
@param download - Whether to download/register immediately.

**removeFamily** — Removes one imported family and its cached bytes.
@param family - Exact imported record or legacy family name.

**getStatus** — Reads the external loader lifecycle for one family.
@param family - Exact configured family name.
@returns Current immutable loader status.

**install** — Installs one disclosed family after an explicit user or host action.
@param family - Exact configured family name.
@returns Completion after browser registration and layout invalidation.

### ClassicEditorDocumentFontStatus

`@quirekit/classic-editor` · AGPL-3.0-only

Product-facing logical and rendered font facts for the current document.

```ts
export interface ClassicEditorDocumentFontStatus {
    readonly requestedFamily: string | null;
    readonly renderedFamily: string | null;
    readonly status: ClassicEditorDocumentFontStatusKind;
    readonly source: QuireFontSubstitutionCandidateSource | null;
}
```

**requestedFamily** — Logical family retained in the canonical document and font control.

**renderedFamily** — Exact family selected before generic glyph fallback, when resolved.

**status** — Current asynchronous availability result.

**source** — Candidate authority that supplied the rendered family.