foldkit-ssr 0.9.0 → 0.10.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (39) hide show
  1. package/README.md +315 -36
  2. package/dist/{client-F16QT0sc.d.ts → client-XnpTQZHw.d.ts} +15 -5
  3. package/dist/client-XnpTQZHw.d.ts.map +1 -0
  4. package/dist/client.d.ts +5 -5
  5. package/dist/client.js +126 -54
  6. package/dist/client.js.map +1 -1
  7. package/dist/context.d.ts +1 -1
  8. package/dist/context.js +12 -0
  9. package/dist/context.js.map +1 -1
  10. package/dist/diagnostics.d.ts +1 -1
  11. package/dist/index.d.ts +83 -23
  12. package/dist/index.d.ts.map +1 -1
  13. package/dist/index.js +174 -54
  14. package/dist/index.js.map +1 -1
  15. package/dist/keep.d.ts +34 -0
  16. package/dist/keep.d.ts.map +1 -0
  17. package/dist/keep.js +80 -0
  18. package/dist/keep.js.map +1 -0
  19. package/dist/{listen-zNd0IIAT.d.ts → listen-DaUPRKVR.d.ts} +4 -2
  20. package/dist/listen-DaUPRKVR.d.ts.map +1 -0
  21. package/dist/listen.d.ts +2 -2
  22. package/dist/listen.js +31 -23
  23. package/dist/listen.js.map +1 -1
  24. package/dist/{resumable-BWItJsxF.d.ts → resumable-BPN_qQHU.d.ts} +33 -12
  25. package/dist/resumable-BPN_qQHU.d.ts.map +1 -0
  26. package/dist/resumable.d.ts +2 -2
  27. package/dist/resumable.js +51 -8
  28. package/dist/resumable.js.map +1 -1
  29. package/dist/{shared-v1u-OEQI.d.ts → shared-DbupL3vO.d.ts} +20 -5
  30. package/dist/shared-DbupL3vO.d.ts.map +1 -0
  31. package/dist/shared.d.ts +2 -2
  32. package/dist/shared.js +25 -2
  33. package/dist/shared.js.map +1 -1
  34. package/dist/vite.d.ts +1 -1
  35. package/package.json +9 -9
  36. package/dist/client-F16QT0sc.d.ts.map +0 -1
  37. package/dist/listen-zNd0IIAT.d.ts.map +0 -1
  38. package/dist/resumable-BWItJsxF.d.ts.map +0 -1
  39. package/dist/shared-v1u-OEQI.d.ts.map +0 -1
package/README.md CHANGED
@@ -70,6 +70,9 @@ and the checks that the browser can start from it.
70
70
  state of its own, and every change after boot goes through `update`.
71
71
  - **Data belongs to its package.** Remote's store crosses through Remote's own
72
72
  part (`Remote.resume`), which decides what to capture.
73
+ - **What the browser stored stays the browser's.** The server cannot read a
74
+ queue kept in `localStorage`, so it is never in the page: it joins after
75
+ the first frame ([`prepare`](#what-only-the-browser-has-prepare)).
73
76
 
74
77
  ## The mental model
75
78
 
@@ -199,7 +202,7 @@ const html = SSR.page(template, result, {
199
202
 
200
203
  A served page has no template head to write to, so `SSR.render`, `SSR.entry`
201
204
  and `SSR.handle` take the same function as `styles` instead, carried as the
202
- rendered root's last child. `foldkit-mixins/foundations` writes the theme
205
+ rendered root's last children. `foldkit-mixins/foundations` writes the theme
203
206
  into `index.html` only, never into a page the server renders, so a served
204
207
  page carries the theme's stylesheet here too, beside the classes it draws
205
208
  (`examples/foldkit/ssr/src/renderPage.ts`):
@@ -212,10 +215,14 @@ SSR.entry(config, plan, { buildId, styles })
212
215
  ```
213
216
 
214
217
  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
217
- refused with `VoidRootWithStyles`, naming the tag. Anything a head owns
218
- (`meta`, links) stays with `SSR.generate`.
218
+ `styles` to `<style>` and stylesheet `<link>`s. The view does not draw them,
219
+ so hydration would remove them from the root, and a page that never renders
220
+ again would keep its classes without their rules; `SSR.hydrate` moves them
221
+ into the document's head before anything adopts the page, whether it resumes
222
+ or is contained, and the browser's Styles find them there and add nothing
223
+ twice. A void root holds no children, so styles for one are refused with
224
+ `VoidRootWithStyles`, naming the tag. Anything else a head owns (`meta`)
225
+ stays with `SSR.generate`.
219
226
 
220
227
  `SSR.generate` takes the same `head`, and answers a `head` that throws `500`,
221
228
  as it does a render that fails. `SSR.entry` takes no `head`: the host owns
@@ -328,25 +335,68 @@ so a Model serialized by another deployment is never decoded. Asking Foldkit
328
335
  to expose that id is [proposal 4](../../docs/upstream-foldkit-ssr.md#proposal-4-expose-the-compiled-build-id).
329
336
 
330
337
  `GET` and `HEAD` render the page for the request's URL; an application with
331
- Flags passes `flags: request => ...`. `POST` is handled only for a plan with a
338
+ Flags passes `flags: request => ...`. `prepare: (model, request) => Effect`
339
+ turns the Model `init` gave into the one the page is rendered from, for what
340
+ must be read before the render (`Data.satisfy`, [below](#what-the-host-hands-the-page-ssrrequestcontext))
341
+ or taken from the request (a cookie). It runs for a posted form too, before
342
+ the Message is checked against the active Surfaces and `update` runs, so the
343
+ post starts from the Model the page it came from was drawn with, and one
344
+ entry, made once, serves every request. A `prepare` that fails is answered
345
+ `500` and reported; one that would rather draw the page unread recovers
346
+ inside its Effect. `POST` is handled only for a plan with a
332
347
  [server fallback](#forms-that-work-without-scripts). `OPTIONS` is answered
333
348
  `204` and any other method `405`, each with the methods the entry answers in
334
349
  `allow`. A render that fails or throws, `flags` that reject, and a plan the
335
350
  render refuses are answered `500` with the reason reported
336
351
  ([`PageFailed`](#diagnostics)), never with a page the browser could not resume.
337
352
 
338
- `headers: request => ...` rides on the `Rendered` result, set over the host's
339
- own: a cache policy for a page that is one visitor's, or the CORS answer to a
340
- preflight, which reaches the entry and not the host.
353
+ `headers: (request, model) => ...` is set over the host's own on every
354
+ answer: a cache policy for a page that is one visitor's, the CORS answer to a
355
+ preflight, which reaches the entry and not the host, or a cookie written from
356
+ the Model. `model` is an `Option`: `some` of the Model the server reached for
357
+ a rendered page (a posted form's, after `update`), `none` for an answer that
358
+ rendered nothing (`OPTIONS`, a `405`, a refused post, a `500`).
341
359
 
342
360
  ```ts
343
361
  SSR.entry(config, Post, {
344
362
  buildId,
345
- headers: () => ({ 'cache-control': 'private, no-store', vary: 'cookie' }),
363
+ headers: (_request, model) => ({
364
+ 'cache-control': 'private, no-store',
365
+ vary: 'cookie',
366
+ ...Option.match(model, {
367
+ onNone: () => ({}),
368
+ onSome: ({ post }) => ({
369
+ 'set-cookie': `last-read=${encodeURIComponent(post.id)}; Path=/; SameSite=Lax`,
370
+ }),
371
+ }),
372
+ }),
346
373
  })
347
374
  ```
348
375
 
349
- A `headers` that throws is answered `500`, as a failed render is.
376
+ A `headers` that throws is answered `500`, as a failed render is, and so is
377
+ one that sets what is not the application's to set: a name or value `Headers`
378
+ refuses (a value holding CR or LF cannot smuggle a second header in), a
379
+ header that frames the response (`content-length`, `transfer-encoding`,
380
+ `connection` and their kin), or `location`. A value from the Model still
381
+ needs encoding for its header, as `encodeURIComponent` does here: a cookie's
382
+ value holds no `;` or `,`.
383
+
384
+ Every rendered page is answered `200` unless `status: (model, request) =>
385
+ ...` says otherwise. It is given the Model the server reached, which already
386
+ says which route it is, so a not-found page is answered `404` without parsing
387
+ the URL twice:
388
+
389
+ ```ts
390
+ SSR.entry(config, Post, {
391
+ buildId,
392
+ status: model =>
393
+ AppRoute.match(model.route, { Home: () => 200, Post: () => 200, NotFound: () => 404 }),
394
+ })
395
+ ```
396
+
397
+ The page is rendered and resumed as any other; only the response's status
398
+ changes. A status outside `200`–`599`, or a `status` that throws, is answered
399
+ `500` and reported.
350
400
 
351
401
  What the page says of itself (`meta`) and per-page `head` markup are written
352
402
  into a template's head, which the host owns here: a plan with `meta` is
@@ -366,7 +416,6 @@ by `handleRequest`, reads it back:
366
416
 
367
417
  ```ts
368
418
  import { Effect, Option, type Layer } from 'effect'
369
- import { Responded } from 'foldkit/experimental/server'
370
419
  import type { RemoteClient, RemoteUnauthenticated } from 'foldkit-remote'
371
420
  import { SSR } from 'foldkit-ssr'
372
421
 
@@ -378,19 +427,15 @@ export const PageContext = SSR.requestContext<{
378
427
  // The host, a Worker's fetch say:
379
428
  // pages.fetch(PageContext.attach(request, { reader: pageReader(page)(request, env) }))
380
429
 
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
- })
430
+ // The server entry, made once. `actives` is the record `Data.wiring` takes.
431
+ export const { renderPage } = SSR.entry(config, Post, {
432
+ buildId,
433
+ prepare: (model, request) =>
434
+ Option.match(PageContext.of(request), {
435
+ onNone: () => Effect.fail(new Error('No reader for this page.')),
436
+ onSome: ({ reader }) => Data.satisfy(model, actives).pipe(Effect.provide(reader)),
437
+ }),
438
+ })
394
439
  ```
395
440
 
396
441
  The value is kept for that request alone, in a `WeakMap` on `globalThis`
@@ -437,8 +482,36 @@ a tuple, so `const [home, about] = pages` needs no check.
437
482
 
438
483
  A static host serves one file for every query, and for `/about` and `/about/`
439
484
  alike, so a generated page records its path alone: `/about?ref=mail` resumes
440
- the page generated for `/about`, and `/other` is refused. A server-rendered page
441
- records its path and query, and resumes only there.
485
+ the page generated for `/about`, and `/other` is refused. The page was made
486
+ without the query, and `init` does not run in the browser, so an application
487
+ with `routing` starts from the resumed Model given `routing.onUrlChange` of
488
+ the URL it is at, as from a navigation, and starts at once whatever its
489
+ `start`: one that reads the query (a search box in `?q=`) shows it, and the
490
+ part of the page that differs is redrawn; one that does not changes nothing.
491
+ The Message goes into the starting Model rather than after boot, so a URL
492
+ mirror does not write the served address back over the real one. A
493
+ server-rendered page records its path and query, and resumes only there.
494
+
495
+ Foldkit's Vite plugin prerenders pages through the server entry itself
496
+ (`ssr.build.prerender`), so `SSR.entry` cannot tell a build's request from a
497
+ visitor's. Name those paths in `prerendered`, and a request for one with no
498
+ query records its path alone, as `SSR.generate` does; export the same list
499
+ as `prerenderPaths`, which the plugin reads:
500
+
501
+ ```ts
502
+ export const prerenderPaths = ['/']
503
+
504
+ export const { renderPage } = SSR.entry(config, Post, { buildId, prerendered: prerenderPaths })
505
+ ```
506
+
507
+ A prerendered file the entry was not told of is refused at any other query,
508
+ and the reason says so.
509
+
510
+ Until the bundle runs, a file shows the state it was recorded with: the
511
+ query reaches the Model only when the browser starts. A page whose first
512
+ paint depends on its query (a search box filled from `?q=`) is better
513
+ rendered per request, which records the query and resumes with nothing
514
+ redrawn; `examples/foldkit/domains-plus` prerenders nothing for that reason.
442
515
 
443
516
  A generated site also wants a sitemap and a `robots.txt` that names it.
444
517
  `SSR.sitemap` takes the pages, with a `modified` date where one is known, and
@@ -604,6 +677,57 @@ needs that is not in the page, say after a Message shows one, is reported
604
677
  ([`StaticRegionMissing`](#diagnostics), once per page) and rendered in the
605
678
  browser.
606
679
 
680
+ ### What only the browser has: `prepare`
681
+
682
+ The server cannot send what it cannot see. What this browser stored (a
683
+ queue of writes kept in `localStorage` or IndexedDB) and what this page
684
+ load mints (an id its writes are named by) exist only in the browser. The
685
+ rule above still holds, so the first client view is the served page, and
686
+ such state is split by whether the view draws it:
687
+
688
+ ```text
689
+ envelope ──▶ resumed Model ──▶ prepare: what the view does not draw ──▶ Runtime.hydrate adopts the served page
690
+ └─▶ a Subscription reads the store ──▶ Message ──▶ update ──▶ drawn
691
+ ```
692
+
693
+ `prepare: model => Effect` runs once, on the Model a page resumes, before
694
+ anything is adopted, and the runtime starts when it succeeds. Keep it to
695
+ what no view draws. What the view draws arrives after, as a Message,
696
+ reduced over whatever the Model is by then. A `prepare` that changes what is
697
+ drawn makes the first client view differ from the served page: Foldkit
698
+ rebuilds every element that differs, and a development build warns that the
699
+ server DOM did not match. It must not fail, as `when` must not throw. A page
700
+ drawn afresh (no served page, or `otherwise: 'render'`) starts from `init`,
701
+ as it would without a server render, and does not run it.
702
+
703
+ Remote's durable outbox is the case it was made for. A page that makes
704
+ durable writes ([`foldkit-remote`'s outbox](../remote/README.md#a-write-that-outlives-the-page-outbox))
705
+ resumes from the outbox's `session`:
706
+
707
+ ```ts
708
+ import { outbox } from 'foldkit-remote/outbox'
709
+
710
+ const durable = outbox(Data, { key: model => `outbox:${model.userId}`, scope: model => model.userId })
711
+
712
+ SSR.hydrate(config, plan, { buildId, prepare: durable.session })
713
+ ```
714
+
715
+ - **The server's page holds none of the queue.** `Remote.resume` carries no
716
+ outbox, and the server has no store to read.
717
+ - **`durable.session` mints the page's id and reads nothing.** A durable
718
+ write made before the queue is read is queued at once, not refused.
719
+ - **The queue arrives through the outbox's own Subscription.** It reads the
720
+ store after the first frame and sends `OutboxRead`, which keeps any write
721
+ made before it and saves it with the rest. The unsent writes then join the
722
+ page, and every tab on the key shows them.
723
+ - **Not `durable.restore`.** As `prepare`, it would read the store before
724
+ adoption and show the queue in a first view the server did not draw. As
725
+ the config's `flags`, it never runs: a resumed page does not run `init`.
726
+
727
+ [`examples/reference`](../../examples/reference) does this on Workers: a
728
+ note added while the server is out of reach survives a reload of the
729
+ Worker's page, shows in a second tab, and is sent once the server answers.
730
+
607
731
  ### Markup the browser adopts: `SSR.serving`
608
732
 
609
733
  `SSR.serving()` is true while the view call in progress is the server rendering a page (both
@@ -651,9 +775,10 @@ const view = (model: Model, h: HtmlBuilder<Message>) => {
651
775
  }
652
776
  ```
653
777
 
654
- `rh` differs from `h` in one place: `OnInput`, `OnChange`, `OnKeyDown` and
778
+ `rh` differs from `h` in two places: `OnInput`, `OnChange`, `OnKeyDown` and
655
779
  `OnKeyUp` also take a Message's own constructor, and the event fills the field
656
- it leaves open. The types check it where it is written: the member must be one
780
+ it leaves open; and `KeepTyped` marks a field whose early typing is kept
781
+ ([below](#typing-before-the-script-arrives)). The types check it where it is written: the member must be one
657
782
  of the view's Messages, and leave exactly one string field, or exactly `key`
658
783
  and `modifiers`. A closure still works. It is not data, so the page cannot
659
784
  answer that event itself and boots on it instead, letting the live page answer.
@@ -745,6 +870,72 @@ meanwhile, whatever `start` says. A binding inside a placement dispatches the
745
870
  parent's Message, as Foldkit's own handlers do, so the plan's Surface lists the
746
871
  wrapper variant, `Message.GotUploadMessage`.
747
872
 
873
+ ### Typing before the script arrives
874
+
875
+ A served page is editable as soon as it is parsed, but its script comes
876
+ later, and hydration re-asserts each field's value to the Model's: what was
877
+ typed in between would vanish. A field marked `rh.KeepTyped()` keeps it,
878
+ whatever the plan's `start`:
879
+
880
+ ```ts
881
+ rh.input([rh.Value(model.draft), rh.OnInput(Message.ChangedDraft), rh.KeepTyped()])
882
+ ```
883
+
884
+ ```text
885
+ parse ──▶ typing (the field holds it) ──▶ script: SSR.hydrate reads the marked fields
886
+ ──▶ each changed one becomes its OnInput Message, first in the queue
887
+ ──▶ first render adopts the served page ──▶ value and caret put back ──▶ update
888
+ ```
889
+
890
+ There is no inline script: the field itself holds what was typed, and an
891
+ `OnInput` Message carries the whole value, so the value when the script runs
892
+ says all the keystrokes would. A page with a Content Security Policy needs no
893
+ nonce for it. When the script runs, `SSR.hydrate` reads each marked field
894
+ whose value differs from what the server rendered and turns it into the
895
+ field's `OnInput` Message (else its `OnChange`), with the hole filled. These
896
+ go ahead of anything the page answers afterwards, once each, in document
897
+ order, so a page that waits to boot replays the early typing first. The first
898
+ render starts from the resumed Model, so it adopts every node and resets the
899
+ field; the field's value and selection are put back as it commits, and the
900
+ Message then finds the field already holding its value and writes nothing.
901
+ The caret stays where it was, and focus never moves. A field inside a lazy
902
+ bundle is replayed once the bundle's code has loaded.
903
+
904
+ Only a field the page can replay may be marked: an `input` that takes text, a
905
+ `textarea` or a `select`, built by `rh` (`rh.input`, not `h.input`), with
906
+ `OnInput` or `OnChange` given a Message member. The resumable builder marks
907
+ the bindings of the elements it builds; on an element `h` builds, the hole
908
+ forms are plain closures to the page and nothing names the Message to replay.
909
+ Anything else is refused on the server (`UnkeepableField`), naming the
910
+ element. What is not kept: an unmarked field (re-asserted to the served value,
911
+ as before); a key press or click before the script (the browser's own, so a
912
+ form submitted then posts, which `fallback: 'server'` answers); a page that is
913
+ contained, declined or stale; and an IME composition in progress at boot,
914
+ which the first render's reset ends, though its text is kept. A value the
915
+ browser restored into the field on a reload or a history visit is kept like
916
+ typing, since it is what the field shows.
917
+
918
+ `KeepTyped` answers the typing as soon as the script runs, not before. Until
919
+ the bundle is parsed no code of the application is in the page, so nothing
920
+ but the field changes: the address stays, and text derived from the query (a
921
+ heading, pending results) shows what the server rendered. When the script
922
+ runs, the replayed Message is the first `update` sees, and the page draws its
923
+ effects as it would any Message's. Typing is the interaction a page started
924
+ `'idle'` or `'on-interaction'` waits for, so such a page starts at once when
925
+ something was typed before its script; only a lazy bundle still loading
926
+ holds the queue undrawn.
927
+
928
+ Answering sooner takes code that runs before the bundle, which only an inline
929
+ script can be. `foldkit-ssr` writes none: it would need a Content Security
930
+ Policy nonce and a second copy of the field's behaviour in plain DOM code. An
931
+ application that keeps one (upstream's foldkit-domains writes `?q=` and fills
932
+ its pending cards from one) may write the address only on a page recorded for
933
+ its path alone (`SSR.generate`, or `SSR.entry`'s `prerendered`), which, opened
934
+ at another query, starts from that URL; a page rendered per request is
935
+ refused at any query but its own. Markup such a script changes is the
936
+ served page no longer, and Foldkit reconciles it at hydration to the Model's
937
+ first render.
938
+
748
939
  ## Forms that work without scripts
749
940
 
750
941
  A form whose `OnSubmit` names a Message can be answered by the server, before
@@ -778,11 +969,15 @@ A form that need not work without scripts sends `Added()` and reads
778
969
 
779
970
  With scripts on, nothing changes: the page answers the submit and the form
780
971
  never posts. Without them, the server wrote the form to post the Message to the
781
- page's own URL, and `SSR.entry` hands that post to `SSR.handle`:
972
+ page's own URL, and `SSR.entry` hands that post to `SSR.handle`. A form given
973
+ its own `Method` is left as the view draws it, with no Message field: a
974
+ search form is `rh.Method('get')` and sends its named fields as the address,
975
+ and one given `Method('post')` posts no Message, which the entry answers
976
+ `400`.
782
977
 
783
978
  ```text
784
979
  POST ──▶ decode the Message ──▶ set the posted fields into it (the typed `title`)
785
- ──▶ init, then boot and its Commands ──▶ update, and every Command after it
980
+ ──▶ init, prepare, then boot and its Commands ──▶ update, and every Command after it
786
981
  ──▶ the page, rendered
787
982
  ```
788
983
 
@@ -805,7 +1000,14 @@ A form a cookie session authorizes is a cross-site request forgery target,
805
1000
  and a form cannot carry a CSRF header. `SSR.entry`'s `origins` names the
806
1001
  origins a form may be posted from; a post whose `Origin` (every browser sends
807
1002
  one on a `POST`) is not among them is answered `403` before its body is read
808
- or `flags` and `resources` run. A page served with `Referrer-Policy:
1003
+ or `flags` and `resources` run. `origins: 'same-origin'` takes a post from
1004
+ the origin the request was addressed to and no other, for a site whose
1005
+ address the entry cannot know when it is made (a dev server's port). It
1006
+ compares with the request's own URL, so **behind a proxy that terminates TLS
1007
+ or rewrites the host** (nginx, Fly, Render), where the server sees
1008
+ `http://host` and the browser sends `Origin: https://host`, every post is
1009
+ refused `403`. There, pass the public origin, `origins:
1010
+ ['https://example.com']`, never `'same-origin'`. A page served with `Referrer-Policy:
809
1011
  no-referrer` posts `Origin: null` even to its own site; such a post, or one
810
1012
  with no `Origin` at all, is taken when its Fetch Metadata `Sec-Fetch-Site`,
811
1013
  which no page or form can set, says `same-origin`, and refused without it. A plan with a server fallback requires `origins`, since a post
@@ -813,6 +1015,72 @@ runs `flags`, the config's `resources` and its own as whoever the cookie says
813
1015
  posted: an entry made without them throws. An entry of your own that calls
814
1016
  `SSR.handle` checks `Origin` itself.
815
1017
 
1018
+ ### Answering a post with a redirect
1019
+
1020
+ The page a post renders sits at the address the form posted to, so a reload
1021
+ asks to post again. That is harmless for an idempotent Message and wrong for
1022
+ one that orders or sends something. `answerPost: 'redirect'` answers the post
1023
+ `303` to the same address instead, and the browser asks for it with a `GET`
1024
+ (Post/Redirect/Get):
1025
+
1026
+ ```text
1027
+ POST /todos ──▶ update, and its Commands ──▶ 303, Location: /todos, headers(request, some(model))
1028
+ GET /todos ──▶ init, prepare ──▶ the page, rendered
1029
+ ```
1030
+
1031
+ ```ts
1032
+ SSR.entry(config, Todos, {
1033
+ buildId,
1034
+ origins: ['https://example.com'],
1035
+ answerPost: 'redirect',
1036
+ // What the post changed has to outlive it: the next request starts from `init`.
1037
+ headers: (_request, model) =>
1038
+ Option.match(model, {
1039
+ onNone: () => ({}),
1040
+ onSome: ({ todos }) => ({
1041
+ 'set-cookie': `todos=${encodeURIComponent(JSON.stringify(todos))}; Path=/; HttpOnly; SameSite=Lax`,
1042
+ }),
1043
+ }),
1044
+ })
1045
+ ```
1046
+
1047
+ The `Location` is the posted address's path and query, relative, so the
1048
+ browser resolves it against the address it posted to and it can name no
1049
+ other origin, whatever `Host` the request claimed. The `GET` starts from
1050
+ `init` and `prepare`, so whatever the post changed reaches it only through
1051
+ what `headers` wrote (a cookie) or a store of the application's; `prepare`
1052
+ reads it back. The page shows nothing else of the post: a message about its
1053
+ outcome is a one-shot cookie the application writes and `prepare` reads. A
1054
+ refused post is still a `400`, and a failing Command a `500`.
1055
+
1056
+ ### A whole page without scripts
1057
+
1058
+ A form that posts is one part of a page that works with JavaScript off. The
1059
+ rest is the application's, and
1060
+ [`examples/foldkit/domains-plus`](../../examples/foldkit/domains-plus) does
1061
+ all of it; [Pages that work without JavaScript](../../docs/progressive-enhancement.md)
1062
+ is the guide. What the port needed from this package:
1063
+
1064
+ - **Render what is shown.** `SSR.render` fetches nothing, so read first, in
1065
+ `prepare` (`Data.satisfy`); send the reading
1066
+ Surfaces' data with `parts: [Remote.resume(Data)]` and list the Surfaces
1067
+ in `surfaces`, so the browser reads none of it again.
1068
+ - **Give a GET form its method.** With a fallback, a form `rh` builds whose
1069
+ `OnSubmit` names a Message posts it; a search or filter form is a GET of
1070
+ the address the URL mirror reads, and `rh.Method('get')` leaves it one.
1071
+ - **Draw the plain controls on both sides.** Show them under
1072
+ `@media (scripting: none)` and hide the scripted ones there; a control in
1073
+ `<noscript>` is not drawn by the view, and the page would not be the one
1074
+ the browser renders first.
1075
+ - **Keep state between posts yourself.** A post starts from `init`, so what
1076
+ must outlive it lives in a cookie the entry reads in `prepare`, validated
1077
+ as it is read, and `headers(request, model)` writes it back from the Model
1078
+ the post reached. With that, answer posts with a redirect
1079
+ (`answerPost: 'redirect'`), so a reload does not post again.
1080
+ - **Wait for the takeover in a scripted test.** The served page works on its
1081
+ own, so a click before boot posts. The root loses `data-foldkit-plus-resume`
1082
+ as the page boots.
1083
+
816
1084
  ## A reader's preferences in the first frame
817
1085
 
818
1086
  A theme, a light or dark choice, a density: a reader expects the page to open
@@ -897,6 +1165,7 @@ of:
897
1165
  | `UnencodableBinding` | The plan has no Message Schema, or a binding's Message does not encode through it | Make the plan from the application; build the Message with its constructor |
898
1166
  | `EagerStartRequired` | A deferred plan would start a Subscription or Managed Resource late | Declare it in `deferrable`, or start `'now'` |
899
1167
  | `VoidRootWithStyles` | `styles` were given for a view whose root is void and holds nothing | Put the styles in the template's head with `SSR.generate`, or return an element root |
1168
+ | `UnkeepableField` | `KeepTyped` on an element that holds no typed value, one `h` built rather than `rh`, or with no `OnInput`/`OnChange` given a Message member | Mark only a text `input`, `textarea` or `select` that `rh` builds, and give its binding the Message's member |
900
1169
  | `UngeneratablePath` | `SSR.generate` was given a path no file can be served at | Leave out the query and fragment; keep paths to distinct files |
901
1170
 
902
1171
  In the browser, `SSR.hydrate` checks in Foldkit's order: the build id first,
@@ -978,10 +1247,19 @@ In a test, `Diagnostics.collect()` gives a reporter and the array it fills.
978
1247
  - **A resumable page leans on two Foldkit behaviours,** each pinned by a test
979
1248
  here and by Foldkit's own: the first patch removes attributes the browser's
980
1249
  view does not assert, and a control's value is re-asserted to the Model's.
1250
+ What the server wrote for the browser's script alone (the envelope, the
1251
+ markers, a placement's slot, a fallback form's method and hidden field) is
1252
+ taken off as the page boots, before Foldkit records the served page, so a
1253
+ development build does not report it as markup the view disagrees with.
981
1254
  It does not depend on `Runtime.hydrate` rendering its first frame before
982
1255
  it returns, which Foldkit does today without promising it: until that
983
1256
  frame commits (`Render.afterCommit`), the page keeps answering from its
984
1257
  markers and sends the live page what only it can answer.
1258
+ - **A kept field is written twice at boot.** Hydration re-asserts the served
1259
+ value, and the page writes the typed one back with its selection, in the
1260
+ same task, so nothing paints between. The write ends an IME composition
1261
+ in progress; leaving a changed control alone is
1262
+ [proposal 6](../../docs/upstream-foldkit-ssr.md#proposal-6-leave-a-control-the-person-changed-alone-at-hydration).
985
1263
  - **Development is not production.** Under Vite's dev server, Foldkit's model
986
1264
  preservation restores the previous Model after a reload and skips adoption.
987
1265
  - **A closure handler makes its event wait for boot.** `SSR.render`'s result
@@ -999,8 +1277,8 @@ In a test, `Diagnostics.collect()` gives a reporter and the array it fills.
999
1277
  as a `Result`. `SSR.render` carries it on the stamped root, beside Foldkit's
1000
1278
  own stamps; the JSON escapes `<` as Foldkit escapes its Flags, and U+2028
1001
1279
  and U+2029, and the attribute escapes `&` and `"` besides, so no string in
1002
- the Model can break out of the value. Hydration drops the attribute on its
1003
- first patch, so the browser reads it before it boots.
1280
+ the Model can break out of the value. The browser reads it, then takes the
1281
+ attribute off as the page boots.
1004
1282
  - **`SSR.inspect(plan, model)`**: the plan's coverage as data.
1005
1283
  - **`Resume.bindings(plan, document, root, model)`** decodes and checks a
1006
1284
  page's bindings, and **`Resume.listen(root, { bindings, onAnswer, events? })`**
@@ -1012,7 +1290,8 @@ In a test, `Diagnostics.collect()` gives a reporter and the array it fills.
1012
1290
  - **Attribute names**, for tools and tests: `RESUME_ATTRIBUTE` (the envelope
1013
1291
  on the stamped root), `STATIC_ATTRIBUTE`, `BINDING_ATTRIBUTE` (a prefix,
1014
1292
  followed by the event), `SLOT_ATTRIBUTE` (a placement's root while the server
1015
- renders) and `FALLBACK_FIELD` (the posted Message).
1293
+ renders), `KEEP_ATTRIBUTE` (a kept field, naming the binding that replays
1294
+ it) and `FALLBACK_FIELD` (the posted Message).
1016
1295
 
1017
1296
  ## The application in these examples
1018
1297
 
@@ -1026,7 +1305,7 @@ for a plan, as `Surface.when(PostActions, App.model.route, AppRoute.Post, route
1026
1305
  [the coverage example](#checking-what-the-browser-will-read).
1027
1306
 
1028
1307
  ```ts
1029
- const AppRoute = defineRouteUnion({ Home: {}, Post: { id: Schema.String } })
1308
+ const AppRoute = defineRouteUnion({ Home: {}, Post: { id: Schema.String }, NotFound: {} })
1030
1309
 
1031
1310
  const Model = Schema.Struct({
1032
1311
  route: AppRoute,
@@ -1,7 +1,7 @@
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";
1
+ import { o as listen } from "./listen-DaUPRKVR.js";
2
+ import { g as view, h as builder } from "./resumable-BPN_qQHU.js";
3
+ import { E as plan, M as serving, P as staticRegion, c as ResumableConfig, k as resume, u as ResumePlan, y as bindings } from "./shared-DbupL3vO.js";
4
+ import { Effect, Schema } from "effect";
5
5
  import { Diagnostic as Diagnostic$1, Diagnostics as Diagnostics$1, ReportDiagnostic, ReportDiagnostic as ReportDiagnostic$1 } from "foldkit-surface";
6
6
  /**
7
7
  * Starts the browser from the page's resumed Model, without running `init`.
@@ -45,6 +45,16 @@ declare const hydrate: <Model, Fields extends Schema.Struct.Fields, Message = an
45
45
  * throw, as `when`.
46
46
  */
47
47
  readonly fresh?: ((version: unknown) => boolean) | undefined;
48
+ /**
49
+ * What only this browser adds to the resumed Model before it is adopted,
50
+ * and the view does not draw: a session minted for this page load (an
51
+ * outbox's `session`). Run once, for a page that resumes; the runtime
52
+ * starts when it succeeds. What the view draws, such as a queue read from
53
+ * storage, arrives after, as a Message: here it would make the first
54
+ * client view differ from the served page. Must not fail, as `when` must
55
+ * not throw.
56
+ */
57
+ readonly prepare?: ((model: Model) => Effect.Effect<Model>) | undefined;
48
58
  /**
49
59
  * Where what the page met goes: a page contained rather than resumed, a
50
60
  * static region the server's page lacked, a lazy bundle that did not
@@ -72,4 +82,4 @@ declare const SSR: {
72
82
  serving: typeof serving;
73
83
  };
74
84
  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
85
+ //# sourceMappingURL=client-XnpTQZHw.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"client-XnpTQZHw.d.ts","names":[],"sources":["../src/client.ts"],"mappings":";;;;;;;;;;;;;;;cAgFM,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;;;;;;;;;;WAUV,YAAY,OAAO,UAAU,OAAO,OAAO;;;;;;;;WAQ3C,cAAc;;;cAwMd;;cAuKA;;;;;;;cAGA"}
package/dist/client.d.ts CHANGED
@@ -1,5 +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 };
1
+ import { n as DecodedBinding } from "./listen-DaUPRKVR.js";
2
+ import { a as FALLBACK_FIELD, d as SLOT_ATTRIBUTE, n as BINDING_ATTRIBUTE, s as KEEP_ATTRIBUTE, u as ResumableBuilder } from "./resumable-BPN_qQHU.js";
3
+ import { C as metaMarkup, G as PageContained, J as StaticRegionMissing, K as PageFailed, U as BundleUnloaded, W as HandlerUnnamed, c as ResumableConfig, d as ResumeRefused, h as Start, i as Meta, l as ResumePart, n as Loadable, o as PlanSurface, p as STATIC_ATTRIBUTE, q as SsrDiagnostic, r as META_ATTRIBUTE, s as RESUME_ATTRIBUTE, t as FOLDKIT_APP_ATTRIBUTE, u as ResumePlan, z as UnnamedHandler } from "./shared-DbupL3vO.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-XnpTQZHw.js";
5
+ export { BINDING_ATTRIBUTE, type BundleUnloaded, type DecodedBinding, type Diagnostic, Diagnostics, FALLBACK_FIELD, FOLDKIT_APP_ATTRIBUTE, type HandlerUnnamed, KEEP_ATTRIBUTE, 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 };