@almateam/app-sdk 0.9.0 → 0.10.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -8,19 +8,18 @@ An app imports the SDK as `@alma/app-sdk`. Install the published package under
8
8
  that name, for its types:
9
9
 
10
10
  ```sh
11
- npm install --save-dev @alma/app-sdk@npm:@almateam/app-sdk@^0.9.0
11
+ npm install --save-dev @alma/app-sdk@npm:@almateam/app-sdk@^0.10.0
12
12
  ```
13
13
 
14
14
  Alma builds an app's source with its own current copy of the SDK, whatever
15
15
  version the source installs or pins, so the copy you install never ships. The
16
16
  SDK's runtime has no dependency and holds no credential (the `alma-app` command
17
- uses the MCP client); an app runs in Alma's isolated frame and talks to its host
18
- through it:
17
+ uses the MCP client). An app is one set of screens (see "Screens" below); in
18
+ Alma's isolated frame its SDK, `useAlma()` from `@alma/app-ui`, talks to the
19
+ host as the member viewing it:
19
20
 
20
21
  ```ts
21
- import { createAppSdk, hostTransport } from "@alma/app-sdk";
22
-
23
- const alma = createAppSdk(hostTransport());
22
+ const alma = useAlma();
24
23
  const page = await alma.listTopics({
25
24
  type: "account",
26
25
  filter: ["stage:eq:Live"],
@@ -389,18 +388,20 @@ try {
389
388
  }
390
389
  ```
391
390
 
392
- ## Publishing an app to the web
391
+ ## Screens: one app in Alma and on the web
393
392
 
394
- An app can also be a website anyone opens at `<name>.sites.alma.team`, with no
395
- sign-in and no Alma around it. The manifest names the site's module
396
- (`site: { entry: "src/site.tsx" }`), which default-exports `defineSite`:
393
+ An app is one module, `src/app.tsx` (or the module the manifest names in
394
+ `screens: { entry }`), that default-exports `defineApp`. Members see its
395
+ routes in Alma's frame; published, anyone sees them at
396
+ `<name>.sites.alma.team`, with no sign-in and no Alma around them. It is the
397
+ same source in both places:
397
398
 
398
399
  ```tsx
399
- import { defineSite, definePage } from "@alma/app-sdk";
400
+ import { defineApp, defineRoute } from "@alma/app-sdk";
400
401
  import { Frame } from "./Frame";
401
402
  import { posts } from "./posts";
402
403
 
403
- export default defineSite({
404
+ export default defineApp({
404
405
  meta: {
405
406
  name: "Field Notes",
406
407
  description: "Notes from the field.",
@@ -408,13 +409,14 @@ export default defineSite({
408
409
  favicon: { light: "/_files/icon.png", dark: "/_files/icon-dark.png" },
409
410
  },
410
411
  layout: Frame,
411
- pages: [
412
+ routes: [
412
413
  {
413
414
  path: "/",
414
415
  component: () => import("./pages/Home"),
415
416
  meta: () => ({ title: "Home" }),
416
417
  },
417
- definePage({
418
+ { path: "/desk", audience: "members", component: () => import("./Desk") },
419
+ defineRoute({
418
420
  path: "/notes/:slug",
419
421
  addresses: () => posts.map((post) => ({ slug: post.slug })),
420
422
  load: ({ slug }) => posts.find((post) => post.slug === slug)!,
@@ -428,35 +430,63 @@ export default defineSite({
428
430
  });
429
431
  ```
430
432
 
431
- Alma builds every address of every page to its own HTML document when it
432
- builds the version: a page with parameters (`:slug`) is built at each address
433
- its `addresses` lists, and only there. `load` runs then, and again in the
434
- browser when a visitor moves to the page, so it returns plain JSON. Each page
433
+ A route is for members and the public both, unless its `audience` says
434
+ `members` (only in Alma: never built at the published address) or `public`
435
+ (only there). One path may be a members' screen and a public one. `meta`,
436
+ `themeScript`, `fonts`, `files` and `embeds` describe the published address;
437
+ an app that only members see needs none of them.
438
+
439
+ Published, Alma builds every address of every public route to its own HTML
440
+ document when it builds the version: a route with parameters (`:slug`) is
441
+ built at each address its `addresses` lists, and only there (in Alma, every
442
+ address that fits is the route's). `load` runs then, and again in the browser
443
+ when a person moves to the route, so it returns plain JSON. Each public route
435
444
  gets its title, description, canonical address, Open Graph and X tags from its
436
- `meta`, and the site gets `sitemap.xml`, `robots.txt` and a `404.html`
437
- (`notFound`, or a plain one). An address names a page without a trailing slash;
438
- where a static segment and a parameter could both fit, the static one wins. A
439
- redirect's `from` is one address or a prefix ending `/*`, which moves the
440
- prefix itself and everything under it; an address a page lists is served by
441
- the page. `throw notFound()` from `load` sends the visitor to the not-found
442
- page.
443
-
444
- The site kit, `@alma/app-ui/site`, starts the site in the browser and moves
445
- between pages without reloading. A site carries none of Alma's styles, theme or
446
- fonts: it is the site's own CSS throughout.
445
+ `meta`, which it must have, and the site gets `sitemap.xml`, `robots.txt` and
446
+ a `404.html` (`notFound`, or a plain one). An address names a route without a
447
+ trailing slash; where a static segment and a parameter could both fit, the
448
+ static one wins. A redirect's `from` is one address or a prefix ending `/*`,
449
+ which moves the prefix itself and everything under it; an address a route
450
+ lists is served by the route. `throw notFound()` from `load` shows the
451
+ not-found screen.
452
+
453
+ Alma's build starts the app with `startApp` from the kit: at the published
454
+ address it takes up the page the build rendered, over the site's transport
455
+ and the browser's history; in Alma's frame it renders the route at the
456
+ host's address, over the host's transport and history. Either way it moves
457
+ between routes without loading a document.
447
458
 
448
459
  ```tsx
449
- import { Link, Markdown, useAlma, usePath, useSite } from "@alma/app-ui/site";
460
+ import {
461
+ Link,
462
+ Markdown,
463
+ useAlma,
464
+ useApp,
465
+ useFileUrl,
466
+ usePath,
467
+ } from "@alma/app-ui";
450
468
  ```
451
469
 
452
- `Link` moves within the site (and is an ordinary link to anywhere else),
453
- `usePath` and `useSite` say where the visitor is and on which origin, and
454
- `Markdown` draws a `.md` file's tokens. A capitalised tag in the Markdown
455
- (`<Callout kind="note">`) is one of the site's components, passed in
456
- `components`; a name it was not given, or any other HTML, fails the build.
470
+ `Link` moves within the app; to anywhere else it is an ordinary link at the
471
+ published address, and in Alma the host opens it in a new tab when a person
472
+ clicks it (the frame never loads a document of its own). `usePath` and
473
+ `useApp` say where the person is, in which place (`frame` or `public`) and on
474
+ which origin, and `Markdown` draws a `.md` file's tokens. A capitalised tag in
475
+ the Markdown (`<Callout kind="note">`) is one of the app's components, passed
476
+ in `components`; a name it was not given, or any other HTML, fails the build.
457
477
 
458
- A visitor is nobody Alma knows, so the SDK on a site (`useAlma()`, or
459
- `createAppSdk(siteTransport())`) can only raise the events the version declares;
478
+ Neither build adds anything of Alma's look to an app that does not ask, so a
479
+ member and a visitor see what the author wrote. To stand on Alma's (its
480
+ tokens, Geist, the accent and the kit's Theme knobs, beneath the app's own
481
+ CSS, and Alma's tokens on its Tailwind utilities), import it once, in both
482
+ places alike:
483
+
484
+ ```ts
485
+ import "@alma/app-ui/base.css";
486
+ ```
487
+
488
+ In Alma, `useAlma()` is the member's SDK. A visitor is nobody Alma knows, so
489
+ at the published address it can only raise the events the version declares;
460
490
  `viewer()` and `shell()` answer null, and everything else rejects with
461
491
  `site.no_viewer`. Where an event's workflow answers the visitor, the raise
462
492
  returns a `result` ticket: `waitForResult(result.token)` reads the answer, and
@@ -476,10 +506,17 @@ try {
476
506
  }
477
507
  ```
478
508
 
479
- A site's pictures, fonts, PDFs and audio are files, not source. Put them in
509
+ An app's pictures, fonts, PDFs and audio are files, not source. Put them in
480
510
  one flat folder, `_site-files` in the app's folder by default (or name another
481
- with `--files <folder>`), and refer to each from a page as `/_files/<name>`:
482
- `_site-files/cover.webp` is `/_files/cover.webp`. A name is letters, digits,
511
+ with `--files <folder>`), and show each with `useFileUrl("<name>")`, which is
512
+ `/_files/<name>` at the published address and, in Alma's frame (which reaches
513
+ no network), a blob: URL of the bytes the host hands over; Markdown's
514
+ `![…](/_files/<name>)` does the same. In the frame an `<img>`, `<audio>`,
515
+ `<video>` or `<source>` written with `src="/_files/<name>"`, and a stylesheet's
516
+ `url(/_files/<name>)` (a font's `@font-face`, a background), are pointed at the
517
+ same bytes, so the screens look the same in both places; a `Link` to
518
+ `/_files/<name>`, or to a declared plain file, saves the file there.
519
+ `_site-files/cover.webp` is `useFileUrl("cover.webp")`. A name is letters, digits,
483
520
  dots, dashes and underscores, and a folder inside the folder is refused. The
484
521
  types are `png`, `jpg`, `jpeg`, `gif`, `webp`, `avif`, `ico`, `woff2`, `woff`,
485
522
  `ttf`, `otf`, `pdf`, `mp3`, `m4a`, `aac`, `ogg`, `oga`, `opus`, `wav`, `weba`
@@ -499,21 +536,29 @@ machine), take its entry out and push again.
499
536
  npx alma-app push ./app --files ./_site-files --org <organization id>
500
537
  ```
501
538
 
502
- Sharing a version that has a site with "Anyone on the internet" needs a
503
- workspace owner's approval, like every change to what it serves.
539
+ Publishing a version follows the workspace's approval level for sharing apps;
540
+ going public counts as widening who sees it.
504
541
 
505
542
  ## Developing an app
506
543
 
507
544
  The package carries the `alma-app` command, which runs under Node.
508
545
  `npx alma-app dev [folder] --app <app id>` (or `bunx`) pushes the folder's
509
- source (`manifest.json` beside `index.html`, and the `.tsx`, `.ts`, `.jsx`,
510
- `.js`, `.mjs`, `.css`, `.html`, `.svg` and `.json` files around it, leaving out
511
- `node_modules`, `dist`, `build`, dotfiles and lockfiles) as a new draft version
546
+ source (`manifest.json` beside `src/`, and the `.tsx`, `.ts`, `.jsx`,
547
+ `.js`, `.mjs`, `.css`, `.html`, `.svg`, `.json`, `.md` and `.txt` files around
548
+ it, leaving out `node_modules`, `dist`, `build`, dotfiles and lockfiles) as a
549
+ new draft version
512
550
  now and on every save, signed in as you in the browser; Alma builds it and your
513
551
  draft moves to it. `npx alma-app push` pushes once. Without `--app` the first
514
552
  push starts a new app; a member of several workspaces names one with
515
553
  `--org <organization id>`.
516
554
 
555
+ An app written as one page (`index.html` loading its own script) becomes an
556
+ app with screens with `npx alma-app convert [folder]`: the page's body and
557
+ scripts become the one members' route, on Alma's look as before, and the
558
+ manifest names `screens.entry`. An inline or outside script, or a head element
559
+ other than the title and the page's own stylesheets, is not carried over:
560
+ the command names each and changes nothing.
561
+
517
562
  While you have your own app open, what it logs (`console`) and every error it
518
563
  does not catch show in its Manage sheet, under Logs, beside how the workflows it
519
564
  starts last ran. Only your own sessions are heard: what an app logs can carry
package/app.d.ts ADDED
@@ -0,0 +1,297 @@
1
+ /** The literal every absolute URL is written with at build time. A build
2
+ * does not know where its app will be published; publishing replaces this
3
+ * in every text file with the address's own origin. */
4
+ export declare const SITE_ORIGIN_TOKEN = "__ALMA_SITE_ORIGIN__";
5
+ /** The id `assetsFor` and a route's hydration data name the not-found
6
+ * screen by. Every route is named by its `path`, which starts with `/`. */
7
+ export declare const NOT_FOUND_ROUTE_ID = "404";
8
+ /** Where an app is running: inside Alma's frame for a member, or at its
9
+ * published address for anyone. */
10
+ export type AppPlace = "frame" | "public";
11
+ /** Who a route is for: `members` in Alma's frame only, `public` at the
12
+ * published address only. A route that names neither is in both. */
13
+ export type RouteAudience = "members" | "public";
14
+ /** A route's parameters, by the names its `path` gives them (`:slug`). */
15
+ export type RouteParams = Record<string, string>;
16
+ export type JsonValue = string | number | boolean | null | JsonValue[] | {
17
+ [key: string]: JsonValue;
18
+ };
19
+ export type JsonLd = {
20
+ [key: string]: JsonValue;
21
+ };
22
+ /** A title and description shown where a page is shared, when they are not
23
+ * the page's own. */
24
+ export interface SharedText {
25
+ title?: string;
26
+ description?: string;
27
+ }
28
+ /** What one route says about itself in its published document's head. */
29
+ export interface RouteMeta {
30
+ title: string;
31
+ /** The title shown as it is, without the app's `titleTemplate`. */
32
+ absoluteTitle?: boolean;
33
+ description?: string;
34
+ /** The route's own address (a path), when it is not the address it was
35
+ * served at. */
36
+ canonical?: string;
37
+ /** A path on the published address (`/_files/cover.png`) or an absolute
38
+ * https URL. */
39
+ image?: string;
40
+ imageAlt?: string;
41
+ /** Open Graph `og:type`; `website` unless said. */
42
+ type?: "website" | "article";
43
+ /** What Open Graph shows, where it is not the route's title, description
44
+ * and image (or the app's `openGraph`). */
45
+ openGraph?: SharedText & {
46
+ image?: string;
47
+ };
48
+ /** What X shows, where it is not the route's title and description (or
49
+ * the app's `x`). */
50
+ x?: SharedText;
51
+ /** Kept out of search engines and the sitemap. */
52
+ noindex?: boolean;
53
+ jsonLd?: JsonLd | JsonLd[];
54
+ }
55
+ /** What the whole app says about itself at its published address, beneath
56
+ * every route's own meta. */
57
+ export interface AppMeta {
58
+ name: string;
59
+ description?: string;
60
+ /** The document's `lang`; `en` unless said. */
61
+ lang?: string;
62
+ /** Open Graph `og:locale`, such as `en_US`. */
63
+ locale?: string;
64
+ /** How a route's title is shown, with `%s` where it goes. Without one a
65
+ * route's title is used as it is. */
66
+ titleTemplate?: string;
67
+ /** The image a route without its own shares with, and its size in
68
+ * pixels. */
69
+ image?: string;
70
+ imageAlt?: string;
71
+ imageWidth?: number;
72
+ imageHeight?: number;
73
+ /** What Open Graph and X show for a route that gives none of its own:
74
+ * without these, the route's title and description. */
75
+ openGraph?: SharedText;
76
+ x?: SharedText;
77
+ /** The app's account on X, such as `@alma`. */
78
+ twitter?: string;
79
+ /** One icon, or one for each colour scheme. */
80
+ favicon?: string | {
81
+ light: string;
82
+ dark: string;
83
+ };
84
+ themeColor?: string | {
85
+ light: string;
86
+ dark: string;
87
+ };
88
+ /** Addresses search engines are asked not to crawl. */
89
+ robots?: {
90
+ disallow?: string[];
91
+ };
92
+ jsonLd?: JsonLd | JsonLd[];
93
+ }
94
+ /** What a route's component is rendered with. */
95
+ export interface RouteProps<D = unknown> {
96
+ params: RouteParams;
97
+ data: D;
98
+ path: string;
99
+ }
100
+ export type RouteComponent<D = unknown> = {
101
+ bivarianceHack(props: RouteProps<D>): unknown;
102
+ }["bivarianceHack"];
103
+ export type AppLayout = {
104
+ bivarianceHack(props: {
105
+ children: unknown;
106
+ path: string;
107
+ }): unknown;
108
+ }["bivarianceHack"];
109
+ export interface RouteMetaContext<D = unknown> {
110
+ params: RouteParams;
111
+ data: D;
112
+ /** The address being described. */
113
+ path: string;
114
+ app: AppMeta;
115
+ }
116
+ export interface SitemapOptions {
117
+ changeFrequency?: "always" | "hourly" | "daily" | "weekly" | "monthly" | "yearly" | "never";
118
+ /** From 0 to 1. */
119
+ priority?: number;
120
+ /** An ISO 8601 date. */
121
+ lastModified?: string;
122
+ }
123
+ export interface AppRoute<D = unknown> {
124
+ /** `/`, `/about`, or a pattern with parameters such as `/blog/:slug`. */
125
+ path: string;
126
+ /** Who the route is for; members and the public both unless said. A
127
+ * route is not routable where its audience is not: a `members` route
128
+ * is never built at the published address, and a `public` one is not
129
+ * in Alma's frame. */
130
+ audience?: RouteAudience;
131
+ /** The route's own module, split from every other route's at the
132
+ * published address. */
133
+ component(): Promise<{
134
+ default: RouteComponent<D>;
135
+ }>;
136
+ /** Every parameter set a pattern is published at. A public route with
137
+ * parameters must list them: an address no route lists is not built.
138
+ * In Alma's frame every address that fits the pattern is the route's. */
139
+ addresses?(): RouteParams[] | Promise<RouteParams[]>;
140
+ /** The route's data, read when its public address is built, and in the
141
+ * browser whenever a person moves to it. It must be plain JSON. */
142
+ load?(params: RouteParams): D | Promise<D>;
143
+ /** The route's document head at the published address, which a public
144
+ * route must have. */
145
+ meta?(context: RouteMetaContext<D>): RouteMeta;
146
+ /** Left out of the sitemap with `false`; listed by default. */
147
+ sitemap?: boolean | SitemapOptions;
148
+ }
149
+ /** The statuses a redirect may answer with: 301 and 308 for a permanent
150
+ * move, 302 and 307 for a temporary one. */
151
+ export declare const SITE_REDIRECT_STATUSES: readonly [301, 302, 307, 308];
152
+ /** A move. `from` is one address, or a prefix ending `/*` that moves the
153
+ * prefix itself and every address under it. `to` is one address of this
154
+ * app or an absolute https URL, used as it is. */
155
+ export interface SiteRedirect {
156
+ from: string;
157
+ to: string;
158
+ status: (typeof SITE_REDIRECT_STATUSES)[number];
159
+ }
160
+ export interface SiteFont {
161
+ /** A path on the published address, such as `/_files/inter.woff2`. */
162
+ href: string;
163
+ /** `font/woff2` unless said. */
164
+ type?: string;
165
+ }
166
+ /** A plain file the published address serves, by its path (`llms.txt`). */
167
+ export type SiteFile = string | ((context: {
168
+ origin: string;
169
+ app: AppMeta;
170
+ }) => string | Promise<string>);
171
+ /** One app's screens, which `src/app.tsx` default-exports. Members see the
172
+ * routes for them in Alma's frame; visitors see the public ones at the
173
+ * published address, each prerendered. `meta`, `themeScript`, `fonts`,
174
+ * `files` and `embeds` describe the published address alone. */
175
+ export interface AppDefinition {
176
+ routes: AppRoute[];
177
+ /** Wraps every route, the not-found screen included. */
178
+ layout?: AppLayout;
179
+ /** The screen shown at an address no route has. */
180
+ notFound?: {
181
+ component(): Promise<{
182
+ default: RouteComponent<null>;
183
+ }>;
184
+ meta?: RouteMeta;
185
+ };
186
+ redirects?: SiteRedirect[];
187
+ /** The published address's name and head; an app needs it to publish. */
188
+ meta?: AppMeta;
189
+ /** Run first in every published document's head, before anything
190
+ * paints, to set the colour scheme. Without one it is
191
+ * `DEFAULT_THEME_SCRIPT`. */
192
+ themeScript?: string;
193
+ /** Fonts every published document preloads. */
194
+ fonts?: SiteFont[];
195
+ files?: Record<string, SiteFile>;
196
+ /** Origins the published routes may frame, such as
197
+ * `https://calendar.google.com`. */
198
+ embeds?: string[];
199
+ }
200
+ /** Sets `<html data-theme>` from the visitor's saved choice
201
+ * (`localStorage["alma-site-theme"]`) or their system's scheme. */
202
+ export declare const DEFAULT_THEME_SCRIPT: string;
203
+ export declare function defineApp(app: AppDefinition): AppDefinition;
204
+ /** A route whose `load`, component and `meta` share one data type. */
205
+ export declare function defineRoute<D>(route: AppRoute<D>): AppRoute;
206
+ /** The app as it is in `place`: only the routes whose audience is there. */
207
+ export declare function appIn(app: AppDefinition, place: AppPlace): AppDefinition;
208
+ /** Thrown from a route's `load`: this address has no route. */
209
+ export declare function notFound(): Error;
210
+ export declare function isNotFound(error: unknown): boolean;
211
+ /** Why `address` is not a clean address (`/` or `/a/b`: no trailing slash,
212
+ * no empty, dot or `index.html` segment, no query or fragment), or null. */
213
+ export declare function siteAddressProblem(address: string): string | null;
214
+ /** The parameters `address` gives `pattern`, or null where it does not fit. */
215
+ export declare function matchPattern(pattern: string, address: string): RouteParams | null;
216
+ /** The address a pattern makes with `params`, each value encoded. */
217
+ export declare function fillPattern(pattern: string, params: RouteParams): string;
218
+ /** The redirect that moves `address`, as the edge applies them: one whose
219
+ * `from` is the address itself first, then the longest `/*` prefix that
220
+ * is the address or one of its parents. */
221
+ export declare function matchRedirect(redirects: readonly SiteRedirect[], address: string): SiteRedirect | null;
222
+ export type AddressMatch<R extends {
223
+ path: string;
224
+ } = AppRoute> = {
225
+ kind: "route";
226
+ route: R;
227
+ params: RouteParams;
228
+ } | {
229
+ kind: "redirect";
230
+ redirect: SiteRedirect;
231
+ };
232
+ /** What an app shows at `address` among the routes it is given (one
233
+ * place's, from `appIn`): a route and its parameters, a redirect, or null
234
+ * for its not-found screen. A route whose path is the address, and a
235
+ * redirect from exactly the address, are one key at the edge and so come
236
+ * first (an app may not have both); then a route whose pattern fits, a
237
+ * static segment winning over a parameter; then a `/*` redirect.
238
+ *
239
+ * The edge holds only the addresses the build listed. Given them as
240
+ * `listed`, a route with parameters fits only an address it listed, and
241
+ * any other falls through to the redirects, so the answer is the edge's
242
+ * own. Without them, every address that fits a pattern is that route's. */
243
+ export declare function matchAddress<R extends {
244
+ path: string;
245
+ }>(app: {
246
+ routes: readonly R[];
247
+ redirects?: readonly SiteRedirect[];
248
+ }, address: string, listed?: ReadonlySet<string>): AddressMatch<R> | null;
249
+ export interface ListedAddress {
250
+ route: AppRoute;
251
+ params: RouteParams;
252
+ address: string;
253
+ }
254
+ /** Every address the given routes list (one place's, from `appIn`), in
255
+ * their order: a route without parameters at its path, one with them at
256
+ * each parameter set its `addresses` gives. Throws when an address is not
257
+ * clean, is listed twice, or would be served by another route or a
258
+ * redirect. */
259
+ export declare function listAddresses(app: Pick<AppDefinition, "routes" | "redirects">): Promise<ListedAddress[]>;
260
+ /** The content type a declared plain file is served with, or null for an
261
+ * extension the published address cannot declare. */
262
+ export declare function siteFileContentType(path: string): string | null;
263
+ /** Everything wrong with an app's definition that can be told without
264
+ * running it, each as a sentence, for the places named (both unless
265
+ * said). Empty when there is nothing. */
266
+ export declare function appDefinitionProblems(app: AppDefinition, places?: readonly AppPlace[]): string[];
267
+ /** Whether `address` is one of the app's declared plain files rather than
268
+ * a route: `/llms.txt` for `llms.txt`, `/manifesto` for
269
+ * `manifesto/index.html`. The edge serves it as its own document, so
270
+ * moving there is a page load. */
271
+ export declare function isSiteFileAddress(app: Pick<AppDefinition, "files">, address: string): boolean;
272
+ /** Where a route's address is written in the published output. */
273
+ export declare function outputPathOf(address: string): string;
274
+ /** `path` made absolute on `origin`; an absolute URL is kept as it is. */
275
+ export declare function absoluteUrl(origin: string, path: string): string;
276
+ export declare function escapeHtml(text: string): string;
277
+ /** JSON safe inside a `<script>` data block: nothing in it can close the
278
+ * element or end a line in a script. */
279
+ export declare function scriptJson(value: unknown): string;
280
+ /** A route's title as the published address shows it. */
281
+ export declare function pageTitle(app: AppMeta, meta: RouteMeta): string;
282
+ /** The tags a published document's head carries for what its route says
283
+ * about itself: title, description, canonical, Open Graph, X, JSON-LD,
284
+ * icons, theme colour and font preloads. Every URL in them is absolute on
285
+ * `origin`. */
286
+ export declare function buildDocumentHead(input: {
287
+ app: AppMeta;
288
+ meta: RouteMeta;
289
+ address: string;
290
+ origin: string;
291
+ fonts?: readonly SiteFont[];
292
+ }): string;
293
+ export interface SitemapEntry extends SitemapOptions {
294
+ address: string;
295
+ }
296
+ export declare function buildSitemap(origin: string, entries: readonly SitemapEntry[]): string;
297
+ export declare function buildRobots(origin: string, robots?: AppMeta["robots"]): string;