@particle-academy/last-word-ui 0.6.0 → 0.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/AGENTS.md ADDED
@@ -0,0 +1,76 @@
1
+ # Using @particle-academy/last-word-ui — guide for agents
2
+
3
+ How an agent installs and uses this package in a consumer app. What the package
4
+ is, is in [README.md](./README.md). Notes for working ON this repo's code are in
5
+ [CONTRIBUTING.md](./CONTRIBUTING.md).
6
+
7
+ ## Install
8
+
9
+ ```bash
10
+ npm install @particle-academy/last-word-ui @particle-academy/react-fancy react react-dom
11
+ ```
12
+
13
+ - **Peers:** `@particle-academy/react-fancy` `>=5.0.0`, `react ^19`,
14
+ `react-dom ^19`. **Node:** `>=22`.
15
+ - **Charts are optional:** install `@particle-academy/fancy-echarts echarts` to
16
+ draw chart blocks; without them each chart is a sized, labelled placeholder.
17
+ - **The viewer does not read `.docx` bytes.** Read on the server (PHP
18
+ `particle-academy/last-word`, Python `fancy-last-word`) and send the JSON, or
19
+ read in the browser with `@particle-academy/last-word`.
20
+
21
+ ## Find it on the Fancy MCP server
22
+
23
+ The catalog server is `https://ui.particle.academy/mcp` (streamable HTTP, no API
24
+ key; MCP id `fancy-ui`). This package's registry entry is
25
+ `last-word-ui-doc-viewer`. Find it with `search-components` ("document
26
+ viewer", "docx"), use `install-instructions` for the exact commands and
27
+ `get-component` for the source bundle. Vendored source:
28
+ `npx fancy-cli@latest add last-word-ui-doc-viewer`. The readers and writers are
29
+ found with `search-backend-packages`.
30
+
31
+ ## API essentials
32
+
33
+ - `import { DocViewer, docFromReader } from "@particle-academy/last-word-ui"`;
34
+ `<DocViewer doc={doc} />`. `docFromReader()` takes a reader result or a JSON
35
+ string.
36
+ - **Props:** `doc`, `fit` (`"width" | "none"`), `scale`, `maxScale`, `gap`,
37
+ `filename`, `now`, `onLayout`, `injectStyles`, `renderChart`, `id`,
38
+ `className`, `style`. The full table is in the [README](./README.md).
39
+ - **`onLayout`** reports `{ pages, pageWidth, pageHeight, scale, font }` as
40
+ JSON; `font` is `"carlito"` (deterministic), `"fallback"` or `"unused"`.
41
+ - **Stable handles:** `data-lw-viewer` on the root, `data-page` (1-based) per
42
+ page, `data-block` (`b0`, `b1`, ...) per block or fragment, `data-footnote`,
43
+ `data-lw-band` / `data-lw-band-variant`, `data-lw-rows`,
44
+ `data-lw-repeated-header`, `data-lw-chart`, `data-lw-chart-placeholder`,
45
+ `data-lw-font`, `data-lw-tracked-changes` / `data-lw-tracked-changes-notice`.
46
+ - **Lower level:** `paginate()`, `pageGeometry()`, `pageMargins()`,
47
+ `bodyBox()`, `numberFootnotes()`, `substituteFields()` lay pages out without
48
+ the DOM.
49
+
50
+ ## Traps
51
+
52
+ - **Render the object you were given.** Footnote numbering is keyed by run
53
+ identity, so deep-cloning the Doc between numbering and render loses the
54
+ marks.
55
+ - **Under a CSP without `'unsafe-inline'` styles**, pass
56
+ `injectStyles={false}` and `import "@particle-academy/last-word-ui/styles.css"`.
57
+ Allow the bundled font files in `font-src`.
58
+ - **The CommonJS build cannot resolve the bundled font** (no `import.meta`), so
59
+ it reports `font: "fallback"`; import `styles.css` there.
60
+ - **Only Calibri and default text paginate deterministically** (the bundled
61
+ Carlito). Other fonts draw as installed on the machine.
62
+ - **Nothing is drawn until the font loads**, up to `FONT_LOAD_TIMEOUT_MS`
63
+ (3 s).
64
+ - **Tracked changes are not shown, and that is a fail-safe.** A `doc` carrying any
65
+ `revision` key draws with a notice (`data-lw-tracked-changes-notice`), deleted and
66
+ moved-away runs (`delete`, `moveFrom`, or a revision it cannot read) are hidden,
67
+ and inserted text draws as normal text. Check `hasRevisions(doc)` (or `onLayout`'s
68
+ `revisions`) before showing a document, and have the person accept or reject the
69
+ changes first. The viewer never edits the model, so the revisions survive for
70
+ whatever writes the file back.
71
+ - **Not yet handled:** a table row taller than a page (`data-lw-overflow`), an
72
+ unbreakable block taller than a page (`data-lw-forced`), a footnote that does
73
+ not fit, page backgrounds and border frames.
74
+ - **A Doc is untrusted input:** links render only for `http(s)`, `mailto`,
75
+ `tel` and `#anchor`; images only from `data:image/...`; colours only as
76
+ `#RRGGBB`.
package/CHANGELOG.md CHANGED
@@ -10,6 +10,38 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
10
10
 
11
11
  ## [Unreleased]
12
12
 
13
+ ## [0.7.0] - 2026-11-22
14
+
15
+ ### Added
16
+
17
+ - **Fail-safe: a document with tracked changes no longer draws deleted text as live
18
+ text.** last-word's model is gaining tracked-changes authoring: a `revision` key on
19
+ runs (`insert`, `delete`, `moveFrom`, `moveTo`, `format`), on paragraph and heading
20
+ blocks and on list items. This viewer cannot show revisions, and before this it drew
21
+ them as if they were not there, so deleted text read as part of the document. Now,
22
+ when a `doc` carries any `revision`: a run that was deleted or moved away
23
+ (`delete`, `moveFrom`) is not drawn, on the pages or in the measuring copy, and its
24
+ footnote is not numbered; inserted, moved-here and reformatted text draws as
25
+ before; a block-level mark keeps its text. A notice above the pages says so
26
+ (`TRACKED_CHANGES_NOTICE`, handle `data-lw-tracked-changes-notice` with
27
+ `data-lw-revisions`, the count), and the root gains `data-lw-tracked-changes`. A
28
+ `revision` this viewer cannot read counts as deleted: hiding text under a notice is
29
+ recoverable, showing deleted text as live is not. The viewer never changes the
30
+ model: the revisions are still there for the host to write back. This is a guard,
31
+ not support; there is no review UI. New exports: `hasRevisions(doc)`,
32
+ `revisionPaths(doc)` (JSON Pointers) and `isDeletedRun(run)`; `onLayout` gains
33
+ `revisions` (the same pointers), absent when there are none. A document without
34
+ revisions draws exactly as before; nothing to do.
35
+
36
+ ### Changed
37
+
38
+ - **CI: the lab-certificate gate verifies against the lab's rotated key list.**
39
+ The lab's first signing key is retired: certificates it already issued still
40
+ verify, and nothing new it signs ever can. Consumers do nothing.
41
+
42
+ - **Docs:** `AGENTS.md` is now the guide to using this package (install, its entries on the Fancy MCP catalog server, API essentials, traps), and it ships in the package. The contributor notes it held moved to `CONTRIBUTING.md`, and `CLAUDE.md` is now a symlink to it. The README points to the MCP server and to `AGENTS.md`. No code changed; nothing to do.
43
+ - CI: re-pin org third-party allowlist to 2614224
44
+
13
45
  ## [0.6.0] - 2026-11-15
14
46
 
15
47
  **What you must do:** to see charts drawn, install the optional peer:
package/README.md CHANGED
@@ -10,6 +10,13 @@ reflows the text.
10
10
  > **Pre-1.0:** breaking changes land in MINOR releases. Read the
11
11
  > [CHANGELOG](./CHANGELOG.md) entry before taking one.
12
12
 
13
+ <!-- fancy-agents-note:start -->
14
+ > **For agents.** This package is listed on the Fancy MCP catalog server at
15
+ > `https://ui.particle.academy/mcp` (streamable HTTP, no API key; MCP id `fancy-ui`),
16
+ > with install commands and docs, alongside the rest of the kit. How an agent
17
+ > installs and uses this package is in [AGENTS.md](https://github.com/Particle-Academy/last-word-ui/blob/main/AGENTS.md).
18
+ <!-- fancy-agents-note:end -->
19
+
13
20
  ## Install
14
21
 
15
22
  ```bash
@@ -201,14 +208,6 @@ It takes heights in and returns page assignments, with no DOM. Use it with
201
208
  applied), `bodyBox()`, `numberFootnotes(doc)` and `substituteFields()` to lay
202
209
  pages out elsewhere.
203
210
 
204
- ## Develop
205
-
206
- ```bash
207
- npm test # vitest + jsdom
208
- npm run lint # tsc + eslint
209
- npm run demo # vite demo: a multi-page memo, wide and narrow
210
- ```
211
-
212
211
  ## License
213
212
 
214
213
  MIT, except the fonts in `fonts/`: Carlito, SIL Open Font License 1.1, see
package/dist/index.cjs CHANGED
@@ -392,6 +392,49 @@ function safeHref(url) {
392
392
  return ALLOWED.has(parsed.protocol) ? url : void 0;
393
393
  }
394
394
 
395
+ // src/revisions.ts
396
+ var TRACKED_CHANGES_NOTICE = "This document has tracked changes, which this viewer can't show yet. Accept them first. Deleted text is hidden.";
397
+ var isObject = (v) => typeof v === "object" && v !== null;
398
+ var KEPT_KINDS = /* @__PURE__ */ new Set(["insert", "moveTo", "format"]);
399
+ var KINDS = ["insert", "delete", "moveFrom", "moveTo", "format"];
400
+ function revisionKind(revision) {
401
+ if (typeof revision === "string") return revision;
402
+ if (!isObject(revision)) return null;
403
+ for (const key of ["type", "kind"]) {
404
+ if (typeof revision[key] === "string") return revision[key];
405
+ }
406
+ const named = KINDS.filter((k) => revision[k] !== void 0 && revision[k] !== false);
407
+ return named.length === 1 ? named[0] : null;
408
+ }
409
+ function isDeletedRun(run) {
410
+ if (!isObject(run) || !("revision" in run) || run.revision === void 0) return false;
411
+ const kind = revisionKind(run.revision);
412
+ return kind === null || !KEPT_KINDS.has(kind);
413
+ }
414
+ var escape = (key) => key.replace(/~/g, "~0").replace(/\//g, "~1");
415
+ function revisionPaths(doc) {
416
+ const found = [];
417
+ if (!isObject(doc)) return found;
418
+ const seen = /* @__PURE__ */ new Set();
419
+ const stack = [{ value: doc, at: "" }];
420
+ while (stack.length > 0) {
421
+ const { value, at } = stack.pop();
422
+ if (!isObject(value) || seen.has(value)) continue;
423
+ seen.add(value);
424
+ if (Array.isArray(value)) {
425
+ for (let i = value.length - 1; i >= 0; i--) stack.push({ value: value[i], at: `${at}/${i}` });
426
+ continue;
427
+ }
428
+ if (value.revision !== void 0) found.push(`${at}/revision`);
429
+ const keys = Object.keys(value).filter((k) => k !== "revision" && !(k === "option" && value.type === "chart"));
430
+ for (let i = keys.length - 1; i >= 0; i--) stack.push({ value: value[keys[i]], at: `${at}/${escape(keys[i])}` });
431
+ }
432
+ return found;
433
+ }
434
+ function hasRevisions(doc) {
435
+ return revisionPaths(doc).length > 0;
436
+ }
437
+
395
438
  // src/style.ts
396
439
  var pt = (n) => `${Math.round(n * 1e3) / 1e3}pt`;
397
440
  var px = (n) => `${Math.round(n * 1e3) / 1e3}px`;
@@ -566,6 +609,7 @@ function WithContext({ value, children }) {
566
609
  }
567
610
  function RunView({ run }) {
568
611
  const ctx = react.useContext(RenderCtx);
612
+ if (isDeletedRun(run)) return null;
569
613
  const mark = ctx.marks.get(run);
570
614
  let text = typeof run.text === "string" ? run.text : "";
571
615
  if (ctx.fields) text = substituteFields(text, ctx.fields);
@@ -609,7 +653,9 @@ function RunView({ run }) {
609
653
  }
610
654
  function Runs({ runs }) {
611
655
  const list = Array.isArray(runs) ? runs : [];
612
- const visible = list.some((r) => typeof r?.text === "string" && r.text !== "" || r?.footnote);
656
+ const visible = list.some(
657
+ (r) => !!r && typeof r === "object" && !isDeletedRun(r) && (typeof r.text === "string" && r.text !== "" || !!r.footnote)
658
+ );
613
659
  return /* @__PURE__ */ jsxRuntime.jsxs(jsxRuntime.Fragment, { children: [
614
660
  list.map((run, i) => run && typeof run === "object" ? /* @__PURE__ */ jsxRuntime.jsx(RunView, { run }, i) : null),
615
661
  !visible && ZWSP
@@ -897,7 +943,7 @@ function numberFootnotes(doc) {
897
943
  if (!Array.isArray(list)) return;
898
944
  for (const run of list) {
899
945
  const fn = run?.footnote;
900
- if (fn && typeof fn === "object" && Array.isArray(fn.blocks)) {
946
+ if (fn && !isDeletedRun(run) && typeof fn === "object" && Array.isArray(fn.blocks)) {
901
947
  const id = notes.length + 1;
902
948
  marks.set(run, id);
903
949
  notes.push({ id, footnote: fn });
@@ -938,9 +984,9 @@ function numberFootnotes(doc) {
938
984
  }
939
985
 
940
986
  // src/stretches.ts
941
- var isObject = (v) => !!v && typeof v === "object" && !Array.isArray(v);
987
+ var isObject2 = (v) => !!v && typeof v === "object" && !Array.isArray(v);
942
988
  function isPageObject(page) {
943
- return isObject(page) || Array.isArray(page) && page.length === 0;
989
+ return isObject2(page) || Array.isArray(page) && page.length === 0;
944
990
  }
945
991
  function mergePage(page, change) {
946
992
  const out = { ...page ?? {} };
@@ -948,7 +994,7 @@ function mergePage(page, change) {
948
994
  delete out.firstFooter;
949
995
  for (const [key, value] of Object.entries(change)) {
950
996
  if (value === void 0 || value === null || key === "background") continue;
951
- if (key === "margins" && isObject(value) && isObject(out.margins)) {
997
+ if (key === "margins" && isObject2(value) && isObject2(out.margins)) {
952
998
  const merged = { ...out.margins };
953
999
  for (const [side, v] of Object.entries(value)) {
954
1000
  if (v !== void 0 && v !== null) merged[side] = v;
@@ -970,8 +1016,8 @@ function docStretches(doc) {
970
1016
  const out = [make(null)];
971
1017
  (Array.isArray(doc?.blocks) ? doc.blocks : []).forEach((block, i) => {
972
1018
  const b = block;
973
- if (!isObject(b) || b.type !== "pageBreak" || !isPageObject(b.page)) return;
974
- page = mergePage(page, isObject(b.page) ? b.page : {});
1019
+ if (!isObject2(b) || b.type !== "pageBreak" || !isPageObject(b.page)) return;
1020
+ page = mergePage(page, isObject2(b.page) ? b.page : {});
975
1021
  out.push(make(i));
976
1022
  });
977
1023
  return out;
@@ -1021,17 +1067,17 @@ function packInput(stretches, measured) {
1021
1067
  // src/layout-notice.ts
1022
1068
  var LAYOUT_NOTICE = "Some page settings in this document aren't shown. It sets them somewhere they don't apply: on a page break directly, in a quote or a table cell, or under a sections key.";
1023
1069
  var NEAR_MISS_KEYS = ["size", "orientation", "margins", "header", "footer", "firstHeader", "firstFooter", "evenHeader", "evenFooter", "background", "border"];
1024
- var isObject2 = (v) => typeof v === "object" && v !== null;
1070
+ var isObject3 = (v) => typeof v === "object" && v !== null;
1025
1071
  function unshownLayout(doc) {
1026
1072
  const found = [];
1027
- if (!isObject2(doc)) return found;
1073
+ if (!isObject3(doc)) return found;
1028
1074
  if (doc.sections !== void 0) found.push("/sections");
1029
1075
  const stack = [{ blocks: doc.blocks, at: "/blocks" }];
1030
1076
  while (stack.length > 0) {
1031
1077
  const { blocks, at } = stack.pop();
1032
1078
  if (!Array.isArray(blocks)) continue;
1033
1079
  blocks.forEach((block, i) => {
1034
- if (!isObject2(block)) return;
1080
+ if (!isObject3(block)) return;
1035
1081
  const path = `${at}/${i}`;
1036
1082
  if (block.type === "pageBreak") {
1037
1083
  for (const key of NEAR_MISS_KEYS) {
@@ -1039,15 +1085,15 @@ function unshownLayout(doc) {
1039
1085
  }
1040
1086
  if (block.page !== void 0) {
1041
1087
  if (at !== "/blocks" || !isPageObject(block.page)) found.push(`${path}/page`);
1042
- else if (isObject2(block.page) && block.page.background !== void 0) found.push(`${path}/page/background`);
1088
+ else if (isObject3(block.page) && block.page.background !== void 0) found.push(`${path}/page/background`);
1043
1089
  }
1044
1090
  } else if (block.type === "quote") {
1045
1091
  stack.push({ blocks: block.blocks, at: `${path}/blocks` });
1046
1092
  } else if (block.type === "table" && Array.isArray(block.rows)) {
1047
1093
  block.rows.forEach((row, r) => {
1048
- if (!isObject2(row) || !Array.isArray(row.cells)) return;
1094
+ if (!isObject3(row) || !Array.isArray(row.cells)) return;
1049
1095
  row.cells.forEach((cell, c) => {
1050
- if (isObject2(cell)) stack.push({ blocks: cell.blocks, at: `${path}/rows/${r}/cells/${c}/blocks` });
1096
+ if (isObject3(cell)) stack.push({ blocks: cell.blocks, at: `${path}/rows/${r}/cells/${c}/blocks` });
1051
1097
  });
1052
1098
  });
1053
1099
  }
@@ -1575,6 +1621,7 @@ function DocViewer({
1575
1621
  const pageWpx = Math.max(...stretches.map((s) => s.geometry.width)) * PX_PER_PT;
1576
1622
  const scale = typeof fixedScale === "number" && fixedScale > 0 ? fixedScale : fit === "none" || !width ? 1 : Math.min(maxScale, width / pageWpx);
1577
1623
  const notShown = react.useMemo(() => unshownLayout(doc), [doc]);
1624
+ const revisions = react.useMemo(() => revisionPaths(doc), [doc]);
1578
1625
  const pageCount = layout?.pages.length ?? 0;
1579
1626
  react.useEffect(() => {
1580
1627
  if (layout && font !== "pending") {
@@ -1585,10 +1632,11 @@ function DocViewer({
1585
1632
  ...stretches.length > 1 ? { pageSizes: layout.pages.map((p) => ({ width: stretches[p.stretch ?? 0].geometry.width, height: stretches[p.stretch ?? 0].geometry.height })) } : {},
1586
1633
  scale,
1587
1634
  font,
1588
- ...notShown.length > 0 ? { notShown } : {}
1635
+ ...notShown.length > 0 ? { notShown } : {},
1636
+ ...revisions.length > 0 ? { revisions } : {}
1589
1637
  });
1590
1638
  }
1591
- }, [layout, geometry, stretches, scale, onLayout, font, notShown]);
1639
+ }, [layout, geometry, stretches, scale, onLayout, font, notShown, revisions]);
1592
1640
  const typography2 = typography(doc?.defaultFont, ctx.size);
1593
1641
  const ready = layout !== null && font !== "pending";
1594
1642
  return /* @__PURE__ */ jsxRuntime.jsxs(
@@ -1599,6 +1647,7 @@ function DocViewer({
1599
1647
  "data-lw-viewer": "",
1600
1648
  "data-lw-pages": ready && pageCount || void 0,
1601
1649
  "data-lw-font": ready ? font : void 0,
1650
+ "data-lw-tracked-changes": revisions.length > 0 ? "" : void 0,
1602
1651
  "aria-busy": ready ? void 0 : true,
1603
1652
  className,
1604
1653
  style: { position: "relative", ...style },
@@ -1606,6 +1655,7 @@ function DocViewer({
1606
1655
  injectStyles && /* @__PURE__ */ jsxRuntime.jsx("style", { href: "particle-academy-last-word-ui", precedence: "default", children: VIEWER_CSS }),
1607
1656
  injectStyles && FONT_CSS && /* @__PURE__ */ jsxRuntime.jsx("style", { href: "particle-academy-last-word-ui-fonts", precedence: "default", children: FONT_CSS }),
1608
1657
  notShown.length > 0 && /* @__PURE__ */ jsxRuntime.jsx("div", { "data-lw-layout-notice": "", style: { marginBottom: gap }, children: /* @__PURE__ */ jsxRuntime.jsx(reactFancy.Callout, { color: "amber", children: LAYOUT_NOTICE }) }),
1658
+ revisions.length > 0 && /* @__PURE__ */ jsxRuntime.jsx("div", { "data-lw-tracked-changes-notice": "", "data-lw-revisions": revisions.length, style: { marginBottom: gap }, children: /* @__PURE__ */ jsxRuntime.jsx(reactFancy.Callout, { color: "amber", children: TRACKED_CHANGES_NOTICE }) }),
1609
1659
  /* @__PURE__ */ jsxRuntime.jsx(
1610
1660
  "div",
1611
1661
  {
@@ -1831,6 +1881,7 @@ exports.PAGE_BAND_DISTANCE_DEFAULT = PAGE_BAND_DISTANCE_DEFAULT;
1831
1881
  exports.PAGE_MARGIN_DEFAULT = PAGE_MARGIN_DEFAULT;
1832
1882
  exports.PAGE_SIZES_PT = PAGE_SIZES_PT;
1833
1883
  exports.PX_PER_PT = PX_PER_PT;
1884
+ exports.TRACKED_CHANGES_NOTICE = TRACKED_CHANGES_NOTICE;
1834
1885
  exports.bandSlot = bandSlot;
1835
1886
  exports.blockStretches = blockStretches;
1836
1887
  exports.bodyBox = bodyBox;
@@ -1839,6 +1890,8 @@ exports.docFromReader = docFromReader;
1839
1890
  exports.docStretches = docStretches;
1840
1891
  exports.fontFaceCss = fontFaceCss;
1841
1892
  exports.formatDatePicture = formatDatePicture;
1893
+ exports.hasRevisions = hasRevisions;
1894
+ exports.isDeletedRun = isDeletedRun;
1842
1895
  exports.numberFootnotes = numberFootnotes;
1843
1896
  exports.packInput = packInput;
1844
1897
  exports.pageBand = pageBand;
@@ -1851,6 +1904,7 @@ exports.pageGeometry = pageGeometry;
1851
1904
  exports.pageMargins = pageMargins;
1852
1905
  exports.paginate = paginate;
1853
1906
  exports.resolveNow = resolveNow;
1907
+ exports.revisionPaths = revisionPaths;
1854
1908
  exports.substituteFields = substituteFields;
1855
1909
  exports.unshownLayout = unshownLayout;
1856
1910
  //# sourceMappingURL=index.cjs.map