@nimbalyst/extension-sdk 0.4.0 → 0.6.0

package/dist/gitOperationLog.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Wire contract and pure selectors for the host's Git operation journal.
+ *
+ * The journal lives in the Electron main process and is published over two host
+ * channels: `git:operation-log:get` (hydration) and `git:operation-log-changed`
+ * (live upsert/clear). Both the Git extension's Output tab and Nimbalyst's own
+ * menu-bar indicator project the same journal, so the merge and "what is running
+ * right now" rules have to agree exactly -- two surfaces disagreeing about
+ * whether a push is still in flight is the bug this module exists to prevent.
+ *
+ * Everything here is pure: no React, no IPC, no host runtime.
+ */
+/** Terminal states are everything except `running`. */
+export type GitOperationStatus = 'running' | 'success' | 'error' | 'interrupted';
+/** Who started the command. Absent on journals written before agent activity existed. */
+export type GitOperationSource = 'nimbalyst' | 'agent';
+/**
+ * How the command reached Git. `git` is an app-owned direct invocation with a
+ * meaningful `args` array; `shell` is an observed command line whose Git segment
+ * we detected but did not spawn ourselves.
+ */
+export type GitOperationExecutor = 'git' | 'shell';
+/** An entry exactly as it crosses the IPC boundary (timestamps are epoch ms). */
+export interface GitOperationLogWireEntry {
+    id: string;
+    timestamp: number;
+    updatedAt: number;
+    /** Redacted, display-ready command text. */
+    command: string;
+    executable: 'git';
+    args: string[];
+    cwd: string;
+    status: GitOperationStatus;
+    output: string;
+    stdout: string;
+    stderr: string;
+    error?: string;
+    exitCode?: number;
+    durationMs?: number;
+    source?: GitOperationSource;
+    executor?: GitOperationExecutor;
+    sessionId?: string;
+    provider?: string;
+    providerToolCallId?: string;
+}
+export type GitOperationLogEvent = {
+    workspacePath: string;
+    type: 'upsert';
+    entry: GitOperationLogWireEntry;
+} | {
+    workspacePath: string;
+    type: 'clear';
+};
+/**
+ * Window CustomEvent the host dispatches when the user asks to see Git activity
+ * detail (for example from the menu-bar indicator's running-command row).
+ *
+ * The Git panel owns which tab is showing, and that state is private to the
+ * extension bundle. Rather than let the host reach into it, the host states the
+ * intent and the panel decides how to honour it. `detail.workspacePath` lets a
+ * panel bound to a different workspace ignore the request.
+ */
+export declare const GIT_SHOW_OUTPUT_REQUEST_EVENT = "nimbalyst:git-show-output";
+export interface GitShowOutputRequestDetail {
+    workspacePath: string;
+}
+/** The minimum shape the selectors below need. */
+interface MergeableEntry {
+    id: string;
+    timestamp: number | Date;
+    updatedAt: number;
+    status: GitOperationStatus;
+}
+/**
+ * Fill in metadata that predates the field. A journal written before agent
+ * activity existed only ever recorded app-owned direct `git` invocations, so
+ * that is what an absent `source`/`executor` means -- resolved here at the
+ * projection boundary rather than by rewriting the persisted journal.
+ */
+export declare function normalizeGitOperationEntry(entry: GitOperationLogWireEntry): GitOperationLogWireEntry & {
+    source: GitOperationSource;
+    executor: GitOperationExecutor;
+};
+/**
+ * Fold incoming entries into the current list, newest write per id wins.
+ *
+ * `updatedAt` is the tiebreak rather than arrival order because hydration and
+ * the live subscription race: a `git:operation-log:get` response can land after
+ * upserts it predates, and applying it blindly would rewind a finished
+ * operation back to `running`.
+ */
+export declare function mergeGitOperationEntries<T extends MergeableEntry>(current: T[], incoming: T[]): T[];
+/** Every entry still in flight, oldest first. */
+export declare function selectRunningGitOperations<T extends MergeableEntry>(entries: T[]): T[];
+/**
+ * The entry a single-line indicator should name. Newest start wins: when an
+ * agent kicks off a fetch while a push is already running, the thing the user
+ * just caused is the more informative label.
+ */
+export declare function selectLatestRunningGitOperation<T extends MergeableEntry>(entries: T[]): T | undefined;
+/** The most recently updated entry that has already settled, if any. */
+export declare function selectLatestTerminalGitOperation<T extends MergeableEntry>(entries: T[]): T | undefined;
+export {};
+//# sourceMappingURL=gitOperationLog.d.ts.map

package/dist/gitOperationLog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gitOperationLog.d.ts","sourceRoot":"","sources":["../src/gitOperationLog.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,uDAAuD;AACvD,MAAM,MAAM,kBAAkB,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,GAAG,aAAa,CAAC;AAEjF,yFAAyF;AACzF,MAAM,MAAM,kBAAkB,GAAG,WAAW,GAAG,OAAO,CAAC;AAEvD;;;;GAIG;AACH,MAAM,MAAM,oBAAoB,GAAG,KAAK,GAAG,OAAO,CAAC;AAEnD,iFAAiF;AACjF,MAAM,WAAW,wBAAwB;IACvC,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,4CAA4C;IAC5C,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,KAAK,CAAC;IAClB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,kBAAkB,CAAC;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,kBAAkB,CAAC;IAC5B,QAAQ,CAAC,EAAE,oBAAoB,CAAC;IAChC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,MAAM,oBAAoB,GAC5B;IAAE,aAAa,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,wBAAwB,CAAA;CAAE,GAC1E;IAAE,aAAa,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,CAAC;AAE7C;;;;;;;;GAQG;AACH,eAAO,MAAM,6BAA6B,8BAA8B,CAAC;AAEzE,MAAM,WAAW,0BAA0B;IACzC,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,kDAAkD;AAClD,UAAU,cAAc;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,kBAAkB,CAAC;CAC5B;AAMD;;;;;GAKG;AACH,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,wBAAwB,GAC9B,wBAAwB,GAAG;IAC5B,MAAM,EAAE,kBAAkB,CAAC;IAC3B,QAAQ,EAAE,oBAAoB,CAAC;CAChC,CAMA;AAED;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CAAC,CAAC,SAAS,cAAc,EAC/D,OAAO,EAAE,CAAC,EAAE,EACZ,QAAQ,EAAE,CAAC,EAAE,GACZ,CAAC,EAAE,CAWL;AAED,iDAAiD;AACjD,wBAAgB,0BAA0B,CAAC,CAAC,SAAS,cAAc,EAAE,OAAO,EAAE,CAAC,EAAE,GAAG,CAAC,EAAE,CAEtF;AAED;;;;GAIG;AACH,wBAAgB,+BAA+B,CAAC,CAAC,SAAS,cAAc,EACtE,OAAO,EAAE,CAAC,EAAE,GACX,CAAC,GAAG,SAAS,CASf;AAED,wEAAwE;AACxE,wBAAgB,gCAAgC,CAAC,CAAC,SAAS,cAAc,EACvE,OAAO,EAAE,CAAC,EAAE,GACX,CAAC,GAAG,SAAS,CASf"}

package/dist/gitOperationLog.js

@@ -0,0 +1,88 @@
+/**
+ * Wire contract and pure selectors for the host's Git operation journal.
+ *
+ * The journal lives in the Electron main process and is published over two host
+ * channels: `git:operation-log:get` (hydration) and `git:operation-log-changed`
+ * (live upsert/clear). Both the Git extension's Output tab and Nimbalyst's own
+ * menu-bar indicator project the same journal, so the merge and "what is running
+ * right now" rules have to agree exactly -- two surfaces disagreeing about
+ * whether a push is still in flight is the bug this module exists to prevent.
+ *
+ * Everything here is pure: no React, no IPC, no host runtime.
+ */
+/**
+ * Window CustomEvent the host dispatches when the user asks to see Git activity
+ * detail (for example from the menu-bar indicator's running-command row).
+ *
+ * The Git panel owns which tab is showing, and that state is private to the
+ * extension bundle. Rather than let the host reach into it, the host states the
+ * intent and the panel decides how to honour it. `detail.workspacePath` lets a
+ * panel bound to a different workspace ignore the request.
+ */
+export const GIT_SHOW_OUTPUT_REQUEST_EVENT = 'nimbalyst:git-show-output';
+function toMillis(timestamp) {
+    return typeof timestamp === 'number' ? timestamp : timestamp.getTime();
+}
+/**
+ * Fill in metadata that predates the field. A journal written before agent
+ * activity existed only ever recorded app-owned direct `git` invocations, so
+ * that is what an absent `source`/`executor` means -- resolved here at the
+ * projection boundary rather than by rewriting the persisted journal.
+ */
+export function normalizeGitOperationEntry(entry) {
+    return {
+        ...entry,
+        source: entry.source ?? 'nimbalyst',
+        executor: entry.executor ?? 'git',
+    };
+}
+/**
+ * Fold incoming entries into the current list, newest write per id wins.
+ *
+ * `updatedAt` is the tiebreak rather than arrival order because hydration and
+ * the live subscription race: a `git:operation-log:get` response can land after
+ * upserts it predates, and applying it blindly would rewind a finished
+ * operation back to `running`.
+ */
+export function mergeGitOperationEntries(current, incoming) {
+    const byId = new Map(current.map((entry) => [entry.id, entry]));
+    for (const entry of incoming) {
+        const existing = byId.get(entry.id);
+        if (!existing || entry.updatedAt >= existing.updatedAt) {
+            byId.set(entry.id, entry);
+        }
+    }
+    return Array.from(byId.values()).sort((a, b) => toMillis(a.timestamp) - toMillis(b.timestamp));
+}
+/** Every entry still in flight, oldest first. */
+export function selectRunningGitOperations(entries) {
+    return entries.filter((entry) => entry.status === 'running');
+}
+/**
+ * The entry a single-line indicator should name. Newest start wins: when an
+ * agent kicks off a fetch while a push is already running, the thing the user
+ * just caused is the more informative label.
+ */
+export function selectLatestRunningGitOperation(entries) {
+    let latest;
+    for (const entry of entries) {
+        if (entry.status !== 'running')
+            continue;
+        if (!latest || toMillis(entry.timestamp) >= toMillis(latest.timestamp)) {
+            latest = entry;
+        }
+    }
+    return latest;
+}
+/** The most recently updated entry that has already settled, if any. */
+export function selectLatestTerminalGitOperation(entries) {
+    let latest;
+    for (const entry of entries) {
+        if (entry.status === 'running')
+            continue;
+        if (!latest || entry.updatedAt >= latest.updatedAt) {
+            latest = entry;
+        }
+    }
+    return latest;
+}

package/dist/index.d.ts

@@ -25,7 +25,8 @@
 export { REQUIRED_EXTERNALS, EXTERNAL_PATTERNS, ROLLUP_EXTERNALS, type RequiredExternal, } from './externals.js';
 export * from './types/index.js';
 export { useEditorLifecycle, type UseEditorLifecycleOptions, type UseEditorLifecycleResult, type DiffState, } from './useEditorLifecycle.js';
-export { useCollaborativeEditor, COLLAB_INIT_ORIGIN, type UseCollaborativeEditorConfig, type UseCollaborativeEditorResult, } from './useCollaborativeEditor.js';
+export { editorHostSupports, editorHostCapabilityGap, } from './editorHostCapabilities.js';
+export { useCollaborativeEditor, COLLAB_INIT_ORIGIN, type UseCollaborativeEditorConfig, type UseCollaborativeEditorResult, type CollaborativeBindingHandle, } from './useCollaborativeEditor.js';
 export { createTextCollabContentAdapter, reconstructCollabContentAdapterFromDescriptor, TEXT_COLLAB_DEFAULT_FIELD, type TextCollabContentAdapterOptions, } from './collab/createTextCollabContentAdapter.js';
 export { applyTextDiff, replaceYText, type ApplyTextEdit, } from './collab/textReplacement.js';
 export { useDocumentPath, type DocumentPathContextValue, } from './documentPath.js';
@@ -37,4 +38,5 @@ export { buildFileDirectoryTree, getFileDirectoryPaths, getFilePathBasename, get
 export { validateExtensionBundle, printValidationResult, type ValidationResult, } from './validate.js';
 export { validateBackendModules, assertBackendModulesValid, effectiveModulePermissions, validateAgentProviders, assertAgentProvidersValid, extractBackendModuleIds, MAX_AGENT_PROVIDERS_PER_EXTENSION, type BackendModuleValidationIssue, type AgentProviderValidationIssue, } from './manifestValidation.js';
 export type { AgentProtocol, ProtocolEvent, ProtocolMessage, ProtocolSession, SessionOptions, ProtocolEventType, ToolResult as ProtocolToolResult, MCPServerConfig, RawProtocolSession, AgentProtocolHost, PermissionMode, McpToolDefinition, } from './agents/index.js';
+export { screenshotService } from '@nimbalyst/runtime';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAGH,OAAO,EACL,kBAAkB,EAClB,iBAAiB,EACjB,gBAAgB,EAChB,KAAK,gBAAgB,GACtB,MAAM,gBAAgB,CAAC;AAGxB,cAAc,kBAAkB,CAAC;AAGjC,OAAO,EACL,kBAAkB,EAClB,KAAK,yBAAyB,EAC9B,KAAK,wBAAwB,EAC7B,KAAK,SAAS,GACf,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EACL,sBAAsB,EACtB,kBAAkB,EAClB,KAAK,4BAA4B,EACjC,KAAK,4BAA4B,GAClC,MAAM,6BAA6B,CAAC;AAErC,OAAO,EACL,8BAA8B,EAC9B,6CAA6C,EAC7C,yBAAyB,EACzB,KAAK,+BAA+B,GACrC,MAAM,4CAA4C,CAAC;AAEpD,OAAO,EACL,aAAa,EACb,YAAY,EACZ,KAAK,aAAa,GACnB,MAAM,6BAA6B,CAAC;AAGrC,OAAO,EACL,eAAe,EACf,KAAK,wBAAwB,GAC9B,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAIrD,OAAO,EACL,oBAAoB,EACpB,sBAAsB,EACtB,0BAA0B,EAC1B,2BAA2B,EAC3B,KAAK,wBAAwB,EAC7B,KAAK,yBAAyB,EAC9B,KAAK,2BAA2B,GACjC,MAAM,wBAAwB,CAAC;AAGhC,OAAO,EACL,kBAAkB,EAClB,KAAK,YAAY,EACjB,KAAK,mBAAmB,GACzB,MAAM,yBAAyB,CAAC;AAGjC,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAGhE,OAAO,EACL,sBAAsB,EACtB,qBAAqB,EACrB,mBAAmB,EACnB,4BAA4B,EAC5B,iBAAiB,EACjB,KAAK,iBAAiB,GACvB,MAAM,wBAAwB,CAAC;AAGhC,OAAO,EACL,uBAAuB,EACvB,qBAAqB,EACrB,KAAK,gBAAgB,GACtB,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,sBAAsB,EACtB,yBAAyB,EACzB,0BAA0B,EAC1B,sBAAsB,EACtB,yBAAyB,EACzB,uBAAuB,EACvB,iCAAiC,EACjC,KAAK,4BAA4B,EACjC,KAAK,4BAA4B,GAClC,MAAM,yBAAyB,CAAC;AAYjC,YAAY,EACV,aAAa,EACb,aAAa,EACb,eAAe,EACf,eAAe,EACf,cAAc,EACd,iBAAiB,EACjB,UAAU,IAAI,kBAAkB,EAChC,eAAe,EACf,kBAAkB,EAClB,iBAAiB,EACjB,cAAc,EACd,iBAAiB,GAClB,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAGH,OAAO,EACL,kBAAkB,EAClB,iBAAiB,EACjB,gBAAgB,EAChB,KAAK,gBAAgB,GACtB,MAAM,gBAAgB,CAAC;AAGxB,cAAc,kBAAkB,CAAC;AAGjC,OAAO,EACL,kBAAkB,EAClB,KAAK,yBAAyB,EAC9B,KAAK,wBAAwB,EAC7B,KAAK,SAAS,GACf,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EACL,kBAAkB,EAClB,uBAAuB,GACxB,MAAM,6BAA6B,CAAC;AAErC,OAAO,EACL,sBAAsB,EACtB,kBAAkB,EAClB,KAAK,4BAA4B,EACjC,KAAK,4BAA4B,EACjC,KAAK,0BAA0B,GAChC,MAAM,6BAA6B,CAAC;AAErC,OAAO,EACL,8BAA8B,EAC9B,6CAA6C,EAC7C,yBAAyB,EACzB,KAAK,+BAA+B,GACrC,MAAM,4CAA4C,CAAC;AAEpD,OAAO,EACL,aAAa,EACb,YAAY,EACZ,KAAK,aAAa,GACnB,MAAM,6BAA6B,CAAC;AAGrC,OAAO,EACL,eAAe,EACf,KAAK,wBAAwB,GAC9B,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAIrD,OAAO,EACL,oBAAoB,EACpB,sBAAsB,EACtB,0BAA0B,EAC1B,2BAA2B,EAC3B,KAAK,wBAAwB,EAC7B,KAAK,yBAAyB,EAC9B,KAAK,2BAA2B,GACjC,MAAM,wBAAwB,CAAC;AAGhC,OAAO,EACL,kBAAkB,EAClB,KAAK,YAAY,EACjB,KAAK,mBAAmB,GACzB,MAAM,yBAAyB,CAAC;AAGjC,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAGhE,OAAO,EACL,sBAAsB,EACtB,qBAAqB,EACrB,mBAAmB,EACnB,4BAA4B,EAC5B,iBAAiB,EACjB,KAAK,iBAAiB,GACvB,MAAM,wBAAwB,CAAC;AAGhC,OAAO,EACL,uBAAuB,EACvB,qBAAqB,EACrB,KAAK,gBAAgB,GACtB,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,sBAAsB,EACtB,yBAAyB,EACzB,0BAA0B,EAC1B,sBAAsB,EACtB,yBAAyB,EACzB,uBAAuB,EACvB,iCAAiC,EACjC,KAAK,4BAA4B,EACjC,KAAK,4BAA4B,GAClC,MAAM,yBAAyB,CAAC;AAYjC,YAAY,EACV,aAAa,EACb,aAAa,EACb,eAAe,EACf,eAAe,EACf,cAAc,EACd,iBAAiB,EACjB,UAAU,IAAI,kBAAkB,EAChC,eAAe,EACf,kBAAkB,EAClB,iBAAiB,EACjB,cAAc,EACd,iBAAiB,GAClB,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/index.js

@@ -28,6 +28,7 @@ export { REQUIRED_EXTERNALS, EXTERNAL_PATTERNS, ROLLUP_EXTERNALS, } from './exte
 export * from './types/index.js';
 // Re-export hooks
 export { useEditorLifecycle, } from './useEditorLifecycle.js';
+export { editorHostSupports, editorHostCapabilityGap, } from './editorHostCapabilities.js';
 export { useCollaborativeEditor, COLLAB_INIT_ORIGIN, } from './useCollaborativeEditor.js';
 export { createTextCollabContentAdapter, reconstructCollabContentAdapterFromDescriptor, TEXT_COLLAB_DEFAULT_FIELD, } from './collab/createTextCollabContentAdapter.js';
 export { applyTextDiff, replaceYText, } from './collab/textReplacement.js';
@@ -46,3 +47,5 @@ export { buildFileDirectoryTree, getFileDirectoryPaths, getFilePathBasename, get
 // Re-export validation
 export { validateExtensionBundle, printValidationResult, } from './validate.js';
 export { validateBackendModules, assertBackendModulesValid, effectiveModulePermissions, validateAgentProviders, assertAgentProvidersValid, extractBackendModuleIds, MAX_AGENT_PROVIDERS_PER_EXTENSION, } from './manifestValidation.js';
+// Host-owned native screenshots for every built-in and extension editor.
+export { screenshotService } from '@nimbalyst/runtime';

package/dist/types/collab.d.ts

@@ -30,6 +30,7 @@
  * @see CollabContentAdapter -- the former name, kept as a deprecated alias.
  */
 import type { Doc } from 'yjs';
+import type { CommentAnchor } from './comments';
 export type CollabContentFileSource = string | Uint8Array;
 /**
  * Serializable description of a CollabContentAdapter that lets the HOST
@@ -52,6 +53,17 @@ export interface CollabCodecMigration {
     to: number;
     run(yDoc: Doc): void;
 }
+/**
+ * Structured-comment anchor support for headless hosts. Hosts invoke these
+ * reads against a detached, disposable Y.Doc snapshot rather than the live
+ * collaborative document, so an accidental mutation cannot alter or sync the
+ * real document. Codecs should still treat the snapshot as read-only.
+ */
+export interface CollabCommentAnchorCodec {
+    handles(anchor: CommentAnchor): boolean;
+    getState(snapshot: Doc, anchor: CommentAnchor): 'attached' | 'orphaned';
+    describe(snapshot: Doc, anchor: CommentAnchor): string;
+}
 /** @deprecated Renamed to {@link CollabCodecMigration}. */
 export type CollabContentAdapterMigration = CollabCodecMigration;
 export interface CollabCodec<TStructured = unknown> {
@@ -95,9 +107,26 @@ export interface CollabCodec<TStructured = unknown> {
      *  `applyStructuredPatch`. */
     toStructured?(yDoc: Doc): TStructured;
     /** Optional: write structured edits back. Paired with
-     *  `toStructured`. AI-write surface is gated on the presence of
-     *  both this and `toStructured`. */
+     *  `toStructured`. The PREFERRED AI-write surface: implementing
+     *  both lets an agent edit this document type structurally.
+     *
+     *  It is NOT a gate. When an adapter does not implement the pair,
+     *  an agent edit falls back to `exportToFile` -> text replacement
+     *  -> `applyFromFile`, so every adapter is AI-writable whether or
+     *  not it opted in. Two consequences an adapter author must know:
+     *
+     *   - `applyFromFile` is called with agent-authored content, not
+     *     just on-disk content, so it must be safe to call on a
+     *     populated Y.Doc (it already must be) AND must be able to
+     *     consume its own `exportToFile` output unchanged. That
+     *     round-trip is asserted for every registered adapter in
+     *     `codecOnlyHeadlessEdit.test.ts`.
+     *   - The fallback rewrites the whole document, so a concurrent
+     *     human edit can interleave. Implement the structured pair to
+     *     get minimal deltas instead. */
     applyStructuredPatch?(yDoc: Doc, patch: unknown): void;
+    /** Optional snapshot-isolated resolver for structured comment anchors. */
+    commentAnchors?: CollabCommentAnchorCodec;
     /** Optional: produce a snapshot for revision history. Defaults to
      *  `Y.encodeStateAsUpdateV2(yDoc)`. Override if you need a denser
      *  snapshot format. */

package/dist/types/collab.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"collab.d.ts","sourceRoot":"","sources":["../../src/types/collab.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,KAAK,CAAC;AAE/B,MAAM,MAAM,uBAAuB,GAAG,MAAM,GAAG,UAAU,CAAC;AAE1D;;;;;;GAMG;AACH,MAAM,WAAW,2BAA2B;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,MAAM,uBAAuB,GAAG,2BAA2B,CAAC;AAElE,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,GAAG,CAAC,IAAI,EAAE,GAAG,GAAG,IAAI,CAAC;CACtB;AAED,2DAA2D;AAC3D,MAAM,MAAM,6BAA6B,GAAG,oBAAoB,CAAC;AAEjE,MAAM,WAAW,WAAW,CAAC,WAAW,GAAG,OAAO;IAChD,oEAAoE;IACpE,YAAY,EAAE,MAAM,CAAC;IAErB;;qEAEiE;IACjE,cAAc,EAAE,MAAM,EAAE,CAAC;IAEzB,iEAAiE;IACjE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;oBAEgB;IAChB,aAAa,EAAE,MAAM,CAAC;IAEtB;;;yBAGqB;IACrB,UAAU,CAAC,EAAE,oBAAoB,EAAE,CAAC;IAEpC;;oEAEgE;IAChE,OAAO,CAAC,IAAI,EAAE,GAAG,GAAG,OAAO,CAAC;IAE5B;gEAC4D;IAC5D,YAAY,CAAC,IAAI,EAAE,GAAG,EAAE,MAAM,EAAE,uBAAuB,GAAG,IAAI,CAAC;IAE/D;;;;yCAIqC;IACrC,aAAa,CAAC,IAAI,EAAE,GAAG,EAAE,MAAM,EAAE,uBAAuB,GAAG,IAAI,CAAC;IAEhE,gEAAgE;IAChE,YAAY,CAAC,IAAI,EAAE,GAAG,GAAG,MAAM,GAAG,UAAU,CAAC;IAE7C;qEACiE;IACjE,WAAW,CAAC,IAAI,EAAE,GAAG,GAAG,MAAM,CAAC;IAE/B;;kCAE8B;IAC9B,YAAY,CAAC,CAAC,IAAI,EAAE,GAAG,GAAG,WAAW,CAAC;IAEtC;;wCAEoC;IACpC,oBAAoB,CAAC,CAAC,IAAI,EAAE,GAAG,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;IAEvD;;2BAEuB;IACvB,sBAAsB,CAAC,CAAC,IAAI,EAAE,GAAG,GAAG,UAAU,CAAC;IAE/C;0CACsC;IACtC,uBAAuB,CAAC,CAAC,IAAI,EAAE,GAAG,EAAE,KAAK,EAAE,UAAU,GAAG,IAAI,CAAC;IAE7D;;;qEAGiE;IACjE,sBAAsB,CAAC,EAAE,uBAAuB,CAAC;CAClD;AAED;;;;GAIG;AACH,MAAM,MAAM,oBAAoB,CAAC,WAAW,GAAG,OAAO,IAAI,WAAW,CAAC,WAAW,CAAC,CAAC;AAEnF;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACrC;;;;;;;OAOG;IACH,sBAAsB,CAAC,KAAK,EAAE,WAAW,GAAG;QAAE,OAAO,IAAI,IAAI,CAAA;KAAE,CAAC;CACjE"}
+{"version":3,"file":"collab.d.ts","sourceRoot":"","sources":["../../src/types/collab.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,KAAK,CAAC;AAC/B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,MAAM,MAAM,uBAAuB,GAAG,MAAM,GAAG,UAAU,CAAC;AAE1D;;;;;;GAMG;AACH,MAAM,WAAW,2BAA2B;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,MAAM,uBAAuB,GAAG,2BAA2B,CAAC;AAElE,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,GAAG,CAAC,IAAI,EAAE,GAAG,GAAG,IAAI,CAAC;CACtB;AAED;;;;;GAKG;AACH,MAAM,WAAW,wBAAwB;IACvC,OAAO,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC;IACxC,QAAQ,CAAC,QAAQ,EAAE,GAAG,EAAE,MAAM,EAAE,aAAa,GAAG,UAAU,GAAG,UAAU,CAAC;IACxE,QAAQ,CAAC,QAAQ,EAAE,GAAG,EAAE,MAAM,EAAE,aAAa,GAAG,MAAM,CAAC;CACxD;AAED,2DAA2D;AAC3D,MAAM,MAAM,6BAA6B,GAAG,oBAAoB,CAAC;AAEjE,MAAM,WAAW,WAAW,CAAC,WAAW,GAAG,OAAO;IAChD,oEAAoE;IACpE,YAAY,EAAE,MAAM,CAAC;IAErB;;qEAEiE;IACjE,cAAc,EAAE,MAAM,EAAE,CAAC;IAEzB,iEAAiE;IACjE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;oBAEgB;IAChB,aAAa,EAAE,MAAM,CAAC;IAEtB;;;yBAGqB;IACrB,UAAU,CAAC,EAAE,oBAAoB,EAAE,CAAC;IAEpC;;oEAEgE;IAChE,OAAO,CAAC,IAAI,EAAE,GAAG,GAAG,OAAO,CAAC;IAE5B;gEAC4D;IAC5D,YAAY,CAAC,IAAI,EAAE,GAAG,EAAE,MAAM,EAAE,uBAAuB,GAAG,IAAI,CAAC;IAE/D;;;;yCAIqC;IACrC,aAAa,CAAC,IAAI,EAAE,GAAG,EAAE,MAAM,EAAE,uBAAuB,GAAG,IAAI,CAAC;IAEhE,gEAAgE;IAChE,YAAY,CAAC,IAAI,EAAE,GAAG,GAAG,MAAM,GAAG,UAAU,CAAC;IAE7C;qEACiE;IACjE,WAAW,CAAC,IAAI,EAAE,GAAG,GAAG,MAAM,CAAC;IAE/B;;kCAE8B;IAC9B,YAAY,CAAC,CAAC,IAAI,EAAE,GAAG,GAAG,WAAW,CAAC;IAEtC;;;;;;;;;;;;;;;;;yCAiBqC;IACrC,oBAAoB,CAAC,CAAC,IAAI,EAAE,GAAG,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;IAEvD,0EAA0E;IAC1E,cAAc,CAAC,EAAE,wBAAwB,CAAC;IAE1C;;2BAEuB;IACvB,sBAAsB,CAAC,CAAC,IAAI,EAAE,GAAG,GAAG,UAAU,CAAC;IAE/C;0CACsC;IACtC,uBAAuB,CAAC,CAAC,IAAI,EAAE,GAAG,EAAE,KAAK,EAAE,UAAU,GAAG,IAAI,CAAC;IAE7D;;;qEAGiE;IACjE,sBAAsB,CAAC,EAAE,uBAAuB,CAAC;CAClD;AAED;;;;GAIG;AACH,MAAM,MAAM,oBAAoB,CAAC,WAAW,GAAG,OAAO,IACpD,WAAW,CAAC,WAAW,CAAC,CAAC;AAE3B;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACrC;;;;;;;OAOG;IACH,sBAAsB,CAAC,KAAK,EAAE,WAAW,GAAG;QAAE,OAAO,IAAI,IAAI,CAAA;KAAE,CAAC;CACjE"}

package/dist/types/comments.d.ts

@@ -0,0 +1,104 @@
+/** Editor-neutral collaborative comment contracts exposed to extensions. */
+export type TextQuoteCommentAnchor = {
+    kind: 'text-quote';
+    exact: string;
+    prefix?: string;
+    suffix?: string;
+};
+export type EntityCommentAnchor = {
+    kind: 'entity';
+    entityType: string;
+    entityId: string;
+    field?: string;
+    labelSnapshot?: string;
+};
+export type CommentAnchor = TextQuoteCommentAnchor | EntityCommentAnchor;
+export type CollaborativeUserCommentActor = {
+    kind: 'user';
+    userId?: string;
+    displayName: string;
+};
+export type CollaborativeAgentCommentActor = {
+    kind: 'agent';
+    sessionId: string;
+    sessionName: string;
+    onBehalfOfUserId: string;
+    onBehalfOfDisplayName?: string;
+};
+export type CollaborativeCommentActor = CollaborativeUserCommentActor | CollaborativeAgentCommentActor;
+export interface CollaborativeComment {
+    readonly actor?: CollaborativeCommentActor;
+    readonly author: string;
+    readonly clientMutationId?: string;
+    readonly content: string;
+    readonly deleted: boolean;
+    readonly id: string;
+    readonly replyToCommentId?: string;
+    readonly timeStamp: number;
+    readonly type: 'comment';
+}
+export interface CollaborativeCommentThread {
+    readonly anchor?: CommentAnchor;
+    readonly comments: ReadonlyArray<CollaborativeComment>;
+    readonly id: string;
+    readonly quote: string;
+    readonly resolved: boolean;
+    readonly type: 'thread';
+}
+/** The immutable canonical view of the document's top-level comments array. */
+export type CollaborativeCommentsSnapshot = ReadonlyArray<CollaborativeComment | CollaborativeCommentThread>;
+export interface CommentCapabilities {
+    read: boolean;
+    comment: boolean;
+}
+export interface CommentMember {
+    userId: string;
+    name: string;
+    email?: string | null;
+    personalOrgId?: string | null;
+}
+export interface CreateCommentThreadInput {
+    anchor: CommentAnchor;
+    content: string;
+    clientMutationId: string;
+    mentionedUserIds?: string[];
+}
+export interface CreateCommentThreadResult {
+    comment: CollaborativeComment;
+    duplicate: boolean;
+    thread: CollaborativeCommentThread;
+}
+export interface ReplyToCommentInput {
+    threadId: string;
+    content: string;
+    clientMutationId: string;
+    mentionedUserIds?: string[];
+    replyToCommentId?: string;
+}
+export interface ReplyToCommentResult {
+    comment: CollaborativeComment;
+    duplicate: boolean;
+    threadId: string;
+}
+export interface MountedCommentAnchorAdapter {
+    handles(anchor: CommentAnchor): boolean;
+    getState(anchor: CommentAnchor): 'attached' | 'orphaned';
+    describe(anchor: CommentAnchor): string;
+    focus(anchor: CommentAnchor): boolean | Promise<boolean>;
+}
+export interface CollaborationCommentsService {
+    getSnapshot(): CollaborativeCommentsSnapshot;
+    subscribe(listener: () => void): () => void;
+    getCapabilities(): CommentCapabilities;
+    getMentionableMembers(): CommentMember[];
+    createThread(input: CreateCommentThreadInput): Promise<CreateCommentThreadResult>;
+    reply(input: ReplyToCommentInput): Promise<ReplyToCommentResult>;
+    setResolved(threadId: string, resolved: boolean): Promise<void>;
+    focusThread(threadId: string): Promise<boolean>;
+    openPanel(input?: {
+        threadId?: string;
+        anchor?: CommentAnchor;
+    }): void;
+    registerAnchorAdapter(adapter: MountedCommentAnchorAdapter): () => void;
+}
+//# sourceMappingURL=comments.d.ts.map

package/dist/types/comments.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"comments.d.ts","sourceRoot":"","sources":["../../src/types/comments.ts"],"names":[],"mappings":"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"}

package/dist/types/comments.js

@@ -0,0 +1,2 @@
+/** Editor-neutral collaborative comment contracts exposed to extensions. */
+export {};