feat(vnext): add CodeMirror completion adapter (#199)

## Summary

- add an explicit `@marimo-team/codemirror-sql/vnext/codemirror` entry
point with one caller-owned service and one session per `EditorView`
- translate composite CodeMirror document, context, and embedded-region
effects into one atomic session update
- map current relation results to exact CodeMirror edits with revision,
document, selection, context, and embedded-region guards
- coalesce exact-token catalog refreshes across active menus and empty
loading results without synchronous provider-driven dispatch
- contain Escape, close, blur, visibility, expiry, service-first
disposal, stale rejection, and repeated teardown races

## Why

The framework-independent service now has the identity and lease
contracts needed for a thin editor boundary. This adapter makes those
contracts usable without leaking CodeMirror into the core, while
preserving marimo's external completion sources and treating
transformed-document regions explicitly rather than guessing their
mapping.

## Validation

- 2,028 tests pass; 1 intentional expected failure
- adapter coverage: 97.70% statements, 95.86% branches, 100% functions,
99.01% lines
- all strict and loose-optional TypeScript configurations pass
- oxlint and test-integrity checks pass
- packed-consumer source covers the new package subpath; hosted package
CI will run the isolated install
- two independent exact-commit adversarial reviews approved `8d72a4c`


<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Adds a CodeMirror 6 adapter for the vNext SQL language service, exposed
as `@marimo-team/codemirror-sql/vnext/codemirror`. This enables exact,
guarded completion edits and atomic document/context/region updates
without leaking CodeMirror into the core.

- **New Features**
- New `sqlEditor` adapter with one document session per `EditorView`;
caller owns the shared `service`.
- Atomic updates: merges document changes with `support.contextEffect`
and `support.embeddedRegionsEffect`.
- Exact completion edits with revision/context/selection guards; maps
unrelated embedded regions through its own edit; ignores overlaps.
- Coalesced refresh intents keyed by service tokens; cancels on Escape,
blur (configurable), visibility loss, selection change, or lease expiry;
no synchronous provider-driven dispatch.
- Single `autocompletion` configuration; supports `externalSources` for
extra providers.
- New docs: `docs/vnext/codemirror-adapter.md`; subpath export added in
`package.json`; smoke test updated.

- **Migration**
- Import from `@marimo-team/codemirror-sql/vnext/codemirror`, create a
service from `@marimo-team/codemirror-sql/vnext`, then add
`support.extension` to the editor.
- Do not install a second `autocompletion` extension; pass extra
providers via `externalSources`.
- Update context/regions via `support.setContext` or by dispatching
`support.contextEffect` and `support.embeddedRegionsEffect`. If embedded
regions exist, include the complete resulting set on every
document-changing transaction.

<sup>Written for commit 8d72a4c.
Summary will update on new commits.</sup>

<a
href="https://cubic.dev/pr/marimo-team/codemirror-sql/pull/199?utm_source=github"
target="_blank" rel="noopener noreferrer"
data-no-image-dialog="true"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://www.cubic.dev/buttons/review-in-cubic-dark.svg"><source
media="(prefers-color-scheme: light)"
srcset="https://www.cubic.dev/buttons/review-in-cubic-light.svg"><img
alt="Review in cubic"
src="https://www.cubic.dev/buttons/review-in-cubic-dark.svg"></picture></a>

<!-- End of auto-generated description by cubic. -->

Author: Light2Dark

docs/vnext/codemirror-adapter.md

@@ -0,0 +1,95 @@
+# vNext CodeMirror Adapter
+
+Status: experimental
+
+Import: `@marimo-team/codemirror-sql/vnext/codemirror`
+
+`sqlEditor` connects one caller-owned vNext language service to one or more
+CodeMirror 6 views. Each view owns a document session, cancellation state,
+catalog-refresh intent, and revision subscription. Destroying a view disposes
+that view's session but never disposes the shared service.
+
+```ts
+import { EditorView } from "@codemirror/view";
+import {
+  createSqlLanguageService,
+  duckdbDialect,
+} from "@marimo-team/codemirror-sql/vnext";
+import {
+  sqlEditor,
+} from "@marimo-team/codemirror-sql/vnext/codemirror";
+
+const service = createSqlLanguageService({
+  dialects: [duckdbDialect()],
+});
+const support = sqlEditor({
+  initialContext: {
+    catalog: { scope: "connection-incarnation:1" },
+    dialect: "duckdb",
+  },
+  service,
+});
+const view = new EditorView({
+  doc: "SELECT * FROM ",
+  extensions: [support.extension],
+});
+
+support.setContext(view, {
+  catalog: { scope: "connection-incarnation:2" },
+  dialect: "duckdb",
+});
+
+view.destroy();
+service.dispose();
+```
+
+The adapter installs one coherent `autocompletion` configuration. Additional
+sources belong in `autocomplete.externalSources`; consumers should not install
+a second independently configured `autocompletion` extension.
+
+## Atomic inputs
+
+Context and document changes can share one CodeMirror transaction:
+
+```ts
+view.dispatch({
+  changes,
+  effects: support.contextEffect.of(nextContext),
+});
+```
+
+CodeMirror's composite `ChangeSet` is converted to sorted, non-overlapping
+pre-update UTF-16 changes and sent to the session exactly once.
+
+Embedded-language ranges are explicit. Their effect payload is the complete
+region set in the resulting document's coordinates:
+
+```ts
+view.dispatch({
+  changes,
+  effects: support.embeddedRegionsEffect.of(nextRegions),
+});
+```
+
+When the current document contains embedded regions, every document-changing
+transaction must include the complete resulting region set. The adapter fails
+closed instead of guessing how host-language delimiters map through edits.
+Region-only updates may use `setEmbeddedRegions`.
+
+The adapter's own completion edit is the narrow exception: it maps unrelated
+regions through the exact edit and includes the complete mapped set in the same
+transaction. A completion edit that overlaps an embedded region is ignored.
+
+## Completion currency
+
+The adapter does not use `validFor` or result mapping in this first slice.
+Every result and completion application rechecks the session revision,
+document identity, selection, and context generation.
+
+Loading completion results retain one bounded, token-correlated refresh intent,
+including empty results that open no menu. Only a session event carrying the
+exact task token can schedule a refresh. A newer request, document/context/
+region/selection change, Escape, configured blur, visibility loss, lease
+expiry, or view destruction cancels the intent. Refresh and close operations
+are always queued; provider and session callbacks never synchronously dispatch
+CodeMirror transactions.

docs/vnext/session-primitives.md

@@ -8,6 +8,9 @@ opaque revisions, dialect registration, lifecycle management, and
 parser-independent relation completion. Diagnostics, hover, navigation, and
 general expression completion are not yet available.
 
+CodeMirror consumers should use the separate
+[vNext CodeMirror adapter](./codemirror-adapter.md).
+
 See [source coordinates](./source-coordinates.md) for the shared UTF-16 range
 contract and the internal immutable source-snapshot model.
 

package.json

@@ -93,6 +93,12 @@
         "default": "./dist/vnext/index.js"
       }
     },
+    "./vnext/codemirror": {
+      "import": {
+        "types": "./dist/vnext/codemirror/index.d.ts",
+        "default": "./dist/vnext/codemirror/index.js"
+      }
+    },
     "./data/common-keywords.json": "./src/data/common-keywords.json",
     "./data/duckdb-keywords.json": "./src/data/duckdb-keywords.json"
   },

scripts/package-smoke.mjs

@@ -231,6 +231,7 @@ import {
   type SqlEmbeddedRegion,
   type SqlTextRange,
 } from "@marimo-team/codemirror-sql/vnext";
+import { sqlEditor } from "@marimo-team/codemirror-sql/vnext/codemirror";
 import commonKeywords from "@marimo-team/codemirror-sql/data/common-keywords.json" with { type: "json" };
 import duckdbKeywords from "@marimo-team/codemirror-sql/data/duckdb-keywords.json" with { type: "json" };
 
@@ -246,6 +247,10 @@ const parser = new NodeSqlParser();
 const service = createSqlLanguageService<HostContext>({
   dialects: [duckdbDialect()],
 });
+const editorSupport = sqlEditor({
+  initialContext: { dialect: "duckdb", engine: "local" },
+  service,
+});
 const embeddedRegions: readonly SqlEmbeddedRegion[] = [
   { from: 14, language: "python", to: 18 },
 ];
@@ -262,6 +267,7 @@ session.update({
 });
 
 void extensions;
+void editorSupport.extension;
 void parser;
 void range;
 void session;
@@ -278,6 +284,7 @@ void duckdbKeywords;
 import * as api from "@marimo-team/codemirror-sql";
 import * as dialects from "@marimo-team/codemirror-sql/dialects";
 import * as vnext from "@marimo-team/codemirror-sql/vnext";
+import * as vnextCodeMirror from "@marimo-team/codemirror-sql/vnext/codemirror";
 import commonKeywords from "@marimo-team/codemirror-sql/data/common-keywords.json" with { type: "json" };
 import duckdbKeywords from "@marimo-team/codemirror-sql/data/duckdb-keywords.json" with { type: "json" };
 
@@ -296,6 +303,9 @@ if (
 ) {
   throw new Error("vNext package exports are incomplete");
 }
+if (typeof vnextCodeMirror.sqlEditor !== "function") {
+  throw new Error("vNext CodeMirror package exports are incomplete");
+}
 for (const dialect of [
   vnext.bigQueryDialect(),
   vnext.dremioDialect(),