@stll/folio-core 0.55.0 → 0.56.0

package/dist/types/canonicalCapabilities.d.ts

@@ -0,0 +1,215 @@
+//#region src/types/canonicalCapabilities.d.ts
+/** Remaining seams to retire before the canonical session becomes the only authority. */
+declare const CANONICAL_GAP: {
+  readonly authorityRouting: "authority-routing";
+  readonly commands: "command-descriptors";
+  readonly suggesting: "adapter-suggesting";
+  readonly trackedHyperlinkResolution: "tracked-hyperlink-resolution";
+  readonly comments: "comment-model-edits";
+  readonly modelEdits: "direct-model-edits";
+  readonly sectionProperties: "section-properties";
+  readonly watermark: "watermark-model-edits";
+  readonly secondaryStories: "secondary-story-routing";
+  readonly collaboration: "collaboration-session";
+  readonly dispatch: "unclassified-transactions";
+  readonly save: "pm-save-projection";
+  readonly resourceReplacement: "canonical-resource-replacement";
+  readonly history: "pm-history";
+  readonly suggestionPlugin: "pm-suggestion-plugin";
+  readonly paragraphTracker: "pm-paragraph-tracker";
+  readonly tableGeometry: "pm-table-geometry";
+  readonly paragraphIdentity: "pm-paragraph-identity";
+  readonly documentOperations: "pm-document-operations";
+  readonly aiSnapshots: "pm-ai-snapshots";
+  readonly publicComments: "publicOps.comments";
+  readonly publicSuggestedMode: "publicOps.suggestedMode";
+  readonly publicTableProjection: "publicOps.tableProjection";
+  readonly publicUnsupportedInline: "publicOps.unsupportedInline";
+  readonly publicPendingParagraphMarkProperties: "publicOps.pendingParagraphMarkProperties";
+  readonly publicHeadlessSession: "publicOps.headlessSession";
+  readonly publicSecondaryStories: "publicOps.secondaryStories";
+};
+type CanonicalGap = (typeof CANONICAL_GAP)[keyof typeof CANONICAL_GAP];
+declare const CANONICAL_CAPABILITIES: {
+  readonly "authority-routing": {
+    readonly owner: "controller";
+    readonly kind: "routing";
+    readonly adapters: readonly ["react", "vue"];
+    readonly summary: "Explicit session selection and legacy authority routing.";
+  };
+  readonly "command-descriptors": {
+    readonly remainingCommands: {
+      readonly registry: "extension-commands";
+    };
+    readonly owner: "controller";
+    readonly kind: "refusal";
+    readonly adapters: readonly ["react", "vue"];
+    readonly summary: "Commands without canonical descriptors retain PM probing and hit the dispatch boundary.";
+  };
+  readonly "tracked-hyperlink-resolution": {
+    readonly owner: "controller";
+    readonly kind: "refusal";
+    readonly adapters: readonly ["react", "vue"];
+    readonly summary: "Hyperlink and TOC suggestions require serializable wrapper review provenance.";
+  };
+  readonly "adapter-suggesting": {
+    readonly owner: "adapters";
+    readonly kind: "refusal";
+    readonly adapters: readonly ["react", "vue"];
+    readonly summary: "Adapter suggesting controls and tracked secondary-story edits remain gated.";
+  };
+  readonly "comment-model-edits": {
+    readonly owner: "adapters";
+    readonly kind: "refusal";
+    readonly adapters: readonly ["react", "vue"];
+    readonly summary: "Comment mutations still use direct model changes.";
+  };
+  readonly "direct-model-edits": {
+    readonly owner: "adapters";
+    readonly kind: "refusal";
+    readonly adapters: readonly ["react", "vue"];
+    readonly summary: "Direct model and pending-suggestion snapshots bypass the canonical journal.";
+  };
+  readonly "section-properties": {
+    readonly owner: "adapters";
+    readonly kind: "routing";
+    readonly adapters: readonly ["react", "vue"];
+    readonly summary: "Section properties select canonical operations or legacy model changes.";
+  };
+  readonly "watermark-model-edits": {
+    readonly owner: "adapters";
+    readonly kind: "refusal";
+    readonly adapters: readonly ["vue"];
+    readonly summary: "Vue watermark mutations still change the model directly.";
+  };
+  readonly "secondary-story-routing": {
+    readonly owner: "controller";
+    readonly kind: "routing";
+    readonly adapters: readonly ["react", "vue"];
+    readonly summary: "Secondary-story creation, views and history still select their session authority.";
+  };
+  readonly "collaboration-session": {
+    readonly owner: "controller";
+    readonly kind: "refusal";
+    readonly adapters: readonly ["react", "vue"];
+    readonly summary: "Collaboration cannot activate a canonical session.";
+  };
+  readonly "unclassified-transactions": {
+    readonly owner: "controller";
+    readonly kind: "refusal";
+    readonly adapters: readonly ["react", "vue"];
+    readonly summary: "Unclassified native and plugin mutations are refused at the projection boundary.";
+  };
+  readonly "pm-save-projection": {
+    readonly owner: "controller";
+    readonly kind: "routing";
+    readonly adapters: readonly ["react", "vue"];
+    readonly summary: "Legacy save and read paths reconstruct documents from PM.";
+  };
+  readonly "canonical-resource-replacement": {
+    readonly owner: "controller";
+    readonly kind: "refusal";
+    readonly adapters: readonly ["react", "vue"];
+    readonly summary: "Canonical save refuses existing style, style-default, and media replacements the package writers cannot express.";
+  };
+  readonly "pm-history": {
+    readonly owner: "prosemirror";
+    readonly kind: "mutation-source";
+    readonly adapters: readonly ["react", "vue"];
+    readonly summary: "PM history remains installed for legacy sessions.";
+  };
+  readonly "pm-suggestion-plugin": {
+    readonly owner: "prosemirror";
+    readonly kind: "mutation-source";
+    readonly adapters: readonly ["react", "vue"];
+    readonly summary: "The legacy suggestion plugin produces PM transactions.";
+  };
+  readonly "pm-paragraph-tracker": {
+    readonly owner: "prosemirror";
+    readonly kind: "mutation-source";
+    readonly adapters: readonly ["react", "vue"];
+    readonly summary: "Dirty tracking and section bookkeeping still observe PM transactions.";
+  };
+  readonly "pm-table-geometry": {
+    readonly owner: "prosemirror";
+    readonly kind: "mutation-source";
+    readonly adapters: readonly ["react", "vue"];
+    readonly summary: "Table geometry, resize and repair still produce PM transactions.";
+  };
+  readonly "pm-paragraph-identity": {
+    readonly owner: "prosemirror";
+    readonly kind: "mutation-source";
+    readonly adapters: readonly ["react", "vue"];
+    readonly summary: "Legacy paragraph identity repair remains a PM append transaction.";
+  };
+  readonly "pm-document-operations": {
+    readonly owner: "document-operations";
+    readonly defaultSessionMutation: "pm-public-operations";
+    readonly kind: "mutation-source";
+    readonly adapters: readonly ["react", "vue"];
+    readonly summary: "Public document operations still execute against a held PM view.";
+  };
+  readonly "publicOps.comments": {
+    readonly owner: "document-operations";
+    readonly defaultSessionMutation: "pm-public-operations";
+    readonly kind: "refusal";
+    readonly adapters: readonly ["react", "vue"];
+    readonly summary: "Public comment operations refuse in canonical sessions; legacy sessions retain PM comments.";
+  };
+  readonly "publicOps.suggestedMode": {
+    readonly owner: "document-operations";
+    readonly defaultSessionMutation: "pm-public-operations";
+    readonly kind: "refusal";
+    readonly adapters: readonly ["react", "vue"];
+    readonly summary: "Public suggested mode refuses in canonical sessions until pending suggestions use the journal.";
+  };
+  readonly "publicOps.tableProjection": {
+    readonly owner: "document-operations";
+    readonly defaultSessionMutation: "pm-public-operations";
+    readonly kind: "refusal";
+    readonly adapters: readonly ["react", "vue"];
+    readonly summary: "Public table operations refuse while canonical projections require paragraph stories.";
+  };
+  readonly "publicOps.unsupportedInline": {
+    readonly owner: "document-operations";
+    readonly defaultSessionMutation: "pm-public-operations";
+    readonly kind: "refusal";
+    readonly adapters: readonly ["react", "vue"];
+    readonly summary: "Unsupported public payloads refuse with a typed compiler capability gap.";
+  };
+  readonly "publicOps.pendingParagraphMarkProperties": {
+    readonly owner: "document-operations";
+    readonly defaultSessionMutation: "pm-public-operations";
+    readonly kind: "refusal";
+    readonly adapters: readonly ["react", "vue"];
+    readonly summary: "Separate paragraph property edits refuse while the paragraph mark is pending deletion; atomic merge properties remain supported.";
+  };
+  readonly "publicOps.secondaryStories": {
+    readonly owner: "document-operations";
+    readonly defaultSessionMutation: "pm-public-operations";
+    readonly kind: "refusal";
+    readonly adapters: readonly ["react", "vue"];
+    readonly summary: "Public secondary-story batches refuse until canonical story routing is available.";
+  };
+  readonly "publicOps.headlessSession": {
+    readonly owner: "document-operations";
+    readonly defaultSessionMutation: "pm-headless-reviewer";
+    readonly kind: "mutation-source";
+    readonly adapters: readonly ["react", "vue"];
+    readonly summary: "The headless reviewer has no canonical session selector while its mutations remain PM-owned.";
+  };
+  readonly "pm-ai-snapshots": {
+    readonly owner: "ai-edits";
+    readonly kind: "mutation-source";
+    readonly adapters: readonly ["react", "vue"];
+    readonly summary: "Headless AI edits still use PM execution and snapshot undo.";
+  };
+};
+/**
+ * The gap argument is a typed tag counted by the source guard, not a runtime policy.
+ * Retire a gap by removing its sites and ledger entry.
+ */
+declare const usesCanonicalSession: (session: "canonical" | undefined, _gap: CanonicalGap) => boolean;
+declare const canonicalRefusalMessage: (gap: CanonicalGap, message: string) => string;
+//#endregion
+export { CANONICAL_CAPABILITIES, CANONICAL_GAP, CanonicalGap, canonicalRefusalMessage, usesCanonicalSession };

package/dist/types/canonicalCapabilities.js

@@ -0,0 +1,212 @@
+//#region src/types/canonicalCapabilities.ts
+/** Remaining seams to retire before the canonical session becomes the only authority. */
+const CANONICAL_GAP = {
+	authorityRouting: "authority-routing",
+	commands: "command-descriptors",
+	suggesting: "adapter-suggesting",
+	trackedHyperlinkResolution: "tracked-hyperlink-resolution",
+	comments: "comment-model-edits",
+	modelEdits: "direct-model-edits",
+	sectionProperties: "section-properties",
+	watermark: "watermark-model-edits",
+	secondaryStories: "secondary-story-routing",
+	collaboration: "collaboration-session",
+	dispatch: "unclassified-transactions",
+	save: "pm-save-projection",
+	resourceReplacement: "canonical-resource-replacement",
+	history: "pm-history",
+	suggestionPlugin: "pm-suggestion-plugin",
+	paragraphTracker: "pm-paragraph-tracker",
+	tableGeometry: "pm-table-geometry",
+	paragraphIdentity: "pm-paragraph-identity",
+	documentOperations: "pm-document-operations",
+	aiSnapshots: "pm-ai-snapshots",
+	publicComments: "publicOps.comments",
+	publicSuggestedMode: "publicOps.suggestedMode",
+	publicTableProjection: "publicOps.tableProjection",
+	publicUnsupportedInline: "publicOps.unsupportedInline",
+	publicPendingParagraphMarkProperties: "publicOps.pendingParagraphMarkProperties",
+	publicHeadlessSession: "publicOps.headlessSession",
+	publicSecondaryStories: "publicOps.secondaryStories"
+};
+const CANONICAL_CAPABILITIES = {
+	[CANONICAL_GAP.authorityRouting]: {
+		owner: "controller",
+		kind: "routing",
+		adapters: ["react", "vue"],
+		summary: "Explicit session selection and legacy authority routing."
+	},
+	[CANONICAL_GAP.commands]: {
+		remainingCommands: { registry: "extension-commands" },
+		owner: "controller",
+		kind: "refusal",
+		adapters: ["react", "vue"],
+		summary: "Commands without canonical descriptors retain PM probing and hit the dispatch boundary."
+	},
+	[CANONICAL_GAP.trackedHyperlinkResolution]: {
+		owner: "controller",
+		kind: "refusal",
+		adapters: ["react", "vue"],
+		summary: "Hyperlink and TOC suggestions require serializable wrapper review provenance."
+	},
+	[CANONICAL_GAP.suggesting]: {
+		owner: "adapters",
+		kind: "refusal",
+		adapters: ["react", "vue"],
+		summary: "Adapter suggesting controls and tracked secondary-story edits remain gated."
+	},
+	[CANONICAL_GAP.comments]: {
+		owner: "adapters",
+		kind: "refusal",
+		adapters: ["react", "vue"],
+		summary: "Comment mutations still use direct model changes."
+	},
+	[CANONICAL_GAP.modelEdits]: {
+		owner: "adapters",
+		kind: "refusal",
+		adapters: ["react", "vue"],
+		summary: "Direct model and pending-suggestion snapshots bypass the canonical journal."
+	},
+	[CANONICAL_GAP.sectionProperties]: {
+		owner: "adapters",
+		kind: "routing",
+		adapters: ["react", "vue"],
+		summary: "Section properties select canonical operations or legacy model changes."
+	},
+	[CANONICAL_GAP.watermark]: {
+		owner: "adapters",
+		kind: "refusal",
+		adapters: ["vue"],
+		summary: "Vue watermark mutations still change the model directly."
+	},
+	[CANONICAL_GAP.secondaryStories]: {
+		owner: "controller",
+		kind: "routing",
+		adapters: ["react", "vue"],
+		summary: "Secondary-story creation, views and history still select their session authority."
+	},
+	[CANONICAL_GAP.collaboration]: {
+		owner: "controller",
+		kind: "refusal",
+		adapters: ["react", "vue"],
+		summary: "Collaboration cannot activate a canonical session."
+	},
+	[CANONICAL_GAP.dispatch]: {
+		owner: "controller",
+		kind: "refusal",
+		adapters: ["react", "vue"],
+		summary: "Unclassified native and plugin mutations are refused at the projection boundary."
+	},
+	[CANONICAL_GAP.save]: {
+		owner: "controller",
+		kind: "routing",
+		adapters: ["react", "vue"],
+		summary: "Legacy save and read paths reconstruct documents from PM."
+	},
+	[CANONICAL_GAP.resourceReplacement]: {
+		owner: "controller",
+		kind: "refusal",
+		adapters: ["react", "vue"],
+		summary: "Canonical save refuses existing style, style-default, and media replacements the package writers cannot express."
+	},
+	[CANONICAL_GAP.history]: {
+		owner: "prosemirror",
+		kind: "mutation-source",
+		adapters: ["react", "vue"],
+		summary: "PM history remains installed for legacy sessions."
+	},
+	[CANONICAL_GAP.suggestionPlugin]: {
+		owner: "prosemirror",
+		kind: "mutation-source",
+		adapters: ["react", "vue"],
+		summary: "The legacy suggestion plugin produces PM transactions."
+	},
+	[CANONICAL_GAP.paragraphTracker]: {
+		owner: "prosemirror",
+		kind: "mutation-source",
+		adapters: ["react", "vue"],
+		summary: "Dirty tracking and section bookkeeping still observe PM transactions."
+	},
+	[CANONICAL_GAP.tableGeometry]: {
+		owner: "prosemirror",
+		kind: "mutation-source",
+		adapters: ["react", "vue"],
+		summary: "Table geometry, resize and repair still produce PM transactions."
+	},
+	[CANONICAL_GAP.paragraphIdentity]: {
+		owner: "prosemirror",
+		kind: "mutation-source",
+		adapters: ["react", "vue"],
+		summary: "Legacy paragraph identity repair remains a PM append transaction."
+	},
+	[CANONICAL_GAP.documentOperations]: {
+		owner: "document-operations",
+		defaultSessionMutation: "pm-public-operations",
+		kind: "mutation-source",
+		adapters: ["react", "vue"],
+		summary: "Public document operations still execute against a held PM view."
+	},
+	[CANONICAL_GAP.publicComments]: {
+		owner: "document-operations",
+		defaultSessionMutation: "pm-public-operations",
+		kind: "refusal",
+		adapters: ["react", "vue"],
+		summary: "Public comment operations refuse in canonical sessions; legacy sessions retain PM comments."
+	},
+	[CANONICAL_GAP.publicSuggestedMode]: {
+		owner: "document-operations",
+		defaultSessionMutation: "pm-public-operations",
+		kind: "refusal",
+		adapters: ["react", "vue"],
+		summary: "Public suggested mode refuses in canonical sessions until pending suggestions use the journal."
+	},
+	[CANONICAL_GAP.publicTableProjection]: {
+		owner: "document-operations",
+		defaultSessionMutation: "pm-public-operations",
+		kind: "refusal",
+		adapters: ["react", "vue"],
+		summary: "Public table operations refuse while canonical projections require paragraph stories."
+	},
+	[CANONICAL_GAP.publicUnsupportedInline]: {
+		owner: "document-operations",
+		defaultSessionMutation: "pm-public-operations",
+		kind: "refusal",
+		adapters: ["react", "vue"],
+		summary: "Unsupported public payloads refuse with a typed compiler capability gap."
+	},
+	[CANONICAL_GAP.publicPendingParagraphMarkProperties]: {
+		owner: "document-operations",
+		defaultSessionMutation: "pm-public-operations",
+		kind: "refusal",
+		adapters: ["react", "vue"],
+		summary: "Separate paragraph property edits refuse while the paragraph mark is pending deletion; atomic merge properties remain supported."
+	},
+	[CANONICAL_GAP.publicSecondaryStories]: {
+		owner: "document-operations",
+		defaultSessionMutation: "pm-public-operations",
+		kind: "refusal",
+		adapters: ["react", "vue"],
+		summary: "Public secondary-story batches refuse until canonical story routing is available."
+	},
+	[CANONICAL_GAP.publicHeadlessSession]: {
+		owner: "document-operations",
+		defaultSessionMutation: "pm-headless-reviewer",
+		kind: "mutation-source",
+		adapters: ["react", "vue"],
+		summary: "The headless reviewer has no canonical session selector while its mutations remain PM-owned."
+	},
+	[CANONICAL_GAP.aiSnapshots]: {
+		owner: "ai-edits",
+		kind: "mutation-source",
+		adapters: ["react", "vue"],
+		summary: "Headless AI edits still use PM execution and snapshot undo."
+	}
+};
+/**
+* The gap argument is a typed tag counted by the source guard, not a runtime policy.
+* Retire a gap by removing its sites and ledger entry.
+*/
+const usesCanonicalSession = (session, _gap) => session === "canonical";
+const canonicalRefusalMessage = (gap, message) => `[${gap}] ${message}`;
+//#endregion
+export { CANONICAL_CAPABILITIES, CANONICAL_GAP, canonicalRefusalMessage, usesCanonicalSession };

package/dist/types/canonicalSave.d.ts

@@ -0,0 +1,11 @@
+import { document_d_exports } from "./document.js";
+//#region src/types/canonicalSave.d.ts
+/** Committed model and conservative changes relative to its parsed source package. */
+type CanonicalSaveSnapshot = {
+  document: document_d_exports.Document;
+  version: number;
+  changedBlockIds: readonly string[];
+  structure: "stable" | "changed";
+};
+//#endregion
+export { CanonicalSaveSnapshot };

package/dist/types/docxSerialization.d.ts

@@ -0,0 +1,14 @@
+import { SaveDiagnosticOptions } from "../docx/saveDiagnostics.js";
+//#region src/types/docxSerialization.d.ts
+declare const FOLIO_DOCX_SERIALIZATION_MODE: Readonly<{
+  readonly full: "full";
+  readonly preferSelective: "prefer-selective";
+}>;
+type FolioDocxSerializationMode = (typeof FOLIO_DOCX_SERIALIZATION_MODE)[keyof typeof FOLIO_DOCX_SERIALIZATION_MODE];
+type FolioGetDocxOptions = {
+  /** Fidelity diagnostics for the exact snapshot being serialized. */
+  onDiagnostic?: SaveDiagnosticOptions["onDiagnostic"];
+  mode?: FolioDocxSerializationMode;
+};
+//#endregion
+export { FOLIO_DOCX_SERIALIZATION_MODE, FolioDocxSerializationMode, FolioGetDocxOptions };

package/dist/types/docxSerialization.js

@@ -0,0 +1,7 @@
+//#region src/types/docxSerialization.ts
+const FOLIO_DOCX_SERIALIZATION_MODE = Object.freeze({
+	full: "full",
+	preferSelective: "prefer-selective"
+});
+//#endregion
+export { FOLIO_DOCX_SERIALIZATION_MODE };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stll/folio-core",
-  "version": "0.55.0",
+  "version": "0.56.0",
   "description": "Headless, framework-neutral core of folio: the OOXML (.docx) parser, document model, ProseMirror integration, and page-layout engine. No React.",
   "keywords": [
     "document-model",
@@ -146,12 +146,12 @@
     "perf": "bun scripts/profile-editor.ts"
   },
   "dependencies": {
-    "@stll/docx-core": "^0.31.0",
+    "@stll/docx-core": "^0.32.0",
     "@stll/docx-utils": "^0.1.0",
     "@stll/template-conditions": "^0.6.2",
     "better-result": "3.0.1",
     "csstype": "^3.1.3",
-    "dompurify": "^3.4.13",
+    "dompurify": "^3.4.16",
     "fast-xml-parser": "^5.10.1",
     "hyphen": "1.14.1",
     "jszip": "3.10.2",
@@ -165,7 +165,7 @@
     "prosemirror-state": "^1.4.4",
     "prosemirror-tables": "^1.8.5",
     "prosemirror-transform": "^1.12.0",
-    "prosemirror-view": "^1.41.8",
+    "prosemirror-view": "^1.42.6",
     "utif2": "^4.1.0",
     "valibot": "1.5.0",
     "y-prosemirror": "^1.3.7",