@almateam/app-sdk 0.9.0 → 0.11.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.11.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"],
@@ -357,6 +356,64 @@ const done = await alma.waitForExecution(run.id, {
357
356
  });
358
357
  ```
359
358
 
359
+ ### A workflow the app ships, started by its key
360
+
361
+ A workflow the app ships with (`workflows: [{ key, definition }]`, its
362
+ definition at `workflows/<key>.json` in the source) has no id until a version
363
+ creates it, and a copy of the app gets its own. To start it from the app's
364
+ pages, mark its entry `"startable": true` and declare the `workflows:run`
365
+ scope: the owners' share card then says "It starts when a member using the
366
+ app starts it from the app", and a version adding `startable` is a wider one.
367
+ Start it, and find its runs, by its key; `listWorkflows()` gives each one's
368
+ `key`. Only a key the version in use ships as startable starts anything: the
369
+ shared app the keys its shared version ships, a draft the keys the draft
370
+ ships, and any other key rejects as not found.
371
+
372
+ ```json
373
+ {
374
+ "scopes": ["topics:read", "workflows:run", "workflows:read"],
375
+ "workflows": [
376
+ { "key": "invite", "definition": "workflows/invite.json", "startable": true }
377
+ ]
378
+ }
379
+ ```
380
+
381
+ ```ts
382
+ const run = await alma.runWorkflow(
383
+ { key: "invite" },
384
+ { input: { email, name } }
385
+ );
386
+ const runs = await alma.listRuns({ key: "invite" });
387
+ ```
388
+
389
+ A step of a shipped workflow can act from the account of whoever starts the
390
+ run, such as the viewer's own Gmail, by naming its grant's key in `accounts`
391
+ with the value `"requester"` (the only value: any other account is set on the
392
+ workflow by hand). The key must be a named tool's, never a whole
393
+ integration's (`gmail:write` is refused):
394
+
395
+ ```json
396
+ {
397
+ "id": "s1",
398
+ "name": "Send the invitation",
399
+ "tool_config": {
400
+ "alma_gmail_send_email": { "recipients": { "kind": "anyone" } }
401
+ },
402
+ "accounts": { "alma_gmail_send_email": "requester" }
403
+ }
404
+ ```
405
+
406
+ Such a grant asks the person who started the run before each call: leave its
407
+ `approval` out or write `"actor"` (the account's owner); any other approval is
408
+ refused. Their card shows the call's input (an email's recipients, subject
409
+ and body) and offers the standing choices the gate would honour for them. The
410
+ viewer must have connected that integration themselves, or the run
411
+ fails before it starts work, saying it needs the connection. A run nobody
412
+ started (an event, a schedule, a visitor) has nobody to act as, so its call is
413
+ refused. Adding or changing `accounts` is a wider version an owner approves:
414
+ the card reads "Its steps may send email to anyone from the Gmail of whoever
415
+ starts it, each time after they approve."
416
+
360
417
  An attachment download returns only a receipt (`attachment_id`, `filename`,
361
418
  `status`): the host fetches the file itself, and neither its URL nor the session
362
419
  token reaches the app.
@@ -389,18 +446,20 @@ try {
389
446
  }
390
447
  ```
391
448
 
392
- ## Publishing an app to the web
449
+ ## Screens: one app in Alma and on the web
393
450
 
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`:
451
+ An app is one module, `src/app.tsx` (or the module the manifest names in
452
+ `screens: { entry }`), that default-exports `defineApp`. Members see its
453
+ routes in Alma's frame; published, anyone sees them at
454
+ `<name>.sites.alma.team`, with no sign-in and no Alma around them. It is the
455
+ same source in both places:
397
456
 
398
457
  ```tsx
399
- import { defineSite, definePage } from "@alma/app-sdk";
458
+ import { defineApp, defineRoute } from "@alma/app-sdk";
400
459
  import { Frame } from "./Frame";
401
460
  import { posts } from "./posts";
402
461
 
403
- export default defineSite({
462
+ export default defineApp({
404
463
  meta: {
405
464
  name: "Field Notes",
406
465
  description: "Notes from the field.",
@@ -408,13 +467,14 @@ export default defineSite({
408
467
  favicon: { light: "/_files/icon.png", dark: "/_files/icon-dark.png" },
409
468
  },
410
469
  layout: Frame,
411
- pages: [
470
+ routes: [
412
471
  {
413
472
  path: "/",
414
473
  component: () => import("./pages/Home"),
415
474
  meta: () => ({ title: "Home" }),
416
475
  },
417
- definePage({
476
+ { path: "/desk", audience: "members", component: () => import("./Desk") },
477
+ defineRoute({
418
478
  path: "/notes/:slug",
419
479
  addresses: () => posts.map((post) => ({ slug: post.slug })),
420
480
  load: ({ slug }) => posts.find((post) => post.slug === slug)!,
@@ -428,35 +488,63 @@ export default defineSite({
428
488
  });
429
489
  ```
430
490
 
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
491
+ A route is for members and the public both, unless its `audience` says
492
+ `members` (only in Alma: never built at the published address) or `public`
493
+ (only there). One path may be a members' screen and a public one. `meta`,
494
+ `themeScript`, `fonts`, `files` and `embeds` describe the published address;
495
+ an app that only members see needs none of them.
496
+
497
+ Published, Alma builds every address of every public route to its own HTML
498
+ document when it builds the version: a route with parameters (`:slug`) is
499
+ built at each address its `addresses` lists, and only there (in Alma, every
500
+ address that fits is the route's). `load` runs then, and again in the browser
501
+ when a person moves to the route, so it returns plain JSON. Each public route
435
502
  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.
503
+ `meta`, which it must have, and the site gets `sitemap.xml`, `robots.txt` and
504
+ a `404.html` (`notFound`, or a plain one). An address names a route without a
505
+ trailing slash; where a static segment and a parameter could both fit, the
506
+ static one wins. A redirect's `from` is one address or a prefix ending `/*`,
507
+ which moves the prefix itself and everything under it; an address a route
508
+ lists is served by the route. `throw notFound()` from `load` shows the
509
+ not-found screen.
510
+
511
+ Alma's build starts the app with `startApp` from the kit: at the published
512
+ address it takes up the page the build rendered, over the site's transport
513
+ and the browser's history; in Alma's frame it renders the route at the
514
+ host's address, over the host's transport and history. Either way it moves
515
+ between routes without loading a document.
447
516
 
448
517
  ```tsx
449
- import { Link, Markdown, useAlma, usePath, useSite } from "@alma/app-ui/site";
518
+ import {
519
+ Link,
520
+ Markdown,
521
+ useAlma,
522
+ useApp,
523
+ useFileUrl,
524
+ usePath,
525
+ } from "@alma/app-ui";
450
526
  ```
451
527
 
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.
528
+ `Link` moves within the app; to anywhere else it is an ordinary link at the
529
+ published address, and in Alma the host opens it in a new tab when a person
530
+ clicks it (the frame never loads a document of its own). `usePath` and
531
+ `useApp` say where the person is, in which place (`frame` or `public`) and on
532
+ which origin, and `Markdown` draws a `.md` file's tokens. A capitalised tag in
533
+ the Markdown (`<Callout kind="note">`) is one of the app's components, passed
534
+ in `components`; a name it was not given, or any other HTML, fails the build.
535
+
536
+ Neither build adds anything of Alma's look to an app that does not ask, so a
537
+ member and a visitor see what the author wrote. To stand on Alma's (its
538
+ tokens, Geist, the accent and the kit's Theme knobs, beneath the app's own
539
+ CSS, and Alma's tokens on its Tailwind utilities), import it once, in both
540
+ places alike:
541
+
542
+ ```ts
543
+ import "@alma/app-ui/base.css";
544
+ ```
457
545
 
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;
546
+ In Alma, `useAlma()` is the member's SDK. A visitor is nobody Alma knows, so
547
+ at the published address it can only raise the events the version declares;
460
548
  `viewer()` and `shell()` answer null, and everything else rejects with
461
549
  `site.no_viewer`. Where an event's workflow answers the visitor, the raise
462
550
  returns a `result` ticket: `waitForResult(result.token)` reads the answer, and
@@ -476,10 +564,17 @@ try {
476
564
  }
477
565
  ```
478
566
 
479
- A site's pictures, fonts, PDFs and audio are files, not source. Put them in
567
+ An app's pictures, fonts, PDFs and audio are files, not source. Put them in
480
568
  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,
569
+ with `--files <folder>`), and show each with `useFileUrl("<name>")`, which is
570
+ `/_files/<name>` at the published address and, in Alma's frame (which reaches
571
+ no network), a blob: URL of the bytes the host hands over; Markdown's
572
+ `![…](/_files/<name>)` does the same. In the frame an `<img>`, `<audio>`,
573
+ `<video>` or `<source>` written with `src="/_files/<name>"`, and a stylesheet's
574
+ `url(/_files/<name>)` (a font's `@font-face`, a background), are pointed at the
575
+ same bytes, so the screens look the same in both places; a `Link` to
576
+ `/_files/<name>`, or to a declared plain file, saves the file there.
577
+ `_site-files/cover.webp` is `useFileUrl("cover.webp")`. A name is letters, digits,
483
578
  dots, dashes and underscores, and a folder inside the folder is refused. The
484
579
  types are `png`, `jpg`, `jpeg`, `gif`, `webp`, `avif`, `ico`, `woff2`, `woff`,
485
580
  `ttf`, `otf`, `pdf`, `mp3`, `m4a`, `aac`, `ogg`, `oga`, `opus`, `wav`, `weba`
@@ -499,16 +594,50 @@ machine), take its entry out and push again.
499
594
  npx alma-app push ./app --files ./_site-files --org <organization id>
500
595
  ```
501
596
 
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.
597
+ Publishing a version follows the workspace's approval level for sharing apps;
598
+ going public counts as widening who sees it.
599
+
600
+ ### Sharing one record by private link
601
+
602
+ A member can hand one of the app's own records to someone outside Alma, who
603
+ reads it on the app's website without signing in. The app declares the
604
+ `records:share` scope (the share card says "People using this app can share
605
+ one of its records by private link"), and the record's type is one `public`
606
+ reads by its private link (`"read": "own"`), whose `fields` are all the link
607
+ shows. Inside Alma:
608
+
609
+ ```ts
610
+ const { url } = await alma.issueRecordLink(snapshot.id, { path: "/report" });
611
+ showCopyableLink(url); // https://<address>/report#<token>
612
+ await alma.revokeRecordLink(snapshot.id); // the link stops working at once
613
+ ```
614
+
615
+ `path` is one of the app's public pages; that page reads the record with
616
+ `alma.ownEntry()`, as a visitor's page reads their own entry. The member must
617
+ be able to edit the record, and it must have been made in the app they are
618
+ using: a link made in their draft opens only the draft's private preview.
619
+ Issuing again replaces the link. The `url` is for the member alone: show it so
620
+ they can copy or send it, and never keep it in a record, app state or anything
621
+ a workflow reads. It rejects with `link.no_address` (the app is not on the
622
+ web), `link.not_public`, `link.not_a_page`, `link.visitor_entry` (a visitor's
623
+ own entry already has their link), `link.cannot_edit` or `link.rate_limited` (past 30 links an hour), and with
624
+ `site.no_viewer` at a published address.
625
+
626
+ A link shows only values a person wrote. A value a workflow worked out from
627
+ other records (a report over many entries) is never shown on the web. To share
628
+ such a result, publish a snapshot: on the member's own action, the app writes
629
+ the content into a record of the linked type as the member (`createTopic`,
630
+ `setTopicField`), then issues the link to that record. When the result
631
+ changes, write the snapshot again and issue a new link.
504
632
 
505
633
  ## Developing an app
506
634
 
507
635
  The package carries the `alma-app` command, which runs under Node.
508
636
  `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
637
+ source (`manifest.json` beside `src/`, and the `.tsx`, `.ts`, `.jsx`,
638
+ `.js`, `.mjs`, `.css`, `.html`, `.svg`, `.json`, `.md` and `.txt` files around
639
+ it, leaving out `node_modules`, `dist`, `build`, dotfiles and lockfiles) as a
640
+ new draft version
512
641
  now and on every save, signed in as you in the browser; Alma builds it and your
513
642
  draft moves to it. `npx alma-app push` pushes once. Without `--app` the first
514
643
  push starts a new app; a member of several workspaces names one with
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;
package/cli.js CHANGED
@@ -12,7 +12,7 @@ import { join as join3 } from "node:path";
12
12
  // src/cli/project.ts
13
13
  import { readdir, readFile } from "node:fs/promises";
14
14
  import { join, relative, sep } from "node:path";
15
- var SOURCE_FILE = /\.(?:tsx|ts|jsx|js|mjs|css|html|svg|json)$/;
15
+ var SOURCE_FILE = /\.(?:tsx|ts|jsx|js|mjs|css|html|svg|json|md|txt)$/;
16
16
  var LOCKFILES = new Set([
17
17
  "package-lock.json",
18
18
  "npm-shrinkwrap.json",
@@ -28,7 +28,7 @@ function isProjectPath(path) {
28
28
  }
29
29
  async function readProject(directory) {
30
30
  const manifestText = await readFile(join(directory, "manifest.json"), "utf8").catch(() => {
31
- throw new Error(`No manifest.json in ${directory}. An app's folder holds its manifest beside index.html.`);
31
+ throw new Error(`No manifest.json in ${directory}. An app's folder holds its manifest beside its source.`);
32
32
  });
33
33
  const manifest = JSON.parse(manifestText);
34
34
  if (typeof manifest !== "object" || manifest === null)
package/files.d.ts ADDED
@@ -0,0 +1,25 @@
1
+ /** The bridge question an app in Alma's frame asks for one of its own
2
+ * files, as an `alma:operation` (`{ type, id, operation, params, query,
3
+ * body: { name } }`). The host answers `alma:result` with the same `id`
4
+ * and `data: { name, media_type, bytes }`, `bytes` an `ArrayBuffer` of
5
+ * the whole file; or with `error` and a `code` (`AppFileRefusalCode`).
6
+ * Only a file of the app version the frame is running is ever answered. */
7
+ export declare const APP_FILE_QUESTION = "getAppFile";
8
+ /** What a host refuses an app file with: `file.not_found` (the version has
9
+ * no file by that name), `file.invalid_name` (not a file name), or
10
+ * `file.unavailable` (the host could not read it now; asking again may
11
+ * succeed). */
12
+ export type AppFileRefusalCode = "file.not_found" | "file.invalid_name" | "file.unavailable";
13
+ /** The host's answer to `APP_FILE_QUESTION`. */
14
+ export interface AppFileAnswer {
15
+ name: string;
16
+ media_type: string;
17
+ bytes: ArrayBuffer;
18
+ }
19
+ /** Whether `name` is one an uploaded file may have: letters, digits, dots,
20
+ * dashes and underscores, at most 128, starting with a letter or digit,
21
+ * with no `..`. The same rule the upload and the build hold names to. */
22
+ export declare function isAppFileName(name: unknown): name is string;
23
+ /** The file name an address on the published address names
24
+ * (`/_files/cover.png` is `cover.png`), or null. */
25
+ export declare function appFileNameOf(address: string): string | null;