foldkit-ssr 0.7.0 → 0.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -411,8 +411,16 @@ export const site = {
411
411
  } satisfies SiteModule
412
412
  ```
413
413
 
414
+ `emit` adds files made from the generated pages, written beside them: what the
415
+ pages reference and the build must also serve, such as the image variants
416
+ their `srcset`s name (`foldkit-media`'s `materialize`). It takes the pages and
417
+ returns `{ file, contents }`s; a path that leaves the output (absolute, `..`)
418
+ or lands on a page, the sitemap, robots or another emitted file is refused, and
419
+ so is one the client build already wrote, a file from `public/` among them.
420
+
414
421
  `generateStaticSite(site)` is the same build without Vite: it renders every
415
- path and returns `{ pages, sitemap?, robots? }`. `fileFor(path, layout)` maps
422
+ path and returns `{ pages, sitemap?, robots?, emitted }`; `writeEmitted(outDir,
423
+ emitted)` writes the emitted files as the plugin does. `fileFor(path, layout)` maps
416
424
  one path to the file a host serves it from, so a caller writes the files
417
425
  itself; `generateStaticSite` refuses two paths that would claim one file.
418
426
 
@@ -702,9 +710,9 @@ and a form cannot carry a CSRF header. `SSR.entry`'s `origins` names the
702
710
  origins a form may be posted from; a post whose `Origin` (every browser sends
703
711
  one on a `POST`) is not among them is answered `403` before its body is read
704
712
  or `flags` and `resources` run. A page served with `Referrer-Policy:
705
- no-referrer` posts `Origin: null` even to its own site; such a post is taken
706
- when its `Sec-Fetch-Site`, which no page or form can set, says
707
- `same-origin`. A plan with a server fallback requires `origins`, since a post
713
+ no-referrer` posts `Origin: null` even to its own site; such a post, or one
714
+ with no `Origin` at all, is taken when its Fetch Metadata `Sec-Fetch-Site`,
715
+ 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
708
716
  runs `flags`, the config's `resources` and its own as whoever the cookie says
709
717
  posted: an entry made without them throws. An entry of your own that calls
710
718
  `SSR.handle` checks `Origin` itself.
@@ -765,6 +773,68 @@ SSR.hydrate(config, plan, { buildId, when, otherwise: 'render', until: Site.answ
765
773
  The served page stays as it was served while it waits: its links are plain
766
774
  links, and nothing it shows becomes live.
767
775
 
776
+ ## A reader's preferences in the first frame
777
+
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.
781
+
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:
784
+
785
+ ```text
786
+ request cookie ─▶ flags ─▶ init ─▶ Model.theme ─┬─ view draws it
787
+ └─ plan.state carries it, so the browser resumes with it
788
+ ```
789
+
790
+ ```ts
791
+ import { Option, Record, Schema, pipe } from 'effect'
792
+ import { Cookies } from 'effect/http'
793
+ import { Theme, Themes } from 'foldkit-mixins/theme'
794
+
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
+ )
808
+ ```
809
+
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`.
837
+
768
838
  ## Costs and limits
769
839
 
770
840
  - **`SSR.render` renders the view twice.** That is the view check. A static
@@ -857,8 +927,6 @@ const Message = defineMessageUnion({
857
927
 
858
928
  ## See also
859
929
 
860
- - [The implementation plan](../../docs/design/ssr-PLAN.md): the decisions and
861
- why, phase by phase.
862
930
  - [What the tests prove](./test/README.md).
863
931
  - [What this package asks of Foldkit](../../docs/upstream-foldkit-ssr.md).
864
932
  - [Site, Remote and SSR together](../../docs/site-remote-ssr.md): a routed