cupertino-files / PagesDocument
Class: PagesDocument
Defined in: src/pages/document.ts:214
cupertino-files — read, inspect and edit Apple iWork documents (Pages, Numbers, Keynote) in pure TypeScript with zero runtime dependencies.
Layering (each importable on its own): primitives: snappy, protobuf wire (RawMessage), zip, varint, crc32 container: IWorkContainer (package layouts), IWA archives (IwaObject) graph: ObjectStore (components, IDs, references, save invariants) model: IWorkDocument + TextStorage/StylesheetModel/DrawableModel apps: PagesDocument, NumbersDocument, KeynoteDocument
Extends
Properties
container
readonlycontainer:IWorkContainer
Defined in: src/tsa/document.ts:125
Inherited from
format
readonlyformat:FormatInfo
Defined in: src/tsa/document.ts:127
Inherited from
store
readonlystore:ObjectStore
Defined in: src/tsa/document.ts:126
Inherited from
Accessors
app
Get Signature
get app():
IWorkApp
Defined in: src/tsa/document.ts:167
Returns
Inherited from
body
Get Signature
get body():
TextStorage
Defined in: src/pages/document.ts:290
The document body text storage. Throws for page-layout documents — check isPageLayout or use bodyOrUndefined when the document kind is unknown.
Returns
bodyOrUndefined
Get Signature
get bodyOrUndefined():
TextStorage|undefined
Defined in: src/pages/document.ts:279
The document body text storage, or undefined for page-layout documents (Pages' "Document Body" switch off) where text lives only in text boxes.
Returns
TextStorage | undefined
bodyText
Get Signature
get bodyText():
string
Defined in: src/pages/document.ts:313
Plain body text ("" for page-layout documents).
Returns
string
era
Get Signature
get era():
"iwork13"|"iwork16"|"iwork19"|"modern"|"current"|"future"
Defined in: src/tsa/document.ts:285
Format era this document was written by (see tsp/version.ts).
Returns
"iwork13" | "iwork16" | "iwork19" | "modern" | "current" | "future"
Inherited from
isPageLayout
Get Signature
get isPageLayout():
boolean
Defined in: src/pages/document.ts:305
True for page-layout documents: TP.SettingsArchive.body is false, or the document has no body storage at all. Word-processing documents (the default) have a body text flow; page-layout ones only have text boxes.
Returns
boolean
settings
Get Signature
get settings():
PagesSettings
Defined in: src/pages/document.ts:804
Document-wide settings (hyphenation, ligatures, footnote config …).
Returns
stylesheet
Get Signature
get stylesheet():
StylesheetModel
Defined in: src/pages/document.ts:387
The document stylesheet (named styles live here).
Returns
Methods
allLinks()
allLinks():
object[]
Defined in: src/pages/document.ts:722
Every hyperlink in the document, including those inside text boxes.
Returns
object[]
allText()
allText():
string
Defined in: src/tsa/document.ts:228
Concatenated plain text of all in-document storages (reading order approximation).
Returns
string
Inherited from
appendParagraph()
appendParagraph(
text,style?,list?):number
Defined in: src/pages/document.ts:354
Append a paragraph to the body. style may be a style name ("Heading 1") or a style object id. Returns the new paragraph index.
list names a list style ("Bullet", "Numbered") to make the paragraph a list item; without it the paragraph is not one, whatever the paragraph before it was.
Parameters
text
string
style?
string | bigint
list?
string | bigint
Returns
number
Agent Tool
append_paragraph
applyCharacterFormatting()
applyCharacterFormatting(
start,end,formatting):bigint
Defined in: src/pages/document.ts:374
Apply direct character formatting to a body range: creates an anonymous TSWP.CharacterStyleArchive (parented on the effective style at start) and spans it over [start, end). Returns the new style's id.
Parameters
start
number
end
number
formatting
Returns
bigint
Agent Tool
format_text
applyEdits()
applyEdits(
edits):void
Defined in: src/pages/document.ts:678
Apply several non-overlapping body edits from one snapshot — offsets for every edit refer to the text as it is now, in any order; an omitted replacement deletes the range. The safe way to make many changes gathered from one paragraphs()/find() pass.
Parameters
edits
readonly object[]
Returns
void
attachments()
attachments():
object[]
Defined in: src/pages/document.ts:739
Body inline attachments (page-number fields, images, footnote marks).
Returns
object[]
bookmarks()
bookmarks():
object[]
Defined in: src/pages/document.ts:744
Bookmarks (named destinations) declared in the body.
Returns
object[]
characterFormattingAt()
characterFormattingAt(
pos):CharacterFormatting
Defined in: src/pages/document.ts:712
Effective character formatting at a body position, inheritance folded in.
Parameters
pos
number
Returns
charts()
charts():
ChartModel[]
Defined in: src/tsa/document.ts:207
Every chart, with its plotted data (see ChartModel).
Returns
Inherited from
comments()
comments():
object[]
Defined in: src/pages/document.ts:768
Comments anchored anywhere in the document.
Returns
object[]
compact()
compact():
number
Defined in: src/tsa/document.ts:310
Drop archives nothing can reach, returning how many went.
What this collects today is very little, and that is worth knowing before reaching for it. Removing a sheet or a table unlinks it from the document tree, but the calc engine keeps its own references to every table it ever knew, so those archives stay genuinely reachable. The gap is in removal — unregistering a table's formula owners is calc-engine surgery this library does not do yet — not in the walk. What compaction does reclaim is objects created and then abandoned.
Roots are the package metadata, each component's first object, and every selection archive; see ObjectStore.prune for the scan and for why it errs towards keeping things. It is a no-op on every untouched document in the corpus, which is the property that matters: a collector that trims a file nobody edited is broken.
Returns
number
Inherited from
compatibility()
compatibility():
CompatibilityReport
Defined in: src/tsa/document.ts:266
What this library can and cannot do with THIS document: declared versions, the era they place it in, structural probes (unknown type IDs, cell-storage generation, patch archives, collaboration state) and any unsupported features. Loading never fails on version grounds — this is how a caller finds out what to expect.
Returns
Inherited from
compatibilitySummary()
compatibilitySummary():
string
Defined in: src/tsa/document.ts:280
One-line human summary of compatibility.
Returns
string
Inherited from
IWorkDocument.compatibilitySummary
createParagraphStyle()
createParagraphStyle(
options):bigint
Defined in: src/pages/document.ts:467
Create a paragraph style and list it in the app's style panel.
Confirmed in Pages. A style created here applies as asked and appears in the paragraph styles panel. Four requirements, found one failed round in the app at a time, each necessary and none sufficient:
- a
super.name; - a
super.identifierand a matchingidentifier_to_style_mapentry — of the 146 paragraph styles in the ladder's base, the 21 that are listed all carry both; - both property bags, the field set all 3130 paragraph styles in these fixtures share;
- an entry in
TSWP.ThemePresetsArchive.paragraph_style_presets(TP.ThemeArchive.super.110.7), which in every fixture holds exactly the names the app shows and whose length tracks what the user sees — twelve in a stock document, 35 and 61 in the two imported from Word.
The first three produce a style that renders correctly and whose name Pages prefills when adding a style by hand — and still does not list. unlistParagraphStyle was built as the control (removal proves which list the panel reads in a way addition cannot), and listedParagraphStyles reads the panel's own order back.
copyOf starts the new style's property bags as a full copy of an existing style's — the dense shape every listed corpus style has. Whether density is also required went unrecorded in the confirming report, so sparse styles list on faith; dense ones on evidence.
Parameters
options
basedOn?
string | bigint
character?
copyOf?
string | bigint
name
string
paragraph?
Returns
bigint
defineAsPlaceholder()
defineAsPlaceholder(
start,end):bigint
Defined in: src/pages/document.ts:707
Mark a body span as placeholder text, the way Format → Advanced → Define as Placeholder Text does. Returns the field's id.
Parameters
start
number
end
number
Returns
bigint
deleteRange()
deleteRange(
start,end):void
Defined in: src/pages/document.ts:341
Parameters
start
number
end
number
Returns
void
drawables()
drawables():
DrawableModel[]
Defined in: src/tsa/document.ts:192
Every object that carries drawable geometry (shapes, images, boxes).
Returns
Inherited from
fillPlaceholder()
fillPlaceholder(
index,text):TextRange
Defined in: src/pages/document.ts:692
Fill the body's index-th placeholder: real text in, placeholder marking off, styling kept — what typing into one does in Pages. Returns the filled span as a fluent range.
Parameters
index
number
text
string
Returns
find()
find(
pattern):TextRange[]
Defined in: src/pages/document.ts:663
Find body-text matches as fluent ranges.
Parameters
pattern
string | RegExp
Returns
floatingDrawablePages()
floatingDrawablePages():
number[]
Defined in: src/pages/document.ts:953
Page indexes that currently hold floating drawables.
Returns
number[]
floatingDrawables()
floatingDrawables(
pageIndex?,options?):DrawableContainer|undefined
Defined in: src/pages/document.ts:913
Floating drawables of one page, for adding, removing and reordering.
Pages groups floating objects per page, not per section or per document: TP.FloatingDrawablesArchive.page_groups holds one entry per page that has any, each with background, foreground and main lists. pageIndex selects the group; omit it for the first one the document has. Pages with no floating objects have no group, so a document can be missing the page you ask for even though the page exists — which is why create exists: without it there is no way to put the first drawable on a page, and "copy this onto page 3" is the ordinary case.
A created group carries exactly what Apple's do. Every page group in every fixture here holds two fields and no others — the page index and the drawable list — and libetonyek-pages5-extra-dir has three of them for pages 0, 1 and 2, in page order, which is what the insert below preserves.
Parameters
pageIndex?
number
options?
create?
boolean
Returns
DrawableContainer | undefined
footnotes()
footnotes():
object[]
Defined in: src/pages/document.ts:763
Footnotes/endnotes anchored in the body (edit via .storage).
Returns
object[]
images()
images():
ImageModel[]
Defined in: src/tsa/document.ts:212
Every image, with filter/mask access (see ImageModel).
Returns
Inherited from
insertInlineImage()
insertInlineImage(
pos,data,options):object
Defined in: src/pages/document.ts:975
Insert an image inline at a body-text position. Registers the bytes as a Data/ file (SHA-1 deduped), creates the TSD.ImageArchive + attachment objects, anchors them at a U+FFFC character, and sizes the image from its intrinsic dimensions (PNG/JPEG/GIF) scaled to fit maxWidth (default 400 pt) unless explicit width/height are given. App-confirmed: ladder rung P11 renders at the size asked.
The image rides the text: it sits in the text column and moves with the paragraph's indent, because the drawable carries the in-the-text-flow exterior_text_wrap. Pass wrap: "page" for the other behaviour, where the image is placed against the page margins and text flows around it — with an indented body that means the picture will not line up with the words above it.
Parameters
pos
number
data
Uint8Array
options
fileName
string
height?
number
maxWidth?
number
width?
number
wrap?
"text" | "page"
Returns
object
dataId
dataId:
bigint
imageId
imageId:
bigint
insertLink()
insertLink(
start,end,url,options?):bigint
Defined in: src/pages/document.ts:753
Make a body range a hyperlink.
Parameters
start
number
end
number
url
string
options?
characterStyle?
string | bigint | false
Returns
bigint
Agent Tool
insert_link
insertSectionBreak()
insertSectionBreak(
paragraphIndex,options?):PagesSection
Defined in: src/pages/document.ts:834
Start a new section at the given body paragraph. The new section clones the enclosing section's configuration and shares its page masters (headers/footers), with inherit_previous_header_footer set — matching Pages' "Create a new section" default. Returns the new section.
Parameters
paragraphIndex
number
options?
name?
string
pageNumberStart?
number
Returns
insertText()
insertText(
pos,text):void
Defined in: src/pages/document.ts:337
Parameters
pos
number
text
string
Returns
void
links()
links():
object[]
Defined in: src/pages/document.ts:717
Body hyperlinks ([] for page-layout documents).
Returns
object[]
listedParagraphStyles()
listedParagraphStyles():
StyleInfo[]
Defined in: src/pages/document.ts:487
The paragraph styles the app lists in its style panel, in panel order.
Distinct from paragraphStyles, which is every style the stylesheet chain holds — 146 of them in the ladder's base document against the twelve the panel shows. The rest are overrides and variations the app deliberately hides.
Returns
listStyles()
listStyles():
StyleInfo[]
Defined in: src/pages/document.ts:783
Named list styles available to this document.
Returns
object()
object(
id):IwaObject|undefined
Defined in: src/tsa/document.ts:235
Parameters
id
bigint
Returns
IwaObject | undefined
Inherited from
pageSetup()
pageSetup():
PageSetup
Defined in: src/pages/document.ts:613
Returns
paragraph()
paragraph(
index):ParagraphHandle
Defined in: src/pages/document.ts:668
Fluent handle for one body paragraph.
Parameters
index
number
Returns
paragraphs()
paragraphs():
ParagraphInfo&object[]
Defined in: src/pages/document.ts:318
Body paragraphs with resolved style names ([] for page-layout documents).
Returns
ParagraphInfo & object[]
paragraphStyles()
paragraphStyles():
StyleInfo[]
Defined in: src/pages/document.ts:395
Named paragraph styles available to this document.
Returns
paragraphStylesInUse()
paragraphStylesInUse():
object[]
Defined in: src/pages/document.ts:424
Which paragraph styles the body actually uses, most-used first — as against paragraphStyles, which is everything the template defines. A template usually defines styles its own sample content never demonstrates, and those are the ones whose look nobody has seen next to the rest.
Returns
object[]
placeholders()
placeholders():
object[]
Defined in: src/pages/document.ts:683
The body's placeholder-text spans ("tap or click to add …").
Returns
object[]
pruneRoots()
protectedpruneRoots():bigint[]
Defined in: src/tsa/document.ts:322
Objects that must survive compact.
The package metadata anchors the component and data tables, and each component's first object anchors that component — a component whose objects all vanished would still be listed in the metadata, which is a worse state than a few extra archives.
Returns
bigint[]
Inherited from
range()
range(
start,end):TextRange
Defined in: src/pages/document.ts:658
Fluent range over body text.
Parameters
start
number
end
number
Returns
replaceText()
replaceText(
find,replace):number
Defined in: src/pages/document.ts:333
Literal find/replace across the body, preserving the styling of the surrounding text. Returns how many occurrences changed.
Parameters
find
string
replace
string
Returns
number
Agent Tool
replace_text
save()
save():
Uint8Array
Defined in: src/tsa/document.ts:341
Returns
Uint8Array
Inherited from
sections()
sections():
PagesSection[]
Defined in: src/pages/document.ts:584
Sections of the document, from the body storage's section table. Every document has at least one.
Returns
setListStyle()
setListStyle(
paragraphIndex,style):void
Defined in: src/pages/document.ts:775
Apply a list style ("Bullet", "Numbered", "None", …) to a paragraph.
Parameters
paragraphIndex
number
style
string | bigint
Returns
void
setPageSetup()
setPageSetup(
update):void
Defined in: src/pages/document.ts:634
Update page geometry (points; 1 pt = 1/72 in). Only given fields change.
Parameters
update
Partial<PageSetup>
Returns
void
Agent Tool
set_page_setup
setParagraphStyle()
setParagraphStyle(
paragraphIndex,style):void
Defined in: src/pages/document.ts:363
Set a paragraph's style by name or id.
Parameters
paragraphIndex
number
style
string | bigint
Returns
void
smartFields()
smartFields():
object[]
Defined in: src/pages/document.ts:734
Body smart fields — page numbers, dates, merge fields, links, …
Returns
object[]
stats()
stats():
DocumentStats
Defined in: src/tsa/document.ts:243
Returns
Inherited from
stylesheets()
stylesheets():
StylesheetModel[]
Defined in: src/tsa/document.ts:183
All stylesheets (document + theme).
Returns
Inherited from
tables()
tables():
TableModel[]
Defined in: src/tsa/document.ts:223
Every table (see TableModel).
Lives on the base because tables are not a Numbers feature: Pages documents and Keynote slides embed the same TST archives, and the reading and writing code is identical for all three.
Returns
Inherited from
textBoxes()
textBoxes():
object[]
Defined in: src/pages/document.ts:812
Text boxes and shapes carrying text: drawable + its text storage.
Returns
object[]
textStorages()
textStorages(
kind?):TextStorage[]
Defined in: src/tsa/document.ts:172
Every text storage in the document (bodies, headers, cells, notes …).
Parameters
kind?
number
Returns
Inherited from
typeNameOf()
typeNameOf(
obj):string|undefined
Defined in: src/tsa/document.ts:239
Parameters
obj
Returns
string | undefined
Inherited from
unlistParagraphStyle()
unlistParagraphStyle(
id):boolean
Defined in: src/pages/document.ts:508
Take a paragraph style out of the panel list, leaving the style itself in place and still applied wherever it is used.
Returns whether it was listed. The inverse of what createParagraphStyle does, and the control for it: adding an entry and seeing nothing appear says only that the addition did not work, while removing an entry and seeing an entry vanish says the list is the thing the panel reads.
Parameters
id
bigint
Returns
boolean
blank()
staticblank():PagesDocument
Defined in: src/pages/document.ts:269
A new, empty Pages document — A4, vanilla styling, no template file needed.
The embedded donor is an Apple-written corpus fixture emptied by blankFrom and re-papered to A4 with byte-measured values, so every style and identity in the "new" document was authored by an Apple app. scripts/make-blanks.ts records its provenance.
Returns
PagesDocument
Agent Tool
create_document
blankFrom()
staticblankFrom(template):PagesDocument
Defined in: src/pages/document.ts:245
A new, empty document built from one you supply.
There is no from-nothing constructor, and there will not be one. A Pages document is dozens of interlinked archives — theme, stylesheet, section templates, master drawables — and inventing that graph would produce a file nothing offline could validate. Emptying a real one is safe: every identity, style and master stays exactly as an Apple app wrote it, and only the content goes.
The body text is cleared and the first paragraph's style is kept, so the result is a blank page in the template's design. Headers, footers and masters are left alone — they are the template.
Parameters
template
Uint8Array
Returns
PagesDocument
load()
staticload(bytes):PagesDocument
Defined in: src/pages/document.ts:222
Parameters
bytes
Uint8Array
Returns
PagesDocument
loadStore()
protectedstaticloadStore(bytes,app,extractors):object
Defined in: src/tsa/document.ts:152
Parameters
bytes
Uint8Array
app
extractors
ReadonlyMap<number, ReferenceExtractor>
Returns
object
container
container:
IWorkContainer
store
store:
ObjectStore
Inherited from
open()
staticopen(bytes):IWorkDocument
Defined in: src/tsa/document.ts:139
Load any modern iWork document, auto-detecting the app. Prefer the app subclasses' load when the type is known — they expose richer APIs.
Parameters
bytes
Uint8Array