The preview

The engine’s output is a display structure: a book’s worth of glyph positions, rules and image boxes. Turning that into pixels is a painter’s job, and the package ships one. It draws a page as SVG: the glyphs, one <text> element per run with an explicit x for every character, and an invisible layer over them, one <text> per line, for a reader to select and copy from.

Mounting

import { Preview } from 'fleuron';

const preview = await Preview.mount(document.querySelector('#book'));
await preview.setStyle(css);
await preview.setMarkdown(markdown);

preview.page = 12;
preview.zoom = 1.5;

Preview starts the worker, loads the module into it, keeps the session that makes a second render cheap, fetches the fonts the book was set in, and paints one page into the element it was given. The encoded buffer, the worker messages and the display structure are handled internally, and all three stay exported.

Images

Nothing in the package fetches a url. The host fetches the file and hands over the bytes, under the same string the manuscript wrote:

// This host reads them from a directory, another might read a
// database or an editor's unsaved buffer.
async function load(url) {
  const file = await fetch(`/manuscript/${url}`);
  return new Uint8Array(await file.arrayBuffer());
}

const preview = await Preview.mount(element, {
  images: { 'images/lilliput.jpg': await load('images/lilliput.jpg') },
});

// One that turns up after the book has already been set.
await preview.addImage('images/colophon.png', await load('images/colophon.png'));

The string the manuscript writes is the name the image is matched under, so the key has to be that string, and it does not have to be a real URL. Where the file was fetched from never reaches the engine, which is why the url appears twice above.

The module reads the header for the intrinsic size, which is how much room the image takes on the page, and decodes nothing. The preview keeps a blob: url over the same bytes and the painter draws from that, so the page on screen and the page in the PDF are one file.

An image the engine has never been handed is a warning and a gap where it would have gone. Pass asset instead of images to supply the urls directly, and the preview hands the display structure’s asset to it rather than resolving a blob of its own.

Faces from a stylesheet

A @font-face rule gives a face a family name, a weight and a style. The host fetches the font file and hands over the bytes under the string that url() holds, the same way as an image. The following example loads one width of Junicode as a family of its own:

const preview = await Preview.mount(element, {
  fonts: { 'Junicode-Cond.otf': await load('fonts/Junicode-Cond.otf') },
});

await preview.setStyle(`
  @font-face {
    font-family: "Junicode Cond";
    src: url("Junicode-Cond.otf");
    font-weight: 400;
    font-style: normal;
  }

  book { font-family: "Junicode Cond", serif; }
`);

The engine registers the face under the family, the weight and the style that the rule declares. The engine does not use the name in the file. A family whose files all give the same name can show each width as a separate family.

The file and the sheet can arrive in either order. addFont(bytes, url) hands over a file after the preview is mounted. A rule whose url has no bytes gives a warning, and the text uses the next family in its font-family list.

When a new sheet changes or removes a @font-face rule, the next render uses the faces that the new sheet declares. addFont(bytes) with no url registers a face under the family name in the file.

Manuscript, as markdown

---
title: The King of Elfland's Daughter
author: Lord Dunsay
year: 1924
---

![](images/lord.png)

## CHAPTER I

### _The Plan of the Parliament of Erl_

In their ruddy jackets of leather that reached to their knees the men of Erl appeared before their lord, the stately white-haired man in his long red room. He leaned in his carven chair and heard their spokesman.

And thus their spokesman said.

"For seven hundred years the chiefs of your race have ruled us well; and their deeds are remembered by the minor minstrels, living on yet in their little tinkling songs. And yet the generations stream away, and there is no new thing."

"What would you?" said the lord.

"We would be ruled by a magic lord," they said.

"So be it," said the lord. "It is five hundred years since my people have spoken thus in parliament, and it shall always be as your parliament saith. You have spoken. So be it."

And he raised his hand and blessed them and they went.

They went back to their ancient crafts, to the fitting of iron to the hooves of horses, to working upon leather, to tending flowers, to ministering to the rugged needs of Earth; they followed the ancient ways, and looked for a new thing. But the old lord sent a word to his eldest son, bidding him come before him.

And very soon the young man stood before him, in that same carven chair from which he had not moved, where light, growing late, from high windows, showed the aged eyes looking far into the future beyond that old lord's time. And seated there he gave his son his commandment.

"Go forth," he said, "before these days of mine are over, and therefore go in haste, and go from here eastwards and pass the fields we know, till you see the lands that clearly pertain to faery; and cross their boundary, which is made of twilight, and come to that palace that is only told of in song."

"It is far from here," said the young man Alveric.

"Yes," answered he, "it is far."

"And further still," the young man said, "to return. For distances in those fields are not as here."

"Even so," said his father.

"What do you bid me do," said the son, "when I come to that palace?"

And his father said: "To wed the King of Elfland's daughter."

The young man thought of her beauty and crown of ice, and the sweetness that fabulous runes had told was hers. Songs were sung of her on wild hills where tiny strawberries grew, at dusk and by early starlight, and if one sought the singer no man was there. Sometimes only her name was sung softly over and over. Her name was Lirazel.

She was a princess of the magic line. The gods had sent their shadows to her christening, and the fairies too would have gone, but that they were frightened to see on their dewy fields the long dark moving shadows of the gods, so they stayed hidden in crowds of pale pink anemones, and thence blessed Lirazel.

"My people demand a magic lord to rule over them. They have chosen foolishly," the old lord said, "and only the Dark Ones that show not their faces know all that this will bring: but we, who see not, follow the ancient custom and do what our people in their parliament say. It may be some spirit of wisdom they have not known may save them even yet. Go then with your face turned towards that light that beats from fairyland, and that faintly illumines the dusk between sunset and early stars, and this shall guide you till you come to the frontier and have passed the fields we know."

Then he unbuckled a strap and a girdle of leather and gave his huge sword to his son, saying: "This that has brought our family down the ages unto this day shall surely guard you always upon your journey, even though you fare beyond the fields we know."

And the young man took it though he knew that no such sword could avail him.

Near the Castle of Erl there lived a lonely witch, on high land near the thunder, which used to roll in Summer along the hills. There she dwelt by herself in a narrow cottage of thatch and roamed the high fields alone to gather the thunderbolts. Of these thunderbolts, that had no earthly forging, were made, with suitable runes, such weapons as had to parry unearthly dangers.

And alone would roam this witch at certain tides of Spring, taking the form of a young girl in her beauty, singing among tall flowers in gardens of Erl. She would go at the hour when hawk-moths first pass from bell to bell. And of those few that had seen her was this son of the Lord of Erl. And though it was calamity to love her, though it rapt men's thoughts away from all things true, yet the beauty of the form that was not hers had lured him to gaze at her with deep young eyes, till—whether flattery or pity moved her, who knows that is mortal?—she spared him whom her arts might well have destroyed and, changing instantly in that garden there, showed him the rightful form of a deadly witch. And even then his eyes did not at once forsake her, and in the moments that his glance still lingered upon that withered shape that haunted the hollyhocks he had her gratitude that may not be bought, nor won by any charms that Christians know. And she had beckoned to him and he had followed, and learned from her on her thunder-haunted hill that on the day of need a sword might be made of metals not sprung from Earth, with runes along it that would waft away, certainly any thrust of earthly sword, and except for three master-runes could thwart the weapons of Elfland.

As he took his father's sword the young man thought of the witch.

It was scarcely dark in the valley when he left the Castle of Erl, and went so swiftly up the witch's hill that a dim light lingered yet on its highest heaths when he came near the cottage of the one that he sought, and found her burning bones at a fire in the open. To her he said that the day of his need was come. And she bade him gather thunderbolts in her garden, in the soft earth under her cabbages.

And there with eyes that saw every minute more dimly, and fingers that grew accustomed to the thunderbolts' curious surfaces, he found before darkness came down on him seventeen: and these he heaped into a silken kerchief and carried back to the witch.

On the grass beside her he laid those strangers to Earth. From wonderful spaces they came to her magical garden, shaken by thunder from paths that we cannot tread; and though not in themselves containing magic were well adapted to carry what magic her runes could give. She laid the thigh-bone of a materialist down, and turned to those stormy wanderers. She arranged them in one straight row by the side of her fire. And over them then she toppled the burning logs and the embers, prodding them down with the ebon stick that is the sceptre of witches, until she had deeply covered those seventeen cousins of Earth that had visited us from their etherial home. She stepped back then from her fire and stretched out her hands, and suddenly blasted it with a frightful rune. The flames leaped up in amazement. And what had been but a lonely fire in the night, with no more mystery than pertains to all such fires, flared suddenly into a thing that wanderers feared.

As the green flames, stung by her runes, leaped up, and the heat of the fire grew intenser, she stepped backwards further and further, and merely uttered her runes a little louder the further she got from the fire. She bade Alveric pile on logs, dark logs of oak that lay there cumbering the heath; and at once, as he dropped them on, the heat licked them up; and the witch went on pronouncing her louder runes, and the flames danced wild and green; and down in the embers the seventeen, whose paths had once crossed Earth's when they wandered free, knew heat again as great as they had known, even on that desperate ride that had brought them here. And when Alveric could no longer come near the fire, and the witch was some yards from it shouting her runes, the magical flames burned all the ashes away and that portent that flared on the hill as suddenly ceased, leaving only a circle that sullenly glowed on the ground, like the evil pool that glares where thermite has burst. And flat in the glow, all liquid still, lay the sword.

The witch approached it and pared its edges with a sword that she drew from her thigh. Then she sat down beside it on the earth and sang to it while it cooled. Not like the runes that enraged the flames was the song she sang to the sword: she whose curses had blasted the fire till it shrivelled big logs of oak crooned now a melody like a wind in summer blowing from wild wood gardens that no man tended, down valleys loved once by children, now lost to them but for dreams, a song of such memories as lurk and hide along the edges of oblivion, now flashing from beautiful years of glimpse of some golden moment, now passing swiftly out of remembrance again, to go back to the shades of oblivion, and leaving on the mind those faintest traces of little shining feet which when dimly perceived by us are called regrets. She sang of old Summer noons in the time of harebells: she sang on that high dark heath a song that seemed so full of mornings and evenings preserved with all their dews by her magical craft from days that had else been lost, that Alveric wondered of each small wandering wing, that her fire had lured from the dusk, if this were the ghost of some day lost to man, called up by the force of her song from times that were fairer. And all the while the unearthly metal grew harder. The white liquid stiffened and turned red. The glow of the red dwindled. And as it cooled it narrowed: little particles came together, little crevices closed: and as they closed they seized the air about them, and with the air they caught the witch's rune, and gripped it and held it forever. And so it was it became a magical sword. And little magic there is in English woods, from the time of anemones to the falling of leaves, that was not in the sword. And little magic there is in southern downs, that only sheep roam over and quiet shepherds, that the sword had not too. And there was scent of thyme in it and sight of lilac, and the chorus of birds that sings before dawn in April, and the deep proud splendour of rhododendrons, and the litheness and laughter of streams, and miles and miles of may. And by the time the sword was black it was all enchanted with magic.

Nobody can tell you about that sword all that there is to be told of it; for those that know of those paths of Space on which its metals once floated, till Earth caught them one by one as she sailed past on her orbit, have little time to waste on such things as magic, and so cannot tell you how the sword was made, and those who know whence poetry is, and the need that man has for song, or know any one of the fifty branches of magic, have little time to waste on such things as science, and so cannot tell you whence its ingredients came. Enough that it was once beyond our Earth and was now here amongst our mundane stones; that it was once but as those stones, and now had something in it such as soft music has; let those that can define it.

And now the witch drew the black blade forth by the hilt, which was thick and on one side rounded, for she had cut a small groove in the soil below the hilt for this purpose, and began to sharpen both sides of the sword by rubbing them with a curious greenish stone, still singing over the sword an eerie song.

Alveric watched her in silence, wondering, not counting time; it may have been for moments, it may have been while the stars went far on their courses. Suddenly she was finished. She stood up with the sword lying on both her hands. She stretched it out curtly to Alveric; he took it, she turned away; and there was a look in her eyes as though she would have kept that sword, or kept Alveric. He turned to pour out his thanks, but she was gone.

He rapped on the door of the dark house; he called "Witch, Witch" along the lonely heath, till children heard on far farms and were terrified. Then he turned home, and that was best for him.

A mounted Preview: setStyle and edit on one side, the page it painted on the other.

Everything in the first table changes an input and repaints. Everything in the second only reads or moves what is already there.


`setMarkdown(text, name?)`	one markdown source as the whole book
`setBook(sources)`	several sources, in reading order
`edit(name, text)`	one source replaced, the rest of the book left standing
`remove(name)`	one source dropped
`setAttributes(name, { classes, id })`	the classes and id of one source’s sections
`setMetadata({ title, author, extra })`	what names the book
`setStyle(css)`	the author’s styling: one string, or named sheets in cascade order
`addFont(bytes, url?)`	a font file, under the `@font-face` url that names it, or under the family name in the file when there is no url
`addImage(url, bytes)`	one image, by the url the manuscript names it by
`render(ops?)`	lay out again, or apply anything the methods above do not reach


`pages`	how many pages the book laid out to
`page`	the page on screen, counting from 1; assigning to it turns the page
`next()`, `previous()`	the same, one page at a time
`zoom`	points to CSS pixels
`warnings`	what the run warned about
`onLink`	the function that a click on a link calls, and assigning to it replaces the function
`follow(link)`	follows a link the same way a click does
`svg(page?)`	the markup for a fetched page, painted but not mounted; empty for one that is not
`exportPdf()`	the same run as PDF bytes
`exportEpub()`	the book as a reflowable EPUB, with its warnings
`exportEpubFiles()`	the same EPUB as its files, not zipped, with the spine
`destroy()`	closes the worker and empties the element

Set the dialect and the section-splitting level when the preview is mounted, not after. Changing either means reading every source again, and the preview keeps no copy of them.

A book of several files

setBook takes the sources in reading order:

await preview.setBook([
  { name: 'ch01.md', text: one },
  { name: 'ch02.md', text: two },
]);

After that, edit(name, text) is the keystroke path: it reads that one file again and every other file keeps the lines it already has. A name the book has not seen is appended, so edit is also how a file arrives mid-session. remove(name) is how one leaves.

A sheet reaches the sections of a source by the classes and the id that the host gives the source. The names stay with the source through an edit and a reorder. A rule for section.chapter matches the same chapters after the author moves one. The text does not change, so no byte offset of a node moves. The following example names the front matter and the first chapter, and then changes the classes of the chapter:

await preview.setBook([
  { name: 'preface.md', text: preface, attributes: { classes: ['front'] } },
  { name: 'ch01.md', text: one, attributes: { classes: ['chapter'], id: 'chapter-one' } },
]);
await preview.setAttributes('ch01.md', { classes: ['chapter', 'opening'] });

setAttributes(name, {}) takes the names away.

A book of one file takes its title and author from that file’s frontmatter. A book of several has no frontmatter of its own, so it is left unnamed until setMetadata names it:

await preview.setMetadata({
  title: "Gulliver's Travels",
  author: 'Jonathan Swift',
  extra: { language: 'en' },
});

Naming a book costs no layout: the pages already on screen are the pages the export writes under the new name. extra.language is the one field a stage below the PDF writer reads, and a book that changes it is hyphenated again.

When it renders

Every method that changes an input renders. There is no timer.

The worker lets everything the host has already posted arrive before it renders anything, so a burst of edits fired without awaiting them collapses into one render. Every edit is still applied, in order, and the render that survives is the same as if nobody had typed. The ones it overtook resolve to nothing rather than painting a stale page.

Nothing is interrupted to make that happen. A render occupies the worker from start to finish, so the collapsing happens in the gap before one begins. A render already running finishes, its output is dropped as stale, and the next one runs. A superseded render is one that never started, not one abandoned half-way, which is what keeps the session’s caches sound.

The effect is a debounce whose delay is the last render’s duration: a long book waits behind its own slow render, and a short one repaints at once. A host that wants a fixed delay puts it in front of these calls.

Turning pages

Preview fetches one page at a time, not the whole book: the page on screen and the one either side of it. Assigning to page inside that reach paints at once, from what is already fetched. A page further off asks the worker and paints once the reply lands, the frame staying as it was until then. pages reports how many pages the book has regardless of how much of it has crossed.

An edit drops whatever pages were fetched, since the book they came from no longer stands, and fetches the page on screen fresh against the book the edit produced.

onRender is called after every render that reaches the screen, with the reply behind the page on screen: output.pages has that page alone, output.bookPages is the book’s own length, and output.fonts, output.assets and output.warnings are the whole run’s.

const preview = await Preview.mount(element, {
  onRender: (output) => console.log(`page ${output.first + 1} of ${output.bookPages}`),
});

In React

fleuron-react is the same thing as a component:

import { Preview } from 'fleuron-react';

<Preview markdown={markdown} css={css} page={page} zoom={1.5} />;

The manuscript and the stylesheet are props, so an edit is a re-render and the engine is handed the one input that changed. onLink is a prop, and a new function on a re-render replaces the old one. images is a prop too, so one that arrives after the book does still reaches the page. fonts is a prop in the same way, keyed by the @font-face url. onMount hands back the underlying preview, for the page count and the PDF export.

React is not a dependency of fleuron. The wrapper contains no engine logic, so a host that does not use React downloads none of it, and deleting the wrapper leaves a preview a plain page can still mount.

Painting a page yourself

Call the painter directly for the pages without the mounting, when drawing to a canvas, running a scroll container of your own, or rendering where there is no DOM:

import { decodeDisplayList, paintPage } from 'fleuron';

const output = decodeDisplayList(bytes);
element.innerHTML = paintPage(output.pages[0], { fonts: output.fonts, zoom: 2 });

paintPage returns the markup of one <svg> element. Its viewBox is the page size in points with the origin at the top left, which is the display structure’s own coordinate system, so nothing is rescaled on the way out.

The second argument is all optional:

option	default
`fonts`	none	The font table, `output.fonts`. Leave it out and the painter cannot name the faces, so every run falls back to a generic serif.
`zoom`	`1`	Points to CSS pixels. This sets the `width` and `height` on the `<svg>` element and nothing else: the coordinates inside it do not move, so the page scales without re-laying out.
`paper`	`'#ffffff'`	The fill of a rectangle painted behind the page. `null` paints none, leaving the page transparent.
`ink`	`'#000000'`	The fill for a run or a rule the sheet left black. A colored run takes its own color instead. `ink` reaches the preview only: the export prints black wherever the sheet named no color.
`assets`	none	The asset table, `output.assets`. Leave it out and the painter has no url to resolve, so every image is drawn as an empty box.
`asset`	none	`(asset, index) => url`, for images.
`links`	`true`	Whether each line of each link gets a transparent mark. `false` leaves the marks out, for a host that marks links itself. See links without the preview.

Layout never decodes an image. It probes the header for the intrinsic size, reserves a box of the right shape, and records an index into output.assets. asset turns that entry back into something a browser can load: any URL an <img> would take, including a blob: or data: one, or null when there is nothing to supply. On null the painter outlines the box the image would have filled, so the space it takes is still visible.

Why the preview matches the export

A browser handed a string and a font does its own typesetting: it chooses glyphs, applies kerning and ligatures, and works out where each one goes. fleuron has already done that work, and if the browser did it again the two answers would differ a little over a different shaper version, a rounded advance or a substituted font.

So the painter leaves the browser nothing to work out. Each <text> sets an x for every one of its characters, taken from the glyph the engine placed there, and the run’s axes and OpenType features are pinned so the browser reaches the glyphs the engine measured rather than the ones the characters spell.

Where text-transform or small capitals changed the characters, the run has both. The painter draws what was shaped; beside it is what the author wrote, which is what selection and copy and paste return.

The PDF writer reads the same display structure, so the two painters draw the same numbers, glyph for glyph.

Selection and copy

A drag over the page selects text from an invisible layer over the glyphs. The layer has one <text> for each line rather than for each run. Nothing that the painter draws under it takes pointer events. A drag that starts between two lines or beside a line starts at the nearest line.

The highlight on a selected line is one band from the first selected character to the last. The band is as tall as the glyphs of the largest run on the line.

Copy answers from that layer’s own selection rather than the browser’s default serialization across it: a selection spanning several lines joins them in reading order, with nothing duplicated or dropped.

A selection stays within one page: there is no boundary between two of them to drag across.

Links

A click on a link follows it. A link to a place in the book turns the preview to the page of that place. A link to a url opens the url in a new window.

onLink lets the host decide what a click does. The preview calls it with the link and the click event, before it follows the link. If onLink returns false, the preview does not turn the page. If the host gives an onLink, the preview opens no url, and the host decides what to do with the url.

The following example opens a url in a browser tab that the host controls, and turns the page for a link in the book:

const preview = await Preview.mount(element, {
  onLink: (link) => {
    if (link.to.kind === 'uri') {
      openTab(link.to.url);
    }
  },
});

The following example shows the target of a link in an editor and keeps the page on screen:

preview.onLink = (link) => {
  if (link.to.kind === 'place') {
    editor.reveal(link.to.node);
    return false;
  }
};

A click at the end of a drag selects text and follows no link. A click whose default the host already prevented follows no link either. follow(link) follows a link the same way a click does.

Links without the preview

Each page has links. A link has areas, one box for each line of the link on the page, in points. It also has to, which is one of these:

{ kind: 'place', node, place }
{ kind: 'uri', url }

node is the element that the link names, and place is its box on the page where it starts. place.page is the index of that page in the book, counting from 0. It is the first of the range that fetches the page. So a host that holds only some pages can follow a link to any page. The display structure describes the boxes.

paintPage puts a transparent <rect> over each box, above the selection layer. Its data-link is the index of the link in page.links. The rectangle takes no pointer events and is not an <a>. A drag still selects the text under it, and a click does only what the host decides.

linkAt(page, x, y) gives the link at a point in page points, or null. It reads the boxes and not the DOM, so the order of the layers in the SVG does not change the answer. The following example follows a click on a page that the host drew, to a page that the host did not fetch yet:

import { linkAt, paintPage } from 'fleuron';

frame.innerHTML = paintPage(page, { fonts: output.fonts });
const svg = frame.querySelector('svg');

svg.addEventListener('click', async (event) => {
  const box = svg.getBoundingClientRect();
  const x = ((event.clientX - box.left) * page.width) / box.width;
  const y = ((event.clientY - box.top) * page.height) / box.height;
  const link = linkAt(page, x, y);
  if (link?.to.kind === 'place') {
    event.preventDefault();
    const reply = await client.preview([], { first: link.to.place.page, count: 1 });
    if (reply !== null) {
      frame.innerHTML = paintPage(reply.pages[0], { fonts: reply.fonts });
    }
  }
});

Fonts

A page is usually set in several faces at once: body text, an italic aside, a bold heading. Each text run in the display structure names a fontId, and output.fonts is the table those ids index. The painter draws every run in the file registered under that run’s id.

Those files have to reach the browser as FontFaces. The host already has the bytes for a face it registered. The face built into the engine has no URL to fetch it from, so the module hands it back:

import { faceFamily } from 'fleuron';

const bytes = await client.fontBytes(fontId);
document.fonts.add(new FontFace(faceFamily(fontId), bytes.buffer));

faceFamily(fontId) is the family name paintPage will ask for, exported so both ends agree on it. Preview does all of this itself, for every face a run actually used.

One file can answer for several faces. The bundled EB Garamond is a variable font whose Regular, Medium, Bold and the rest are one file read at different points on a wght axis, and each of those is its own fontId. The font table records the point and the painter writes it out as font-variation-settings. A painter that ignored it would draw every weight at the file’s default.

A face that never arrives does not blank the run. The painter’s font-family list ends in serif, so the text appears in whatever font the reader has.

That fallback is also a setting. Preview.mount(element, { faces: 'host' }) registers nothing and leaves the painter’s list to resolve against whatever the document already has, under the family the display structure names. Use it when the host already serves the same file, or a subset of it with the same metrics: the glyphs land on the x the display structure gave them either way, and parsing a book face twice is main-thread work. The default is 'module', which is the only way to be certain the page on screen is set in the face the export will use.

The harness

examples/preview/ is a page that opens the fixture book, pages through it, and puts the browser’s own PDF viewer beside the preview, showing the same page of the same run.

node examples/preview/serve.mjs

It is written the way a consumer writes one, naming no buffer, no worker and no display structure.