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.
Files changed (50) hide show
  1. package/README.md +203 -69
  2. package/dist/client-F16QT0sc.d.ts +75 -0
  3. package/dist/client-F16QT0sc.d.ts.map +1 -0
  4. package/dist/client.d.ts +5 -0
  5. package/dist/client.js +271 -0
  6. package/dist/client.js.map +1 -0
  7. package/dist/context.d.ts +2 -0
  8. package/dist/context.js +21 -0
  9. package/dist/context.js.map +1 -0
  10. package/dist/diagnostics.d.ts +2 -0
  11. package/dist/diagnostics.js +59 -0
  12. package/dist/diagnostics.js.map +1 -0
  13. package/dist/{index.d.mts → index.d.ts} +18 -7
  14. package/dist/index.d.ts.map +1 -0
  15. package/dist/{index.mjs → index.js} +79 -60
  16. package/dist/index.js.map +1 -0
  17. package/dist/listen-zNd0IIAT.d.ts +69 -0
  18. package/dist/listen-zNd0IIAT.d.ts.map +1 -0
  19. package/dist/listen.d.ts +2 -0
  20. package/dist/listen.js +179 -0
  21. package/dist/listen.js.map +1 -0
  22. package/dist/requestContext-D9nsbGSJ.d.ts +21 -0
  23. package/dist/requestContext-D9nsbGSJ.d.ts.map +1 -0
  24. package/dist/requestContext.d.ts +2 -0
  25. package/dist/requestContext.js +48 -0
  26. package/dist/requestContext.js.map +1 -0
  27. package/dist/resumable-BWItJsxF.d.ts +86 -0
  28. package/dist/resumable-BWItJsxF.d.ts.map +1 -0
  29. package/dist/resumable.d.ts +2 -0
  30. package/dist/resumable.js +358 -0
  31. package/dist/resumable.js.map +1 -0
  32. package/dist/{client-DkwAniQQ.d.mts → shared-v1u-OEQI.d.ts} +218 -194
  33. package/dist/shared-v1u-OEQI.d.ts.map +1 -0
  34. package/dist/shared.d.ts +2 -0
  35. package/dist/shared.js +324 -0
  36. package/dist/shared.js.map +1 -0
  37. package/dist/{vite.d.mts → vite.d.ts} +3 -5
  38. package/dist/vite.d.ts.map +1 -0
  39. package/dist/{vite.mjs → vite.js} +3 -4
  40. package/dist/vite.js.map +1 -0
  41. package/package.json +17 -17
  42. package/dist/client-DVG9_3rL.mjs +0 -1113
  43. package/dist/client-DVG9_3rL.mjs.map +0 -1
  44. package/dist/client-DkwAniQQ.d.mts.map +0 -1
  45. package/dist/client.d.mts +0 -2
  46. package/dist/client.mjs +0 -1
  47. package/dist/index.d.mts.map +0 -1
  48. package/dist/index.mjs.map +0 -1
  49. package/dist/vite.d.mts.map +0 -1
  50. 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`. Foldkit still
63
- refuses a page from another build and still adopts the server's nodes.
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. In the browser, Styles bring their rules as they draw and skip what
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. Keep it to `<style>`: hydration adopts the nodes
197
- around it and drops it on its first patch, and the browser's Styles skip what
198
- it already carries. A void root holds no children, so styles for one are
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 logged, never with a page
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 logged and
513
- rendered in the browser.
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. The plan opts in:
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 logged.
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
- ## A reader's preferences in the first frame
935
+ ## Diagnostics
777
936
 
778
- A theme, a light or dark choice, a density: a reader expects the page to open
779
- in what they chose, not in the default and then theirs. Under the rule above,
780
- the first frame shows whatever the server knew when it rendered.
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
- **Rendered per request, the server can know it, from a cookie.** It is the
783
- [example's](../../examples/foldkit/ssr) count, by the same route:
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
- ```text
786
- request cookie ─▶ flags ─▶ init ─▶ Model.theme ─┬─ view draws it
787
- └─ plan.state carries it, so the browser resumes with it
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
- import { Option, Record, Schema, pipe } from 'effect'
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
- const themes = Themes.make(
796
- { plain: Theme.make({}), dense: Theme.make({ shape: { density: 0.85 } }) },
797
- { initial: 'plain' },
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
- Read it in `flags: request => …`, keep it in the plan's `state` (leaving it out
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` warn about each once per process, naming the fix.
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. `PostActionsAt` and `PostPageAt` are Surfaces placed
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"}
@@ -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 };