feat(vnext): expose statement boundaries

Author: Light2Dark

docs/vnext/session-primitives.md

@@ -14,6 +14,47 @@ CodeMirror consumers should use the separate
 See [source coordinates](./source-coordinates.md) for the shared UTF-16 range
 contract and the internal immutable source-snapshot model.
 
+Statement boundaries are available as a synchronous structural query:
+
+```ts
+const result = session.statementBoundaryAt({
+  affinity: "left",
+  position: cursorOffset,
+});
+
+if (
+  session.isCurrent(result.revision) &&
+  result.boundary.boundaryQuality === "exact" &&
+  result.boundary.hasCode
+) {
+  executeRange(result.boundary.source);
+}
+```
+
+The immutable result carries the current session revision. Exact boundaries
+expose their full extent, source range, optional terminator, lexical end state,
+and a nullable range from the first through last SQL code token. Source ranges
+retain attached
+whitespace and comments; they are factual lexical boundaries, not pre-trimmed
+visual selections. The `code` range excludes leading and trailing separator
+trivia so presentation layers do not need to re-lex the document. Opaque
+procedural, custom-delimiter, and resource-limited
+regions expose only their extent and reason, so consumers cannot mistake them
+for safely executable SQL.
+
+Viewport consumers can retrieve every structural boundary in one half-open
+range without probing or re-lexing the document:
+
+```ts
+const visible = session.statementBoundariesIntersecting({
+  from: viewport.from,
+  to: viewport.to,
+});
+```
+
+The query runs in logarithmic lookup time plus the number of intersecting
+boundaries and returns a frozen, revision-stamped array.
+
 ## Example
 
 ```ts

scripts/package-smoke.mjs

@@ -207,6 +207,13 @@ session.update({
   baseRevision: session.revision,
   document: { kind: "replace", text: "SELECT * FROM {next_df}" },
 });
+const statement = session.statementBoundaryAt({ affinity: "left", position: 0 });
+if (
+  statement.boundary.boundaryQuality !== "exact" ||
+  !statement.boundary.hasCode
+) {
+  throw new Error("The packaged vNext statement boundary was unavailable");
+}
 service.dispose();
 `,
   );
@@ -229,6 +236,7 @@ import {
   duckdbDialect,
   type SqlDocumentContext,
   type SqlEmbeddedRegion,
+  type SqlStatementBoundaryAtResult,
   type SqlTextRange,
 } from "@marimo-team/codemirror-sql/vnext";
 import { sqlEditor } from "@marimo-team/codemirror-sql/vnext/codemirror";
@@ -265,12 +273,17 @@ session.update({
   baseRevision: session.revision,
   document: { kind: "changes", changes: [] },
 });
+const statement: SqlStatementBoundaryAtResult = session.statementBoundaryAt({
+  affinity: "left",
+  position: 0,
+});
 
 void extensions;
 void editorSupport.extension;
 void parser;
 void range;
 void session;
+void statement;
 void BigQueryDialect;
 void DremioDialect;
 void commonKeywords;
@@ -349,6 +362,20 @@ const updatedRevision = session.update({
 if (session.isCurrent(originalRevision) || !session.isCurrent(updatedRevision)) {
   throw new Error("The packaged vNext session violated revision identity");
 }
+const statement = session.statementBoundaryAt({ affinity: "left", position: 0 });
+const visible = session.statementBoundariesIntersecting({
+  from: 0,
+  to: 23,
+});
+if (
+  statement.revision !== updatedRevision ||
+  statement.boundary.boundaryQuality !== "exact" ||
+  !statement.boundary.hasCode ||
+  visible.revision !== updatedRevision ||
+  visible.boundaries.length !== 1
+) {
+  throw new Error("The packaged vNext statement boundary is invalid");
+}
 service.dispose();
 `,
   );