foldkit-ssr 0.8.2 → 0.9.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 +203 -69
- package/dist/client-F16QT0sc.d.ts +75 -0
- package/dist/client-F16QT0sc.d.ts.map +1 -0
- package/dist/client.d.ts +5 -0
- package/dist/client.js +271 -0
- package/dist/client.js.map +1 -0
- package/dist/context.d.ts +2 -0
- package/dist/context.js +21 -0
- package/dist/context.js.map +1 -0
- package/dist/diagnostics.d.ts +2 -0
- package/dist/diagnostics.js +59 -0
- package/dist/diagnostics.js.map +1 -0
- package/dist/{index.d.mts → index.d.ts} +18 -7
- package/dist/index.d.ts.map +1 -0
- package/dist/{index.mjs → index.js} +79 -60
- package/dist/index.js.map +1 -0
- package/dist/listen-zNd0IIAT.d.ts +69 -0
- package/dist/listen-zNd0IIAT.d.ts.map +1 -0
- package/dist/listen.d.ts +2 -0
- package/dist/listen.js +179 -0
- package/dist/listen.js.map +1 -0
- package/dist/requestContext-D9nsbGSJ.d.ts +21 -0
- package/dist/requestContext-D9nsbGSJ.d.ts.map +1 -0
- package/dist/requestContext.d.ts +2 -0
- package/dist/requestContext.js +48 -0
- package/dist/requestContext.js.map +1 -0
- package/dist/resumable-BWItJsxF.d.ts +86 -0
- package/dist/resumable-BWItJsxF.d.ts.map +1 -0
- package/dist/resumable.d.ts +2 -0
- package/dist/resumable.js +358 -0
- package/dist/resumable.js.map +1 -0
- package/dist/{client-DkwAniQQ.d.mts → shared-v1u-OEQI.d.ts} +218 -194
- package/dist/shared-v1u-OEQI.d.ts.map +1 -0
- package/dist/shared.d.ts +2 -0
- package/dist/shared.js +324 -0
- package/dist/shared.js.map +1 -0
- package/dist/{vite.d.mts → vite.d.ts} +3 -5
- package/dist/vite.d.ts.map +1 -0
- package/dist/{vite.mjs → vite.js} +3 -4
- package/dist/vite.js.map +1 -0
- package/package.json +17 -17
- package/dist/client-DVG9_3rL.mjs +0 -1113
- package/dist/client-DVG9_3rL.mjs.map +0 -1
- package/dist/client-DkwAniQQ.d.mts.map +0 -1
- package/dist/client.d.mts +0 -2
- package/dist/client.mjs +0 -1
- package/dist/index.d.mts.map +0 -1
- package/dist/index.mjs.map +0 -1
- package/dist/vite.d.mts.map +0 -1
- package/dist/vite.mjs.map +0 -1
package/README.md
CHANGED
|
@@ -13,6 +13,9 @@ pnpm add foldkit-ssr foldkit-surface foldkit effect
|
|
|
13
13
|
```
|
|
14
14
|
|
|
15
15
|
```ts
|
|
16
|
+
// In outline; `App`, `config` and `template` are the application's own, and
|
|
17
|
+
// [A first page](#a-first-page) splits this into its modules.
|
|
18
|
+
|
|
16
19
|
// Which part of the Model the browser owns.
|
|
17
20
|
const Post = SSR.plan(App, {
|
|
18
21
|
id: 'post',
|
|
@@ -59,8 +62,10 @@ It owns **the handover**: which slice crosses, how it is written into the page,
|
|
|
59
62
|
and the checks that the browser can start from it.
|
|
60
63
|
|
|
61
64
|
- **Rendering and adoption stay Foldkit's.** `SSR.render` calls Foldkit's
|
|
62
|
-
`renderToString` and `SSR.hydrate` calls `Runtime.hydrate
|
|
63
|
-
|
|
65
|
+
`renderToString` and `SSR.hydrate` calls `Runtime.hydrate`, which adopts the
|
|
66
|
+
server's nodes. `SSR.hydrate` compares the page's build id with its own
|
|
67
|
+
before it reads the envelope, so a Model serialized by another deployment is
|
|
68
|
+
never decoded.
|
|
64
69
|
- **The Model stays the application's.** A plan names fields of it; it adds no
|
|
65
70
|
state of its own, and every change after boot goes through `update`.
|
|
66
71
|
- **Data belongs to its package.** Remote's store crosses through Remote's own
|
|
@@ -180,7 +185,8 @@ boot: model => assembly.init(model).commands ?? []
|
|
|
180
185
|
A generated page styled with `foldkit-mixins` can ship the CSS its markup uses
|
|
181
186
|
in the head, so it is styled before any script runs. `head` is given the rendered
|
|
182
187
|
application; `Style.usedIn` returns the CSS of every compiled class the markup
|
|
183
|
-
carries
|
|
188
|
+
carries, with the global rules (keyframes, `raise`'s depth rules) of the Styles
|
|
189
|
+
those classes came from. In the browser, Styles bring their rules as they draw and skip what
|
|
184
190
|
this sheet already carries, so nothing is added twice.
|
|
185
191
|
|
|
186
192
|
```ts
|
|
@@ -193,9 +199,21 @@ const html = SSR.page(template, result, {
|
|
|
193
199
|
|
|
194
200
|
A served page has no template head to write to, so `SSR.render`, `SSR.entry`
|
|
195
201
|
and `SSR.handle` take the same function as `styles` instead, carried as the
|
|
196
|
-
rendered root's last child.
|
|
197
|
-
|
|
198
|
-
|
|
202
|
+
rendered root's last child. `foldkit-mixins/foundations` writes the theme
|
|
203
|
+
into `index.html` only, never into a page the server renders, so a served
|
|
204
|
+
page carries the theme's stylesheet here too, beside the classes it draws
|
|
205
|
+
(`examples/foldkit/ssr/src/renderPage.ts`):
|
|
206
|
+
|
|
207
|
+
```ts
|
|
208
|
+
const styles = (rendered: { readonly html: string }): string =>
|
|
209
|
+
`<style>${stylesheet}</style><style>${Style.usedIn(rendered.html)}</style>`
|
|
210
|
+
|
|
211
|
+
SSR.entry(config, plan, { buildId, styles })
|
|
212
|
+
```
|
|
213
|
+
|
|
214
|
+
Without it, every served page flashes unstyled until the script runs. Keep
|
|
215
|
+
`styles` to `<style>`: hydration adopts the nodes around it and drops it on
|
|
216
|
+
its first patch, and the browser's Styles skip what it already carries. A void root holds no children, so styles for one are
|
|
199
217
|
refused with `VoidRootWithStyles`, naming the tag. Anything a head owns
|
|
200
218
|
(`meta`, links) stays with `SSR.generate`.
|
|
201
219
|
|
|
@@ -271,6 +289,7 @@ export default {
|
|
|
271
289
|
```ts
|
|
272
290
|
// vite.config.ts, for the dev server and the build id both entries compile in.
|
|
273
291
|
import { foldkit } from '@foldkit/vite-plugin'
|
|
292
|
+
import { defineConfig } from 'vite'
|
|
274
293
|
|
|
275
294
|
export default defineConfig({
|
|
276
295
|
plugins: [foldkit({ ssr: { serverEntry: '/src/entry.server.ts' } })],
|
|
@@ -285,7 +304,22 @@ buildId: import.meta.env.FOLDKIT_BUILD_ID,
|
|
|
285
304
|
`FOLDKIT_BUILD_ID` names the deployment, from the environment: a commit or a
|
|
286
305
|
release tag, public and unique per deployment. The plugin compiles it into
|
|
287
306
|
both bundles; a script outside Vite, such as a prerender, reads
|
|
288
|
-
`process.env.FOLDKIT_BUILD_ID`, the same value the build saw.
|
|
307
|
+
`process.env.FOLDKIT_BUILD_ID`, the same value the build saw. With it unset,
|
|
308
|
+
`import.meta.env.FOLDKIT_BUILD_ID` is undefined in the client, and
|
|
309
|
+
`SSR.hydrate`, given no id, contains the page and reports why
|
|
310
|
+
([`PageContained`](#diagnostics), reason `NoBuildId`) rather than adopting it.
|
|
311
|
+
|
|
312
|
+
The client and the server must be built with one id. A page whose stamp is
|
|
313
|
+
not the client's is contained and reported as reason `OtherBuild`, naming both
|
|
314
|
+
ids. When nothing sets the variable and one `vite build` makes both bundles,
|
|
315
|
+
set it in `vite.config.ts` before `foldkit()` reads it, so every environment
|
|
316
|
+
of the build sees the same value (a script run after the build does not):
|
|
317
|
+
|
|
318
|
+
```ts
|
|
319
|
+
import { randomUUID } from 'node:crypto'
|
|
320
|
+
|
|
321
|
+
process.env.FOLDKIT_BUILD_ID ??= randomUUID()
|
|
322
|
+
```
|
|
289
323
|
|
|
290
324
|
Set it even though `@foldkit/vite-plugin` can now generate an id on its own.
|
|
291
325
|
The generated one is compiled into Foldkit alone, where `foldkit-ssr` cannot
|
|
@@ -298,8 +332,8 @@ Flags passes `flags: request => ...`. `POST` is handled only for a plan with a
|
|
|
298
332
|
[server fallback](#forms-that-work-without-scripts). `OPTIONS` is answered
|
|
299
333
|
`204` and any other method `405`, each with the methods the entry answers in
|
|
300
334
|
`allow`. A render that fails or throws, `flags` that reject, and a plan the
|
|
301
|
-
render refuses are answered `500` with the reason
|
|
302
|
-
the browser could not resume.
|
|
335
|
+
render refuses are answered `500` with the reason reported
|
|
336
|
+
([`PageFailed`](#diagnostics)), never with a page the browser could not resume.
|
|
303
337
|
|
|
304
338
|
`headers: request => ...` rides on the `Rendered` result, set over the host's
|
|
305
339
|
own: a cache policy for a page that is one visitor's, or the CORS answer to a
|
|
@@ -321,6 +355,60 @@ owns its template.
|
|
|
321
355
|
[foldkit#1448](https://github.com/foldkit/foldkit/issues/1448) asks Foldkit
|
|
322
356
|
for a per-request head channel beside the envelope.
|
|
323
357
|
|
|
358
|
+
### What the host hands the page: `SSR.requestContext`
|
|
359
|
+
|
|
360
|
+
`handleRequest` calls `renderPage(request)` and nothing more, and the
|
|
361
|
+
`fetch(request)` a build emits passes on no Worker's `env`. A page that reads
|
|
362
|
+
before it renders (`Data.satisfy`) needs what only the host holds: the
|
|
363
|
+
bindings, or a reader built from them. `SSR.requestContext` carries it on the
|
|
364
|
+
request. The host attaches a value, and `renderPage`, given the same request
|
|
365
|
+
by `handleRequest`, reads it back:
|
|
366
|
+
|
|
367
|
+
```ts
|
|
368
|
+
import { Effect, Option, type Layer } from 'effect'
|
|
369
|
+
import { Responded } from 'foldkit/experimental/server'
|
|
370
|
+
import type { RemoteClient, RemoteUnauthenticated } from 'foldkit-remote'
|
|
371
|
+
import { SSR } from 'foldkit-ssr'
|
|
372
|
+
|
|
373
|
+
// One module the host and the server entry both import.
|
|
374
|
+
export const PageContext = SSR.requestContext<{
|
|
375
|
+
readonly reader: Layer.Layer<RemoteClient, RemoteUnauthenticated>
|
|
376
|
+
}>('app/page')
|
|
377
|
+
|
|
378
|
+
// The host, a Worker's fetch say:
|
|
379
|
+
// pages.fetch(PageContext.attach(request, { reader: pageReader(page)(request, env) }))
|
|
380
|
+
|
|
381
|
+
// The server entry. `actives` is the record `Data.wiring` takes.
|
|
382
|
+
export const renderPage = (request: Request) =>
|
|
383
|
+
Option.match(PageContext.of(request), {
|
|
384
|
+
onNone: async () => Responded(new Response('No reader for this page.', { status: 500 })),
|
|
385
|
+
onSome: async ({ reader }) => {
|
|
386
|
+
const model = await Effect.runPromise(
|
|
387
|
+
Data.satisfy(App.initial, actives).pipe(Effect.provide(reader)),
|
|
388
|
+
)
|
|
389
|
+
return SSR.entry({ ...config, init: () => ({ model }) }, Post, { buildId }).renderPage(
|
|
390
|
+
request,
|
|
391
|
+
)
|
|
392
|
+
},
|
|
393
|
+
})
|
|
394
|
+
```
|
|
395
|
+
|
|
396
|
+
The value is kept for that request alone, in a `WeakMap` on `globalThis`
|
|
397
|
+
under a registered symbol, so a Worker's bundle and the page bundle Vite
|
|
398
|
+
built, each with its own copy of `foldkit-ssr`, find each other's values by
|
|
399
|
+
the context's name. Nothing outlives the request, and no request reads
|
|
400
|
+
another's. `of` is `Option.none()` for a request the host attached nothing
|
|
401
|
+
to: Vite's dev server builds its own `Request`, and a host that passes on a
|
|
402
|
+
copy (`new Request(request)`) drops it. A second value under one name on one
|
|
403
|
+
request throws. The value is not checked at run time: its type is the one the
|
|
404
|
+
shared module declares.
|
|
405
|
+
|
|
406
|
+
The reader is `pageReader` from `foldkit-remote-server/fetch`: the request's
|
|
407
|
+
Remote client, answered in the same process by the server `serveFetch`
|
|
408
|
+
serves. [`examples/auth`](../../examples/auth)'s `src/host.ts` is the whole
|
|
409
|
+
site behind one handler; its development server, another process, attaches
|
|
410
|
+
an HTTP reader instead.
|
|
411
|
+
|
|
324
412
|
### At build time
|
|
325
413
|
|
|
326
414
|
```ts
|
|
@@ -382,7 +470,10 @@ application code:
|
|
|
382
470
|
|
|
383
471
|
```ts
|
|
384
472
|
// vite.config.ts
|
|
473
|
+
import { foldkit } from '@foldkit/vite-plugin'
|
|
385
474
|
import { staticSite } from 'foldkit-ssr/vite'
|
|
475
|
+
import { defineConfig } from 'vite'
|
|
476
|
+
|
|
386
477
|
export default defineConfig({
|
|
387
478
|
plugins: [foldkit(), staticSite({ site: { module: '/src/site.ts' } })],
|
|
388
479
|
})
|
|
@@ -509,8 +600,9 @@ cannot attach a handler. The browser adopts the server's markup as it is and
|
|
|
509
600
|
never runs the render, so this plan sends neither `post.title` nor `post.body`
|
|
510
601
|
and the view check still passes. A region changes only with a new document;
|
|
511
602
|
content a Message should change belongs in a Surface. A region the browser
|
|
512
|
-
needs that is not in the page, say after a Message shows one, is
|
|
513
|
-
rendered in the
|
|
603
|
+
needs that is not in the page, say after a Message shows one, is reported
|
|
604
|
+
([`StaticRegionMissing`](#diagnostics), once per page) and rendered in the
|
|
605
|
+
browser.
|
|
514
606
|
|
|
515
607
|
### Markup the browser adopts: `SSR.serving`
|
|
516
608
|
|
|
@@ -628,7 +720,9 @@ boots it, so the Model ends where an eager boot would have taken it.
|
|
|
628
720
|
### Bundles whose code loads on demand
|
|
629
721
|
|
|
630
722
|
A `Bundle.lazy` from `foldkit-bundle` keeps a bundle's `update` and `view` out
|
|
631
|
-
of the boot chunk. Name each in the config's `lazy` list
|
|
723
|
+
of the boot chunk. Name each in the config's `lazy` list. A sketch, after
|
|
724
|
+
`test/lazyFixture.ts`: `Upload` is the lazy bundle, `PlacedUpload` its
|
|
725
|
+
placement, and `placements` their `Bundle.assemble`:
|
|
632
726
|
|
|
633
727
|
```ts
|
|
634
728
|
const config = {
|
|
@@ -655,7 +749,9 @@ wrapper variant, `Message.GotUploadMessage`.
|
|
|
655
749
|
|
|
656
750
|
A form whose `OnSubmit` names a Message can be answered by the server, before
|
|
657
751
|
any script has run or with scripts blocked, because `update` is pure and the
|
|
658
|
-
server can run it.
|
|
752
|
+
server can run it. This example is a to-do list, not the post page: its Model
|
|
753
|
+
holds `draft` and `todos`, its Message `Added({ title })` and `Typed({ value
|
|
754
|
+
})`, and the `TodoList` Surface lists both. The plan opts in:
|
|
659
755
|
|
|
660
756
|
```ts
|
|
661
757
|
const Todos = SSR.plan(App, {
|
|
@@ -717,11 +813,74 @@ runs `flags`, the config's `resources` and its own as whoever the cookie says
|
|
|
717
813
|
posted: an entry made without them throws. An entry of your own that calls
|
|
718
814
|
`SSR.handle` checks `Origin` itself.
|
|
719
815
|
|
|
816
|
+
## A reader's preferences in the first frame
|
|
817
|
+
|
|
818
|
+
A theme, a light or dark choice, a density: a reader expects the page to open
|
|
819
|
+
in what they chose, not in the default and then theirs. Under the rule above,
|
|
820
|
+
the first frame shows whatever the server knew when it rendered.
|
|
821
|
+
|
|
822
|
+
**Rendered per request, the server can know it, from a cookie.** It is the
|
|
823
|
+
[example's](../../examples/foldkit/ssr) count, by the same route:
|
|
824
|
+
|
|
825
|
+
```text
|
|
826
|
+
request cookie ─▶ flags ─▶ init ─▶ Model.theme ─┬─ view draws it
|
|
827
|
+
└─ plan.state carries it, so the browser resumes with it
|
|
828
|
+
```
|
|
829
|
+
|
|
830
|
+
```ts
|
|
831
|
+
import { Option, Record, Schema, pipe } from 'effect'
|
|
832
|
+
import { Cookies } from 'effect/http'
|
|
833
|
+
import { Theme, Themes } from 'foldkit-mixins/theme'
|
|
834
|
+
|
|
835
|
+
const themes = Themes.make(
|
|
836
|
+
{ plain: Theme.make({}), dense: Theme.make({ shape: { density: 0.85 } }) },
|
|
837
|
+
{ initial: 'plain' },
|
|
838
|
+
)
|
|
839
|
+
|
|
840
|
+
/** The kept theme for a request, or the initial one for a missing or unknown cookie. */
|
|
841
|
+
export const readThemeCookie = (cookieHeader: string) =>
|
|
842
|
+
pipe(
|
|
843
|
+
Cookies.parseHeader(cookieHeader),
|
|
844
|
+
Record.get('theme'),
|
|
845
|
+
Option.flatMap(Schema.decodeUnknownOption(themes.Name)),
|
|
846
|
+
Option.getOrElse(() => themes.initial),
|
|
847
|
+
)
|
|
848
|
+
```
|
|
849
|
+
|
|
850
|
+
Read it in `flags: request => …`, keep it in the plan's `state` (leaving it out
|
|
851
|
+
is refused: the view reads a field the browser would not have), and answer
|
|
852
|
+
with `cache-control: private` and `vary: cookie`, as the example does: such a
|
|
853
|
+
page is one reader's, and no shared cache may keep it.
|
|
854
|
+
|
|
855
|
+
What the view draws is then right in the first frame. What it cannot draw is
|
|
856
|
+
`<html>`: `Themes` shows a theme by an attribute there, and `color-scheme`
|
|
857
|
+
lives there. The view renders the application's root only, so:
|
|
858
|
+
|
|
859
|
+
- the host's template carries a head script, `Themes.script(themes)` (and
|
|
860
|
+
`Theme.schemeScript()`). It is static text, so a template that is the same
|
|
861
|
+
for every request holds it, and it reads the name the Command kept in
|
|
862
|
+
`localStorage`;
|
|
863
|
+
- the Command that keeps a choice keeps it twice, the cookie for the server
|
|
864
|
+
and storage for the script: `Themes.choose(themes, name)`, then
|
|
865
|
+
`document.cookie = 'theme=…; Path=/; Max-Age=31536000; SameSite=Lax'`
|
|
866
|
+
(`Secure` on HTTPS);
|
|
867
|
+
- the plan's `boot` applies the Model's theme (`Themes.apply`), so storage that
|
|
868
|
+
was refused or cleared costs one frame, not the visit.
|
|
869
|
+
|
|
870
|
+
**Generated at build time** (`SSR.generate`), there is no reader to ask, and
|
|
871
|
+
every page is built in the default. No change inside the application helps:
|
|
872
|
+
its script runs after the browser may have painted. The head script alone
|
|
873
|
+
draws the first frame, written through the generator's `head`; the Model
|
|
874
|
+
catches up in `boot`. `foldkit-mixins/theme` ships the pairs: `schemeScript`
|
|
875
|
+
and `chooseScheme`, `Themes.script` and `Themes.choose`, `Theme.knobScript`
|
|
876
|
+
and `Theme.chooseKnobs`.
|
|
877
|
+
|
|
720
878
|
## When a page is refused
|
|
721
879
|
|
|
722
880
|
A refusal never shows a user a half-working page. On the server it is an error
|
|
723
881
|
before anything is served; in the browser the page is contained, as Foldkit
|
|
724
|
-
contains a page from another build, and the reason is
|
|
882
|
+
contains a page from another build, and the reason is reported
|
|
883
|
+
([`PageContained`](#diagnostics)).
|
|
725
884
|
|
|
726
885
|
On the server, `SSR.render` fails with `ResumeUnsafe`, whose `reason` is one
|
|
727
886
|
of:
|
|
@@ -773,67 +932,38 @@ SSR.hydrate(config, plan, { buildId, when, otherwise: 'render', until: Site.answ
|
|
|
773
932
|
The served page stays as it was served while it waits: its links are plain
|
|
774
933
|
links, and nothing it shows becomes live.
|
|
775
934
|
|
|
776
|
-
##
|
|
935
|
+
## Diagnostics
|
|
777
936
|
|
|
778
|
-
|
|
779
|
-
|
|
780
|
-
|
|
937
|
+
What SSR meets and keeps going past, a page it contains or a request it
|
|
938
|
+
answers `500`, is a typed diagnostic, reported through `Diagnostics.Reporter`
|
|
939
|
+
(`foldkit-surface`'s channel, re-exported here), which by default is
|
|
940
|
+
Effect's log: the browser's console, or a server's or Worker's log.
|
|
781
941
|
|
|
782
|
-
|
|
783
|
-
|
|
942
|
+
| `_tag` | `level` | When |
|
|
943
|
+
| --------------------- | --------- | ------------------------------------------------------------------------------------------------------------- |
|
|
944
|
+
| `PageContained` | `error` | The browser contained the page instead of resuming it: `reason` is `NoBuildId`, `OtherBuild` or the `ResumeRefused` reason |
|
|
945
|
+
| `StaticRegionMissing` | `error` | A static region the browser drew is not in the server's page, so it was rendered in the browser (`region`) |
|
|
946
|
+
| `BundleUnloaded` | `error` | A lazy bundle's bodies did not load, and the page booted without them (`error`) |
|
|
947
|
+
| `PageFailed` | `error` | `SSR.entry` answered `500`: `headers` threw, or the page could not be rendered (`url`, `cause`) |
|
|
948
|
+
| `HandlerUnnamed` | `warning` | A handler the page cannot name keeps a page that waits to boot from answering it, once per process |
|
|
784
949
|
|
|
785
|
-
|
|
786
|
-
|
|
787
|
-
|
|
788
|
-
|
|
950
|
+
A page's refusals happen before any runtime starts, so the reporter in its
|
|
951
|
+
`resources` is not in effect yet: `SSR.hydrate` takes its own. `SSR.entry`
|
|
952
|
+
takes one with the request beside it, used for everything that request runs, a
|
|
953
|
+
posted form's Commands included. `SSR.generate` reports to the reporter in
|
|
954
|
+
its Effect's context.
|
|
789
955
|
|
|
790
956
|
```ts
|
|
791
|
-
|
|
792
|
-
import { Cookies } from 'effect/http'
|
|
793
|
-
import { Theme, Themes } from 'foldkit-mixins/theme'
|
|
957
|
+
SSR.hydrate(config, plan, { buildId, diagnostics: diagnostic => send(diagnostic) })
|
|
794
958
|
|
|
795
|
-
|
|
796
|
-
|
|
797
|
-
|
|
798
|
-
)
|
|
799
|
-
|
|
800
|
-
/** The kept theme for a request, or the initial one for a missing or unknown cookie. */
|
|
801
|
-
export const readThemeCookie = (cookieHeader: string) =>
|
|
802
|
-
pipe(
|
|
803
|
-
Cookies.parseHeader(cookieHeader),
|
|
804
|
-
Record.get('theme'),
|
|
805
|
-
Option.flatMap(Schema.decodeUnknownOption(themes.Name)),
|
|
806
|
-
Option.getOrElse(() => themes.initial),
|
|
807
|
-
)
|
|
959
|
+
SSR.entry(config, plan, {
|
|
960
|
+
buildId,
|
|
961
|
+
diagnostics: (diagnostic, request) =>
|
|
962
|
+
Effect.logError(`${request.method} ${request.url}: ${diagnostic.message}`),
|
|
963
|
+
})
|
|
808
964
|
```
|
|
809
965
|
|
|
810
|
-
|
|
811
|
-
is refused: the view reads a field the browser would not have), and answer
|
|
812
|
-
with `cache-control: private` and `vary: cookie`, as the example does: such a
|
|
813
|
-
page is one reader's, and no shared cache may keep it.
|
|
814
|
-
|
|
815
|
-
What the view draws is then right in the first frame. What it cannot draw is
|
|
816
|
-
`<html>`: `Themes` shows a theme by an attribute there, and `color-scheme`
|
|
817
|
-
lives there. The view renders the application's root only, so:
|
|
818
|
-
|
|
819
|
-
- the host's template carries a head script, `Themes.script(themes)` (and
|
|
820
|
-
`Theme.schemeScript()`). It is static text, so a template that is the same
|
|
821
|
-
for every request holds it, and it reads the name the Command kept in
|
|
822
|
-
`localStorage`;
|
|
823
|
-
- the Command that keeps a choice keeps it twice, the cookie for the server
|
|
824
|
-
and storage for the script: `Themes.choose(themes, name)`, then
|
|
825
|
-
`document.cookie = 'theme=…; Path=/; Max-Age=31536000; SameSite=Lax'`
|
|
826
|
-
(`Secure` on HTTPS);
|
|
827
|
-
- the plan's `boot` applies the Model's theme (`Themes.apply`), so storage that
|
|
828
|
-
was refused or cleared costs one frame, not the visit.
|
|
829
|
-
|
|
830
|
-
**Generated at build time** (`SSR.generate`), there is no reader to ask, and
|
|
831
|
-
every page is built in the default. No change inside the application helps:
|
|
832
|
-
its script runs after the browser may have painted. The head script alone
|
|
833
|
-
draws the first frame, written through the generator's `head`; the Model
|
|
834
|
-
catches up in `boot`. `foldkit-mixins/theme` ships the pairs: `schemeScript`
|
|
835
|
-
and `chooseScheme`, `Themes.script` and `Themes.choose`, `Theme.knobScript`
|
|
836
|
-
and `Theme.chooseKnobs`.
|
|
966
|
+
In a test, `Diagnostics.collect()` gives a reporter and the array it fills.
|
|
837
967
|
|
|
838
968
|
## Costs and limits
|
|
839
969
|
|
|
@@ -857,7 +987,8 @@ and `Theme.chooseKnobs`.
|
|
|
857
987
|
- **A closure handler makes its event wait for boot.** `SSR.render`'s result
|
|
858
988
|
lists each under `unnamed` (`{ element: 'button#point', event:
|
|
859
989
|
'pointerdown' }`), and on a page that waits to boot `SSR.entry` and
|
|
860
|
-
`SSR.generate`
|
|
990
|
+
`SSR.generate` report each once per process (`HandlerUnnamed`), naming
|
|
991
|
+
the fix.
|
|
861
992
|
|
|
862
993
|
## Lower-level API
|
|
863
994
|
|
|
@@ -888,7 +1019,8 @@ and `Theme.chooseKnobs`.
|
|
|
888
1019
|
A post page. `App` is `Surface.application({ Model, Message, initial, update
|
|
889
1020
|
})`. The Surfaces (`PostActions`, `Menu`, `Like`), `Data` (a `Remote.make`
|
|
890
1021
|
domain over `App.model.remote`) and `LoadPreferences` (a `Command.define`) are
|
|
891
|
-
the application's own
|
|
1022
|
+
the application's own; a Surface a resumable page dispatches from lists its
|
|
1023
|
+
Messages (`messages: [Message.Liked]`). `PostActionsAt` and `PostPageAt` are Surfaces placed
|
|
892
1024
|
for a plan, as `Surface.when(PostActions, App.model.route, AppRoute.Post, route
|
|
893
1025
|
=> ({ id: route.id }))` places one in
|
|
894
1026
|
[the coverage example](#checking-what-the-browser-will-read).
|
|
@@ -902,6 +1034,8 @@ const Model = Schema.Struct({
|
|
|
902
1034
|
id: Schema.String,
|
|
903
1035
|
title: Schema.String,
|
|
904
1036
|
body: Schema.String,
|
|
1037
|
+
excerpt: Schema.String,
|
|
1038
|
+
publishedAt: Schema.String,
|
|
905
1039
|
liked: Schema.Boolean,
|
|
906
1040
|
}),
|
|
907
1041
|
draft: Schema.String,
|
|
@@ -0,0 +1,75 @@
|
|
|
1
|
+
import { o as listen } from "./listen-zNd0IIAT.js";
|
|
2
|
+
import { m as view, p as builder } from "./resumable-BWItJsxF.js";
|
|
3
|
+
import { A as serving, D as resume, M as staticRegion, _ as bindings, c as ResumableConfig, u as ResumePlan, w as plan } from "./shared-v1u-OEQI.js";
|
|
4
|
+
import { Schema } from "effect";
|
|
5
|
+
import { Diagnostic as Diagnostic$1, Diagnostics as Diagnostics$1, ReportDiagnostic, ReportDiagnostic as ReportDiagnostic$1 } from "foldkit-surface";
|
|
6
|
+
/**
|
|
7
|
+
* Starts the browser from the page's resumed Model, without running `init`.
|
|
8
|
+
*
|
|
9
|
+
* In the order Foldkit checks a page: the build id first, before the payload
|
|
10
|
+
* is read, then the envelope and its route. A page from another build is
|
|
11
|
+
* refused by Foldkit itself. A page that cannot resume is refused and contained
|
|
12
|
+
* by Foldkit's own refusal, and the reason is reported (`options.diagnostics`). A server page is never
|
|
13
|
+
* rendered again on the client. A page with no server render at all, no
|
|
14
|
+
* stamped root, is rendered on the client as usual.
|
|
15
|
+
*/
|
|
16
|
+
declare const hydrate: <Model, Fields extends Schema.Struct.Fields, Message = any>(config: ResumableConfig<Model, Message>, plan: ResumePlan<Model, Fields>, options: {
|
|
17
|
+
readonly buildId: string;
|
|
18
|
+
/**
|
|
19
|
+
* Whether this page is taken over: asked before anything is adopted, so
|
|
20
|
+
* a page showing another reader's data never becomes live facts. Omitted
|
|
21
|
+
* adopts as before. Must not throw: a throwing predicate propagates out
|
|
22
|
+
* of `hydrate` with no runtime booted and nothing contained.
|
|
23
|
+
*/
|
|
24
|
+
readonly when?: ((page: Document) => boolean) | undefined;
|
|
25
|
+
/**
|
|
26
|
+
* What a declined or stale page does: `render` runs the application
|
|
27
|
+
* afresh where the rendered page is, replacing its markup in place (the
|
|
28
|
+
* config's container with no served page). Omitted contains the page the
|
|
29
|
+
* way a resume failure does.
|
|
30
|
+
*/
|
|
31
|
+
readonly otherwise?: 'render' | undefined;
|
|
32
|
+
/**
|
|
33
|
+
* With `otherwise: 'render'`, when the fresh application is ready to be
|
|
34
|
+
* seen: until a Model it has drawn satisfies this, it draws out of view
|
|
35
|
+
* and the served page stays, so a page is not swapped for its loading
|
|
36
|
+
* state and back. Omitted, the fresh application replaces the page at
|
|
37
|
+
* once. The served page stays no longer than `UNTIL_LIMIT_MS`.
|
|
38
|
+
*/
|
|
39
|
+
readonly until?: ((model: Model) => boolean) | undefined;
|
|
40
|
+
/**
|
|
41
|
+
* Whether the plan's data version is still current: asked once, with
|
|
42
|
+
* `plan.version`, before anything is adopted. Omitted never asks. A plan
|
|
43
|
+
* with no version still asks, with `undefined` (a check shaped like
|
|
44
|
+
* `version === expected` then marks every such page stale). Must not
|
|
45
|
+
* throw, as `when`.
|
|
46
|
+
*/
|
|
47
|
+
readonly fresh?: ((version: unknown) => boolean) | undefined;
|
|
48
|
+
/**
|
|
49
|
+
* Where what the page met goes: a page contained rather than resumed, a
|
|
50
|
+
* static region the server's page lacked, a lazy bundle that did not
|
|
51
|
+
* load. Each is reported before or apart from the runtime, so its
|
|
52
|
+
* resources' reporter is not in effect. Omitted, Effect's log: the
|
|
53
|
+
* browser's console.
|
|
54
|
+
*/
|
|
55
|
+
readonly diagnostics?: ReportDiagnostic | undefined;
|
|
56
|
+
}) => void;
|
|
57
|
+
/** The longest a served page stays in view while a fresh application waits for `until`. */
|
|
58
|
+
declare const UNTIL_LIMIT_MS = 3000;
|
|
59
|
+
/** The resumable track: bindings the server's markup names, so a page can answer before it boots. */
|
|
60
|
+
declare const Resume: {
|
|
61
|
+
builder: typeof builder;
|
|
62
|
+
view: typeof view;
|
|
63
|
+
bindings: typeof bindings;
|
|
64
|
+
listen: typeof listen;
|
|
65
|
+
};
|
|
66
|
+
/** The browser's part of `SSR`: the same functions, without the server's. */
|
|
67
|
+
declare const SSR: {
|
|
68
|
+
plan: typeof plan;
|
|
69
|
+
resume: typeof resume;
|
|
70
|
+
hydrate: typeof hydrate;
|
|
71
|
+
static: typeof staticRegion;
|
|
72
|
+
serving: typeof serving;
|
|
73
|
+
};
|
|
74
|
+
export { SSR as a, Resume as i, Diagnostics$1 as n, UNTIL_LIMIT_MS as o, ReportDiagnostic$1 as r, Diagnostic$1 as t };
|
|
75
|
+
//# sourceMappingURL=client-F16QT0sc.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"client-F16QT0sc.d.ts","names":[],"sources":["../src/client.ts"],"mappings":";;;;;;;;;;;;;;;cAoEM,UAAW,OAAO,eAAe,OAAO,OAAO,QAAQ,eAAa,QAChE,gBAAgB,OAAO,UAAQ,MACjC,WAAW,OAAO,SAAO;WAEpB;;;;;;;WAOA,SAAS,MAAM;;;;;;;WAOf;;;;;;;;WAQA,UAAU,OAAO;;;;;;;;WAQjB,UAAU;;;;;;;;WAQV,cAAc;;;cA8Gd;;cA+JA;;;;;;;cAGA"}
|
package/dist/client.d.ts
ADDED
|
@@ -0,0 +1,5 @@
|
|
|
1
|
+
import { n as DecodedBinding } from "./listen-zNd0IIAT.js";
|
|
2
|
+
import { a as FALLBACK_FIELD, l as ResumableBuilder, n as BINDING_ATTRIBUTE, u as SLOT_ATTRIBUTE } from "./resumable-BWItJsxF.js";
|
|
3
|
+
import { G as SsrDiagnostic, H as HandlerUnnamed, K as StaticRegionMissing, L as UnnamedHandler, U as PageContained, V as BundleUnloaded, W as PageFailed, c as ResumableConfig, d as ResumeRefused, i as Meta, l as ResumePart, m as Start, n as Loadable, o as PlanSurface, p as STATIC_ATTRIBUTE, r as META_ATTRIBUTE, s as RESUME_ATTRIBUTE, t as FOLDKIT_APP_ATTRIBUTE, u as ResumePlan, x as metaMarkup } from "./shared-v1u-OEQI.js";
|
|
4
|
+
import { a as SSR, i as Resume, n as Diagnostics, o as UNTIL_LIMIT_MS, r as ReportDiagnostic, t as Diagnostic } from "./client-F16QT0sc.js";
|
|
5
|
+
export { BINDING_ATTRIBUTE, type BundleUnloaded, type DecodedBinding, type Diagnostic, Diagnostics, FALLBACK_FIELD, FOLDKIT_APP_ATTRIBUTE, type HandlerUnnamed, type Loadable, META_ATTRIBUTE, type Meta, type PageContained, type PageFailed, type PlanSurface, RESUME_ATTRIBUTE, type ReportDiagnostic, type ResumableBuilder, type ResumableConfig, Resume, type ResumePart, type ResumePlan, ResumeRefused, SLOT_ATTRIBUTE, SSR, STATIC_ATTRIBUTE, type SsrDiagnostic, type Start, type StaticRegionMissing, UNTIL_LIMIT_MS, type UnnamedHandler, metaMarkup };
|