@heroiclands/package-build 23.13.0 → 24.0.0

package/types/engine/site-preview.d.mts

@@ -1,14 +1,24 @@
 /**
- * Render one complete buffer with no configuration, index, filesystem or database.
+ * Render one complete buffer.
+ *
+ * Without `index` the buffer is rendered with no configuration, content index,
+ * filesystem or database: wikilinks, spans and expressions show as highlighted
+ * authored source. With `index` the buffer is expanded as the website expands
+ * a page and rendered as every target renders it, so links, embeds, marked
+ * text, icons and figure numbers read as they will on the page; only what a
+ * buffer cannot answer, such as a query, stays highlighted source.
+ *
  * @param {string} text - Markdown, optionally beginning with YAML frontmatter.
- * @param {{dark?: boolean, infobox?: boolean, file?: string, currentDate?: string}} [options] - Explicit palette, profile visibility, diagnostic filename and neutral current date (default "720.1").
+ * @param {{dark?: boolean, infobox?: boolean, file?: string, currentDate?: string,
+ *   index?: import("./preview-index.mjs").PreviewIndex}} [options] - Explicit palette, profile visibility, diagnostic filename, neutral current date (default "720.1") and the content index, from {@link module:engine/preview-index.previewIndex}.
  * @returns {{ok: boolean, html: string, frontmatter: object, findings: object[]}} HTML and metadata with locally calculable ages; unavailable ages remain absent or null.
  */
-export function renderPreview(text: string, { dark, infobox, file, currentDate }?: {
+export function renderPreview(text: string, { dark, infobox, file, currentDate, index }?: {
     dark?: boolean;
     infobox?: boolean;
     file?: string;
     currentDate?: string;
+    index?: import("./preview-index.mjs").PreviewIndex;
 }): {
     ok: boolean;
     html: string;
@@ -23,19 +33,5 @@ export function renderPreview(text: string, { dark, infobox, file, currentDate }
 export function readPreviewCurrentDate(root: string): Promise<string>;
 /** Both explicit palettes, scoped to the preview container. */
 export function previewStyles(): string;
-/** Explicit dependency policy: a new registered helper requires a preview decision. */
-export const PREVIEW_HELPERS: Readonly<{
-    eq: "local";
-    gt: "local";
-    gte: "local";
-    lt: "local";
-    lte: "local";
-    not: "local";
-    and: "local";
-    or: "local";
-    words: "local";
-    digits: "local";
-    sql: "dependent";
-    dateformat: "dependent";
-    ref: "reference";
-}>;
+export { PREVIEW_HELPERS };
+import { PREVIEW_HELPERS } from "./preview-source.mjs";

package/types/engine/site-render.d.mts

@@ -0,0 +1,171 @@
+/**
+ * Pages in the order a reader walks them: by `weight`, lightest first and an
+ * unweighted page last; then newest first by `date`; then by title; then by
+ * address. A page's own `weight` and `date` are read before its `params`'.
+ *
+ * @template {{title?: string, url: string, date?: unknown, weight?: number, params?: object}} T
+ * @param {readonly T[]} pages - The pages.
+ * @returns {T[]} A sorted copy.
+ */
+export function siteOrder<T extends {
+    title?: string;
+    url: string;
+    date?: unknown;
+    weight?: number;
+    params?: object;
+}>(pages: readonly T[]): T[];
+/**
+ * Every page of a site: the pages it is given, with their siblings, and the
+ * listings derived from them.
+ *
+ * @param {object} site - The site, as {@link writeSite} takes it.
+ * @param {readonly object[]} pages - The home page, the regular pages and any
+ *   authored section pages.
+ * @returns {object[]} Every page, home first, then the regular pages, the
+ *   sections, and the tag pages.
+ */
+export function siteTree(site: object, pages: readonly object[]): object[];
+/**
+ * Write the files the layouts link: the theme's own, and the code stylesheet.
+ *
+ * @param {string} out - The directory the site is written to.
+ * @param {string} [staticDir] - The theme's own files.
+ * @returns {string[]} The files the theme generates, each written. The theme's
+ *   own files are copied as a tree and not listed.
+ */
+export function writeThemeFiles(out: string, staticDir?: string): string[];
+/**
+ * Draw a site and write it.
+ *
+ * @param {object} options - The inputs.
+ * @param {object} options.site - The site, as
+ *   {@link module:engine/site-theme.createSiteTheme} takes it, with `tagPages`,
+ *   `feed` and `sitemaps` as the module description sets out. `pages` and
+ *   `pageExists` are filled in here.
+ * @param {readonly object[]} options.pages - The home page, the regular pages
+ *   and any authored section pages, each as a layout is given it.
+ * @param {string} options.out - The directory written to. Emptied first.
+ * @param {(finding: import("./site-theme.mjs").Finding) => void} [options.report] -
+ *   Receives each finding the layouts make.
+ * @param {string} [options.staticDir] - The theme's own files, copied first.
+ * @param {ReadonlySet<string>} [options.only] - The addresses of the pages to
+ *   draw again into a site already written. Nothing else is touched.
+ * @returns {{files: string[], pages: string[], findings: object[]}} Every file
+ *   written, the address of every page, and the layouts' findings.
+ * @throws {Error} When a page's address is outside the site, or a site served
+ *   under a path asks for a sitemap index.
+ */
+export function writeSite({ site, pages, out, report, staticDir, only }: {
+    site: object;
+    pages: readonly object[];
+    out: string;
+    report?: ((finding: import("./site-theme.mjs").Finding) => void) | undefined;
+    staticDir?: string | undefined;
+    only?: ReadonlySet<string> | undefined;
+}): {
+    files: string[];
+    pages: string[];
+    findings: object[];
+};
+/**
+ * A package's pages, from its site build.
+ *
+ * Each body is rendered by the `web` renderer from the markdown the build
+ * expanded, and each page carries what it tells the search; see
+ * {@link module:engine/site-search}. The site carries what the configuration
+ * asks for: `site.tags` as `tagPages`, `site.feed` as the feed's section, each
+ * package of `site.sitemaps` as its sitemap's address on the site's origin,
+ * and each of `site.mergeIndexes` as the path of its search bundle.
+ *
+ * @param {object} options - The inputs.
+ * @param {object} options.config - The resolved configuration.
+ * @param {object} options.built - What `buildSite` returned with `write: false`.
+ * @param {{baseURL: string, title: string, params: object}} options.settings -
+ *   From {@link module:engine/site-config.siteSettings}.
+ * @param {readonly {name: string, url: string, children?: object[]}[]} [options.navigation] -
+ *   The menu.
+ * @param {number} [options.year] - The year the footer states.
+ * @returns {{site: object, pages: object[], pageOf: (entry: object) => object}}
+ *   What {@link writeSite} is given, and how one note the build rendered again
+ *   becomes its page.
+ */
+export function packageSite({ config, built, settings, navigation, year }: {
+    config: object;
+    built: object;
+    settings: {
+        baseURL: string;
+        title: string;
+        params: object;
+    };
+    navigation?: readonly {
+        name: string;
+        url: string;
+        children?: object[];
+    }[] | undefined;
+    year?: number | undefined;
+}): {
+    site: object;
+    pages: object[];
+    pageOf: (entry: object) => object;
+};
+/**
+ * The directory a package's site is written to: its base path under the
+ * deployed root, so a site served at `/` is written at the root itself.
+ *
+ * @param {object} config - The resolved configuration.
+ * @param {string} root - The deployed root.
+ * @returns {string} The directory.
+ */
+export function siteDirectory(config: object, root: string): string;
+/**
+ * Copy the script fonts the site's pages set their marked text in.
+ *
+ * @param {object} config - The resolved configuration.
+ * @param {string} out - The directory the site is written to.
+ * @returns {{findings: object[], count: number, dest?: string}} What checking
+ *   the installed fonts found, and how many files were copied where. Nothing is
+ *   copied when there is a finding, or when the package sets no script.
+ */
+export function deliverSiteFonts(config: object, out: string): {
+    findings: object[];
+    count: number;
+    dest?: string;
+};
+/**
+ * Build a package's site from its content tree and write it.
+ *
+ * The site's address, title and menu are read before the tree is, so a site
+ * that cannot be described fails before anything is built. A gate that fires
+ * stops the build before anything is written; a note in error is written as
+ * its page shows it, with the finding in what is returned, which
+ * `siteBuildFailed` reads.
+ *
+ * @param {object} options - The inputs.
+ * @param {object} options.config - The resolved configuration.
+ * @param {string} options.out - The directory the site is written to, which
+ *   is the package's own directory under the deployed root.
+ * @param {number} [options.year] - The year the footer states.
+ * @returns {Promise<{built: object, written: object|null, fonts: object|null,
+ *   site?: object, pages?: object[], pageOf?: (entry: object) => object}>}
+ *   What the build found, and, when it found nothing that stops it, what was
+ *   written, the pages it was written from and how a note rendered again
+ *   becomes its page. `written` is `null` when a gate fired.
+ * @throws {Error} When the site's settings or its cached menu cannot be read.
+ */
+export function buildPackageSite({ config, out, year }: {
+    config: object;
+    out: string;
+    year?: number | undefined;
+}): Promise<{
+    built: object;
+    written: object | null;
+    fonts: object | null;
+    site?: object;
+    pages?: object[];
+    pageOf?: (entry: object) => object;
+}>;
+/**
+ * The files the layouts link that the theme ships as they are: the site and
+ * icon stylesheets, the spoiler script, the icon font and the theme's images.
+ */
+export const SITE_STATIC_DIR: string;

package/types/engine/site-root.d.mts

@@ -27,12 +27,16 @@ export function noindexHeaders(): string[];
  * that names their version, so a year's lifetime never serves a stale file.
  *
  * @param {object} [options] - Options.
- * @param {string} [options.pkg] - The content package, which is the prefix.
+ * @param {string} [options.pkg] - The content package, whose site is served at
+ *   `/<pkg>/` unless `base` says otherwise.
+ * @param {string} [options.base] - The path the site is served at, beginning
+ *   and ending with `/`.
  * @param {boolean} [options.fonts] - Whether the site carries the fonts.
  * @returns {string} The file's contents.
  */
-export function headers({ pkg, fonts }?: {
+export function headers({ pkg, base, fonts }?: {
     pkg?: string | undefined;
+    base?: string | undefined;
     fonts?: boolean | undefined;
 }): string;
 export function indexSite(where: {
@@ -59,7 +63,10 @@ export function indexSite(where: {
  *
  * @param {object} options - Options.
  * @param {string} options.pkg - The content package name, which is also the
- *   directory Hugo rendered into.
+ *   directory the site is rendered into unless `base` says otherwise.
+ * @param {string} [options.base] - The path the site is served at, beginning
+ *   and ending with `/`; the site is rendered into that path under `out`, so
+ *   a site served at `/` is rendered at `out` itself.
  * @param {string} options.out - The directory that is deployed.
  * @param {boolean} [options.search] - Whether to build the search index;
  *   `site.search` in the configuration. Default `true`.
@@ -73,8 +80,9 @@ export function indexSite(where: {
  *   under the prefix; or, located at the rendered site, when the indexer
  *   fails.
  */
-export function writeSiteRoot({ pkg, out, search, indexer }: {
+export function writeSiteRoot({ pkg, base, out, search, indexer }: {
     pkg: string;
+    base?: string | undefined;
     out: string;
     search?: boolean | undefined;
     indexer?: SiteIndexer | undefined;

package/types/engine/site-search.d.mts

@@ -0,0 +1,54 @@
+/**
+ * The continents and regions every place lies in.
+ *
+ * @param {Map<string, {shortcode: string, name: string, subType?: string, parents: string[]}>} places -
+ *   Every place, by shortcode, as {@link module:engine/map-places.mapWorld} reads them.
+ * @returns {(shortcodes: Iterable<string>) => {continents: string[], regions: string[]}}
+ *   The names of the continents and the outermost regions the given places lie
+ *   in, each sorted.
+ */
+export function placeGeography(places: Map<string, {
+    shortcode: string;
+    name: string;
+    subType?: string;
+    parents: string[];
+}>): (shortcodes: Iterable<string>) => {
+    continents: string[];
+    regions: string[];
+};
+/**
+ * The places a note lies in: itself for a place, its `homes` and its
+ * `locations` otherwise.
+ *
+ * @param {object} fm - The note's frontmatter.
+ * @returns {string[]} Shortcodes, lower case.
+ */
+export function notePlaces(fm: object): string[];
+/**
+ * What a note's page tells the search.
+ *
+ * @param {object} fm - The page's frontmatter: the note's, with its `package`.
+ * @param {object} options - What the values resolve against.
+ * @param {(shortcodes: Iterable<string>) => {continents: string[], regions: string[]}} options.geography -
+ *   From {@link placeGeography}.
+ * @param {object} [options.index] - The site's address index, which names the
+ *   culture `data.culture` names.
+ * @returns {{filters: Array<{name: string, values: string[]}>, names: string[]}}
+ *   Each filter with a value, in {@link SEARCH_FILTERS} order, and the names a
+ *   search weights.
+ */
+export function searchMetadata(fm: object, { geography, index }: {
+    geography: (shortcodes: Iterable<string>) => {
+        continents: string[];
+        regions: string[];
+    };
+    index?: object | undefined;
+}): {
+    filters: Array<{
+        name: string;
+        values: string[];
+    }>;
+    names: string[];
+};
+/** The filters a note's page carries, in the order a reader is offered them. */
+export const SEARCH_FILTERS: readonly string[];

package/types/engine/site-serve.d.mts

@@ -0,0 +1,44 @@
+/**
+ * Serve a package's site, and keep it current.
+ *
+ * @param {object} options - The inputs.
+ * @param {object} options.config - The resolved configuration.
+ * @param {string} options.out - The site's directory under the deployed
+ *   root, which the site is written to.
+ * @param {string} [options.root] - The deployed root, which is served. The
+ *   directory above `out` by default; `out` itself for a site served at `/`.
+ * @param {string} [options.host] - The address to listen on.
+ * @param {number} [options.port] - The port; `0` takes any free one.
+ * @param {boolean} [options.search] - Build the search index after the first
+ *   build, where the site has one.
+ * @param {number} [options.year] - The year the footer states.
+ * @param {(event: {kind: string, built?: object, files?: string[], findings?: object[], error?: unknown}) => void} [options.report] -
+ *   Told of each build: `built` for a whole build, `page` for one note's page,
+ *   `theme` for the theme, `failed` with what the build found, `error` with
+ *   what it threw.
+ * @returns {Promise<{url: string, close: () => Promise<void>, settled: () => Promise<void>}>}
+ *   The address of the site's home page, how to stop serving, and a promise
+ *   for the moment every change seen so far has been written.
+ */
+export function serveSite({ config, out, root, host, port, search, year, report, }: {
+    config: object;
+    out: string;
+    root?: string | undefined;
+    host?: string | undefined;
+    port?: number | undefined;
+    search?: boolean | undefined;
+    year?: number | undefined;
+    report?: ((event: {
+        kind: string;
+        built?: object;
+        files?: string[];
+        findings?: object[];
+        error?: unknown;
+    }) => void) | undefined;
+}): Promise<{
+    url: string;
+    close: () => Promise<void>;
+    settled: () => Promise<void>;
+}>;
+/** The address a served page listens on for the server's reloads. */
+export const RELOAD_PATH: "/__package-build/reload";

package/types/engine/site-theme-banner.d.mts

@@ -0,0 +1,51 @@
+/**
+ * The banner data the theme ships.
+ *
+ * @returns {{banners: object, kinds: object}} The inventory and the kind mapping.
+ */
+export function shippedBannerData(): {
+    banners: object;
+    kinds: object;
+};
+/**
+ * The address of a page's banner.
+ *
+ * @param {object} site - The site: `params.cdnBaseURL` and `basePath`.
+ * @param {object} fields - What the page states.
+ * @param {object} [fields.data] - The page's `data`, read for the resolved `banner`.
+ * @param {unknown} [fields.banner] - The hand-authored `banner` value.
+ * @param {string} [fields.type] - The note `type`.
+ * @param {string} [fields.subType] - The note `subType`.
+ * @param {string} [fields.category] - The page's `category`.
+ * @param {string} [fields.subtype] - The name to default to when no `type` is given.
+ * @param {string} [fields.context] - The page address, named in a report.
+ * @param {object} [options] - Options.
+ * @param {{banners: object, kinds: object}} [options.data] - The inventory and the
+ *   kind mapping. The shipped ones by default.
+ * @param {(finding: {severity: string, message: string, page?: string}) => void} [options.report] -
+ *   Receives each name that misses the inventory, once.
+ * @param {Set<string>} [options.reported] - The names already reported.
+ * @returns {string} The address, or `""` when the page has no banner.
+ */
+export function bannerUrl(site: object, fields: {
+    data?: object | undefined;
+    banner?: unknown;
+    type?: string | undefined;
+    subType?: string | undefined;
+    category?: string | undefined;
+    subtype?: string | undefined;
+    context?: string | undefined;
+}, { data, report, reported }?: {
+    data?: {
+        banners: object;
+        kinds: object;
+    } | undefined;
+    report?: ((finding: {
+        severity: string;
+        message: string;
+        page?: string;
+    }) => void) | undefined;
+    reported?: Set<string> | undefined;
+}): string;
+/** The directory holding the banner inventory and the kind mapping. */
+export const BANNER_DATA_DIR: string;

package/types/engine/site-theme-urls.d.mts

@@ -0,0 +1,60 @@
+/** Whether an address names a host: `http://`, `https://` or `//`. */
+export function isAbsoluteUrl(url: any): boolean;
+/**
+ * The path a site is served under, with a leading and a trailing slash.
+ *
+ * @param {object} site - The site; `baseURL` is its address.
+ * @returns {string} `/` for a site at its origin's root, `/thalorna/` for one under a prefix.
+ */
+export function basePath(site: object): string;
+/**
+ * A path inside the site, under its base path.
+ *
+ * A leading slash is dropped first: it would otherwise read as "from the
+ * origin" and leave the base path off.
+ *
+ * @param {object} site - The site.
+ * @param {string} [target] - The path; empty for the site's root.
+ * @returns {string} The address.
+ */
+export function relUrl(site: object, target?: string): string;
+/**
+ * An asset path, resolved against the site's asset host.
+ *
+ * An absolute address is returned as written. Otherwise the path is joined onto
+ * `params.cdnBaseURL`, and with none set it is a path inside the site.
+ *
+ * @param {object} site - The site; `params.cdnBaseURL` is the asset root.
+ * @param {string} target - The asset path.
+ * @returns {string} The address.
+ */
+export function cdnUrl(site: object, target: string): string;
+/**
+ * A link a consuming site supplied, resolved against the site it is rendered on.
+ *
+ * An absolute address, a fragment and a query are returned as written; anything
+ * else is a path inside the site.
+ *
+ * @param {object} site - The site.
+ * @param {string} [url] - The link; empty for the site's root.
+ * @returns {string} The address.
+ */
+export function siteUrl(site: object, url?: string): string;
+/**
+ * A link from a page's data, with a scheme that could run script refused.
+ *
+ * @param {unknown} url - The link as the data states it.
+ * @returns {string} The link, or `#` when its scheme is not one a reader should follow.
+ */
+export function safeUrl(url: unknown): string;
+/**
+ * The address of a tag's listing page.
+ *
+ * One function writes it for the link in a page's tag row and for the page the
+ * site build writes, so the two cannot disagree.
+ *
+ * @param {object} site - The site.
+ * @param {string} tag - The tag.
+ * @returns {string} The address.
+ */
+export function tagUrl(site: object, tag: string): string;

package/types/engine/site-theme.d.mts

@@ -0,0 +1,127 @@
+/** A string with its first letter capitalised and its separators read as spaces. */
+export function humanize(value: any): string;
+/** The text of HTML: tags dropped, character references decoded, whitespace collapsed. */
+export function plainText(html: any): string;
+/** Whether a page states it is a draft. */
+export function isDraft(params?: {}): any;
+/**
+ * The subject tags of a page: every tag but the one that marks a draft.
+ *
+ * @param {object} params - The page's frontmatter.
+ * @returns {string[]} The tags.
+ */
+export function subjectTags(params?: object): string[];
+/**
+ * The headings of rendered HTML that a contents list names.
+ *
+ * @param {string} html - A page's body.
+ * @returns {Array<{level: number, id: string, text: string}>} The `h2` and `h3`
+ *   headings in document order, the footnote list's own heading left out; `id`
+ *   is empty for a heading that has none.
+ */
+export function pageHeadings(html: string): Array<{
+    level: number;
+    id: string;
+    text: string;
+}>;
+/**
+ * A contents list for a page's headings.
+ *
+ * @param {Array<{level: number, id: string, text: string}>} headings - From {@link pageHeadings}.
+ * @returns {string} A `nav` of nested lists, or `""` when there are no headings. A
+ *   heading with no id is listed without a link.
+ */
+export function tableOfContents(headings: Array<{
+    level: number;
+    id: string;
+    text: string;
+}>): string;
+/**
+ * The page before and the page after this one.
+ *
+ * `siblings` is in the order a reader walks. Where the section holds more than
+ * one catalog, the siblings are narrowed to the pages sharing this page's
+ * catalog key: `type`, or for a `doc` its `subType` or `category`. A section
+ * holding one catalog is left alone, as is a page declaring none.
+ *
+ * @param {object} page - The page.
+ * @param {boolean} [narrow] - Whether to narrow to the page's catalog.
+ * @returns {{prev?: object, next?: object}} The neighbours; `prev` is the entry
+ *   after this one in `siblings`, and `next` the entry before it.
+ */
+export function neighbours(page: object, narrow?: boolean): {
+    prev?: object;
+    next?: object;
+};
+/**
+ * @typedef {object} Finding
+ * @property {"warning"|"error"} severity
+ * @property {string} message
+ * @property {string} [page] - The address of the page the finding is about.
+ * @property {string} [file] - The file the page was written in.
+ * @property {Array<string|number>} [param] - The path of the site parameter
+ *   the finding is about, such as `["notfound", "links", 1, "url"]`.
+ */
+/**
+ * Create the layouts for one site.
+ *
+ * @param {object} options - The inputs.
+ * @param {object} options.site - The site; see the module description.
+ * @param {string} [options.dir] - The directory holding `layouts/` and
+ *   `partials/`. The shipped theme by default.
+ * @param {{banners: object, kinds: object}} [options.bannerData] - The banner
+ *   inventory and kind mapping. The shipped ones by default.
+ * @param {(finding: Finding) => void} [options.report] - Receives each finding
+ *   as it is made. Every finding is also kept in `findings`.
+ * @returns {{
+ *   render: (page: object) => string,
+ *   layoutFor: (page: object) => string,
+ *   partial: (name: string, context?: object) => string,
+ *   findings: Finding[],
+ * }} The theme.
+ */
+export function createSiteTheme({ site, dir, bannerData, report }: {
+    site: object;
+    dir?: string | undefined;
+    bannerData?: {
+        banners: object;
+        kinds: object;
+    } | undefined;
+    report?: ((finding: Finding) => void) | undefined;
+}): {
+    render: (page: object) => string;
+    layoutFor: (page: object) => string;
+    partial: (name: string, context?: object) => string;
+    findings: Finding[];
+};
+/**
+ * The files the layouts link that the theme generates.
+ *
+ * @returns {Array<{path: string, content: string}>} Each file's path under the
+ *   site and its contents.
+ */
+export function siteThemeAssets(): Array<{
+    path: string;
+    content: string;
+}>;
+/** The directory the layouts and partials are read from. */
+export const SITE_THEME_DIR: string;
+/** The layouts a page can be drawn by. */
+export const LAYOUTS: readonly string[];
+export type Finding = {
+    severity: "warning" | "error";
+    message: string;
+    /**
+     * - The address of the page the finding is about.
+     */
+    page?: string | undefined;
+    /**
+     * - The file the page was written in.
+     */
+    file?: string | undefined;
+    /**
+     * - The path of the site parameter
+     * the finding is about, such as `["notfound", "links", 1, "url"]`.
+     */
+    param?: (string | number)[] | undefined;
+};

package/types/engine/text-maps.d.mts

@@ -39,14 +39,16 @@ export function capitalNative(map: TextMap, font: string | undefined, word: stri
  *   as it is.
  * @param {string} text - The text, with no escapes in it.
  * @param {MapOptions} [options] - The face, and the native forms of words.
- * @returns {{text: string, pieces: Array<{at: number, from: string, to: string, row: boolean, native?: boolean}>}}
+ * @returns {{text: string, pieces: Array<{at: number, from: string, to: string, row: boolean, native?: boolean, unwritten?: object}>}}
  *   The rewritten text, and each piece of it with the UTF-16 offset in `text`
  *   it came from: a matched row's `from` and what it wrote, a word and its
  *   native form (`native: true`), or one character that passed through. A
  *   capitalised word whose native form the rows cannot capitalise is written
  *   as stated and carries `uncapitalised`, the lowercase form it was found by.
+ *   Under a logographic map, a word with no writing is written as typed and
+ *   carries `unwritten`, why it has none.
  */
-export function applyMap(map: TextMap | undefined, text: string, { font, native }?: MapOptions): {
+export function applyMap(map: TextMap | undefined, text: string, { font, native, writing }?: MapOptions): {
     text: string;
     pieces: Array<{
         at: number;
@@ -54,6 +56,7 @@ export function applyMap(map: TextMap | undefined, text: string, { font, native
         to: string;
         row: boolean;
         native?: boolean;
+        unwritten?: object;
     }>;
 };
 /**
@@ -78,7 +81,8 @@ export function mapRows(records: Iterable<Record<string, any>>, ownerOf: (record
 /**
  * Check a note's `data.map`: its name, that no other note declares it, each
  * row written as a list, a `before` condition on a map with no `vowels`, an
- * empty `fonts`, and a generic family in it. The data-key check owns every
+ * empty `fonts`, a generic family in it, and a row of a logographic map that
+ * matches a letter. The data-key check owns every
  * key, its kind and the words a condition takes; whether a listed face is
  * installed, and draws what the map writes, is
  * {@link module:engine/map-lexicon.checkMapFonts}'s.
@@ -136,6 +140,11 @@ export type TextMap = {
      * - Its name.
      */
     name: string;
+    /**
+     * - Whether it writes words from the lexicon
+     * alone, its rows only between them.
+     */
+    logographic: boolean;
     /**
      * - The characters `before: vowel` reads.
      */
@@ -172,4 +181,9 @@ export type MapOptions = {
      * form, for the word exactly as given, or `undefined` where it states none.
      */
     native?: ((word: string) => string | undefined) | undefined;
+    /**
+     * -
+     * A word's writing under a logographic map; without one, no word has one.
+     */
+    writing?: ((word: string) => import("./logographic.mjs").Writing) | undefined;
 };

package/types/engine/typographer.d.mts

@@ -0,0 +1,11 @@
+/**
+ * Set typographic punctuation in every inline run.
+ *
+ * @param {import("markdown-it")} md - Markdown parser to extend.
+ */
+export function typographerPlugin(md: typeof import("markdown-it")): void;
+/**
+ * The token a typographic character is written as. It is a token of its own,
+ * not text, so a reader of a heading's text can tell where it stands.
+ */
+export const TYPOGRAPHIC: "typographic";