@docx-editor.dev/pro 0.0.1-placeholder → 2.0.0

package/LICENSE.md

@@ -0,0 +1,121 @@
+# EigenPal Pro Evaluation License 1.0
+
+Copyright (c) 2026 EigenPal, Inc. All rights reserved.
+
+By copying, modifying, or using the Software, you agree to these terms.
+
+## 1. Covered Software
+
+“Software” means all source code, object code, documentation, assets, and other
+materials contained in the “packages/pro/” directory of the EigenPal DOCX
+Editor repository, except for any material that expressly states that it is
+subject to a different license.
+
+## 2. Evaluation Permission; Modifications
+
+Subject to these terms, EigenPal, Inc. grants you a limited, non-exclusive,
+non-transferable, non-sublicensable, royalty-free license to:
+
+1. view, clone, and copy the Software;
+2. run the Software internally in a non-production environment solely to
+   evaluate its suitability for your intended application; and
+3. modify the Software solely as reasonably necessary for that internal,
+   non-production evaluation.
+
+For any such modification, the following applies:
+
+You may keep any modification to yourself. If you do not disclose it to EigenPal, Inc. or to anyone else, it remains yours
+If you disclose a modification to EigenPal, Inc. or to any third party, in any form, you assign all right, title, and interest in it to EigenPal, Inc. at the moment of disclosure. The same applies to any feedback you give EigenPal, Inc. You will promptly send EigenPal, Inc. the source code of any modification you disclose, and will sign any document needed to record the assignment.
+Disclosing a modification to a third party grants that third party no rights in it or in the Software. You will not license or purport to license any modification to anyone.
+You may continue using an assigned modification for the internal, non-production evaluation permitted by Section 2 for as long as this license is in effect. EigenPal, Inc. is not obliged to use or support any modification or feedback, and owes you nothing for it.
+You confirm that any modification or feedback you disclose is yours to assign and is not subject to any license that would impose obligations on EigenPal, Inc. or grant rights to any third party.
+
+
+No other rights are granted.
+
+## 3. No Production Use
+
+You may not use the Software for Production Use.
+
+“Production Use” means any use of the Software:
+
+1. in a live, operational, or customer-facing environment;
+2. to provide, operate, support, or enhance a product or service for another
+   person or organization;
+3. to process live, customer, or business-operational data; or
+4. as part of your ordinary internal business operations, other than evaluation
+   and testing.
+
+For the avoidance of doubt, Production Use includes embedding the Software in a product made available to
+others, offering the Software through a hosted or managed service, and using it
+in a customer pilot or paid proof of concept.
+
+## 4. No Distribution or Sublicensing
+
+You may not sell, sublicense, distribute, publish, transfer, or otherwise make
+the Software or modifications to the Software available to any third party.
+
+You may allow your employees and contractors to access the Software solely for
+your evaluation, provided they are bound by restrictions at least as protective
+as these terms. You are responsible for their compliance.
+
+## 5. Commercial Rights
+
+Production Use and any rights not expressly granted by this license require a
+separate written commercial agreement signed by EigenPal, Inc.
+
+Commercial licenses are available by contacting licensing@eigenpal.com.
+
+Access to the Software, correspondence with EigenPal, Inc., or payment of an
+invoice does not by itself grant production or commercial rights unless those
+rights are set out in a written agreement signed by EigenPal, Inc.
+
+## 6. Ownership
+
+EigenPal, Inc. and its licensors retain all rights, title, and interest in the
+Software. This license does not transfer ownership or grant any rights by
+implication.
+
+Modifying the Software does not grant you the right to use the Software or those
+modifications in production.
+
+## 7. Termination
+
+Your rights under this license terminate automatically if you breach these
+terms or if EigenPal terminates this license.
+
+Following termination, you must stop using the Software and delete your copies
+and modifications, except for copies that you are legally required to retain.
+EigenPal, Inc. may reinstate your rights in writing.
+
+## 8. No Warranty
+
+TO THE MAXIMUM EXTENT PERMITTED BY LAW, THE SOFTWARE IS PROVIDED “AS IS” AND
+WITHOUT WARRANTIES OF ANY KIND, WHETHER EXPRESS, IMPLIED, OR STATUTORY,
+INCLUDING WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE,
+TITLE, AND NON-INFRINGEMENT.
+
+## 9. Limitation of Liability
+
+TO THE MAXIMUM EXTENT PERMITTED BY LAW, EIGENPAL, INC. AND ITS LICENSORS WILL NOT BE LIABLE FOR ANY INDIRECT, INCIDENTAL, SPECIAL, CONSEQUENTIAL, EXEMPLARY, OR PUNITIVE DAMAGES, OR FOR ANY LOSS OF DATA, REVENUE, PROFITS, OR BUSINESS, ARISING FROM OR RELATING TO THE SOFTWARE OR THIS LICENSE. TO THE MAXIMUM EXTENT PERMITTED BY LAW, THE TOTAL AGGREGATE LIABILITY OF EIGENPAL, INC. AND ITS LICENSORS FOR ALL CLAIMS ARISING FROM OR RELATING TO THE SOFTWARE OR THIS LICENSE, WHETHER IN CONTRACT, TORT, STRICT LIABILITY, OR ANY OTHER THEORY, WILL NOT EXCEED TEN UNITED STATES DOLLARS (US$10). THE FOREGOING LIMITATIONS APPLY EVEN IF EIGENPAL, INC. HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES AND EVEN IF ANY LIMITED REMEDY IS FOUND TO HAVE FAILED OF ITS ESSENTIAL PURPOSE.
+
+## 10. Trademarks
+
+This license does not grant permission to use the names, trademarks, service
+marks, or logos of EigenPal, Inc., except to identify the origin of an
+unmodified copy of the Software.
+
+## 11. Governing Law and Jurisdiction
+
+This license is governed by the laws of the State of California, without regard
+to its conflict-of-laws rules.
+
+Any dispute arising from or relating to this license will be subject to the
+exclusive jurisdiction of the state and federal courts located in California,
+and you consent to their jurisdiction.
+
+## 12. Separate Commercial Agreements
+
+If EigenPal, Inc. and you enter into a separate written commercial agreement,
+that agreement controls to the extent it grants additional rights or conflicts
+with this license.

package/README.md

@@ -1,5 +1,139 @@
+<p align="center">
+  <a href="https://www.docx-editor.dev/">
+    <img src="https://raw.githubusercontent.com/eigenpal/docx-editor/main/.github/assets/header.png" alt="DOCX Editor — .docx in, .docx out. Open source, client-side." width="500" />
+  </a>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@docx-editor.dev/pro"><img src="https://img.shields.io/npm/v/@docx-editor.dev/pro.svg?style=flat-square&color=3B5BDB" alt="npm version" /></a>
+  <a href="https://github.com/eigenpal/docx-editor/blob/main/packages/pro/LICENSE.md"><img src="https://img.shields.io/badge/license-EigenPal_Pro_Evaluation_1.0-blue.svg?style=flat-square&color=3B5BDB" alt="license" /></a>
+  <a href="https://docx-editor.dev/editor"><img src="https://img.shields.io/badge/Live_Demo-3B5BDB?style=flat-square&logo=vercel&logoColor=white" alt="Demo" /></a>
+  <a href="https://www.docx-editor.dev/docs/2.x/pro"><img src="https://img.shields.io/badge/Docs-3B5BDB?style=flat-square&logo=readthedocs&logoColor=white" alt="Documentation" /></a>
+</p>
+
 # @docx-editor.dev/pro
 
-Placeholder package reserving this name.
+Three capabilities for the [docx-editor.dev](https://docx-editor.dev) React editor:
+
+- **Tracked changes** — suggesting mode, markup rendering, accept and reject
+- **Comments** — threads anchored to a range, with replies
+- **Custom nodes** — your own inline node types, stored as Word content controls
+
+```bash
+npm install @docx-editor.dev/react @docx-editor.dev/pro
+```
+
+The framework-neutral entry is `@docx-editor.dev/pro`; React chrome lives at
+`@docx-editor.dev/pro/react`.
+
+## Register a module
+
+Capabilities are modules passed to the editor root. Registration happens at construction, so
+the array identity must be stable. Build it outside render, or the editor rebuilds every time.
+
+```tsx
+import { DocxEditor } from '@docx-editor.dev/react';
+import { reviewModule, DocxEditorReview } from '@docx-editor.dev/pro/react';
+
+const MODULES = [reviewModule()];
+
+export function Reviewer({ bytes }: { bytes: Uint8Array }) {
+  return (
+    <DocxEditor.Root document={bytes} modules={MODULES} author="Jess Lin">
+      <DocxEditor.Toolbar />
+      <DocxEditor.Viewport>
+        <DocxEditor.Content />
+        {/* Tracked changes and comments as cards beside the page. */}
+        <DocxEditorReview />
+      </DocxEditor.Viewport>
+    </DocxEditor.Root>
+  );
+}
+```
+
+`author` is what lands in `w:author`. OOXML requires it, so the engine refuses a comment or
+reply with no author rather than writing an empty attribute.
+
+Without a review module the editor still opens a document containing revisions and comments and
+still saves them back untouched. It renders revisions in their final state and offers no review
+UI; the module is what makes them visible and actionable.
+
+## Chrome or hooks
+
+Everything the packaged sidebar renders is reachable from `useReview()`. Take the sidebar for
+Word-like cards out of the box; take the hook for your own markup.
+
+```tsx
+import { useReview } from '@docx-editor.dev/pro/react';
+
+function ChangeList() {
+  const { items, accept, reject, ready } = useReview();
+  if (!ready) return null;
+
+  return (
+    <ul>
+      {items.map((item) => (
+        <li key={item.key}>
+          {/* File-derived. Render as text, never as markup. */}
+          {item.text} — {item.author}
+          {!item.readOnly && (
+            <>
+              <button onClick={() => accept(item)}>Accept</button>
+              <button onClick={() => reject(item)}>Reject</button>
+            </>
+          )}
+        </li>
+      ))}
+    </ul>
+  );
+}
+```
+
+Items come from the document tree rather than from what is currently painted, and each anchor
+comes from layout records rather than measured DOM, so a sidebar built on this does not lag a
+repaint behind the page or break during pagination.
+
+## Custom nodes
+
+An inline node type you define — a citation, a mention, a merge field — stored as a Word content
+control whose `w:tag` carries your identity and attributes. Word opens the document, shows the
+node's text, and gives it back unchanged.
+
+```ts
+import { defineCustomNode, customNodesModule } from '@docx-editor.dev/pro';
+
+const Citation = defineCustomNode({
+  name: 'citation',
+  tagPrefix: 'docx',
+  label: 'Citation',
+  chrome: { color: '#7c3aed' },
+  fromDocx: ({ attrs, text }) => ({ ...attrs, label: text }),
+});
+
+const MODULES = [customNodesModule({ nodes: [Citation] })];
+```
+
+Every value reaching `fromDocx` came out of a `.docx`, so treat `attrs` and `text` as untrusted.
+
+`insertCustomNode`, `updateCustomNode`, and `removeCustomNode` author them from code, and
+`customNodeXml` builds the same content control on a server with no editor and no DOM.
+
+## Licensing
+
+Not Apache 2.0 like the editor packages. Licensed under the
+[EigenPal Pro Evaluation License 1.0](https://github.com/eigenpal/docx-editor/blob/main/packages/pro/LICENSE.md):
+free to read, run, and modify internally to evaluate. Production use — a live or customer-facing
+environment, business-operational data, or this package inside something you offer to others —
+requires a written commercial agreement, and so does redistribution.
+
+Commercial licensing: [licensing@eigenpal.com](mailto:licensing@eigenpal.com)
+
+Both module factories accept an optional `licenseKey`. Construction never validates it and never
+touches the network.
+
+## Documentation
 
-See [docx-editor.dev](https://docx-editor.dev/) for docs.
+- [Pro overview](https://www.docx-editor.dev/docs/2.x/pro)
+- [Tracked changes](https://www.docx-editor.dev/docs/2.x/pro/tracked-changes)
+- [Comments](https://www.docx-editor.dev/docs/2.x/pro/comments)
+- [Custom nodes](https://www.docx-editor.dev/docs/2.x/pro/custom-nodes)

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,22 @@
+# Third-party notices
+
+`@docx-editor.dev/pro` is distributed under LicenseRef-EigenPal-Pro-Evaluation-1.0. Its published bundles also contain
+source from the open-source packages listed below, redistributed here under
+their own licenses, reproduced in full.
+
+Those copies are not verbatim. The build inlines, minifies and tree-shakes
+them, and includes only the parts each bundle reaches, so what ships is a
+modified form of the original source.
+
+The terms of LicenseRef-EigenPal-Pro-Evaluation-1.0 do not apply to the portions of these bundles
+derived from the packages listed below. Those portions are licensed to you
+under their own terms.
+
+This file covers code copied INTO the published bundles. Packages this one
+declares as `dependencies` or `peerDependencies` are installed separately by
+the consumer and are not repeated here.
+
+Generated by `bun run notices:generate` from the build's esbuild metafile.
+Do not edit by hand.
+
+No third-party code is bundled into this package.

package/dist/chunk-NZOS3H23.js

@@ -0,0 +1 @@
+import {findNode,revisionItemsOf,collectReviewItems,paragraphOrderOfPart,locateSites,segmentsOf}from'@docx-editor.dev/core/store';import {reviewItemPositionRank}from'@docx-editor.dev/core/layout';function f(e){}var z=64,I=new Set(["__proto__","constructor","prototype"]);function p(e,i,r){let s=new URLSearchParams;for(let[o,d]of Object.entries(r))s.set(o,d);let a=s.toString(),t=a.length>0?`${e}:${i}?${a}`:`${e}:${i}`;return t.length>64?{ok:false,reason:"tag-overflow",length:t.length}:{ok:true,tag:t}}function g(e){if(e.length>64)return null;let i=e.indexOf(":");if(i<=0)return null;let r=e.slice(0,i),s=e.slice(i+1),a=s.indexOf("?"),t=a===-1?s:s.slice(0,a);if(t.length===0)return null;let o=Object.create(null);if(a!==-1)for(let[d,n]of new URLSearchParams(s.slice(a+1))){if(I.has(d))return null;o[d]=n;}return {prefix:r,name:t,attrs:o}}function x(e){return typeof e=="object"&&e!==null&&typeof e.name=="string"&&typeof e.tagPrefix=="string"}var y=/^[A-Za-z0-9_.-]+$/;function U(e){if(!y.test(e.name??""))throw new Error(`defineCustomNode: invalid name ${JSON.stringify(e.name)}`);if(!y.test(e.tagPrefix??""))throw new Error(`defineCustomNode: invalid tagPrefix ${JSON.stringify(e.tagPrefix)}`);return Object.freeze({...e})}function F(e){return f(e.licenseKey),{id:"custom-nodes",customNodes:e.nodes}}function k(e){for(let i of e.children)if(!(i.kind==="textValue"||i.localName!=="sdtPr")){for(let r of i.children)if(!(r.kind==="textValue"||r.localName!=="tag")){for(let s of r.attributes)if(s.localName==="val")return s.value}}}function v(e){if(e.kind==="textValue")return e.value;let i="";for(let r of e.children)i+=v(r);return i}function N(e,i){if(i.length===0)return [];let r=new Map;for(let t of i){let o=`${t.tagPrefix}:${t.name}`;if(r.has(o))throw new Error(`recognizeCustomNodes: duplicate definition for ${JSON.stringify(o)}`);r.set(o,t);}let s=[],a=(t,o)=>{if(!(t.kind==="textValue"||o>64)){if(t.kind==="contentControl"){let d=k(t),n=d!==void 0?g(d):null,l=n?r.get(`${n.prefix}:${n.name}`):void 0;if(n&&l&&d!==void 0){let c=v(t),u=l.fromDocx?l.fromDocx({attrs:n.attrs,text:c}):n.attrs;if(u!==null){s.push({name:l.name,attrs:u,text:c,nodeId:t.id,tag:d});return}}}for(let d of t.children)a(d,o+1);}};return a(e.root,0),s}function R(e,i){let r=findNode(e,i);return !r||r.kind!=="paragraph"?[]:revisionItemsOf({id:e.id,name:e.name,contentType:e.contentType,root:r})}function b(e,i){let r=i.filter(o=>o.reviewCard);if(r.length===0)return [];let s=N(e,r);if(s.length===0)return [];let a=locateSites(e),t=[];for(let o of s){let d=r.find(c=>c.name===o.name&&o.tag.startsWith(`${c.tagPrefix}:`));if(!d)continue;let n=d.reviewCard({attrs:o.attrs,text:o.text});if(n===null)continue;let l=a.get(o.nodeId);t.push({kind:"custom",id:o.nodeId,name:o.name,tag:o.tag,attrs:o.attrs,text:o.text,title:n.title,...n.detail!==void 0?{detail:n.detail}:{},range:l?{partName:e.name,start:{paragraphId:l.paragraphId,offset:l.start},end:{paragraphId:l.paragraphId,offset:l.end}}:null});}return t}function O(e){let i=collectReviewItems(e),r=(e.customNodes??[]).filter(x);if(r.length===0)return i;let s=[e.storyPart],a=new Set([e.storyPart.name]);for(let n of e.furnitureParts??[])a.has(n.name)||(a.add(n.name),s.push(n));let t=[],o=new Map;for(let n of s){t.push(...b(n,r));let l=o.size;for(let[c,u]of paragraphOrderOfPart(n))o.has(c)||o.set(c,l+u);}return t.length===0?i:[...i,...t].sort((n,l)=>reviewItemPositionRank(n,o)-reviewItemPositionRank(l,o))}function se(e={}){return f(e.licenseKey),{id:"review",review:{displayModes:["all-markup","proposed","original"],collectReviewItems:O,revisionItemsOfParagraph:R}}}function w(e){return e.surface??null}function _(e,i){let r=null,s=t=>t.id===i?true:t.kind==="textValue"?false:t.children.some(s),a=(t,o)=>{if(!(r||t.kind==="textValue"||o>64)){if(t.kind==="paragraph"){s(t)&&(r=t);return}for(let d of t.children)a(d,o+1);}};return a(e.root,0),r}function A(e,i){let r=new Set,s=n=>{if(r.add(n.id),n.kind!=="textValue")for(let l of n.children)s(l);},a=n=>{if(n.id===i)return n;if(n.kind==="textValue")return null;for(let l of n.children){let c=a(l);if(c)return c}return null},t=a(e);if(!t)return null;s(t);let o=Number.MAX_SAFE_INTEGER,d=-1;for(let n of segmentsOf(e))r.has(n.runId)&&(n.start<o&&(o=n.start),n.end>d&&(d=n.end));return d<0?null:{start:o,end:d}}function ce(e,i){let r=w(e);if(!r)return {ok:false,code:"notFound",reason:"no document is mounted"};let s=r.session.applyTreeOps([{op:"removeContentControl",controlId:i,keepContent:false}]);return s.committed?{ok:true,changed:true}:{ok:false,code:"unsupported",reason:typeof s.reason=="string"?s.reason:"the removal was refused"}}function ue(e,i,r,s,a,t={}){let o=w(e);if(!o)return {ok:false,code:"notFound",reason:"no document is mounted"};let d=p(i.tagPrefix,i.name,s);if(!d.ok)return {ok:false,code:"invalidArgs",reason:`the encoded tag is ${d.length} characters; Word caps w:tag at 64 \u2014 shorten the attrs`};let n=o.session.part(),l=_(n,r),c=l?A(l,r):null;if(!l||!c)return {ok:false,code:"notFound",reason:"no custom node with that id"};let u=t.lock===void 0?"contentLocked":t.lock,m=o.session.applyTreeOps([{op:"removeContentControl",controlId:r,keepContent:false},{op:"insertInlineContentControl",paragraphId:l.id,offset:c.start,tag:d.tag,text:a,...t.alias===void 0?{}:{alias:t.alias},...u===false?{}:{lock:u}}]);return m.committed?{ok:true,changed:true}:{ok:false,code:"unsupported",reason:typeof m.reason=="string"?m.reason:"the update was refused"}}export{z as a,p as b,g as c,x as d,y as e,U as f,F as g,N as h,se as i,ce as j,ue as k};

package/dist/chunk-TNSHSAA4.cjs

@@ -0,0 +1 @@
+'use strict';var store=require('@docx-editor.dev/core/store'),layout=require('@docx-editor.dev/core/layout');function f(e){}var z=64,I=new Set(["__proto__","constructor","prototype"]);function p(e,i,r){let s=new URLSearchParams;for(let[o,d]of Object.entries(r))s.set(o,d);let a=s.toString(),t=a.length>0?`${e}:${i}?${a}`:`${e}:${i}`;return t.length>64?{ok:false,reason:"tag-overflow",length:t.length}:{ok:true,tag:t}}function g(e){if(e.length>64)return null;let i=e.indexOf(":");if(i<=0)return null;let r=e.slice(0,i),s=e.slice(i+1),a=s.indexOf("?"),t=a===-1?s:s.slice(0,a);if(t.length===0)return null;let o=Object.create(null);if(a!==-1)for(let[d,n]of new URLSearchParams(s.slice(a+1))){if(I.has(d))return null;o[d]=n;}return {prefix:r,name:t,attrs:o}}function x(e){return typeof e=="object"&&e!==null&&typeof e.name=="string"&&typeof e.tagPrefix=="string"}var y=/^[A-Za-z0-9_.-]+$/;function U(e){if(!y.test(e.name??""))throw new Error(`defineCustomNode: invalid name ${JSON.stringify(e.name)}`);if(!y.test(e.tagPrefix??""))throw new Error(`defineCustomNode: invalid tagPrefix ${JSON.stringify(e.tagPrefix)}`);return Object.freeze({...e})}function F(e){return f(e.licenseKey),{id:"custom-nodes",customNodes:e.nodes}}function k(e){for(let i of e.children)if(!(i.kind==="textValue"||i.localName!=="sdtPr")){for(let r of i.children)if(!(r.kind==="textValue"||r.localName!=="tag")){for(let s of r.attributes)if(s.localName==="val")return s.value}}}function v(e){if(e.kind==="textValue")return e.value;let i="";for(let r of e.children)i+=v(r);return i}function N(e,i){if(i.length===0)return [];let r=new Map;for(let t of i){let o=`${t.tagPrefix}:${t.name}`;if(r.has(o))throw new Error(`recognizeCustomNodes: duplicate definition for ${JSON.stringify(o)}`);r.set(o,t);}let s=[],a=(t,o)=>{if(!(t.kind==="textValue"||o>64)){if(t.kind==="contentControl"){let d=k(t),n=d!==void 0?g(d):null,l=n?r.get(`${n.prefix}:${n.name}`):void 0;if(n&&l&&d!==void 0){let c=v(t),u=l.fromDocx?l.fromDocx({attrs:n.attrs,text:c}):n.attrs;if(u!==null){s.push({name:l.name,attrs:u,text:c,nodeId:t.id,tag:d});return}}}for(let d of t.children)a(d,o+1);}};return a(e.root,0),s}function R(e,i){let r=store.findNode(e,i);return !r||r.kind!=="paragraph"?[]:store.revisionItemsOf({id:e.id,name:e.name,contentType:e.contentType,root:r})}function b(e,i){let r=i.filter(o=>o.reviewCard);if(r.length===0)return [];let s=N(e,r);if(s.length===0)return [];let a=store.locateSites(e),t=[];for(let o of s){let d=r.find(c=>c.name===o.name&&o.tag.startsWith(`${c.tagPrefix}:`));if(!d)continue;let n=d.reviewCard({attrs:o.attrs,text:o.text});if(n===null)continue;let l=a.get(o.nodeId);t.push({kind:"custom",id:o.nodeId,name:o.name,tag:o.tag,attrs:o.attrs,text:o.text,title:n.title,...n.detail!==void 0?{detail:n.detail}:{},range:l?{partName:e.name,start:{paragraphId:l.paragraphId,offset:l.start},end:{paragraphId:l.paragraphId,offset:l.end}}:null});}return t}function O(e){let i=store.collectReviewItems(e),r=(e.customNodes??[]).filter(x);if(r.length===0)return i;let s=[e.storyPart],a=new Set([e.storyPart.name]);for(let n of e.furnitureParts??[])a.has(n.name)||(a.add(n.name),s.push(n));let t=[],o=new Map;for(let n of s){t.push(...b(n,r));let l=o.size;for(let[c,u]of store.paragraphOrderOfPart(n))o.has(c)||o.set(c,l+u);}return t.length===0?i:[...i,...t].sort((n,l)=>layout.reviewItemPositionRank(n,o)-layout.reviewItemPositionRank(l,o))}function se(e={}){return f(e.licenseKey),{id:"review",review:{displayModes:["all-markup","proposed","original"],collectReviewItems:O,revisionItemsOfParagraph:R}}}function w(e){return e.surface??null}function _(e,i){let r=null,s=t=>t.id===i?true:t.kind==="textValue"?false:t.children.some(s),a=(t,o)=>{if(!(r||t.kind==="textValue"||o>64)){if(t.kind==="paragraph"){s(t)&&(r=t);return}for(let d of t.children)a(d,o+1);}};return a(e.root,0),r}function A(e,i){let r=new Set,s=n=>{if(r.add(n.id),n.kind!=="textValue")for(let l of n.children)s(l);},a=n=>{if(n.id===i)return n;if(n.kind==="textValue")return null;for(let l of n.children){let c=a(l);if(c)return c}return null},t=a(e);if(!t)return null;s(t);let o=Number.MAX_SAFE_INTEGER,d=-1;for(let n of store.segmentsOf(e))r.has(n.runId)&&(n.start<o&&(o=n.start),n.end>d&&(d=n.end));return d<0?null:{start:o,end:d}}function ce(e,i){let r=w(e);if(!r)return {ok:false,code:"notFound",reason:"no document is mounted"};let s=r.session.applyTreeOps([{op:"removeContentControl",controlId:i,keepContent:false}]);return s.committed?{ok:true,changed:true}:{ok:false,code:"unsupported",reason:typeof s.reason=="string"?s.reason:"the removal was refused"}}function ue(e,i,r,s,a,t={}){let o=w(e);if(!o)return {ok:false,code:"notFound",reason:"no document is mounted"};let d=p(i.tagPrefix,i.name,s);if(!d.ok)return {ok:false,code:"invalidArgs",reason:`the encoded tag is ${d.length} characters; Word caps w:tag at 64 \u2014 shorten the attrs`};let n=o.session.part(),l=_(n,r),c=l?A(l,r):null;if(!l||!c)return {ok:false,code:"notFound",reason:"no custom node with that id"};let u=t.lock===void 0?"contentLocked":t.lock,m=o.session.applyTreeOps([{op:"removeContentControl",controlId:r,keepContent:false},{op:"insertInlineContentControl",paragraphId:l.id,offset:c.start,tag:d.tag,text:a,...t.alias===void 0?{}:{alias:t.alias},...u===false?{}:{lock:u}}]);return m.committed?{ok:true,changed:true}:{ok:false,code:"unsupported",reason:typeof m.reason=="string"?m.reason:"the update was refused"}}exports.a=z;exports.b=p;exports.c=g;exports.d=x;exports.e=y;exports.f=U;exports.g=F;exports.h=N;exports.i=se;exports.j=ce;exports.k=ue;

package/dist/define-custom-node-CkkDPdB0.d.cts

@@ -0,0 +1,191 @@
+import { EditorModule } from '@docx-editor.dev/core/editor';
+import { OoxmlPart } from '@docx-editor.dev/core/store';
+
+/**
+ * Licensing, v1: honor system.
+ *
+ * The key is accepted and remembered so that adding offline (Ed25519)
+ * verification later is not a breaking change — but nothing validates it,
+ * nothing warns, nothing renders differently, and NOTHING EVER LEAVES THE
+ * PROCESS: no network request is made for licensing, ever. That last property
+ * is a spec requirement (`pro-licensing`), not an implementation detail.
+ */
+/** Accepted by every pro entry point. */
+interface ProLicenseOptions {
+    /**
+     * Your license key from docx-editor.dev. Optional in v1: unlicensed use in
+     * development and evaluation is permitted, production use requires a
+     * license (see LICENSE.md) — the package trusts you either way.
+     */
+    readonly licenseKey?: string;
+}
+
+/**
+ * The review module: comments, tracked changes, and markup rendering as an
+ * `EditorModule` for `createDocxEditor({ modules })`.
+ *
+ * Registering it is the whole enablement story: the review chrome slots light
+ * up through the same `toolbarCommandState` they were disabled by, suggesting
+ * mode becomes reachable, and the editor renders revisions in markup rather
+ * than the free tier's final-state projection.
+ */
+
+/**
+ * How {@link reviewModule} is configured. Carries only the licence key today, so
+ * `reviewModule()` with no argument is the ordinary call.
+ *
+ * @public
+ */
+interface ReviewModuleOptions extends ProLicenseOptions {
+}
+/** Build the review module. Construction never validates the key and never touches the network. */
+declare function reviewModule(options?: ReviewModuleOptions): EditorModule;
+
+/** A recognized custom node: one inline SDT whose tag matched a definition. */
+interface RecognizedCustomNode {
+    /** The definition's `name`. */
+    readonly name: string;
+    /** Attrs after the definition's `fromDocx` had its say. Untrusted input. */
+    readonly attrs: Readonly<Record<string, string>>;
+    /** The SDT's literal content text — what Word users see and may have edited. */
+    readonly text: string;
+    /** The SDT node's stable id in the canonical tree. */
+    readonly nodeId: string;
+    /** The raw `w:tag` the node was recognized from. */
+    readonly tag: string;
+}
+/**
+ * One integrator-defined inline node, anchored on a run-level SDT whose `w:tag` carries its
+ * identity.
+ *
+ * A definition claims a tag PREFIX, so `acme` recognizes every `acme:*` tag. An SDT whose prefix
+ * no definition claims stays literal — which is also what the free tier and Word itself render,
+ * so an unrecognized node never loses content or locks editing.
+ *
+ * Build one with {@link defineCustomNode}, which validates the shape, then register it through
+ * {@link customNodesModule}.
+ *
+ * @example
+ * ```ts
+ * const citation = defineCustomNode({
+ *   name: 'citation',
+ *   tagPrefix: 'acme',
+ *   chrome: { color: '#2563eb' },
+ *   onClick: (node) => openCitation(node.attrs.key),
+ * });
+ * ```
+ *
+ * @public
+ */
+interface CustomNodeDefinition {
+    /** Node type name — the second segment of the tag (`<prefix>:<name>?…`). */
+    readonly name: string;
+    /** Tag prefix this definition claims (`acme` claims `acme:*`). No colons. */
+    readonly tagPrefix: string;
+    /**
+     * Recognition hook. Receives the decoded attrs and the SDT's literal text
+     * (so label drift from Word edits is visible) and returns the attrs the node
+     * should carry — or null to leave this SDT unrecognized and literal.
+     *
+     * Every input value originates in a file an attacker controls; treat it as
+     * untrusted and never build DOM or URLs from it without sanitizing.
+     */
+    readonly fromDocx?: (input: {
+        readonly attrs: Readonly<Record<string, string>>;
+        readonly text: string;
+    }) => Readonly<Record<string, string>> | null;
+    /**
+     * Chip appearance, HOST-authored (never file data). `color` tints the chip
+     * and its border; applied by `CustomNodeChrome` from `@docx-editor.dev/pro/react`.
+     */
+    readonly chrome?: {
+        readonly color?: string;
+    };
+    /** Click on the painted chip. UI state belongs in `CustomNodeChrome`'s `onNodeClick`. */
+    readonly onClick?: (node: ActivatedCustomNode) => void;
+    /** Pointer enters the painted chip. */
+    readonly onHover?: (node: ActivatedCustomNode) => void;
+    /**
+     * Contribute a card to the review sidebar for every recognized node of this
+     * definition, anchored at the node's range. Return null to skip one node.
+     *
+     * `attrs` and `text` originate in the file — untrusted; the returned strings
+     * are rendered as TEXT by the pane, never markup. The context-menu section
+     * reuses this hook for its info block and may invoke it with `text: ''` when
+     * no review module is registered (the DOM decode alone cannot see the text).
+     */
+    readonly reviewCard?: (node: {
+        readonly attrs: Readonly<Record<string, string>>;
+        readonly text: string;
+    }) => {
+        readonly title: string;
+        readonly detail?: string;
+    } | null;
+    /**
+     * The "Edit {label}" row the context menu shows at the top when the
+     * right-click lands on the node's chip. The HOST owns the dialog.
+     *
+     * HONEST LIMIT: there is no in-place update call yet — re-authoring is
+     * `removeContentControl` + `insertCustomNode` at the node's range (the
+     * activation carries `nodeId` and, when a review module is registered, the
+     * current `text` to prefill a form). Schema-driven edit forms are the planned
+     * follow-up.
+     */
+    readonly onEdit?: (node: ActivatedCustomNode) => void;
+    /**
+     * Display name for chrome — the "Edit {label}" context-menu row. Defaults to
+     * `name`. Host-authored, never file data; provide a localized string.
+     */
+    readonly label?: string;
+}
+/**
+ * A chip activation: identity + attrs, plus where it sits.
+ *
+ * `attrs` are the definition's OWN shape — the raw tag decode has already been
+ * through `fromDocx`, exactly as the review derivation runs it, so every
+ * surface (click, hover, edit, cards) sees one attrs vocabulary. `text` and
+ * `nodeId` are present when the surface could resolve them (a registered
+ * review module resolves both).
+ */
+interface ActivatedCustomNode {
+    readonly name: string;
+    readonly attrs: Readonly<Record<string, string>>;
+    readonly tag: string;
+    /** Viewport-relative rect of the chip's boundary, for anchoring host UI. */
+    readonly rect: DOMRect;
+    /** The SDT node's canonical id — the address `removeContentControl` takes. */
+    readonly nodeId?: string;
+    /** The node's literal content text, when resolvable. */
+    readonly text?: string;
+}
+/**
+ * Whether an opaque registry value is a custom-node definition.
+ *
+ * The engine carries registered definitions as unknowns (`getCustomNodeDefinitions`), so
+ * every pro surface that reads them back narrows through this ONE guard.
+ */
+declare function isCustomNodeDefinition(candidate: unknown): candidate is CustomNodeDefinition;
+/** Validate and freeze a definition. Throws on a shape mistake — author error, not file input. */
+declare function defineCustomNode(definition: CustomNodeDefinition): CustomNodeDefinition;
+/**
+ * How {@link customNodesModule} is configured.
+ *
+ * @public
+ */
+interface CustomNodesModuleOptions extends ProLicenseOptions {
+    /** The definitions this editor recognizes. A tag prefix no definition claims stays literal. */
+    readonly nodes: readonly CustomNodeDefinition[];
+}
+/** Register custom node definitions with `createDocxEditor({ modules })`. */
+declare function customNodesModule(options: CustomNodesModuleOptions): EditorModule;
+/**
+ * Every recognized custom node in one story, in document order.
+ *
+ * Tag-prefix keyed, exactly as the change specifies: an inline SDT whose tag
+ * decodes to a registered `<prefix>:<name>` pair is offered to that
+ * definition's `fromDocx`; everything else — foreign tags, unregistered
+ * prefixes, a `fromDocx` veto — stays a literal SDT.
+ */
+declare function recognizeCustomNodes(part: OoxmlPart, definitions: readonly CustomNodeDefinition[]): RecognizedCustomNode[];
+
+export { type ActivatedCustomNode as A, type CustomNodeDefinition as C, type ProLicenseOptions as P, type RecognizedCustomNode as R, type CustomNodesModuleOptions as a, type ReviewModuleOptions as b, customNodesModule as c, defineCustomNode as d, reviewModule as e, isCustomNodeDefinition as i, recognizeCustomNodes as r };