@domternal-pro/extension-ai

Bring-your-own-endpoint AI assistant for Domternal: generated answers stream into a local preview, proposed text transformations appear as an in-document red/green diff you accept or discard, and one undo after accepting restores the exact original. The package contacts only the endpoint the host application explicitly configures, when a user invokes an AI operation. It has no default or hard-coded Domternal model endpoint and sends no license telemetry or metering data. The Domternal-operated website playground separately configures Domternal's AI proxy under its published Privacy Policy.

Links

Documentation    •    Live examples

Licensing

This is a commercial package distributed through the public npm registry. A DOM-connected editor surface remains fully featured without a key for internal evaluation and shows a small evaluation badge. Guarded headless, standalone, server and worker operations have no badge surface, so they require an explicit evaluation mode or production mode with a covered DMP2 Commercial Key. Evaluation does not permit production use.

Domternal supplies the connector, streaming transport and review interface, not the model or provider your application configures. You choose and contract with that provider, control the endpoint, credentials, prompts and submitted data, and remain responsible for input rights, legal basis, provider terms and security. Model output can be inaccurate, incomplete, biased, unsafe, infringing or otherwise unsuitable. Review it with human oversight and any domain-specific validation appropriate to the intended use before accepting, publishing or acting on it. Domternal does not guarantee a configured provider's availability, security, legality, accuracy or output. These provider and output limitations do not excuse a defect in Domternal's own connector code or override liability that applicable law does not permit us to exclude.

Keyless headless evaluation is explicit and remains fully functional:

import { configureProLicense } from '@domternal-pro/core';

configureProLicense({ mode: 'evaluation' });

Production uses the signed Commercial Key from the Order confirmation:

import { configureProLicense } from '@domternal-pro/core';

configureProLicense({
  mode: 'production',
  key: 'DMP2...',
});

A Commercial DMP2 Key carries exactly one signed Product Line. Every registered commercial package in an ordinary release must carry that same Product Line. A security-only release must carry it in both package metadata and its separate DMS1 certificate. Missing, conflicting or mismatched Product Line metadata remains uncovered and does not activate production. DMS1 never changes the key or grants another Product Line. Evaluation, Internal and legacy DMP1 keys do not use this Commercial Product Line field.

The signed key payload is not encrypted and may be readable in delivered browser code. Permitted embedding is expected, but the raw key must remain within the Customer scope allowed by the license. DMP2 omits Customer identity, contact details, Order reference, plan, price, separate payment and paid-through fields, and Developer limits. Commercial entitlement and per-key identifiers are random and opaque; the public status API does not expose them.

License validation runs entirely offline and never contacts Domternal: there is no online activation, license telemetry, metering, seat-counting or revocation request. A DMP2 Evaluation Key can remove visible evaluation notices only in explicitly selected evaluation mode and only through its signed UTC expiry day; it can never activate production mode. In production mode it remains visibly badged or marked. A DMP1 key is recognized only for legacy diagnostics: it leaves editor badges and marked-output notices in place and never authorizes guarded production use. A DMP2 Commercial Key does not activate before its signed not-before day. For ordinary and renewal keys that day is the Subscription start; an exceptional surviving-rights or remedy key can use the later decision or issuance day required by the license. During its paid Subscription and 14-day grace period, ordinary package coverage stops at its signed ordinaryReleaseThrough day; grace does not extend that boundary. After grace, a key without signed technical post-grace eligibility reports subscription-expired. A technically eligible key can continue coverage through ordinaryReleaseThrough, qualifying DMS1 releases and exact Section 10 remedy days, while the public status exposes a compatible derived fallbackThrough equal to ordinaryReleaseThrough. That technical marker does not prove 12 paid months or define the surviving legal scope: the Agreement and accepted Order define the legal scope, while the key and minimum durable entitlement state support later recognition of that scope, including whether it covers Qualified Builds, discontinuation final retained builds or another express surviving right. Post-expiry use is runtime-only for the exact permitted artifacts. Development, modification, rebuilding and new Applications require an active Subscription, subject only to the Agreement's narrow security, intellectual-property and replacement-key exceptions. A key-only reproduction changes no other code, dependency or feature and inherits the original build status. The contractual post-expiry Developer limit remains as a final derived value in the minimum durable entitlement state while it is relevant; supporting Order, payment and calculation records follow their separate retention periods; the runtime does not count people or expose that limit. Rights from different expiries remain attached to their own Commercial Keys. Coverage therefore uses both baked package release dates and the current UTC day reported by the runtime. Guarded headless production activates only when that Commercial Key covers every registered Pro package. Each JavaScript context that runs guarded headless work needs its own configuration. Activation is technical, not the license itself: permitted use is defined by LICENSE.md. See Installation and licensing for the complete setup.

Security-only releases use a separate signed DMS1 Security Release Certificate embedded in the package set; DMS1 does not add fields to or modify the Customer's DMP2 key. During the paid Subscription and grace, DMS1 requires a signed feature-baseline Release Date on or before ordinaryReleaseThrough; after grace, the key must also have technical post-grace eligibility. An exact Section 10 replacement date does not establish DMS1 baseline eligibility. A key without post-grace eligibility is never revived after grace. DMS1 does not renew a Subscription, move an ordinary-release boundary, change a Developer limit, unlock features or grant another Product Line. Post-expiry use is limited to the narrow security replacement of an eligible artifact, with no unrelated code, dependency or feature change, and the result inherits that artifact's status. The fixed Product Line Security Support End Date ends the obligation to issue further Security Updates, subject to mandatory law. An eligible DMS1 update signed and released during that period may remain usable afterward only within the same existing or surviving production right and limits; continued use does not make the Product Line supported or create, restore, renew or expand a right. The controlling terms are in Section 8 of LICENSE.md and the public security policy.

The standalone streamCompletion transport, direct StreamController starts and restarts, stream-plugin start and restart transactions, and AI runs against a detached editor are guarded before credentials are resolved, a request is sent or document review state changes. The transport rechecks before resolving credentials and again immediately before every fetch attempt, including retries, so detachment or a policy change during an asynchronous credential provider or retry delay cannot authorize a later request from stale state. Connected editors carrying either the AI extension or the standalone stream plugin use the visible evaluation surface instead.

Standalone transport rejects a blocked live boundary with DomternalProLicenseError. A built-in editor run first cleans up its pending review state, then reports the interruption through onError and storage.ai.lastError as a non-retryable AiError with code license; its cause retains the original DomternalProLicenseError.

Prompt builders and read-only review inspection remain available without a guard. Accept, Insert, Replace, Discard and recovery complete or release a result already obtained through a guarded request start; they do not send another AI request. Those completion and data-exit operations remain available if the editor detaches or its license state changes after the response enters review, so license handling cannot trap the user's document data or an already received result. Retry and Refine start a new request and therefore run the live request guard again.

Install

pnpm add @domternal-pro/core @domternal-pro/extension-ai @domternal/extension-markdown

@domternal/extension-markdown is a required peer dependency: the package imports its parser and serializer directly. It does not have to be registered as an editor extension, but it must resolve. @domternal-pro/core, @domternal/core and @domternal/pm are the other peers.

One copy of the core

@domternal/core must resolve to a single instance across your app. An extension belongs to the core that created it: Extension is its base class, the schema it contributes to is that copy's, and so are its plugin keys. Hand one to an editor built by another copy and nothing disagrees out loud, so this package checks at construction and refuses, naming the fix.

The free core performs the same check from its own side. This one exists because the peer range on @domternal/core is open-ended on purpose, so you may be holding a core released before that check existed. Full dedupe recipe per package manager and bundler: https://domternal.dev/v1/guides/single-prosemirror-copy/

Usage

import { Ai } from '@domternal-pro/extension-ai';
import '@domternal-pro/extension-ai/ai.css';

const editor = new Editor({
  extensions: [
    StarterKit,
    Ai.configure({
      connection: {
        endpoint: 'https://your-backend.example.com/ai',
        headers: async () => ({ authorization: `Bearer ${await getShortLivedToken()}` }),
      },
    }),
  ],
});

The toolbar, the text bubble menu, and the floating menu gain an Ask AI entry that opens the prompt panel: pick a command (Improve writing, Fix spelling & grammar, Make shorter/longer, Simplify, Change tone, Translate, Continue writing, Summarize) or type a free prompt.

Two wire dialects cover the documented request formats: openai-chat targets OpenAI Chat Completions and endpoints that implement the same supported wire contract, while anthropic-messages targets Anthropic Messages. A provider's label alone does not guarantee compatible authentication, streaming, CORS or response behavior. Prompts and replies travel as Markdown through the same pipeline as @domternal/extension-markdown.

Behavior worth knowing

• The suggestion streams into a LOCAL overlay; the document is not touched until Accept, which commits it as a single undo step.
• Selection commands keep the original text struck through and stream the replacement after it: a live red/green diff.
• An in-progress table is held back as a plain preview until complete; a partial table never reaches the document.
• Errors before the first token retry automatically. Nothing is ever retried after content has rendered.
• The document is locked for typing while the assistant writes.
• Keyboard: Mod-J opens the prompt panel (the shortcut option rebinds it, false removes it), Enter accepts a pending in-document review, and Escape closes the panel, stops a run (keeping the partial for review) or discards a review.
• Runs alongside Collaboration: un-accepted suggestions stay local to the author (peers see nothing until Accept), and a remote edit that touches the text under review dismisses the suggestion with a notice.

Commands and headless use

aiCommand(id, input?), aiPrompt({ prompt, scope? }), aiStop(), aiAccept(), aiReplace(), aiDiscard(), aiRetry(), aiRefine(instruction), aiOpenPanel(). State lives on editor.storage.ai.status (idle | thinking | writing | reviewing | error) with an aiStatus editor event and the failure behind an error on storage.ai.lastError; an aiOpen event fires whenever a toolbar, bubble or floating item asks for the prompt panel, which is what a custom UI listens to. Set defaultUI: false to bring your own panel and review bar. The transport is exported standalone as streamCompletion for use outside the editor.

Support

Report a defect that reproduces with synthetic content on the public tracker, using the Pro bug report template. Anything involving your own documents, your data or a collaboration update goes to email instead, and security vulnerabilities go to email only.

The Support and reporting issues policy explains where confirmed defects may be documented and how material notices are handled. Public channels are not a complete record of internal reports, investigations or other issues. Security vulnerabilities are handled through coordinated private disclosure.