foldkit 0.57.0 → 0.58.0

package/README.md

@@ -13,7 +13,7 @@
 <h3 align="center">The frontend framework for correctness.</h3>
 
 <p align="center">
-  <a href="https://foldkit.dev"><strong>Documentation</strong></a> · <a href="https://foldkit.dev/example-apps"><strong>Examples</strong></a> · <a href="https://foldkit.dev/getting-started"><strong>Getting Started</strong></a>
+  <a href="https://foldkit.dev"><strong>Documentation</strong></a> · <a href="https://foldkit.dev/manifesto"><strong>Manifesto</strong></a> · <a href="https://foldkit.dev/example-apps"><strong>Examples</strong></a> · <a href="https://foldkit.dev/getting-started"><strong>Getting Started</strong></a>
 </p>
 
 ---
@@ -33,6 +33,10 @@ It's not incremental. There's no React interop, no escape hatch from Effect, no
 
 Every Foldkit application is an [Effect](https://effect.website/) program. Your Model is a [Schema](https://effect.website/docs/schema/introduction/). Side effects are values you return, not callbacks you fire — the runtime handles when and how. If you already know Effect, Foldkit feels natural. If you're new to Effect, Foldkit is a great way to immerse yourself in it.
 
+## Coming from React?
+
+[Coming from React](https://foldkit.dev/coming-from-react) is a guided walk through the differences. [Foldkit vs React: Side by Side](https://foldkit.dev/foldkit-vs-react-side-by-side) implements the same pixel-art editor in both frameworks so you can read them line by line.
+
 ## Get Started
 
 `create-foldkit-app` is the recommended way to start a new project. It scaffolds a complete setup with Tailwind, TypeScript, ESLint, Prettier, and the Vite plugin for state-preserving HMR — and lets you choose from a set of examples as your starting point.
@@ -136,16 +140,21 @@ Source: [examples/counter/src/main.ts](https://github.com/foldkit/foldkit/blob/m
 
 Foldkit is a complete system, not a collection of libraries you stitch together.
 
-- **Commands** — Side effects are named Effects that return Messages and are executed by the runtime. Each Command has a `name` for identification in tracing and testing, and an `effect` that the runtime runs. Use any Effect combinator you want — retry, timeout, race, parallel.
-- **Routing** — Type-safe bidirectional routing. URLs parse into typed routes and routes build back into URLs. No string matching, no mismatches between parsing and building.
-- **Subscriptions** — Declare which streams your app needs as a function of the Model. The runtime diffs and switches them when the Model changes.
-- **Managed Resources** — Model-driven lifecycle for long-lived browser resources like WebSockets, AudioContext, and RTCPeerConnection. Acquire on state change, release on cleanup.
-- **UI Components** — Dialog, menu, tabs, listbox, disclosure — fully accessible primitives that are easy to style and customize.
-- **Field Validation** — Per-field validation state modeled as a discriminated union. Define rules as data, apply them in update, and the Model tracks the result.
-- **Virtual DOM** — Declarative Views powered by [Snabbdom](https://github.com/snabbdom/snabbdom). Fast, keyed diffing. Views are plain functions of your Model.
-- **DevTools** — Built-in overlay for inspecting Messages, Model state, and Commands. Time-travel mode lets you jump to any point in your app's history.
-- **Testing** — Simulate the update loop in tests. Send Messages, resolve Commands inline, and assert on the Model. No mocking libraries, no fake timers, no setup or teardown.
-- **HMR** — Vite plugin with state-preserving hot module replacement. Change your view, keep your state.
+- **Commands**: Side effects are named Effects that return Messages and are executed by the runtime. Define them with `Command.define`, passing the result Message schemas so the Effect's return type stays in lockstep with your Messages. Use any Effect combinator you want: retry, timeout, race, parallel. You write the Effect, the runtime runs it.
+- **Routing**: Type-safe bidirectional routing built from parser combinators. URLs parse into typed Routes and Routes build back into URLs. No string matching, no mismatches between parsing and building.
+- **Subscriptions**: Declare which streams your app needs as a function of the Model. The runtime diffs and switches them as the Model changes.
+- **Managed Resources**: Model-driven lifecycle for long-lived browser resources like WebSockets, AudioContext, and RTCPeerConnection. Acquire on state change, release on cleanup.
+- **Submodels**: A pattern for composing nested modules. A child owns its own Model, Messages, update function, and view; the parent embeds it and wraps child Messages in a `Got*Message` envelope. The pattern scales unchanged from a login form to a multi-page app.
+- **OutMessage**: A typed channel for a child Submodel to emit domain events up to its parent, so the parent reacts to meaningful facts instead of internal child Messages.
+- **UI Components**: Accessible, keyboard-friendly primitives covering Button, Checkbox, Combobox, Dialog, Disclosure, DragAndDrop, Fieldset, Input, Listbox, Menu, Popover, RadioGroup, Select, Switch, Tabs, Textarea, and Transition. Every component is a Submodel with a typed `ViewConfig`, domain-event callbacks like `onSelected`, `onClosed`, and `onToggled`, and `className` plus `attributes` props on every slot for styling and extension. Animated components share a `Transition` Submodel that coordinates CSS enter and leave animations.
+- **Field Validation**: Per-field validation state modeled as a discriminated union. Define rules as data, apply them in update, and the Model tracks the result.
+- **Virtual DOM**: Declarative views powered by [Snabbdom](https://github.com/snabbdom/snabbdom), with lazy memoization and fast, keyed diffing. Views are plain functions of your Model.
+- **DevTools**: Built-in overlay for inspecting Messages, Model state, and Commands. Time-travel mode lets you jump to any point in history, Inspect mode browses snapshots without pausing, and Submodel drill-in filtering scopes the Message list to any nested module.
+- **Crash View and Reporting**: Configure `crash.view` to render a custom fallback UI when the update loop throws. A `crash.report` callback fires first with the error, Model, and triggering Message, so you can ship it straight to Sentry or your logger.
+- **Story Testing**: Exercise the update function directly. Send Messages, resolve Commands inline with `resolve` and `resolveAll`, and assert with focused helpers: `Story.model`, `Story.expectHasCommands`, `Story.expectExactCommands`, `Story.expectNoCommands`, and `Story.expectOutMessage`. No mocking libraries, no fake timers.
+- **Scene Testing**: Drive your app the way a user does. Scene renders your real view, then clicks buttons, types into inputs, presses keys, and asserts on what's on screen. Accessible locators (`role`, `label`, `placeholder`, `altText`, `title`, `testId`, `displayValue`) with full options (`name`, `level`, `checked`, `selected`, `pressed`, `expanded`, `disabled`), multi-match `Scene.all` with `Scene.filter` and `Scene.nth`, scoped steps via `Scene.inside`, pointer events, event bubbling, and Vitest matchers like `toHaveText`, `toBeVisible`, `toHaveAccessibleName`, and `toHaveCount`. API parity with React Testing Library and Playwright, without a browser.
+- **Slow-View Monitoring**: Wire `slowView` on `makeProgram` to catch renders that exceed a threshold you set. The callback fires with the current Model, the triggering Message, and the render duration, so you can log it, sample it, or ship it to your observability tool.
+- **HMR**: Vite plugin with state-preserving hot module replacement. Change your view, keep your state.
 
 ## Correctness You (And Your LLM) Can See
 
@@ -168,6 +177,7 @@ This is what makes Foldkit unusually AI-friendly. The same property that makes t
 - **[Shopping Cart](https://foldkit.dev/example-apps/shopping-cart)** — Nested models and complex state
 - **[WebSocket Chat](https://foldkit.dev/example-apps/websocket-chat)** — Managed Resources with WebSocket integration
 - **[Kanban](https://foldkit.dev/example-apps/kanban)** — Drag-and-drop kanban board with cross-column reordering and keyboard navigation
+- **[Pixel Art](https://foldkit.dev/example-apps/pixel-art)** — Grid-based pixel editor with painting, erasing, and palette selection
 - **[UI Showcase](https://foldkit.dev/example-apps/ui-showcase)** — Interactive showcase of every Foldkit UI component
 - **[Typing Game](https://github.com/foldkit/foldkit/tree/main/packages/typing-game)** — Multiplayer typing game with Effect RPC backend ([play it live](https://typingterminal.com))
 

package/dist/file/error.d.ts

@@ -0,0 +1,10 @@
+declare const FileReadError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => import("effect/Cause").YieldableError & {
+    readonly _tag: "FileReadError";
+} & Readonly<A>;
+/** Error raised when a `FileReader` operation fails. */
+export declare class FileReadError extends FileReadError_base<{
+    readonly reason: string;
+}> {
+}
+export {};
+//# sourceMappingURL=error.d.ts.map

package/dist/file/error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error.d.ts","sourceRoot":"","sources":["../../src/file/error.ts"],"names":[],"mappings":";;;AAEA,wDAAwD;AACxD,qBAAa,aAAc,SAAQ,mBAAkC;IACnE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CACxB,CAAC;CAAG"}

package/dist/file/error.js

@@ -0,0 +1,4 @@
+import { Data } from 'effect';
+/** Error raised when a `FileReader` operation fails. */
+export class FileReadError extends Data.TaggedError('FileReadError') {
+}

package/dist/file/file.d.ts

@@ -0,0 +1,24 @@
+import { Schema as S } from 'effect';
+/**
+ * A file selected by the user. Direct alias for the browser's native `File`
+ * type — opaque by convention (Foldkit never constructs files itself, only
+ * receives them from `File.select`, `File.selectMultiple`, or from
+ * `OnFileChange`/`OnDropFiles` event attributes).
+ */
+export type File = globalThis.File;
+/**
+ * Schema that accepts any value that is an instance of the DOM `File` class.
+ * Use in Model fields that hold user-selected files:
+ *
+ * ```ts
+ * attachedResume: S.OptionFromSelf(File.File)
+ * ```
+ */
+export declare const File: S.Schema<File>;
+/** The file's name including extension, as reported by the browser. */
+export declare const name: (file: File) => string;
+/** The file's size in bytes. */
+export declare const size: (file: File) => number;
+/** The file's MIME type (e.g. `"application/pdf"`), or empty string if the browser cannot determine one. */
+export declare const mimeType: (file: File) => string;
+//# sourceMappingURL=file.d.ts.map

package/dist/file/file.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file.d.ts","sourceRoot":"","sources":["../../src/file/file.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,IAAI,CAAC,EAAE,MAAM,QAAQ,CAAA;AAEpC;;;;;GAKG;AACH,MAAM,MAAM,IAAI,GAAG,UAAU,CAAC,IAAI,CAAA;AAElC;;;;;;;GAOG;AACH,eAAO,MAAM,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,IAAI,CAAiC,CAAA;AAEjE,uEAAuE;AACvE,eAAO,MAAM,IAAI,GAAI,MAAM,IAAI,KAAG,MAAmB,CAAA;AAErD,gCAAgC;AAChC,eAAO,MAAM,IAAI,GAAI,MAAM,IAAI,KAAG,MAAmB,CAAA;AAErD,4GAA4G;AAC5G,eAAO,MAAM,QAAQ,GAAI,MAAM,IAAI,KAAG,MAAmB,CAAA"}

package/dist/file/file.js

@@ -0,0 +1,16 @@
+import { Schema as S } from 'effect';
+/**
+ * Schema that accepts any value that is an instance of the DOM `File` class.
+ * Use in Model fields that hold user-selected files:
+ *
+ * ```ts
+ * attachedResume: S.OptionFromSelf(File.File)
+ * ```
+ */
+export const File = S.instanceOf(globalThis.File);
+/** The file's name including extension, as reported by the browser. */
+export const name = (file) => file.name;
+/** The file's size in bytes. */
+export const size = (file) => file.size;
+/** The file's MIME type (e.g. `"application/pdf"`), or empty string if the browser cannot determine one. */
+export const mimeType = (file) => file.type;

package/dist/file/index.d.ts

@@ -0,0 +1,5 @@
+export { File, mimeType, name, size } from './file';
+export { FileReadError } from './error';
+export { select, selectMultiple } from './select';
+export { readAsArrayBuffer, readAsDataUrl, readAsText } from './reader';
+//# sourceMappingURL=index.d.ts.map

package/dist/file/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/file/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAA;AACnD,OAAO,EAAE,aAAa,EAAE,MAAM,SAAS,CAAA;AACvC,OAAO,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,UAAU,CAAA;AACjD,OAAO,EAAE,iBAAiB,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA"}

package/dist/file/index.js

@@ -0,0 +1,4 @@
+export { File, mimeType, name, size } from './file';
+export { FileReadError } from './error';
+export { select, selectMultiple } from './select';
+export { readAsArrayBuffer, readAsDataUrl, readAsText } from './reader';

package/dist/file/public.d.ts

@@ -0,0 +1,2 @@
+export { File, FileReadError, mimeType, name, readAsArrayBuffer, readAsDataUrl, readAsText, select, selectMultiple, size, } from './index';
+//# sourceMappingURL=public.d.ts.map

package/dist/file/public.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"public.d.ts","sourceRoot":"","sources":["../../src/file/public.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,IAAI,EACJ,aAAa,EACb,QAAQ,EACR,IAAI,EACJ,iBAAiB,EACjB,aAAa,EACb,UAAU,EACV,MAAM,EACN,cAAc,EACd,IAAI,GACL,MAAM,SAAS,CAAA"}

package/dist/file/public.js

@@ -0,0 +1 @@
+export { File, FileReadError, mimeType, name, readAsArrayBuffer, readAsDataUrl, readAsText, select, selectMultiple, size, } from './index';

package/dist/file/reader.d.ts

@@ -0,0 +1,56 @@
+import { Effect } from 'effect';
+import { FileReadError } from './error';
+import type { File } from './file';
+/**
+ * Reads the file's contents as a UTF-8 string. Mirrors Elm's `File.toString`.
+ *
+ * Fails with a `FileReadError` if the browser's `FileReader` encounters an
+ * error (e.g. the file was deleted while reading). Handle failures with
+ * `Effect.catchAll` to convert them into a failure Message.
+ *
+ * @example
+ * ```typescript
+ * ReadResumeText(
+ *   File.readAsText(file).pipe(
+ *     Effect.map(text => GotResumeText({ text })),
+ *     Effect.catchAll(error => Effect.succeed(FailedReadResume({ error: error.reason }))),
+ *   ),
+ * )
+ * ```
+ */
+export declare const readAsText: (file: File) => Effect.Effect<string, FileReadError>;
+/**
+ * Reads the file's contents as a base64-encoded data URL. Useful for rendering
+ * image previews without uploading the file first. Mirrors Elm's `File.toUrl`.
+ *
+ * @example
+ * ```typescript
+ * ReadImagePreview(
+ *   File.readAsDataUrl(imageFile).pipe(
+ *     Effect.map(dataUrl => GotImagePreview({ dataUrl })),
+ *     Effect.catchAll(error => Effect.succeed(FailedReadImage({ error: error.reason }))),
+ *   ),
+ * )
+ * ```
+ */
+export declare const readAsDataUrl: (file: File) => Effect.Effect<string, FileReadError>;
+/**
+ * Reads the file's contents as raw binary data. Mirrors Elm's `File.toBytes`.
+ *
+ * Use this when you need the full binary payload (e.g. to upload, hash, or
+ * parse a custom file format). For images you usually want `readAsDataUrl`
+ * instead.
+ *
+ * @example
+ * ```typescript
+ * UploadFile(
+ *   File.readAsArrayBuffer(file).pipe(
+ *     Effect.flatMap(buffer => uploadToServer(buffer)),
+ *     Effect.map(() => SucceededUpload()),
+ *     Effect.catchAll(error => Effect.succeed(FailedUpload({ reason: String(error) }))),
+ *   ),
+ * )
+ * ```
+ */
+export declare const readAsArrayBuffer: (file: File) => Effect.Effect<ArrayBuffer, FileReadError>;
+//# sourceMappingURL=reader.d.ts.map

package/dist/file/reader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reader.d.ts","sourceRoot":"","sources":["../../src/file/reader.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AAE/B,OAAO,EAAE,aAAa,EAAE,MAAM,SAAS,CAAA;AACvC,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAA;AAoDlC;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,UAAU,GAAI,MAAM,IAAI,KAAG,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,aAAa,CAGxE,CAAA;AAEH;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,aAAa,GACxB,MAAM,IAAI,KACT,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,aAAa,CAGnC,CAAA;AAEH;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,iBAAiB,GAC5B,MAAM,IAAI,KACT,MAAM,CAAC,MAAM,CAAC,WAAW,EAAE,aAAa,CAGxC,CAAA"}

package/dist/file/reader.js

@@ -0,0 +1,92 @@
+import { Effect } from 'effect';
+import { FileReadError } from './error';
+const readFile = (file, mode, extract) => Effect.async((resume, signal) => {
+    const reader = new FileReader();
+    const handleLoad = () => {
+        const extracted = extract(reader);
+        if (extracted === null) {
+            resume(Effect.fail(new FileReadError({
+                reason: `FileReader returned an unexpected result type for mode "${mode}"`,
+            })));
+        }
+        else {
+            resume(Effect.succeed(extracted));
+        }
+    };
+    const handleError = () => {
+        const reason = reader.error?.message ?? 'Unknown FileReader error';
+        resume(Effect.fail(new FileReadError({ reason })));
+    };
+    reader.addEventListener('load', handleLoad);
+    reader.addEventListener('error', handleError);
+    signal.addEventListener('abort', () => {
+        reader.abort();
+    });
+    try {
+        if (mode === 'text') {
+            reader.readAsText(file);
+        }
+        else if (mode === 'dataUrl') {
+            reader.readAsDataURL(file);
+        }
+        else {
+            reader.readAsArrayBuffer(file);
+        }
+    }
+    catch (thrown) {
+        const reason = thrown instanceof Error ? thrown.message : String(thrown);
+        resume(Effect.fail(new FileReadError({ reason })));
+    }
+});
+/**
+ * Reads the file's contents as a UTF-8 string. Mirrors Elm's `File.toString`.
+ *
+ * Fails with a `FileReadError` if the browser's `FileReader` encounters an
+ * error (e.g. the file was deleted while reading). Handle failures with
+ * `Effect.catchAll` to convert them into a failure Message.
+ *
+ * @example
+ * ```typescript
+ * ReadResumeText(
+ *   File.readAsText(file).pipe(
+ *     Effect.map(text => GotResumeText({ text })),
+ *     Effect.catchAll(error => Effect.succeed(FailedReadResume({ error: error.reason }))),
+ *   ),
+ * )
+ * ```
+ */
+export const readAsText = (file) => readFile(file, 'text', reader => typeof reader.result === 'string' ? reader.result : null);
+/**
+ * Reads the file's contents as a base64-encoded data URL. Useful for rendering
+ * image previews without uploading the file first. Mirrors Elm's `File.toUrl`.
+ *
+ * @example
+ * ```typescript
+ * ReadImagePreview(
+ *   File.readAsDataUrl(imageFile).pipe(
+ *     Effect.map(dataUrl => GotImagePreview({ dataUrl })),
+ *     Effect.catchAll(error => Effect.succeed(FailedReadImage({ error: error.reason }))),
+ *   ),
+ * )
+ * ```
+ */
+export const readAsDataUrl = (file) => readFile(file, 'dataUrl', reader => typeof reader.result === 'string' ? reader.result : null);
+/**
+ * Reads the file's contents as raw binary data. Mirrors Elm's `File.toBytes`.
+ *
+ * Use this when you need the full binary payload (e.g. to upload, hash, or
+ * parse a custom file format). For images you usually want `readAsDataUrl`
+ * instead.
+ *
+ * @example
+ * ```typescript
+ * UploadFile(
+ *   File.readAsArrayBuffer(file).pipe(
+ *     Effect.flatMap(buffer => uploadToServer(buffer)),
+ *     Effect.map(() => SucceededUpload()),
+ *     Effect.catchAll(error => Effect.succeed(FailedUpload({ reason: String(error) }))),
+ *   ),
+ * )
+ * ```
+ */
+export const readAsArrayBuffer = (file) => readFile(file, 'arrayBuffer', reader => reader.result instanceof ArrayBuffer ? reader.result : null);

package/dist/file/select.d.ts

@@ -0,0 +1,36 @@
+import { Effect } from 'effect';
+import type { File } from './file';
+/**
+ * Opens the native file picker allowing a single file to be selected. Resolves
+ * with an array containing the selected file, or an empty array if the user
+ * cancelled. Mirrors Elm's `File.Select.file`.
+ *
+ * The `accept` argument is a list of MIME types or file extensions that
+ * restrict what the picker shows. Pass an empty array to allow any file.
+ *
+ * @example
+ * ```typescript
+ * SelectResume(
+ *   File.select(['application/pdf']).pipe(
+ *     Effect.map(files => SelectedResume({ files })),
+ *   ),
+ * )
+ * ```
+ */
+export declare const select: (accept: ReadonlyArray<string>) => Effect.Effect<ReadonlyArray<File>>;
+/**
+ * Opens the native file picker allowing multiple files to be selected at
+ * once. Resolves with the array of selected files, or an empty array if the
+ * user cancelled. Mirrors Elm's `File.Select.files`.
+ *
+ * @example
+ * ```typescript
+ * SelectAttachments(
+ *   File.selectMultiple(['image/*', 'application/pdf']).pipe(
+ *     Effect.map(files => SelectedAttachments({ files })),
+ *   ),
+ * )
+ * ```
+ */
+export declare const selectMultiple: (accept: ReadonlyArray<string>) => Effect.Effect<ReadonlyArray<File>>;
+//# sourceMappingURL=select.d.ts.map

package/dist/file/select.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"select.d.ts","sourceRoot":"","sources":["../../src/file/select.ts"],"names":[],"mappings":"AAAA,OAAO,EAAS,MAAM,EAAE,MAAM,QAAQ,CAAA;AAEtC,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAA;AA2ClC;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,MAAM,GACjB,QAAQ,aAAa,CAAC,MAAM,CAAC,KAC5B,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,IAAI,CAAC,CAA4C,CAAA;AAEhF;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,cAAc,GACzB,QAAQ,aAAa,CAAC,MAAM,CAAC,KAC5B,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,IAAI,CAAC,CAA2C,CAAA"}

package/dist/file/select.js

@@ -0,0 +1,60 @@
+import { Array, Effect } from 'effect';
+const openPicker = ({ accept, multiple, }) => Effect.async((resume, signal) => {
+    const input = document.createElement('input');
+    input.type = 'file';
+    input.accept = accept.join(',');
+    input.multiple = multiple;
+    input.style.display = 'none';
+    const cleanup = () => {
+        input.remove();
+    };
+    const handleChange = () => {
+        const files = input.files
+            ? Array.fromIterable(input.files)
+            : Array.empty();
+        cleanup();
+        resume(Effect.succeed(files));
+    };
+    const handleCancel = () => {
+        cleanup();
+        resume(Effect.succeed(Array.empty()));
+    };
+    input.addEventListener('change', handleChange);
+    input.addEventListener('cancel', handleCancel);
+    signal.addEventListener('abort', cleanup);
+    document.body.appendChild(input);
+    input.click();
+});
+/**
+ * Opens the native file picker allowing a single file to be selected. Resolves
+ * with an array containing the selected file, or an empty array if the user
+ * cancelled. Mirrors Elm's `File.Select.file`.
+ *
+ * The `accept` argument is a list of MIME types or file extensions that
+ * restrict what the picker shows. Pass an empty array to allow any file.
+ *
+ * @example
+ * ```typescript
+ * SelectResume(
+ *   File.select(['application/pdf']).pipe(
+ *     Effect.map(files => SelectedResume({ files })),
+ *   ),
+ * )
+ * ```
+ */
+export const select = (accept) => openPicker({ accept, multiple: false });
+/**
+ * Opens the native file picker allowing multiple files to be selected at
+ * once. Resolves with the array of selected files, or an empty array if the
+ * user cancelled. Mirrors Elm's `File.Select.files`.
+ *
+ * @example
+ * ```typescript
+ * SelectAttachments(
+ *   File.selectMultiple(['image/*', 'application/pdf']).pipe(
+ *     Effect.map(files => SelectedAttachments({ files })),
+ *   ),
+ * )
+ * ```
+ */
+export const selectMultiple = (accept) => openPicker({ accept, multiple: true });

package/dist/html/index.d.ts

@@ -1,7 +1,18 @@
 import { Data, Effect, Option } from 'effect';
+import type { File } from '../file';
 import { Dispatch } from '../runtime';
 import { VNode } from '../vdom';
 export { createKeyedLazy, createLazy } from './lazy';
+/**
+ * Tag symbol attached to file-aware event handler functions so Scene test
+ * helpers can distinguish `OnFileChange` from `OnChange` (both register on
+ * the DOM `change` event) and `OnDropFiles` from `OnDrop` (both register on
+ * the DOM `drop` event). Internal implementation detail — consumer code
+ * should never need to reference this directly.
+ */
+export declare const FileHandlerSymbol: unique symbol;
+/** Type-level brand for file-aware event handler tags. */
+export type FileHandlerSymbol = typeof FileHandlerSymbol;
 /** Modifier key state extracted from a `KeyboardEvent`. */
 export type KeyboardModifiers = Readonly<{
     shiftKey: boolean;
@@ -130,6 +141,9 @@ export type Attribute<Message> = Data.TaggedEnum<{
     OnChange: {
         readonly f: (value: string) => Message;
     };
+    OnFileChange: {
+        readonly f: (files: ReadonlyArray<File>) => Message;
+    };
     OnSubmit: {
         readonly message: Message;
     };
@@ -181,6 +195,9 @@ export type Attribute<Message> = Data.TaggedEnum<{
     OnDrop: {
         readonly message: Message;
     };
+    OnDropFiles: {
+        readonly f: (files: ReadonlyArray<File>) => Message;
+    };
     OnTouchStart: {
         readonly message: Message;
     };
@@ -878,6 +895,9 @@ export declare const html: <Message = never>() => {
     } | {
         readonly _tag: "OnChange";
         readonly f: (value: string) => Message;
+    } | {
+        readonly _tag: "OnFileChange";
+        readonly f: (files: ReadonlyArray<File>) => Message;
     } | {
         readonly _tag: "OnSubmit";
         readonly message: Message;
@@ -929,6 +949,9 @@ export declare const html: <Message = never>() => {
     } | {
         readonly _tag: "OnDrop";
         readonly message: Message;
+    } | {
+        readonly _tag: "OnDropFiles";
+        readonly f: (files: ReadonlyArray<File>) => Message;
     } | {
         readonly _tag: "OnTouchStart";
         readonly message: Message;
@@ -1668,6 +1691,10 @@ export declare const html: <Message = never>() => {
         readonly _tag: "OnChange";
         readonly f: (value: string) => Message;
     };
+    OnFileChange: (f: (files: ReadonlyArray<File>) => Message) => {
+        readonly _tag: "OnFileChange";
+        readonly f: (files: ReadonlyArray<File>) => Message;
+    };
     OnSubmit: (message: Message) => {
         readonly _tag: "OnSubmit";
         readonly message: Message;
@@ -1736,6 +1763,10 @@ export declare const html: <Message = never>() => {
         readonly _tag: "OnDrop";
         readonly message: Message;
     };
+    OnDropFiles: (f: (files: ReadonlyArray<File>) => Message) => {
+        readonly _tag: "OnDropFiles";
+        readonly f: (files: ReadonlyArray<File>) => Message;
+    };
     OnTouchStart: (message: Message) => {
         readonly _tag: "OnTouchStart";
         readonly message: Message;