foldkit-media 0.0.0-stage → 0.2.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 (69) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +637 -2
  3. package/client.d.ts +10 -0
  4. package/dist/asset-Dlkss5qp.d.mts +80 -0
  5. package/dist/asset-Dlkss5qp.d.mts.map +1 -0
  6. package/dist/browser/index.d.mts +15 -0
  7. package/dist/browser/index.d.mts.map +1 -0
  8. package/dist/browser/index.mjs +69 -0
  9. package/dist/browser/index.mjs.map +1 -0
  10. package/dist/cloudflare/index.d.mts +54 -0
  11. package/dist/cloudflare/index.d.mts.map +1 -0
  12. package/dist/cloudflare/index.mjs +163 -0
  13. package/dist/cloudflare/index.mjs.map +1 -0
  14. package/dist/describe-CivKHl4x.d.mts +56 -0
  15. package/dist/describe-CivKHl4x.d.mts.map +1 -0
  16. package/dist/describe-h9F5stgR.mjs +174 -0
  17. package/dist/describe-h9F5stgR.mjs.map +1 -0
  18. package/dist/errors-qETj7Pgi.mjs +21 -0
  19. package/dist/errors-qETj7Pgi.mjs.map +1 -0
  20. package/dist/format-BmfnR4jg.mjs +21 -0
  21. package/dist/format-BmfnR4jg.mjs.map +1 -0
  22. package/dist/icon-ClqtprHT.d.mts +89 -0
  23. package/dist/icon-ClqtprHT.d.mts.map +1 -0
  24. package/dist/icon-CowP8fQ0.mjs +185 -0
  25. package/dist/icon-CowP8fQ0.mjs.map +1 -0
  26. package/dist/icons/index.d.mts +51 -0
  27. package/dist/icons/index.d.mts.map +1 -0
  28. package/dist/icons/index.mjs +320 -0
  29. package/dist/icons/index.mjs.map +1 -0
  30. package/dist/index.d.mts +160 -0
  31. package/dist/index.d.mts.map +1 -0
  32. package/dist/index.mjs +326 -0
  33. package/dist/index.mjs.map +1 -0
  34. package/dist/limits-B6C9OOLl.mjs +13 -0
  35. package/dist/limits-B6C9OOLl.mjs.map +1 -0
  36. package/dist/provider-g0Vlvlrb.d.mts +81 -0
  37. package/dist/provider-g0Vlvlrb.d.mts.map +1 -0
  38. package/dist/rolldown-runtime-8H4AJuhK.mjs +14 -0
  39. package/dist/server/index.d.mts +181 -0
  40. package/dist/server/index.d.mts.map +1 -0
  41. package/dist/server/index.mjs +235 -0
  42. package/dist/server/index.mjs.map +1 -0
  43. package/dist/services-8_h0ubLB.d.mts +54 -0
  44. package/dist/services-8_h0ubLB.d.mts.map +1 -0
  45. package/dist/services-BeakQl7F.mjs +39 -0
  46. package/dist/services-BeakQl7F.mjs.map +1 -0
  47. package/dist/sharp/index.d.mts +21 -0
  48. package/dist/sharp/index.d.mts.map +1 -0
  49. package/dist/sharp/index.mjs +103 -0
  50. package/dist/sharp/index.mjs.map +1 -0
  51. package/dist/stores-BtmSl8X3.mjs +448 -0
  52. package/dist/stores-BtmSl8X3.mjs.map +1 -0
  53. package/dist/unpic/index.d.mts +27 -0
  54. package/dist/unpic/index.d.mts.map +1 -0
  55. package/dist/unpic/index.mjs +44 -0
  56. package/dist/unpic/index.mjs.map +1 -0
  57. package/dist/upload-kp0_oK76.d.mts +131 -0
  58. package/dist/upload-kp0_oK76.d.mts.map +1 -0
  59. package/dist/variant-BOg1M0Wj.d.mts +69 -0
  60. package/dist/variant-BOg1M0Wj.d.mts.map +1 -0
  61. package/dist/vite/index.d.mts +41 -0
  62. package/dist/vite/index.d.mts.map +1 -0
  63. package/dist/vite/index.mjs +330 -0
  64. package/dist/vite/index.mjs.map +1 -0
  65. package/dist/widths-BEa9odY6.mjs +40 -0
  66. package/dist/widths-BEa9odY6.mjs.map +1 -0
  67. package/dist/widths-Cg7-x89y.d.mts +38 -0
  68. package/dist/widths-Cg7-x89y.d.mts.map +1 -0
  69. package/package.json +107 -3
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Patrick Glenn
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,638 @@
1
- # Temporary Holding Version
1
+ # foldkit-media
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Responsive images for Foldkit Plus. An image is a URL to write: given an
4
+ image's facts, a provider that knows a host's URL scheme, and how wide the image
5
+ is drawn, `foldkit-media` derives every attribute of its markup (`srcset`,
6
+ `sizes`, a `source` per format, the box it reserves, how eagerly it loads). It
7
+ performs no I/O. Icons are its second half: an icon is data (`IconData`), read
8
+ from an SVG file or an Iconify set at build time and checked there, then drawn
9
+ inline or as a mask ([Icons](#icons)). Its subpaths add the I/O around both:
10
+ a resizing server, its Cloudflare and Node layers, uploads, and Vite plugins.
11
+
12
+ ## What it owns, and what it does not
13
+
14
+ - **It owns** the derivation: which widths are worth offering, what `sizes`
15
+ says, which URL each variant has.
16
+ - **The original image** belongs to its source: a file in your repository, an
17
+ upload your CMS stores, a third-party host.
18
+ - **An image's facts** (width, height, alpha, placeholder) are derived from the
19
+ original once and stored beside it. This package reads them as an
20
+ `ImageAsset`; `describe` computes them where an original enters, while the
21
+ view only reads them.
22
+ - **Variants** belong to whoever makes them, a CDN or a resizing server, and
23
+ are a cache: they can be made again from the original.
24
+ - **Which variant a page shows** is the browser's choice, from `srcset` and
25
+ `sizes`. Nothing in your Model decides it.
26
+ - **An icon's drawing** belongs to its set (Lucide, an application's SVG
27
+ folder); this package reads and checks it once, at build, and the theme's
28
+ `icon` tokens (`foldkit-mixins`) choose which drawing a component shows.
29
+
30
+ ## The model
31
+
32
+ ```text
33
+ ImageAsset + Provider + Layout -> Picture.derive -> attributes a view writes
34
+ facts URL scheme how wide (no I/O)
35
+ ```
36
+
37
+ One `Widths` ladder, carried by the provider, decides which widths exist. A
38
+ `Layout` picks the ones worth offering:
39
+
40
+ | Layout | Candidates | `sizes` |
41
+ | --- | --- | --- |
42
+ | `Fixed({ width })` | the ladder widths covering 1x and 2x | `${width}px` |
43
+ | `Constrained({ width })` | every width up to the one covering 2x | `(min-width: ${width}px) ${width}px, 100vw` |
44
+ | `FullWidth()` | the whole ladder | `100vw` |
45
+
46
+ A width above the original's own is described with the original's width, and
47
+ only the first such width is offered: a provider that does not enlarge answers
48
+ all of them with the same pixels.
49
+
50
+ ## Sixty seconds
51
+
52
+ ```ts
53
+ import { Option, Schema } from 'effect'
54
+ import { ImageAsset, Layout, Picture, Provider } from 'foldkit-media'
55
+
56
+ const hero = Schema.decodeUnknownSync(ImageAsset)({
57
+ key: 'photos/hero.jpg',
58
+ width: 2400,
59
+ height: 1600,
60
+ alpha: false,
61
+ hash: null,
62
+ placeholder: null,
63
+ })
64
+
65
+ const picture = Picture.derive({
66
+ asset: hero,
67
+ provider: Provider.cdnCgi(),
68
+ layout: Layout.Constrained({ width: 720 }),
69
+ })
70
+
71
+ Option.map(picture, ({ img }) => img.srcset)
72
+ // "/cdn-cgi/image/width=320,format=auto,fit=scale-down/photos/hero.jpg 320w, …"
73
+ ```
74
+
75
+ - `ImageAsset` is a Schema: decode stored facts with it. Its optional fields
76
+ (`hash`, `placeholder`) are `null` when stored and `Option` in code.
77
+ - `Provider.cdnCgi()` writes Cloudflare's `/cdn-cgi/image/` URLs: the zone
78
+ resizes the original itself, and no code of yours runs. It only writes URLs.
79
+ - `Picture.derive` returns `Option.none()` when the provider has no URL for any
80
+ candidate; otherwise every attribute: `sources`, `img`, and the `ratio`.
81
+
82
+ ## Providers
83
+
84
+ - **`Provider.cdnCgi({ zone?, widths?, quality? })`** — Cloudflare's resizing on
85
+ a zone that has it on. It picks the format from `Accept`, so it offers no
86
+ `source`s. A `key` may be a path on the zone or an absolute URL.
87
+ - **`Provider.fromFiles(files, { sources, fallback })`** — variants a build
88
+ already wrote, as a table of `{ width, format, url }`. Its ladder is the
89
+ widths it has; a variant it lacks is left out of `srcset`.
90
+
91
+ - **`Provider.hosted({ baseUrl?, space?, sources?, fallback?, quality? })`** —
92
+ this package's own server, for originals no CDN can fetch. A variant's URL is
93
+ `/_image/<sha-256>/w640.avif`: the original is named by its content hash, so
94
+ it is a `Provider<HashedAsset>`, and facts without `hash` are a type error
95
+ where the picture is derived. Decode stored facts with the `HashedAsset`
96
+ Schema (an upload answers one), or narrow with `isHashed`. The format is in the URL, so every
97
+ cache can key on it.
98
+
99
+ - **`detect(url, { widths?, sources?, fallback?, quality? })`** from
100
+ `foldkit-media/unpic` — an image on a host that resizes it (Shopify,
101
+ Cloudinary, imgix, Contentful, and the rest [unpic](https://unpic.pics)
102
+ knows), through unpic, an optional peer. It answers `Option<Provider>`: none
103
+ for a host unpic does not know. By default the `img` asks for `auto` and the
104
+ host picks the format from `Accept`; a format asked as a `source` is left out
105
+ on a host that ignores it (Shopify's), and an asset on another host gets no
106
+ URL. The asset's `key` is the image's URL, and its size comes from
107
+ `factsOf(url)` (see Facts, below).
108
+
109
+ ```ts
110
+ import { Option } from 'effect'
111
+ import { detect } from 'foldkit-media/unpic'
112
+
113
+ const shopify = detect('https://cdn.shopify.com/s/files/1/0/products/shirt.jpg')
114
+ Option.isSome(shopify) // true
115
+ ```
116
+
117
+ A provider is a plain value (`Provider.Provider`): `widths`, the `sources`
118
+ formats offered before the `img`, the `img`'s own `fallback` encoding, and a
119
+ `url` function answering `Option<string>`.
120
+
121
+ ## Images in the repository
122
+
123
+ An image the application ships with needs no server and no CDN: the build
124
+ reads it and writes its variants beside the bundle. Add the plugin, and the
125
+ type of a `?image` import (`"types": ["foldkit-media/client"]` in the
126
+ `tsconfig`):
127
+
128
+ ```ts
129
+ // vite.config.ts
130
+ import { images } from 'foldkit-media/vite'
131
+ import { defineConfig } from 'vite'
132
+
133
+ export default defineConfig({ plugins: [images({ sources: ['avif'], fallback: 'webp' })] })
134
+ ```
135
+
136
+ ```ts
137
+ import hero from './hero.jpg?image'
138
+ import { Layout } from 'foldkit-media'
139
+ import { Image } from 'foldkit-mixins-ui'
140
+
141
+ Image.view({ ...hero, layout: Layout.Constrained({ width: 800 }), alt: 'The finals' }, h)
142
+ ```
143
+
144
+ The import is `{ asset, provider }`. The build measures the file once
145
+ (`describe`, through sharp, so the application needs `sharp`): its size, its
146
+ alpha, its SHA-256 and a ThumbHash. It writes one file for each ladder width
147
+ below the original's own, and one at its own width, in each format, named by
148
+ content so the host's long cache is honest; `provider` is
149
+ `Provider.fromFiles` over them. Facts and variants are kept in Vite's cache
150
+ directory by the original's hash, so an unchanged image, AVIF included, is
151
+ not encoded again. The development server makes the same variants when a page
152
+ asks for one, under `/@foldkit-media/image/`, and answers any width or format
153
+ it did not offer with a 404.
154
+
155
+ Every image costs `widths × formats` files: with the standard ladder and two
156
+ formats, a large photograph is eighteen. A static host counts files
157
+ (Cloudflare Pages allows 20,000 on its free plan), so a site with many images
158
+ offers fewer formats or widths (`images({ widths: Widths.make([…]) })`), or
159
+ keeps its originals on the media server (`Provider.hosted`) instead.
160
+
161
+ ## Preloading the largest image
162
+
163
+ A page's largest image is found sooner from a preload in the head. Foldkit adds
164
+ no head tags, so `Picture.preload(picture)` returns the `<link rel="preload">`
165
+ for your SSR `head` function to include, from the same `Picture.derive` the view
166
+ draws with `priority: true`:
167
+
168
+ ```ts
169
+ const preloadTag = Option.map(picture, Picture.preload)
170
+ ```
171
+
172
+ It names the first `source`'s candidates with its `type`, so a browser that
173
+ cannot show that format skips the preload rather than fetch a file it will not
174
+ use. With `foldkit-mixins-ui`, `Image.preloadsIn` is a `Head` that reads the
175
+ same from the rendered page, so a page marks `priority` where it draws the
176
+ image and nothing more.
177
+
178
+ ## Open Graph
179
+
180
+ `Picture.ogImage(asset, provider, origin)` is the absolute URL of a variant at
181
+ least 1200 wide for `og:image`: JPEG where the provider makes it, else WebP or
182
+ PNG, never AVIF, which not every link-preview fetcher reads.
183
+
184
+ ## Placeholders
185
+
186
+ An `ImageAsset`'s `placeholder` is painted behind the image until it loads;
187
+ `Picture.derive` gives it as a CSS `background` value (`picture.placeholder`):
188
+
189
+ - `Placeholder.cases.Color.make({ value })` paints one CSS color.
190
+ - `ThumbHash` paints a blurred likeness decoded to a PNG data URL, a few
191
+ kilobytes of HTML per image, so the page paints it with no request; or the
192
+ same hash's average color, a few bytes. `Picture.derive` paints the
193
+ likeness for the `priority` image and the color for the rest, so a grid of
194
+ thumbnails stays small; `placeholder: 'detail' | 'average'` overrides it.
195
+ - `LowRes` paints the provider's smallest width of the image: no stored data,
196
+ one small request.
197
+
198
+ An image with `alpha: true` gets no placeholder, since it would show through the
199
+ transparent pixels once the image loads.
200
+
201
+ ## Focal point
202
+
203
+ An asset's `focus` (`{ x, y }`, 0 to 1 from the top left) is where a crop
204
+ keeps the subject; `picture.focus` writes it as `object-position` does
205
+ (`"25% 80%"`). It is the one fact an editor sets rather than one derived from
206
+ the original, and a stored asset without it reads as none.
207
+
208
+ ## Loading
209
+
210
+ `priority: true` marks the page's largest image: `loading="eager"` and
211
+ `fetchpriority="high"`. Every other image is `loading="lazy"` and
212
+ `decoding="async"`, and its `sizes` begins with `auto, `, which lets a browser
213
+ that supports it use the laid-out width.
214
+
215
+ ## Facts
216
+
217
+ An `ImageAsset`'s facts are derived from its original once, where it enters,
218
+ and stored beside it. `describe` is in the core; each inspector is the
219
+ subpath of where it runs (`/sharp`, `/browser`, `/cloudflare`), and `factsOf`
220
+ is `foldkit-media/server`'s:
221
+
222
+ - `describe(key, bytes)` reads them through the `Inspector`: size, alpha, the
223
+ SHA-256, and a ThumbHash where the inspector makes a thumbnail.
224
+ - `inspectorSharp({ maxPixels? })` (Node) reads all of them; alpha is whether
225
+ any pixel is transparent, so an opaque PNG still gets a placeholder.
226
+ - `inspectorBrowser({ maxPixels? })` (`foldkit-media/browser`) reads them in
227
+ the browser or a web worker, with its own decoder: an editor describes a
228
+ file a reader dropped, ThumbHash and hash included, before anything is
229
+ uploaded, and stores its facts beside the image (a rich-text `Image`'s
230
+ `asset`). What the browser cannot decode is refused.
231
+ - `inspectorImages(binding)` (Cloudflare) reads the size from `info`, which
232
+ costs no transformation. It makes no thumbnail, since the binding's raw
233
+ pixels are not offered offline, and takes every format but JPEG to be
234
+ transparent; both cost a placeholder, never show a wrong one.
235
+ - `factsOf(url, { allow, maxBytes?, cache?, fetch? })` describes an image a
236
+ page names only by URL (a rich-text image), so it gets its box like any
237
+ other. Only `https` on a host in `allow` (matched exactly), at its default
238
+ port, is read, each redirect is checked again, and the body is limited as
239
+ it streams. Given a
240
+ `KeyValueStore` as `cache`, the facts are kept by URL and the original is
241
+ asked for again with its `ETag`, so an unchanged one is not read twice.
242
+
243
+ ## The variant space
244
+
245
+ A server makes only what its `Variant.space({ widths?, formats?, qualities?, revision? })`
246
+ allows: the width ladder, a set of formats (AVIF and WebP by default) and a set
247
+ of qualities (none by default: no URL names one, and the encoder uses its own).
248
+ A request outside it is refused before any work, so an original has at most
249
+ `space.size` variants, whoever asks: 16 for `Variant.standard`. The server
250
+ reads its space from the provider the pages use, so the two cannot differ:
251
+ define `const media = Provider.hosted({ space })` once and give the same value
252
+ to `serveFetch`'s `images.provider` (or `layer({ provider })`). The provider
253
+ refuses, when defined, a format or quality its space does not make.
254
+
255
+ A variant's URL names the variant (the original's hash, a width, a format, a
256
+ quality), and what it answers is kept for a year under it. Nothing checks that
257
+ two makings of one variant give the same bytes, and an upgraded encoder may
258
+ not: the server cannot tell. So a change to what a variant is (the encoder's
259
+ settings, how it resizes) is a new `revision` of the space, which the
260
+ application bumps, never new bytes behind an old URL. `Variant.space({ revision: 1 })`
261
+ writes `w640.r1.avif`; revision 0, the default, writes no revision, so every
262
+ URL written before revisions keeps its spelling. A server of revision 2 still
263
+ answers what earlier ones wrote: an earlier revision's variant while its store
264
+ keeps it, and else a `302` to the current revision's URL, kept briefly, since
265
+ a rollback, or a server of the earlier revision still in the rollout, answers
266
+ the old URL again. A later revision it answers as it would a width it does not
267
+ make, briefly, since the next release in a rollout may.
268
+
269
+ ## The server
270
+
271
+ `foldkit-media/server` answers the route `Provider.hosted` writes, for
272
+ originals no CDN can fetch. `MediaApi` is its Effect `HttpApi`, one route;
273
+ the handler decodes the path with the space's Schema, the one the provider
274
+ encodes with. A URL outside the grammar (a leading zero, a malformed hash) is
275
+ a 400; one well formed but outside this space (a width off the ladder) is a
276
+ 404. Only a variant is kept long: every refusal is kept a minute at the edge
277
+ and not at all by a browser, since another release, the next one in a
278
+ rollout, or the same one configured otherwise, may answer it.
279
+
280
+ The route checks no permission: anyone holding a variant's URL can read it. A content
281
+ hash cannot be guessed, but every page that shows the image hands it out, so
282
+ an original that must stay private does not belong on this server.
283
+
284
+ It needs three services, each a Layer you choose per host:
285
+
286
+ | Service | Job | Kind |
287
+ | --- | --- | --- |
288
+ | `Originals` | an original's bytes by content hash | authoritative; the server never writes it |
289
+ | `Transformer` | resize and encode, never above the original's width | does the work |
290
+ | `Variants` | variants already made, by the encoded request | a cache: clearing it costs time, not data |
291
+
292
+ A request is served from `Variants` when it can; otherwise the original is
293
+ read, transformed, kept, and served. A failure is its own response, never the
294
+ original in the variant's place, naming its kind (`{ "error": "NotFound" }`)
295
+ and nothing of the server's internals.
296
+
297
+ Every answer the route gives has its headers from one function, `headersFor`.
298
+ A defect is not an answer: a store that fails, or a Worker's layer that
299
+ cannot be built, is the framework's own `500`, with none of them.
300
+
301
+ | Answer | Status | `Cache-Control` |
302
+ | --- | --- | --- |
303
+ | A variant (`ETag: "<hash>/<spelling>"`) | 200 | `public, max-age=31536000, immutable`: the path names the variant, and a new way of making it is a new revision |
304
+ | A request already holding it (`If-None-Match`) | 304 | the same; the store is not read |
305
+ | A URL outside this release's grammar | 400 | `no-store`, and `CDN-Cache-Control: public, max-age=60`: a later release may read it (a new format) |
306
+ | A well-formed URL outside this space | 404 | the same: a later release may offer it |
307
+ | An earlier revision's variant, no longer kept | 302 to the current revision's URL | the same: a rollback answers the old URL again |
308
+ | No original under the hash | 404 | the same: an upload may yet put it there |
309
+ | The original above `maxBytes` (20 MB by default) | 413 | the same: a server configured to read more may answer it |
310
+ | The transformer failed | 502 | `no-store` |
311
+ | The client past its rate limit | 429 | `no-store`, `Retry-After` |
312
+ | The allowance spent | 503 | `no-store`, `Retry-After: 3600` |
313
+
314
+ Every image response also says `X-Content-Type-Options: nosniff`,
315
+ `Access-Control-Allow-Origin: *` (a canvas may read it), `Cross-Origin-Resource-Policy:
316
+ cross-origin` and `Timing-Allow-Origin: *`, and a variant says where it came
317
+ from in `Server-Timing` (`edge`, `store` or `made`). Nothing sends `Vary`: the
318
+ format is in the URL.
319
+
320
+ - `serveFetch({ images?, uploads?, otherwise? })` is a Worker's fetch handler.
321
+ It owns `/_image/` and `/_media/`: `images` (`{ provider?, maxBytes?, layer }`)
322
+ serves the variants, `uploads` (below) the upload route, each with its
323
+ services built from the request's bindings once per environment. Anything
324
+ else under those two prefixes, a route it was not given or a preflight, is a
325
+ 404, and every other path goes to `otherwise` (a 404 without one), so the
326
+ application's own routes need not know the media paths.
327
+ - `layer({ provider?, maxBytes?, coalesce? })` is the route as an Effect
328
+ `HttpRouter` layer, for a Node server beside other routes.
329
+ - `variantsNone` keeps nothing, for a host with a cache of its own in front.
330
+
331
+ ### Stores
332
+
333
+ `Originals` and `Variants` are kept in any Effect `KeyValueStore`
334
+ (`effect/persistence`), the store the application already has:
335
+
336
+ ```ts
337
+ import { NodeServices } from '@effect/platform-node'
338
+ import { Layer } from 'effect'
339
+ import { KeyValueStore } from 'effect/persistence'
340
+ import { originalsKeyValueStore, variantsKeyValueStore } from 'foldkit-media/server'
341
+
342
+ const stores = Layer.mergeAll(originalsKeyValueStore(), variantsKeyValueStore()).pipe(
343
+ Layer.provide(KeyValueStore.layerFileSystem('./media')),
344
+ Layer.provide(NodeServices.layer),
345
+ )
346
+ ```
347
+
348
+ - `KeyValueStore.layerMemory` for tests, `layerFileSystem` on a disk (it
349
+ needs the platform's `FileSystem` and `Path`, Node's on a server),
350
+ `layerSql` over SQLite or D1, `keyValueStoreR2` (below) over R2.
351
+ - `variantsKeyValueStore({ prefix })` keeps a variant's bytes under
352
+ `variants/<hash>/<spelling>`; its media type is the key's extension, so
353
+ nothing else is stored. A store that fails a read or a write is logged and
354
+ the request is answered by making the variant: variants are a cache.
355
+ - `originalsKeyValueStore({ prefix })` reads an original under its hash. A
356
+ store that fails is a 500, not a 404: the original is the data.
357
+
358
+ ### Rate limits
359
+
360
+ Only a miss costs work, so only a miss is limited: `Admission` is asked after
361
+ the store and before the original is read, and a variant already made is
362
+ served to anyone. It is optional; without it every miss is admitted.
363
+
364
+ - `admissionRateLimiter({ limit, window, algorithm? })` is Effect's
365
+ `RateLimiter` (`effect/persistence`): `limit` misses a client per `window`,
366
+ over `RateLimiter.layerStoreMemory` in one process or Redis across several.
367
+ - `admissionRateLimit(binding)` (`foldkit-media/cloudflare`) is a Workers
368
+ rate-limit binding (`[[ratelimits]]`), whose limit and period are its
369
+ configuration.
370
+ - A refused client gets a 429 with `Retry-After`. A limiter that fails admits
371
+ the request, logged: a limiter that is down should not take the images down.
372
+ - The client is `CF-Connecting-IP`, else the connection's address. Pass
373
+ `clientOf` to read your own proxy's header; `X-Forwarded-For` is the
374
+ client's to write, so it is not read by default.
375
+
376
+ ### On a Node server
377
+
378
+ `foldkit-media/sharp` gives the `Transformer` (sharp is an optional peer):
379
+
380
+ ```ts
381
+ import { NodeServices } from '@effect/platform-node'
382
+ import { Layer } from 'effect'
383
+ import { KeyValueStore } from 'effect/persistence'
384
+ import { layer, originalsKeyValueStore, variantsKeyValueStore } from 'foldkit-media/server'
385
+ import { transformerSharp } from 'foldkit-media/sharp'
386
+
387
+ const media = layer().pipe(
388
+ Layer.provide(
389
+ Layer.mergeAll(
390
+ transformerSharp({ concurrency: 4, maxPixels: 50_000_000 }),
391
+ originalsKeyValueStore(),
392
+ variantsKeyValueStore(),
393
+ ),
394
+ ),
395
+ Layer.provide(KeyValueStore.layerFileSystem('./media')),
396
+ Layer.provide(NodeServices.layer),
397
+ )
398
+ ```
399
+
400
+ - `transformerSharp` and `inspectorSharp` read an original as its EXIF
401
+ orientation shows it: a phone's portrait photograph, stored landscape, is
402
+ measured, resized and placeheld upright, as a browser draws it.
403
+ - `transformerSharp` reads an original's size from its header before decoding
404
+ it, and refuses one above `maxPixels` (50 megapixels by default) with a 413,
405
+ so a small file that inflates to a huge picture never reaches the heap. It
406
+ never enlarges, and encodes at the URL's quality.
407
+ - At most `concurrency` transforms run at once (the machine's cores by
408
+ default), through `limitTransforms(n)`, which wraps any `Transformer`.
409
+ - `layer` coalesces: concurrent misses for one variant share one transform
410
+ and one write (`coalesce`, on by default here and off for `serveFetch`,
411
+ since a Worker request cannot wait on another's).
412
+
413
+ ### Uploads
414
+
415
+ An original that no CDN or build holds, such as an editor's upload, enters
416
+ through `POST /_media/upload`: the bytes are the body, with an `image/*`
417
+ `Content-Type`. The route reads at most `maxBytes` (20 MB by default) as the
418
+ body streams, reads its facts through the `Inspector`, keeps the bytes under
419
+ their SHA-256 in `Uploads` (where `Originals` reads them), and answers the
420
+ facts as a `HashedAsset`, keyed by that hash, with a `201`. The variant server
421
+ serves it at once. Only the facts go on to the application's data (a CMS's
422
+ asset row); the bytes never travel through RPC. The answer is the server's
423
+ reading of the bytes, but once it has passed through a client it is the
424
+ client's word: a client can change a width or name another original's hash.
425
+ Decoding with `HashedAsset` checks the facts' shape, not that they are true,
426
+ so store facts your server read, not ones a client sends back.
427
+
428
+ Who may upload is the application's to say, and the route has no default:
429
+ `UploadPolicy` is asked before a byte is read. `uploadPolicyBearer(secret)` is
430
+ the one for a deployment's secret: it admits `Authorization: Bearer <secret>`,
431
+ compared by digest so the time taken says nothing of the secret, and admits
432
+ nobody while the secret is unset or empty. Who may upload by session is a
433
+ policy of your own (`Layer.succeed(UploadPolicy, { admit })`, a `foldkit-guard`
434
+ check).
435
+
436
+ ```ts
437
+ import { Layer } from 'effect'
438
+ import { uploadLayer, uploadPolicyBearer, uploadsKeyValueStore } from 'foldkit-media/server'
439
+ import { inspectorSharp } from 'foldkit-media/sharp'
440
+
441
+ const uploads = uploadLayer({ maxBytes: 10 * 1024 * 1024 }).pipe(
442
+ Layer.provide(
443
+ Layer.mergeAll(
444
+ uploadsKeyValueStore(),
445
+ inspectorSharp(),
446
+ uploadPolicyBearer(process.env['UPLOAD_TOKEN']),
447
+ ),
448
+ ),
449
+ )
450
+ ```
451
+
452
+ `uploadsKeyValueStore()` keeps them where `originalsKeyValueStore()` reads,
453
+ over the same `KeyValueStore`; on Cloudflare, `uploadsR2(bucket)` beside
454
+ `originalsR2(bucket)`, and `serveFetch`'s `uploads` hosts the route in a
455
+ Worker. A refusal answers its kind and nothing more, and no browser keeps it:
456
+ `403` from the policy, `415` for a body that is not `image/*` or not an image
457
+ the inspector reads, `413` past `maxBytes` or the inspector's pixel limit, and
458
+ `400` for a body that broke off. Because the body must be `image/*`, which is
459
+ not a type a browser sends to another origin without a preflight, and the
460
+ route answers no preflight, a cookie alone cannot upload from another site.
461
+
462
+ An image a page names only by URL gets its facts from the same route set:
463
+ `GET /_media/facts?url=` reads it with `factsOf`, behind the same
464
+ `UploadPolicy`, and answers them keyed by the URL (`200`). Only `https` on a
465
+ host in `uploadLayer({ facts: { allow } })` is read, and `allow` is empty
466
+ unless given, so a server names every host it fetches. An editor asks it when
467
+ a URL is set, and stores the facts beside the URL. Neither route limits how
468
+ often it is asked: each admitted call reads up to `maxBytes` and decodes it,
469
+ so the `UploadPolicy` is where an application limits who calls, and how often. What cannot be read (a host
470
+ not allowed, a missing file, no image) is a `422`, saying only that.
471
+
472
+ ### Written out at build
473
+
474
+ A static site needs no server for its hosted images: `materialize` makes every
475
+ variant the built pages name, through the server's own handler, and returns
476
+ them as files at their own paths, for `foldkit-ssr`'s `staticSite` `emit`:
477
+
478
+ ```ts
479
+ const media = serveFetch<object>({
480
+ images: {
481
+ layer: () =>
482
+ Layer.mergeAll(transformerSharp(), originalsKeyValueStore(), variantsKeyValueStore()).pipe(
483
+ Layer.provide(KeyValueStore.layerFileSystem('.media')),
484
+ // The disk itself: Node's file system and paths.
485
+ Layer.provide(NodeServices.layer),
486
+ ),
487
+ },
488
+ })
489
+ const env = {}
490
+
491
+ export const site = {
492
+ // …
493
+ emit: pages =>
494
+ materialize({
495
+ pages,
496
+ fetch: request => media(request, env),
497
+ headersFile: readFileSync('public/_headers', 'utf8'),
498
+ }),
499
+ }
500
+ ```
501
+
502
+ - A variant that cannot be made fails the build, naming each one: a page that
503
+ names it would show a broken image.
504
+ - More than `maxFiles` (20,000 by default, Cloudflare Pages' free limit) fails
505
+ the build.
506
+ - A static host sends what its `_headers` says. Add `headersRule()` (what the
507
+ server sends a variant) to `public/_headers`; given that file's text as
508
+ `headersFile`, the build fails without it, since Pages would otherwise serve
509
+ every variant with `max-age=0`.
510
+ - With `Variants` on disk, a second build writes without encoding again.
511
+
512
+ ### On Cloudflare
513
+
514
+ `foldkit-media/cloudflare` gives the services from a Worker's bindings, and
515
+ `serveFetch` is the Worker:
516
+
517
+ ```ts
518
+ export default {
519
+ fetch: serveFetch<WorkerEnv>({
520
+ images: {
521
+ layer: env =>
522
+ Layer.mergeAll(
523
+ originalsR2(env.MEDIA),
524
+ transformerImages(env.IMAGES),
525
+ variantsR2(env.MEDIA, { cache: true }),
526
+ admissionRateLimit(env.LIMITER),
527
+ ),
528
+ },
529
+ uploads: {
530
+ layer: env =>
531
+ Layer.mergeAll(
532
+ uploadsR2(env.MEDIA),
533
+ inspectorImages(env.IMAGES),
534
+ uploadPolicyBearer(env.UPLOAD_TOKEN),
535
+ ),
536
+ },
537
+ // The application's own routes.
538
+ otherwise: async () => new Response('Not found', { status: 404 }),
539
+ }),
540
+ }
541
+ ```
542
+
543
+ - `transformerImages(images)` is the Images binding: it scales down, never up,
544
+ and names the format. Cloudflare's code for a spent allowance (9422) is the
545
+ 503; any other refusal is the 502, its reason logged.
546
+ - `keyValueStoreR2(bucket)` is an R2 bucket as a `KeyValueStore`, for the
547
+ store adapters above or the application's own (`clear` and `size` list the
548
+ bucket).
549
+ - `variantsR2(bucket, { prefix?, cache? })` is `variantsKeyValueStore` over
550
+ it, so a variant made last month is not made, and billed, again. Two misses
551
+ for one variant at the same moment both make it, since a Worker request
552
+ cannot wait on another's; with
553
+ `cache`, the Cache API is read first and filled from R2: `true` for the
554
+ Worker's `caches.default`, or a cache of your own (`await caches.open(…)`).
555
+ `true` outside a Worker throws where the layer is made.
556
+ - `originalsR2(bucket)` streams an original rather than reading it into
557
+ memory, unlike the general adapter.
558
+
559
+ Cloudflare bills each new width of each original once a month (format and
560
+ quality do not count), so the ladder is the cost: eight widths are at most
561
+ eight transformations an original. `examples/cloudflare` is such a Worker,
562
+ with Remote and Sync as its `otherwise`.
563
+
564
+ ## Icons
565
+
566
+ An icon is data too: `IconData` holds its `viewBox`, what its root paints
567
+ (`fill`, `stroke`), and its drawing as nodes, never markup to set as HTML. An
568
+ application imports icons by name, and the build reads them:
569
+
570
+ ```ts
571
+ // vite.config.ts
572
+ import { icons } from 'foldkit-media/vite'
573
+ import { defineConfig } from 'vite'
574
+
575
+ export default defineConfig({
576
+ plugins: [icons({ iconify: ['lucide'], folders: { app: './src/icons' } })],
577
+ })
578
+ ```
579
+
580
+ ```ts
581
+ import { arrowLeft } from 'virtual:foldkit-icons/lucide'
582
+ import { logo } from 'virtual:foldkit-icons/app'
583
+ ```
584
+
585
+ `iconify` names Iconify sets by prefix, each read from the application's
586
+ `@iconify-json/<prefix>` (any set: `lucide`, `uil`, `mdi`); `folders` names
587
+ the application's own sets, a folder of SVG files each named by its file
588
+ (`star-filled.svg` is `starFilled`). The import is the selection: the bundler
589
+ drops every icon nothing imports. The plugin writes `foldkit-icons.d.ts` at
590
+ the root (`dts` moves it, `false` writes none), declaring every icon of every
591
+ set, so a misspelt name is a type error; include it in the `tsconfig`.
592
+
593
+ A view draws an icon with `Icon.draw(icon, h)`: inline SVG through the view's
594
+ builder (Foldkit's `h`, or anything of its shape, `SvgBuilder`), every
595
+ attribute in the server's markup, `1em` square unless `size` is given, and
596
+ `aria-hidden`, since the control it sits in carries the name.
597
+ `foldkit-mixins-ui`'s `Icon.view({ icon, label? })` draws it into its glyph,
598
+ sized by the recipe, and names it when given a `label`. A style masks with `Icon.maskUrl(icon)`, a CSS `url()`.
599
+
600
+ Every icon is parsed against a presentational allowlist, because it is drawn
601
+ inline. The parse refuses, naming the icon, an element or attribute outside
602
+ it (`script`, `style`, `foreignObject`, an animation, an event, a `class`),
603
+ an `href` or `url()` that leaves the icon or names an id it does not define,
604
+ a CSS function other than a colour, a transform or `url()` (a mask's
605
+ `image-set()` would fetch an image), and a CSS escape. It drops the root's
606
+ size and namespaces, comments and declarations, and the words of `title`,
607
+ `desc` and `metadata`, which a label replaces. A
608
+ refused SVG in a folder fails the build. A refused icon of an Iconify set is
609
+ left out, the declaration says why, and only importing it fails.
610
+
611
+ A package cannot rely on an application's plugin, so it commits its icons as
612
+ constants, read by `foldkit-media/icons` in a script (in this repository,
613
+ `pnpm icons` writes them from a package's `icons.json`):
614
+
615
+ ```ts
616
+ import { Icon } from 'foldkit-media'
617
+ import { parse } from 'foldkit-media/icons'
618
+
619
+ const check = parse(
620
+ '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor"><path d="M20 6 9 17l-5-5"/></svg>',
621
+ 'check',
622
+ )
623
+ Icon.maskUrl(check) // url("data:image/svg+xml,…") for a mask
624
+ ```
625
+
626
+ `fromIconify(set, name)` reads one icon of an Iconify set's JSON (decoded
627
+ with the `IconifySet` Schema), through its aliases. `Icon.key(icon)` is a
628
+ short name from the icon's content, the same on a server and in a browser;
629
+ `Icon.prefixIds(icon, prefix)` renames the ids the icon defines and every
630
+ `href` and `url()` naming one, so two icons drawn on one page keep their own.
631
+ `Icon.draw` does both; its `key` option sets two copies of one icon apart,
632
+ because a gradient defined in a hidden copy paints nothing for a shown one.
633
+
634
+ ## Validation
635
+
636
+ Facts are untrusted input. `ImageAsset` refuses an image with no pixels, and a
637
+ `Placeholder.Color` that is anything but one CSS color (no `;`, no `url(`),
638
+ since it lands in a style the page writes.
package/client.d.ts ADDED
@@ -0,0 +1,10 @@
1
+ /**
2
+ * The type of a `?image` import, for an application using `foldkit-media/vite`'s
3
+ * `images` plugin: add `"foldkit-media/client"` to the tsconfig's `types`.
4
+ */
5
+ declare module '*?image' {
6
+ import type { HashedAsset, Provider } from 'foldkit-media'
7
+
8
+ const image: { readonly asset: HashedAsset; readonly provider: Provider.Provider }
9
+ export default image
10
+ }