@xnetjs/plugins 0.12.0 → 2.0.0

package/dist/services/node.d.ts

@@ -1,6 +1,7 @@
 import { NodeQueryDescriptor, NodeQueryResult } from '@xnetjs/data';
 import { PublicWriteBudgetPolicy, AbuseSurface, AISignalProvenanceInput } from '@xnetjs/abuse';
 import { IncomingMessage, ServerResponse } from 'node:http';
+import * as Y from 'yjs';
 
 /**
  * AI surface contract types for xNet resources, tools, mutation plans, and audit events.
@@ -234,7 +235,12 @@ type AiPageMarkdownApplyAdapterInput = {
     operation: AiOperation;
 };
 type AiPageMarkdownApplyAdapterResult = {
-    mode: 'tiptap-yjs' | 'yjs' | 'custom';
+    /**
+     * `blocknote-yjs` = applied into the BlockNote `content-v4` fragment
+     * (see `createBlockNotePageMarkdownAdapter`); `yjs` = another Yjs-backed
+     * document shape; `custom` = host-specific.
+     */
+    mode: 'blocknote-yjs' | 'yjs' | 'custom';
     yjsField?: string;
     documentUpdate?: unknown;
     warnings?: string[];
@@ -246,7 +252,7 @@ type AiPageMarkdownApplyResult = {
     applied: boolean;
     pageId: string;
     planId: string;
-    mode: 'tiptap-yjs' | 'yjs' | 'custom' | 'node-property';
+    mode: 'blocknote-yjs' | 'yjs' | 'custom' | 'node-property';
     baseRevision: string;
     liveRevision: string;
     markdownHash: string;
@@ -522,6 +528,77 @@ declare function stripXNetPageFrontmatter(markdown: string): string;
 declare function renderMarkdownLineDiff(before: string, after: string): string;
 declare function renderMarkdownReviewDiff(before: string, after: string): XNetMarkdownReviewDiff;
 
+/**
+ * Yjs-fragment ↔ markdown conversion for AI page projections (0312).
+ *
+ * v4 pages persist BlockNote's ProseMirror schema in the Y.XmlFragment
+ * `content-v4`: the fragment holds one `blockGroup`, each block is a
+ * `blockContainer` (with a unique `id` attribute) wrapping one blockContent
+ * element (paragraph/heading/…) plus an optional nested `blockGroup` of
+ * child blocks. v3 and earlier documents live in the legacy `content`
+ * fragment (TipTap schema) and are read-only here.
+ *
+ * Both directions walk the Yjs XML tree directly — no editor, DOM, or
+ * BlockNote dependency — mirroring the dependency-light approach of the
+ * editor package's lazy legacy importer. The write path covers the markdown
+ * subset AI agents emit (paragraphs, headings, bullet/numbered/check lists,
+ * fenced code, quotes, callouts, wikilinks); reading is broader and degrades
+ * unknown blocks to text, like the legacy importer.
+ */
+
+/** The Y.XmlFragment field that holds v4 (BlockNote) page documents. */
+declare const XNET_PAGE_FRAGMENT_FIELD = "content-v4";
+/** The legacy (TipTap, v3 and below) fragment field, read as a fallback. */
+declare const XNET_PAGE_LEGACY_FRAGMENT_FIELD = "content";
+type XNetPageFragmentReadOptions = {
+    /** BlockNote fragment field. Defaults to `content-v4`. */
+    field?: string;
+    /** Legacy TipTap fragment field read when the v4 fragment is empty. */
+    legacyField?: string;
+};
+/** Convert a BlockNote (`content-v4`) fragment to markdown. */
+declare function blockNoteFragmentToMarkdown(fragment: Y.XmlFragment): string;
+/** Convert a legacy TipTap (`content`) fragment to markdown (lossy). */
+declare function legacyFragmentToMarkdown(fragment: Y.XmlFragment): string;
+/**
+ * Read a page Y.Doc as markdown: the BlockNote `content-v4` fragment when it
+ * has content, otherwise the legacy TipTap `content` fragment.
+ */
+declare function xnetPageFragmentToMarkdown(doc: Y.Doc, options?: XNetPageFragmentReadOptions): string;
+type XNetPageFragmentWriteOptions = {
+    /** BlockNote fragment field. Defaults to `content-v4`. */
+    field?: string;
+    /** Block id factory (BlockNote requires a unique `id` per blockContainer). */
+    generateBlockId?: () => string;
+};
+/**
+ * Replace a page's BlockNote fragment with the given markdown (the AI apply
+ * path). Runs in a single Yjs transaction; every blockContainer gets a fresh
+ * unique id. Covers the AI markdown subset: paragraphs, headings,
+ * bullet/numbered/check lists (2-space nesting), fenced code, quotes,
+ * `> [!kind]` callouts, and `[[wikilinks]]`. Anything else lands as
+ * paragraph text — never dropped.
+ */
+declare function replaceXNetPageFragmentWithMarkdown(doc: Y.Doc, markdown: string, options?: XNetPageFragmentWriteOptions): void;
+/** Resolves the live (or loaded) Y.Doc for a page node id. */
+type XNetPageDocResolver = (pageId: string) => Promise<Y.Doc | null> | Y.Doc | null;
+type BlockNotePageMarkdownAdapterOptions = {
+    resolveDoc: XNetPageDocResolver;
+    /** BlockNote fragment field. Defaults to `content-v4`. */
+    field?: string;
+    generateBlockId?: () => string;
+};
+/**
+ * The BlockNote/Yjs `AiPageMarkdownApplyAdapter` (replaces the TipTap-era
+ * document bridge): applies validated AI markdown plans into the page's
+ * `content-v4` fragment, and reads pages back out of it. Hosts wire
+ * `resolveDoc` to their document store; without an adapter the AI surface
+ * falls back to the `markdown` node property.
+ */
+declare function createBlockNotePageMarkdownAdapter(options: BlockNotePageMarkdownAdapterOptions): AiPageMarkdownApplyAdapter & {
+    readMarkdown: (pageId: string) => Promise<string | null>;
+};
+
 /**
  * Local HTTP API Server
  *
@@ -1798,4 +1875,4 @@ declare const SERVICE_IPC_CHANNELS: {
     readonly OUTPUT: "xnet:service:output";
 };
 
-export { AI_RISK_LEVELS, AI_SCOPES, AI_TARGET_KINDS, type AgentApi, type AgentScriptContext, type AgentScriptSession, type AgentSearchResult, type AgentWriteProposal, type AiAuditEvent, type AiChangeSet, type AiContextPack, type AiContextPackResource, type AiContextSeed, type AiJsonSchema, type AiJsonSchemaType, type AiMutationPlan, type AiMutationPlanStatus, type AiOperation, type AiPageMarkdownApplyAdapter, type AiPageMarkdownApplyAdapterInput, type AiPageMarkdownApplyAdapterResult, type AiPageMarkdownApplyResult, type AiPageMarkdownRollbackResult, type AiResource, type AiResourceContent, type AiRiskLevel, type AiScope, type AiSearchOptions, type AiSearchResult, type AiSurfaceLimits, AiSurfaceService, type AiSurfaceServiceConfig, type AiTargetKind, type AiToolCallResult, type AiToolDefinition, type AiValidationResult, type AiWorkspaceChangedFile, type AiWorkspaceChangedFileStatus, type AiWorkspaceCheckoutOptions, type AiWorkspaceConflict, type AiWorkspaceConflictKind, type AiWorkspaceExportKind, type AiWorkspaceExportOptions, type AiWorkspaceExportResult, type AiWorkspaceExportScope, AiWorkspaceExporter, type AiWorkspaceExporterConfig, type AiWorkspaceManifestEntry, type AiWorkspacePendingPlan, type AiWorkspaceReviewAction, type AiWorkspaceReviewEntry, type AiWorkspaceReviewEntryKind, type AiWorkspaceReviewIndex, type AiWorkspaceReviewStatus, type AiWorkspaceWatchHandle, type AiWorkspaceWatchOptions, AiWorkspaceWatcher, type AiWorkspaceWatcherScanOptions, type AiWorkspaceWatcherScanResult, type CreateAgentScriptContextInput, type FlatNode, type IProcessManager, type LocalAPIConfig, LocalAPIServer, type LocalAPITokenConfig, type LocalAPITokenScope, type LocalAPITokenSummary, type MCPPropertySchema, type MCPRequest, type MCPResource, type MCPResponse, MCPServer, type MCPServerConfig, type MCPTool, type McpHttpServerConfig, type McpHttpServerHandle, type MemoryNodeStore, type NodeChangeEventData, type NodeData, type NodeStoreAPI, ProcessManager, type ProcessManagerEvents, SERVICE_IPC_CHANNELS, type SchemaData, type SchemaRegistryAPI, ScriptSandbox, type ServiceClient, type ServiceCommunication, type ServiceDefinition, type ServiceHealthCheck, type ServiceLifecycle, type ServiceOutputEvent, type ServiceProcessConfig, type ServiceProvides, type ServiceState, type ServiceStatus, type ServiceStatusEvent, XNET_AGENT_SKILL_MD, XNET_MARKDOWN_DIRECTIVE_SPECS, type XNetMarkdownDiffLine, type XNetMarkdownDiffLineKind, type XNetMarkdownDirective, type XNetMarkdownDirectiveSpec, type XNetMarkdownReviewDiff, type XNetPageMarkdownFrontmatter, type XNetPageMarkdownValidation, type XNetPageMarkdownValidationOptions, attachAiPlanValidation, createAgentScriptContext, createAiChangeSet, createAiOperation, createAiSurfaceService, createAiValidationResult, createAiWorkspaceExporter, createAiWorkspaceWatcher, createLocalAPI, createMCPServer, createMcpHttpServer, createMemoryNodeStore, createMemorySchemaRegistry, createWorkspaceFixtureSchemas, flattenRowForTsv, getXNetMarkdownDirectiveSpecs, isAiRiskLevel, isAiScope, isAiTargetKind, parseAiMutationPlan, parseXNetPageFrontmatter, renderMarkdownLineDiff, renderMarkdownReviewDiff, serializeAiMutationPlan, stripXNetPageFrontmatter, toTsv, validateAiMutationPlan, validateXNetPageMarkdown };
+export { AI_RISK_LEVELS, AI_SCOPES, AI_TARGET_KINDS, type AgentApi, type AgentScriptContext, type AgentScriptSession, type AgentSearchResult, type AgentWriteProposal, type AiAuditEvent, type AiChangeSet, type AiContextPack, type AiContextPackResource, type AiContextSeed, type AiJsonSchema, type AiJsonSchemaType, type AiMutationPlan, type AiMutationPlanStatus, type AiOperation, type AiPageMarkdownApplyAdapter, type AiPageMarkdownApplyAdapterInput, type AiPageMarkdownApplyAdapterResult, type AiPageMarkdownApplyResult, type AiPageMarkdownRollbackResult, type AiResource, type AiResourceContent, type AiRiskLevel, type AiScope, type AiSearchOptions, type AiSearchResult, type AiSurfaceLimits, AiSurfaceService, type AiSurfaceServiceConfig, type AiTargetKind, type AiToolCallResult, type AiToolDefinition, type AiValidationResult, type AiWorkspaceChangedFile, type AiWorkspaceChangedFileStatus, type AiWorkspaceCheckoutOptions, type AiWorkspaceConflict, type AiWorkspaceConflictKind, type AiWorkspaceExportKind, type AiWorkspaceExportOptions, type AiWorkspaceExportResult, type AiWorkspaceExportScope, AiWorkspaceExporter, type AiWorkspaceExporterConfig, type AiWorkspaceManifestEntry, type AiWorkspacePendingPlan, type AiWorkspaceReviewAction, type AiWorkspaceReviewEntry, type AiWorkspaceReviewEntryKind, type AiWorkspaceReviewIndex, type AiWorkspaceReviewStatus, type AiWorkspaceWatchHandle, type AiWorkspaceWatchOptions, AiWorkspaceWatcher, type AiWorkspaceWatcherScanOptions, type AiWorkspaceWatcherScanResult, type BlockNotePageMarkdownAdapterOptions, type CreateAgentScriptContextInput, type FlatNode, type IProcessManager, type LocalAPIConfig, LocalAPIServer, type LocalAPITokenConfig, type LocalAPITokenScope, type LocalAPITokenSummary, type MCPPropertySchema, type MCPRequest, type MCPResource, type MCPResponse, MCPServer, type MCPServerConfig, type MCPTool, type McpHttpServerConfig, type McpHttpServerHandle, type MemoryNodeStore, type NodeChangeEventData, type NodeData, type NodeStoreAPI, ProcessManager, type ProcessManagerEvents, SERVICE_IPC_CHANNELS, type SchemaData, type SchemaRegistryAPI, ScriptSandbox, type ServiceClient, type ServiceCommunication, type ServiceDefinition, type ServiceHealthCheck, type ServiceLifecycle, type ServiceOutputEvent, type ServiceProcessConfig, type ServiceProvides, type ServiceState, type ServiceStatus, type ServiceStatusEvent, XNET_AGENT_SKILL_MD, XNET_MARKDOWN_DIRECTIVE_SPECS, XNET_PAGE_FRAGMENT_FIELD, XNET_PAGE_LEGACY_FRAGMENT_FIELD, type XNetMarkdownDiffLine, type XNetMarkdownDiffLineKind, type XNetMarkdownDirective, type XNetMarkdownDirectiveSpec, type XNetMarkdownReviewDiff, type XNetPageDocResolver, type XNetPageFragmentReadOptions, type XNetPageFragmentWriteOptions, type XNetPageMarkdownFrontmatter, type XNetPageMarkdownValidation, type XNetPageMarkdownValidationOptions, attachAiPlanValidation, blockNoteFragmentToMarkdown, createAgentScriptContext, createAiChangeSet, createAiOperation, createAiSurfaceService, createAiValidationResult, createAiWorkspaceExporter, createAiWorkspaceWatcher, createBlockNotePageMarkdownAdapter, createLocalAPI, createMCPServer, createMcpHttpServer, createMemoryNodeStore, createMemorySchemaRegistry, createWorkspaceFixtureSchemas, flattenRowForTsv, getXNetMarkdownDirectiveSpecs, isAiRiskLevel, isAiScope, isAiTargetKind, legacyFragmentToMarkdown, parseAiMutationPlan, parseXNetPageFrontmatter, renderMarkdownLineDiff, renderMarkdownReviewDiff, replaceXNetPageFragmentWithMarkdown, serializeAiMutationPlan, stripXNetPageFrontmatter, toTsv, validateAiMutationPlan, validateXNetPageMarkdown, xnetPageFragmentToMarkdown };