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