@crossworks/content-core 0.230.43

package/LICENSE.md

@@ -0,0 +1,135 @@
+# License
+
+Mantle is **dual-licensed** by Cross Works Engineering (Pty) Ltd:
+
+1. **Public license — Functional Source License 1.1 (MIT Future), reproduced in
+   full below.** Free to use, self-host, modify, and run for any purpose that is
+   not a Competing Use (see the _Permitted Purpose_ clause). Two years after each
+   version is first published, that version automatically converts to the MIT
+   license.
+2. **Commercial license — see [`LICENSE-COMMERCIAL.md`](./LICENSE-COMMERCIAL.md).**
+   A paid agreement that lifts the FSL's _Competing Use_ restriction for partners
+   who want to embed Mantle in a commercial product or offer it as a service
+   during the two-year window. Contact **licensing@crossworks.engineering**.
+
+For a plain-language explanation of how the two licenses fit together and what the
+key terms mean, see [`LICENSING.md`](./LICENSING.md). Third-party open-source
+components bundled with Mantle are attributed in
+[`THIRD-PARTY-NOTICES.md`](./THIRD-PARTY-NOTICES.md).
+
+The "Change Date" for each release is **two years after that release is first made
+available** under this license; on the Change Date that release becomes available
+under the MIT license (the _Grant of Future License_ below).
+
+---
+
+# Functional Source License, Version 1.1, MIT Future License
+
+## Abbreviation
+
+FSL-1.1-MIT
+
+## Notice
+
+Copyright 2026 Cross Works Engineering (Pty) Ltd
+
+## Terms and Conditions
+
+### Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+### The Software
+
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
+
+### License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to
+use, copy, modify, create derivative works, publicly perform, publicly display
+and redistribute the Software for any Permitted Purpose identified below.
+
+### Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
+means making the Software available to others in a commercial product or
+service that:
+
+1. substitutes for the Software;
+
+2. substitutes for any other product or service we offer using the Software
+   that exists as of the date we make the Software available; or
+
+3. offers the same or substantially similar functionality as the Software.
+
+Permitted Purposes specifically include using the Software:
+
+1. for your internal use and access;
+
+2. for non-commercial education;
+
+3. for non-commercial research; and
+
+4. in connection with professional services that you provide to a licensee
+   using the Software in accordance with these Terms and Conditions.
+
+### Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our
+patents, the license grant above includes a license under our patents. If you
+make a claim against any party that the Software infringes or contributes to
+the infringement of any patent, then your patent license to the Software ends
+immediately.
+
+### Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives of
+the Software.
+
+If you redistribute any copies, modifications or derivatives of the Software,
+you must include a copy of or a link to these Terms and Conditions and not
+remove any copyright notices provided in or with the Software.
+
+### Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
+PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
+SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
+EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
+
+### Trademarks
+
+Except for displaying the License Details and identifying us as the origin of
+the Software, you have no right under these Terms and Conditions to use our
+trademarks, trade names, service marks or product names.
+
+## Grant of Future License
+
+We hereby irrevocably grant you an additional license to use the Software under
+the MIT license that is effective on the second anniversary of the date we make
+the Software available. On or after that date, you may use the Software under
+the MIT license, in which case the following will apply:
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@crossworks/content-core",
+  "version": "0.230.43",
+  "description": "Browser-safe content logic — markdown, blocks, pages, tables, formulas — shared by the server and any client. Zero server deps by design: nothing here may reach @mantle/db, node-only APIs, or the network (the jackdaw-repo-split P0 boundary).",
+  "exports": {
+    "./markdown": "./src/markdown-to-doc.ts",
+    "./markdown-refs": "./src/markdown-refs.ts",
+    "./doc-to-markdown": "./src/doc-to-markdown.ts",
+    "./block-ids": "./src/block-ids.ts",
+    "./block-list": "./src/block-list.ts",
+    "./block-diff": "./src/block-diff.ts",
+    "./page-toc": "./src/page-toc.ts",
+    "./page-split": "./src/page-split.ts",
+    "./page-diff": "./src/page-diff.ts",
+    "./table-model": "./src/table-model.ts",
+    "./table-formula": "./src/table-formula.ts",
+    "./table-formula-mathjs": "./src/table-formula-mathjs.ts",
+    "./formula-spec": "./src/formula-spec.ts",
+    "./formula-eval": "./src/formula-eval.ts",
+    "./formula-seed": "./src/formula-seed.ts",
+    "./formula-dimensions": "./src/formula-dimensions.ts",
+    "./contacts-format": "./src/contacts-format.ts",
+    "./journal-options": "./src/journal-options.ts",
+    "./onboarding-questions": "./src/onboarding-questions.ts",
+    "./persona-bank": "./src/persona-bank.ts",
+    "./thinking-tiers": "./src/thinking-tiers.ts",
+    "./formula-signature": "./src/formula-signature.ts"
+  },
+  "dependencies": {
+    "marked": "^18.0.7",
+    "mathjs": "15.2.0"
+  },
+  "license": "SEE LICENSE IN LICENSE.md",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/crossworks-engineering/mantle"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/block-diff.test.ts

@@ -0,0 +1,190 @@
+/**
+ * Unit tests for diffBlocks — drives the AI-assist panel's diff summary
+ * + (later) the editor's per-block diff view. Stable per-block ids are
+ * the foundation; this test layer locks down the matching semantics.
+ */
+
+import { describe, expect, it } from 'vitest';
+import { ensureBlockIds } from './block-ids';
+import { diffBlocks } from './block-diff';
+
+function blocked(doc: Record<string, unknown>): Record<string, unknown> {
+  return ensureBlockIds(doc);
+}
+
+describe('diffBlocks', () => {
+  it('reports zero changes when doc and draft are identical', () => {
+    const doc = blocked({
+      type: 'doc',
+      content: [
+        { type: 'paragraph', content: [{ type: 'text', text: 'hi' }] },
+        { type: 'paragraph', content: [{ type: 'text', text: 'world' }] },
+      ],
+    });
+    const d = diffBlocks(doc, doc);
+    expect(d.added).toEqual([]);
+    expect(d.removed).toEqual([]);
+    expect(d.changed).toEqual([]);
+    expect(d.unchangedCount).toBe(2);
+    expect(d.ordered).toEqual([]);
+  });
+
+  it("reports an added block when the draft has one the doc doesn't", () => {
+    const doc = blocked({
+      type: 'doc',
+      content: [{ type: 'paragraph', content: [{ type: 'text', text: 'one' }] }],
+    });
+    // Draft = doc + a new paragraph (fresh id).
+    const draftContent = [
+      ...(doc as { content: unknown[] }).content,
+      { type: 'paragraph', attrs: { id: 'new-block' }, content: [{ type: 'text', text: 'two' }] },
+    ];
+    const draft = { type: 'doc', content: draftContent };
+
+    const d = diffBlocks(doc, draft);
+    expect(d.added).toHaveLength(1);
+    expect(d.added[0]!.id).toBe('new-block');
+    expect(d.removed).toEqual([]);
+    expect(d.changed).toEqual([]);
+    expect(d.unchangedCount).toBe(1);
+    expect(d.ordered).toHaveLength(1);
+    expect(d.ordered[0]!.kind).toBe('added');
+  });
+
+  it('reports a removed block when the draft is missing one the doc has', () => {
+    type N = { attrs: { id: string } };
+    const doc = blocked({
+      type: 'doc',
+      content: [
+        { type: 'paragraph', content: [{ type: 'text', text: 'keep' }] },
+        { type: 'paragraph', content: [{ type: 'text', text: 'drop' }] },
+      ],
+    });
+    const keepId = (doc as { content: N[] }).content[0]!.attrs.id;
+    const draft = blocked({
+      type: 'doc',
+      content: [
+        { type: 'paragraph', attrs: { id: keepId }, content: [{ type: 'text', text: 'keep' }] },
+      ],
+    });
+
+    const d = diffBlocks(doc, draft);
+    expect(d.added).toEqual([]);
+    expect(d.removed).toHaveLength(1);
+    expect(d.removed[0]!.preview).toBe('drop');
+    expect(d.changed).toEqual([]);
+    expect(d.unchangedCount).toBe(1);
+  });
+
+  it('reports a changed block when same id has different content', () => {
+    type N = { attrs: { id: string } };
+    const doc = blocked({
+      type: 'doc',
+      content: [{ type: 'paragraph', content: [{ type: 'text', text: 'old text' }] }],
+    });
+    const id = (doc as { content: N[] }).content[0]!.attrs.id;
+    const draft = {
+      type: 'doc',
+      content: [
+        { type: 'paragraph', attrs: { id }, content: [{ type: 'text', text: 'new text' }] },
+      ],
+    };
+
+    const d = diffBlocks(doc, draft);
+    expect(d.changed).toHaveLength(1);
+    expect(d.changed[0]!.from.preview).toBe('old text');
+    expect(d.changed[0]!.to.preview).toBe('new text');
+    expect(d.added).toEqual([]);
+    expect(d.removed).toEqual([]);
+    expect(d.unchangedCount).toBe(0);
+  });
+
+  it('detects style-only changes (callout variant flip) as changed, not unchanged', () => {
+    const id = 'call-1';
+    const doc = {
+      type: 'doc',
+      content: [
+        {
+          type: 'callout',
+          attrs: { id, variant: 'info' },
+          content: [
+            { type: 'paragraph', attrs: { id: 'p-1' }, content: [{ type: 'text', text: 'note' }] },
+          ],
+        },
+      ],
+    };
+    const draft = {
+      type: 'doc',
+      content: [
+        {
+          type: 'callout',
+          attrs: { id, variant: 'warning' }, // only the variant changed
+          content: [
+            { type: 'paragraph', attrs: { id: 'p-1' }, content: [{ type: 'text', text: 'note' }] },
+          ],
+        },
+      ],
+    };
+
+    const d = diffBlocks(doc, draft);
+    // The callout (id call-1) is changed; the inner paragraph (id p-1) is unchanged.
+    expect(d.changed.map((c) => c.to.id)).toContain(id);
+    // p-1's text is the same, JSON identical → unchanged.
+    expect(d.changed.map((c) => c.to.id)).not.toContain('p-1');
+  });
+
+  it('handles a complete restyle (every block changed)', () => {
+    type N = { attrs: { id: string } };
+    const doc = blocked({
+      type: 'doc',
+      content: [
+        { type: 'paragraph', content: [{ type: 'text', text: 'A' }] },
+        { type: 'paragraph', content: [{ type: 'text', text: 'B' }] },
+        { type: 'paragraph', content: [{ type: 'text', text: 'C' }] },
+      ],
+    });
+    const ids = (doc as { content: N[] }).content.map((b) => b.attrs.id);
+    const draft = {
+      type: 'doc',
+      content: [
+        { type: 'paragraph', attrs: { id: ids[0] }, content: [{ type: 'text', text: 'AA' }] },
+        { type: 'paragraph', attrs: { id: ids[1] }, content: [{ type: 'text', text: 'BB' }] },
+        { type: 'paragraph', attrs: { id: ids[2] }, content: [{ type: 'text', text: 'CC' }] },
+      ],
+    };
+    const d = diffBlocks(doc, draft);
+    expect(d.changed).toHaveLength(3);
+    expect(d.unchangedCount).toBe(0);
+    expect(d.added).toEqual([]);
+    expect(d.removed).toEqual([]);
+  });
+
+  it('ordered output preserves the document-walk order', () => {
+    type N = { attrs: { id: string } };
+    const doc = blocked({
+      type: 'doc',
+      content: [
+        { type: 'paragraph', content: [{ type: 'text', text: 'A' }] },
+        { type: 'paragraph', content: [{ type: 'text', text: 'B' }] },
+        { type: 'paragraph', content: [{ type: 'text', text: 'C' }] },
+      ],
+    });
+    const [aId, bId, cId] = (doc as { content: N[] }).content.map((b) => b.attrs.id);
+    // Draft: change A, leave B, drop C, add a new D at the end.
+    const draft = {
+      type: 'doc',
+      content: [
+        { type: 'paragraph', attrs: { id: aId }, content: [{ type: 'text', text: 'AA' }] },
+        { type: 'paragraph', attrs: { id: bId }, content: [{ type: 'text', text: 'B' }] },
+        { type: 'paragraph', attrs: { id: 'new-d' }, content: [{ type: 'text', text: 'D' }] },
+      ],
+    };
+    const d = diffBlocks(doc, draft);
+    // Expected ordering: walk draft (A=changed, B=unchanged-skipped, D=added),
+    // then removals from doc (C=removed).
+    expect(d.ordered.map((c) => c.kind)).toEqual(['changed', 'added', 'removed']);
+    expect((d.ordered[0]! as { kind: 'changed'; to: { id: string } }).to.id).toBe(aId);
+    expect((d.ordered[1]! as { kind: 'added'; block: { id: string } }).block.id).toBe('new-d');
+    expect((d.ordered[2]! as { kind: 'removed'; block: { id: string } }).block.id).toBe(cId);
+  });
+});

package/src/block-diff.ts

@@ -0,0 +1,163 @@
+/**
+ * Block-level diff between two PM docs — typically the published `doc`
+ * vs the in-flight `draft_doc`. Powers the Phase 3a AI-assist panel
+ * ("Pages changed 3 blocks") and (later) the per-block visual diff in
+ * the editor.
+ *
+ * Algorithm: match blocks by stable id (the foundation that block-ids.ts
+ * provides). The four states per block are:
+ *
+ *   - unchanged: same id in both, content equal → no entry
+ *   - added:     id only in draft → DRAFT introduced a new block
+ *   - removed:   id only in doc → DRAFT removed a block
+ *   - changed:   same id in both, content differs → DRAFT modified the block
+ *
+ * "Content equal" uses JSON.stringify of the block node (cheap, exact —
+ * captures attribute, mark, and structure changes, not just text).
+ *
+ * Returns flat lists, not a tree. The panel renders these grouped;
+ * downstream tools (commit, discard) operate at the doc level (the diff
+ * is just for displaying what's about to happen).
+ *
+ * Pure. Imports the same listBlocks helper as `page_blocks_list` so the
+ * shape of each entry matches what the agent already saw.
+ */
+
+import { listBlocks, type BlockListEntry } from './block-list';
+
+export type BlockChange =
+  | { kind: 'added'; block: BlockListEntry }
+  | { kind: 'removed'; block: BlockListEntry }
+  | { kind: 'changed'; from: BlockListEntry; to: BlockListEntry };
+
+export type BlockDiff = {
+  /** Blocks present in draft, absent in doc — agent inserted these. */
+  added: BlockListEntry[];
+  /** Blocks present in doc, absent in draft — agent removed these. */
+  removed: BlockListEntry[];
+  /** Same id in both, content differs — agent rewrote these. */
+  changed: Array<{ from: BlockListEntry; to: BlockListEntry }>;
+  /** Total blocks in the draft that weren't touched. Useful for "23 of 25 blocks unchanged" UX. */
+  unchangedCount: number;
+  /** Flat list of every change in document order — for diff rendering. */
+  ordered: BlockChange[];
+};
+
+/**
+ * Compute the block-level diff. Pass the doc (published) and draft.
+ * If either is null/empty, the diff is computed against an empty
+ * counterpart — callers can pass an empty doc when one side is missing.
+ */
+export function diffBlocks(
+  doc: Record<string, unknown>,
+  draft: Record<string, unknown>,
+): BlockDiff {
+  const docBlocks = listBlocks(doc);
+  const draftBlocks = listBlocks(draft);
+
+  // We need the full nodes for content-equality, but listBlocks only
+  // returns previews. Walk both docs again to capture id → full JSON.
+  // Cheap (single pass each) — only done when something invokes us.
+  const docJsonById = collectBlockJson(doc);
+  const draftJsonById = collectBlockJson(draft);
+
+  const docById = new Map(docBlocks.map((b) => [b.id, b]));
+  const draftById = new Map(draftBlocks.map((b) => [b.id, b]));
+
+  const added: BlockListEntry[] = [];
+  const removed: BlockListEntry[] = [];
+  const changed: Array<{ from: BlockListEntry; to: BlockListEntry }> = [];
+  let unchangedCount = 0;
+  const ordered: BlockChange[] = [];
+
+  for (const draftBlock of draftBlocks) {
+    const docBlock = docById.get(draftBlock.id);
+    if (!docBlock) {
+      added.push(draftBlock);
+      ordered.push({ kind: 'added', block: draftBlock });
+      continue;
+    }
+    const docJson = docJsonById.get(draftBlock.id);
+    const draftJson = draftJsonById.get(draftBlock.id);
+    if (blockJsonEqual(docJson, draftJson)) {
+      unchangedCount++;
+    } else {
+      changed.push({ from: docBlock, to: draftBlock });
+      ordered.push({ kind: 'changed', from: docBlock, to: draftBlock });
+    }
+  }
+  // Blocks only in the doc (not in draft) are removals — preserve doc order
+  // for these, then concat after the draft-ordered changes so the consumer
+  // can render "everything in draft order, then what got removed".
+  for (const docBlock of docBlocks) {
+    if (!draftById.has(docBlock.id)) {
+      removed.push(docBlock);
+      ordered.push({ kind: 'removed', block: docBlock });
+    }
+  }
+
+  return { added, removed, changed, unchangedCount, ordered };
+}
+
+// ─── Helpers ───────────────────────────────────────────────────────────
+
+type AnyNode = {
+  type?: string;
+  attrs?: Record<string, unknown> | null;
+  content?: AnyNode[];
+};
+
+/**
+ * Walk a doc and collect every addressable block's full JSON, keyed by
+ * id. Used for content-equality in the diff. We compare full node JSON
+ * rather than just text so style changes (callout variant flip, heading
+ * level change, mark added/removed) register as 'changed' even if the
+ * plaintext is identical.
+ */
+function collectBlockJson(doc: Record<string, unknown>): Map<string, AnyNode> {
+  const out = new Map<string, AnyNode>();
+  walkCollect(doc as AnyNode, out);
+  return out;
+}
+
+function walkCollect(node: AnyNode, out: Map<string, AnyNode>): void {
+  if (!node || typeof node !== 'object') return;
+  const id = node.attrs && typeof node.attrs.id === 'string' ? node.attrs.id : null;
+  if (id) out.set(id, node);
+  if (Array.isArray(node.content)) {
+    for (const child of node.content) walkCollect(child, out);
+  }
+}
+
+/**
+ * Compare two PM block nodes for content equality. Uses stable
+ * (sorted-key) JSON stringification so two nodes with the same fields
+ * in different orders compare equal — necessary because ensureBlockIds
+ * produces `{ type, content, attrs }` (spread + add) while hand-built
+ * nodes (e.g. agent tool output, autosave round-trips through different
+ * serializers) often have `{ type, attrs, content }`. JSON-string
+ * compare is fast enough for the panel diff (typical block ~200 bytes;
+ * even a 200-block page is ~40 KB of stringification — one-shot per
+ * diff call).
+ */
+function blockJsonEqual(a: AnyNode | undefined, b: AnyNode | undefined): boolean {
+  if (a === b) return true;
+  if (!a || !b) return false;
+  return stableStringify(a) === stableStringify(b);
+}
+
+/** JSON.stringify with sorted object keys at every depth. Arrays keep
+ *  their order (semantic in PM). Stable across the runtime — the same
+ *  input always produces the same string. */
+function stableStringify(value: unknown): string {
+  return JSON.stringify(value, (_key, v) => {
+    if (v && typeof v === 'object' && !Array.isArray(v)) {
+      const sorted: Record<string, unknown> = {};
+      for (const k of Object.keys(v as Record<string, unknown>).sort()) {
+        sorted[k] = (v as Record<string, unknown>)[k];
+      }
+      return sorted;
+    }
+    return v;
+  });
+}