npm - @docpensieve/core - Versions diffs - 0.1.0 - Mend

@docpensieve/core 0.1.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.

Files changed (20) hide show

package/LICENSE +21 -0
package/README.md +38 -0
package/package.json +58 -0
package/src/compiler.js +415 -0
package/src/config.js +265 -0
package/src/generator.js +517 -0
package/src/index.js +35 -0
package/src/loader.js +260 -0
package/src/sidebar.js +105 -0
package/src/structured-data.js +334 -0
package/templates/layout.hbs +94 -0
package/templates/nav-items.hbs +14 -0
package/templates/toc-items.hbs +10 -0
package/types/compiler.d.ts +108 -0
package/types/config.d.ts +149 -0
package/types/generator.d.ts +82 -0
package/types/index.d.ts +34 -0
package/types/loader.d.ts +66 -0
package/types/sidebar.d.ts +60 -0
package/types/structured-data.d.ts +51 -0

package/templates/layout.hbs ADDED Viewed

@@ -0,0 +1,94 @@
+<!doctype html>
+<html lang="{{lang}}"{{#if darkModeClass}} class="{{darkModeClass}}"{{/if}}>
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>{{title}}</title>
+    {{#if description}}
+    <meta name="description" content="{{description}}" />
+    {{/if}}
+    {{#if noindex}}
+    <meta name="robots" content="noindex, follow" />
+    {{/if}}
+    {{#if canonical}}
+    <link rel="canonical" href="{{canonical}}" />
+    {{/if}}
+    {{#each preloads}}
+    <link rel="preload" as="{{as}}" href="{{href}}" />
+    {{/each}}
+    <link rel="stylesheet" href="{{cssHref}}" />
+    {{{jsonld}}}
+  </head>
+  <body>
+    <a class="{{{cls.skip}}}" href="#content">Skip to content</a>
+    {{!-- Target of the back-to-top link: bring the focus back, not only the view. --}}
+    <header class="{{{cls.header}}}" id="top" tabindex="-1">
+      <a class="{{{cls.brand}}}" href="{{homeUrl}}">{{projectName}}</a>
+      {{#if showVersions}}
+      <details class="{{{cls.versions}}}">
+        {{!-- The accessible name contains the visible label: when dictated by
+        voice, what is read on screen must find this button. --}}
+        <summary aria-label="Version {{versionName}}, switch version">{{versionName}}</summary>
+        <ul class="{{{cls.versionsList}}}">
+          {{#each versions}}
+          <li><a href="{{url}}"{{#if current}} aria-current="true"{{/if}}>{{name}}</a></li>
+          {{/each}}
+        </ul>
+      </details>
+      {{/if}}
+    </header>
+    <div class="{{#if wide}}{{{cls.shellWide}}}{{else}}{{{cls.shell}}}{{/if}}">
+      {{#if sidebar.length}}
+      <nav class="{{{cls.sidebar}}}" aria-label="Documentation navigation">
+        {{> navItems sidebar}}
+      </nav>
+      {{/if}}
+      <main class="{{{cls.main}}}" id="content" tabindex="-1">
+        {{#if notice}}
+        <aside class="{{{cls.notice}}}" role="note">
+          {{#if notice.prerelease}}
+          This version is in preparation and may change.
+          {{else}}
+          This version is no longer maintained.
+          {{/if}}
+          The current version is <a href="{{notice.url}}">{{notice.name}}</a>.
+        </aside>
+        {{/if}}
+        <article class="{{{cls.article}}}">{{{content}}}</article>
+      </main>
+      {{#if toc.length}}
+      <nav class="{{{cls.toc}}}" aria-label="On this page">
+        <p class="{{{cls.tocTitle}}}">On this page</p>
+        {{> tocItems toc}}
+      </nav>
+      {{/if}}
+    </div>
+    <footer class="{{{cls.footer}}}">
+      <p>{{projectName}} — version {{versionName}}</p>
+    </footer>
+    {{#if scrollToTop}}
+    <a class="{{{cls.scrollTop}}}" href="#top" aria-label="Back to top">
+      <svg
+        class="{{{cls.scrollTopIcon}}}"
+        viewBox="0 0 24 24"
+        fill="none"
+        stroke="currentColor"
+        stroke-width="2"
+        stroke-linecap="round"
+        stroke-linejoin="round"
+        aria-hidden="true"
+        focusable="false"
+      >
+        <path d="M12 19V5" />
+        <path d="m5 12 7-7 7 7" />
+      </svg>
+    </a>
+    {{/if}}
+  </body>
+</html>

package/templates/nav-items.hbs ADDED Viewed

@@ -0,0 +1,14 @@
+<ul class="{{{@root.cls.nav}}}">
+  {{#each this}}
+  <li class="{{{@root.cls.navItem}}}{{#if items.length}} {{{@root.cls.navItemParent}}}{{/if}}">
+    {{#if url}}
+    <a class="{{{@root.cls.navLink}}}" href="{{url}}"{{#if (eq url @root.currentUrl)}} aria-current="page"{{/if}}>{{label}}</a>
+    {{else}}
+    <span class="{{{@root.cls.navLabel}}}">{{label}}</span>
+    {{/if}}
+    {{#if items.length}}
+    {{> navItems items}}
+    {{/if}}
+  </li>
+  {{/each}}
+</ul>

package/templates/toc-items.hbs ADDED Viewed

@@ -0,0 +1,10 @@
+<ul class="{{{@root.cls.tocList}}}">
+  {{#each this}}
+  <li class="{{{@root.cls.tocItem}}}">
+    <a href="#{{id}}">{{text}}</a>
+    {{#if children.length}}
+    {{> tocItems children}}
+    {{/if}}
+  </li>
+  {{/each}}
+</ul>

package/types/compiler.d.ts ADDED Viewed

@@ -0,0 +1,108 @@
+/**
+ * Compiles Markdown/MDX content into static HTML.
+ *
+ * Chosen pipeline: `.md` and `.mdx` both go through @mdx-js/mdx, then the
+ * resulting component is rendered by `react-dom/server`. React only serves
+ * the build; the HTML produced contains no React runtime.
+ *
+ * @module @docpensieve/core/compiler
+ */
+export type TocEntry = {
+    /**
+     * Heading anchor (`'installation'`).
+     */
+    id: string;
+    /**
+     * Heading text, tags removed.
+     */
+    text: string;
+    /**
+     * Heading level (2 for `h2`).
+     */
+    depth: number;
+    /**
+     * Nested sub-headings.
+     */
+    children: TocEntry[];
+};
+export type Preload = {
+    /**
+     * Resource to preload.
+     */
+    href: string;
+    /**
+     * Resource type (`'image'`).
+     */
+    as: string;
+};
+export type CompileResult = {
+    /**
+     * HTML fragment of the content alone.
+     */
+    html: string;
+    /**
+     * Nested table of contents.
+     */
+    toc: TocEntry[];
+    /**
+     * Resources to preload, meant for the `<head>`.
+     */
+    preloads: Preload[];
+};
+/** Compiles an MDX/Markdown source into an HTML fragment. */
+export declare class Compiler {
+    #private;
+    options: {
+        components?: Record<string, Function>;
+        remarkPlugins?: any[];
+        rehypePlugins?: any[];
+        highlight?: false | Record<string, any>;
+        tocDepth?: [number, number];
+    };
+    components: Record<string, Function>;
+    remarkPlugins: any[];
+    rehypePlugins: any[];
+    highlight: false | Record<string, any> | {
+        themes: {
+            light: string;
+            dark: string;
+        };
+    };
+    tocDepth: number[];
+    /**
+     * @param {{
+     *   components?: Record<string, Function>,
+     *   remarkPlugins?: any[],
+     *   rehypePlugins?: any[],
+     *   highlight?: false | Record<string, any>,
+     *   tocDepth?: [number, number],
+     * }} [options]
+     *   `components` is the table of global components injected into MDX: it is
+     *   what lets a page write `<Card>` without an import. `highlight` takes the
+     *   @shikijs/rehype options, or `false` to turn highlighting off. `tocDepth`
+     *   bounds the headings kept in the table of contents.
+     */
+    constructor(options?: {
+        components?: Record<string, Function>;
+        remarkPlugins?: any[];
+        rehypePlugins?: any[];
+        highlight?: false | Record<string, any>;
+        tocDepth?: [number, number];
+    });
+    /**
+     * Compiles a source into an HTML fragment and a table of contents.
+     *
+     * @param {string} source Markdown/MDX content, frontmatter already removed.
+     * @param {{ filepath?: string, url?: string, dirUrl?: string, basePath?: string }} [context]
+     *   `filepath` locates errors, `dirUrl` is the base of relative targets and
+     *   `basePath` prefixes absolute targets (the version root).
+     * @returns {Promise<CompileResult>}
+     * @throws {CompileError} Invalid syntax, or a component unknown at use.
+     */
+    compile(source: string, context?: {
+        filepath?: string;
+        url?: string;
+        dirUrl?: string;
+        basePath?: string;
+    }): Promise<CompileResult>;
+}

package/types/config.d.ts ADDED Viewed

@@ -0,0 +1,149 @@
+/**
+ * Loading and normalisation of `docpensieve.config.js`.
+ * @module @docpensieve/core/config
+ */
+export type Version = {
+    /**
+     * URL and branch identifier (`'v1.0'`).
+     */
+    slug: string;
+    /**
+     * Label shown in the version switcher (`'1.0'`).
+     */
+    name: string;
+    /**
+     * Source folder, relative to the root.
+     */
+    folder: string;
+    /**
+     * Version served by default. At most one.
+     */
+    current?: boolean;
+    /**
+     * Version kept but no longer maintained.
+     */
+    archived?: boolean;
+    /**
+     * Version in preparation, not yet the
+     * reference one. Its pages carry a notice and are not indexed.
+     */
+    prerelease?: boolean;
+};
+export type DocPensieveConfig = {
+    /**
+     * Name shown in the header and in the JSON-LD.
+     */
+    projectName: string;
+    /**
+     * Public URL, empty when unknown.
+     */
+    siteUrl: string;
+    /**
+     * Deployment prefix, slashes included.
+     */
+    baseUrl: string;
+    /**
+     * Output folder, relative to the root.
+     */
+    outDir: string;
+    /**
+     * At least one.
+     */
+    versions: Version[];
+    theme: {
+        framework: string;
+        darkMode?: string;
+        tokens?: Record<string, string>;
+        css?: string;
+        source?: string;
+    };
+    /**
+     * `'auto'`, or the path of a description.
+     */
+    sidebar: string;
+    globalComponents: boolean;
+    /**
+     * Back-to-top button on every page.
+     */
+    scrollToTop: boolean;
+    jsonld: {
+        enabled: boolean;
+    };
+    /**
+     * Project root, set by `loadConfig`.
+     */
+    rootDir?: string;
+    /**
+     * Document language, `'en'` by default.
+     */
+    lang?: string;
+};
+/**
+ * @typedef {object} Version
+ * @property {string} slug   URL and branch identifier (`'v1.0'`).
+ * @property {string} name   Label shown in the version switcher (`'1.0'`).
+ * @property {string} folder Source folder, relative to the root.
+ * @property {boolean} [current]  Version served by default. At most one.
+ * @property {boolean} [archived] Version kept but no longer maintained.
+ * @property {boolean} [prerelease] Version in preparation, not yet the
+ *   reference one. Its pages carry a notice and are not indexed.
+ */
+/**
+ * @typedef {object} DocPensieveConfig
+ * @property {string} projectName Name shown in the header and in the JSON-LD.
+ * @property {string} siteUrl     Public URL, empty when unknown.
+ * @property {string} baseUrl     Deployment prefix, slashes included.
+ * @property {string} outDir      Output folder, relative to the root.
+ * @property {Version[]} versions At least one.
+ * @property {{ framework: string, darkMode?: string, tokens?: Record<string, string>, css?: string, source?: string }} theme
+ * @property {string} sidebar     `'auto'`, or the path of a description.
+ * @property {boolean} globalComponents
+ * @property {boolean} scrollToTop Back-to-top button on every page.
+ * @property {{ enabled: boolean }} jsonld
+ * @property {string} [rootDir]   Project root, set by `loadConfig`.
+ * @property {string} [lang]      Document language, `'en'` by default.
+ */
+/**
+ * Values applied when the user config leaves them out.
+ *
+ * The type is spelled out: without it, TypeScript would infer
+ * `versions: never[]` from the empty array and refuse every read of its
+ * elements elsewhere in the file.
+ *
+ * @type {Readonly<DocPensieveConfig>}
+ */
+export declare const DEFAULT_CONFIG: Readonly<DocPensieveConfig>;
+/**
+ * Identity over the config, used only for autocompletion and type checking
+ * in the editor.
+ *
+ * @template T
+ * @param {T} config
+ * @returns {T}
+ */
+export declare function defineConfig<T>(config: T): T;
+/**
+ * Merges the user config with the defaults and validates it.
+ *
+ * @param {Record<string, unknown>} userConfig
+ * @returns {DocPensieveConfig} Normalised config.
+ * @throws {ConfigError} When the config is structurally invalid.
+ */
+export declare function normalizeConfig(userConfig: Record<string, unknown>): DocPensieveConfig;
+/**
+ * Loads `docpensieve.config.js` from a project folder.
+ *
+ * @param {string} [cwd] Project root. Default: `process.cwd()`.
+ * @returns {Promise<DocPensieveConfig>} Normalised config.
+ * @throws {ConfigError} When the file is missing or exports no object.
+ */
+export declare function loadConfig(cwd?: string): Promise<DocPensieveConfig>;
+/**
+ * Finds a declared version by its slug.
+ *
+ * @param {DocPensieveConfig} config Normalised config.
+ * @param {string} [slug] Slug to look for. Omitted: the "current" version.
+ * @returns {Version} The requested version.
+ * @throws {ConfigError} When the slug does not exist.
+ */
+export declare function resolveVersion(config: DocPensieveConfig, slug?: string): Version;

package/types/generator.d.ts ADDED Viewed

@@ -0,0 +1,82 @@
+/**
+ * Orchestration: loader → compiler → Handlebars shell → disk.
+ *
+ * @module @docpensieve/core/generator
+ */
+import { Compiler } from './compiler.js';
+import { DocLoader } from './loader.js';
+/** Generates the static site of one or more versions. */
+export declare class SiteGenerator {
+    #private;
+    config: import("./config.js").DocPensieveConfig;
+    deps: {
+        components?: Record<string, Function>;
+        theme?: any;
+        loader?: DocLoader;
+        compiler?: Compiler;
+        onPage?: (page: {
+            url: string;
+            dirUrl?: string;
+            basePath: string;
+            filepath?: string;
+            sourceDir?: string;
+        }) => void;
+    };
+    loader: DocLoader;
+    compiler: Compiler;
+    /**
+     * @param {import('./config.js').DocPensieveConfig} config Normalised config.
+     * @param {{
+     *   components?: Record<string, Function>,
+     *   theme?: any,
+     *   loader?: DocLoader,
+     *   compiler?: Compiler,
+     *   onPage?: (page: {
+     *     url: string, dirUrl?: string, basePath: string,
+     *     filepath?: string, sourceDir?: string,
+     *   }) => void,
+     * }} [deps]
+     *   Global components and the theme are injected rather than imported:
+     *   `core` stays independent of `components` and `theme` (ADR-002). `loader`
+     *   and `compiler` only serve tests. `onPage` is called before every page:
+     *   components learn from it the URL they render, which the compiler
+     *   plugins cannot tell them (ADR-006), and how to find a file of the
+     *   version.
+     */
+    constructor(config: import('./config.js').DocPensieveConfig, deps?: {
+        components?: Record<string, Function>;
+        theme?: any;
+        loader?: DocLoader;
+        compiler?: Compiler;
+        onPage?: (page: {
+            url: string;
+            dirUrl?: string;
+            basePath: string;
+            filepath?: string;
+            sourceDir?: string;
+        }) => void;
+    });
+    /**
+     * Generates one version into a folder.
+     *
+     * @param {string} versionSlug Slug of the version to generate.
+     * @param {string} outDir Output folder of that version.
+     * @returns {Promise<{ pages: number, outDir: string }>}
+     * @throws {GeneratorError} Write failure.
+     */
+    buildVersion(versionSlug: string, outDir: string): Promise<{
+        pages: number;
+        outDir: string;
+    }>;
+    /**
+     * Generates every declared version, plus `versions.json` and a root that
+     * redirects to the current version.
+     *
+     * @returns {Promise<{ versions: number, pages: number, outDir: string }>}
+     */
+    buildAll(): Promise<{
+        versions: number;
+        pages: number;
+        outDir: string;
+    }>;
+}

package/types/index.d.ts ADDED Viewed

@@ -0,0 +1,34 @@
+/**
+ * @docpensieve/core — the generation engine.
+ *
+ * Depends on `@docpensieve/shared` only. Global components and the theme are
+ * injected by the caller (the CLI), which keeps the engine testable without
+ * React or CSS.
+ *
+ * @module @docpensieve/core
+ */
+export type DocPensieveConfig = import('./config.js').DocPensieveConfig;
+export type Version = import('./config.js').Version;
+export type Doc = import('./loader.js').Doc;
+export type CompileResult = import('./compiler.js').CompileResult;
+export type TocEntry = import('./compiler.js').TocEntry;
+export type Preload = import('./compiler.js').Preload;
+export type SidebarNode = import('./sidebar.js').SidebarNode;
+/**
+ * Engine types, re-exported for consumers of the published package: without
+ * this they would only be reachable through an internal path.
+ *
+ * @typedef {import('./config.js').DocPensieveConfig} DocPensieveConfig
+ * @typedef {import('./config.js').Version} Version
+ * @typedef {import('./loader.js').Doc} Doc
+ * @typedef {import('./compiler.js').CompileResult} CompileResult
+ * @typedef {import('./compiler.js').TocEntry} TocEntry
+ * @typedef {import('./compiler.js').Preload} Preload
+ * @typedef {import('./sidebar.js').SidebarNode} SidebarNode
+ */
+export { DEFAULT_CONFIG, defineConfig, loadConfig, normalizeConfig, resolveVersion, } from './config.js';
+export { DocLoader } from './loader.js';
+export { Compiler } from './compiler.js';
+export { StructuredDataBuilder } from './structured-data.js';
+export { SiteGenerator } from './generator.js';
+export { buildSidebar, collectSectionTitles } from './sidebar.js';

package/types/loader.d.ts ADDED Viewed

@@ -0,0 +1,66 @@
+/**
+ * Loads the Markdown/MDX sources of a version.
+ *
+ * @module @docpensieve/core/loader
+ */
+export type Doc = {
+    /**
+     * Page slug (`'guide/install'`).
+     */
+    slug: string;
+    /**
+     * Absolute path of the source file.
+     */
+    path: string;
+    /**
+     * Site URL (`'/guide/install/'`).
+     */
+    url: string;
+    /**
+     * Frontmatter parsed by gray-matter.
+     */
+    frontmatter: Record<string, any>;
+    /**
+     * Raw Markdown/MDX body, frontmatter removed.
+     */
+    content: string;
+    /**
+     * Ordering weight for the sidebar.
+     */
+    order: number;
+};
+/** Walks a version folder and produces the list of documents. */
+export declare class DocLoader {
+    #private;
+    options: {
+        extensions?: string[];
+        includeDrafts?: boolean;
+    };
+    extensions: string[];
+    includeDrafts: boolean;
+    /**
+     * @param {{ extensions?: string[], includeDrafts?: boolean }} [options]
+     *   `extensions` replaces the default list (`.md`, `.mdx`);
+     *   `includeDrafts` keeps the pages marked `draft: true`.
+     */
+    constructor(options?: {
+        extensions?: string[];
+        includeDrafts?: boolean;
+    });
+    /**
+     * Recursively loads every document of a folder.
+     *
+     * Documents come back in the site's reading order: at each level, the index
+     * page first, then numeric prefixes, then alphabetical. That is the order
+     * the sidebar needs, hence sorting during the walk rather than a flat sort
+     * of the result.
+     *
+     * The URLs produced carry no version prefix: the loader does not know which
+     * version it works on, the generator adds it.
+     *
+     * @param {string} dir Version folder (e.g. `docs/v1.0`).
+     * @returns {Promise<Doc[]>}
+     * @throws {LoaderError} Missing folder, invalid frontmatter, colliding slugs.
+     */
+    load(dir: string): Promise<Doc[]>;
+}

package/types/sidebar.d.ts ADDED Viewed

@@ -0,0 +1,60 @@
+/**
+ * Builds the sidebar from the loaded documents.
+ *
+ * @module @docpensieve/core/sidebar
+ */
+export type SidebarNode = {
+    /**
+     * Displayed title.
+     */
+    label: string;
+    /**
+     * Page URL, or `null` for a folder without an
+     * index page — the category is then a mere grouping.
+     */
+    url: string | null;
+    /**
+     * Child entries.
+     */
+    items: SidebarNode[];
+};
+/**
+ * @typedef {object} SidebarNode
+ * @property {string} label   Displayed title.
+ * @property {string | null} url Page URL, or `null` for a folder without an
+ *   index page — the category is then a mere grouping.
+ * @property {SidebarNode[]} items Child entries.
+ */
+/**
+ * Builds the navigation tree of a version.
+ *
+ * The order is the `DocLoader`'s, which has already sorted: index page first,
+ * then numeric prefixes, then alphabetical. Nothing is re-sorted here, which
+ * guarantees that the sidebar follows the reading order of the files exactly.
+ *
+ * That order has a useful consequence: since `guide/index.md` is loaded
+ * before `guide/installation.md`, the “guide” category receives its real
+ * title before a child page creates it with a default one.
+ *
+ * @param {import('./loader.js').Doc[]} docs Documents in loader order.
+ * @param {(doc: import('./loader.js').Doc) => string} [toUrl] Turns a
+ *   document into a URL. By default, the document's URL as is.
+ * @param {{ brand?: string }} [options] `brand` is the name shown in the
+ *   header: a root entry carrying exactly that title is dropped, since the
+ *   brand already leads to that page. The same word twice, an inch apart,
+ *   tells the reader nothing.
+ * @returns {SidebarNode[]}
+ */
+export declare function buildSidebar(docs: import('./loader.js').Doc[], toUrl?: (doc: import('./loader.js').Doc) => string, options?: {
+    brand?: string;
+}): SidebarNode[];
+/**
+ * Collects folder titles, for the breadcrumb.
+ *
+ * Only folders with an index page have a known title; the others will be
+ * humanised from their slug by `StructuredDataBuilder`.
+ *
+ * @param {import('./loader.js').Doc[]} docs
+ * @returns {Record<string, string>} Full folder slug to title.
+ */
+export declare function collectSectionTitles(docs: import('./loader.js').Doc[]): Record<string, string>;

package/types/structured-data.d.ts ADDED Viewed

@@ -0,0 +1,51 @@
+/**
+ * Builds the JSON-LD from the frontmatter.
+ *
+ * @module @docpensieve/core/structured-data
+ */
+/** Assembles a schema.org graph for a page. */
+export declare class StructuredDataBuilder {
+    #private;
+    frontmatter: Record<string, any>;
+    url: string;
+    config: Record<string, any>;
+    options: {
+        breadcrumbTitles?: Record<string, string>;
+        basePath?: string;
+        dirUrl?: string;
+    };
+    breadcrumbTitles: Record<string, string>;
+    basePath: string;
+    dirUrl: string | undefined;
+    /**
+     * @param {Record<string, any>} frontmatter Page frontmatter.
+     * @param {string} url Page URL on the site (`'/guide/install/'`).
+     * @param {Record<string, any>} config Normalised project config.
+     * @param {{ breadcrumbTitles?: Record<string, string>, basePath?: string, dirUrl?: string }} [options]
+     *   `breadcrumbTitles` maps a folder slug to its real title, so that the
+     *   breadcrumb shows “Café Guide” rather than “Cafe guide”. `basePath` is
+     *   the site root from which crumbs are counted: the generator sets
+     *   `/versions/v1.0/`, otherwise the breadcrumb would show “Versions” and
+     *   “V1.0”, which are neither pages nor titles. `dirUrl` is the source
+     *   file's folder as a URL: the base of the frontmatter's relative targets.
+     */
+    constructor(frontmatter: Record<string, any>, url: string, config: Record<string, any>, options?: {
+        breadcrumbTitles?: Record<string, string>;
+        basePath?: string;
+        dirUrl?: string;
+    });
+    /**
+     * Builds the page's schema.org graph.
+     *
+     * @returns {Record<string, any> | null} Object ready to serialise, or
+     *   `null` when structured data is turned off in the configuration.
+     * @throws {StructuredDataError} Unknown article type, or malformed FAQ.
+     */
+    build(): Record<string, any> | null;
+    /**
+     * Serialises the graph into a tag ready for the `<head>`.
+     *
+     * @returns {string} `<script>` tag, or an empty string when disabled.
+     */
+    toScriptTag(): string;
+}