@hyper-effect/core 0.0.0-stage → 0.1.0-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Potti1234
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,55 @@
-# Temporary Holding Version
-
-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.
+# @hyper-effect/core
+
+Foldkit programs whose loop runs on the server, on Effect, rendered with Foldkit views and driven by Datastar in the browser.
+
+```ts
+import * as Hyper from '@hyper-effect/core'
+
+HttpRouter.serve(
+  Layer.mergeAll(
+    Hyper.layer(Board.program, { path: '/', stylesheets: ['/styles.css'] }),
+    Hyper.layer(Incident.program, { path: '/incidents/:id' }),
+  ),
+)
+```
+
+A `Program` is Foldkit's application shape plus what a server needs:
+- a `name` for its endpoints;
+- `Model` and `ClientMessage` Schemas (snapshots, unforgeable events);
+- effectful, request-aware `flags`, which can fail with `PageNotFound` or `PageRedirect`.
+
+## Exports
+
+| Entry | Contents |
+|---|---|
+| `@hyper-effect/core` | `layer`, `Options`, `Limits`, `Program`, `PageRequest`, `PageNotFound`, `PageRedirect`, `RequestContext`, `ContentSecurityPolicy`, `Secret`, `region`, `shared`, `keyBindings`, `sampleLatest`, `memoizeLast`, `nodeOfPath`, `fileStore`, `sqlStore`, `foldkitUiCommands`, `metricsRoutes` |
+| `@hyper-effect/core/binding` | Event-to-Datastar rewriting, for packages that render their own elements (islands) |
+| `@hyper-effect/core/builder` | The server `HtmlBuilder` and `binderOf` |
+| `@hyper-effect/core/testing` | `serve` (with the program's services as a Layer), `openPage`, `postEvent`, `openStream`, `readUntil`, `makeStore`, `waitForSnapshot`, `token`, `renderModel` |
+
+## Options worth knowing
+
+| Option | Default | What it does |
+|---|---|---|
+| `principal` | none | Who a request acts for; sessions are bound to it |
+| `contentSecurityPolicy` | on | Nonce-based policy; add sources per directive, `reportOnly`, or `false` |
+| `snapshotSecret` | none | Seals snapshots (AES-256-GCM); a list rotates secrets |
+| `snapshotTtl` | `1 day` | Older snapshots no longer restore a session |
+| `compression` | `false` | Brotli (or gzip) per event stream, one compressor per stream flushed after each patch |
+| `durableEvents` | `true` | Answer an event only once it is in the snapshot store, so a failing process loses no answered event; `false` snapshots a quiet second later |
+| `trustProxy` | `0` | Proxies whose `X-Forwarded-For` / `X-Forwarded-Host` entries count |
+| `node` | none | This process's name when several serve one app: session ids become `<node>.<uuid>`, for routing (`nodeOfPath`) |
+| `allowedOrigins` | `[]` | Extra origins allowed to post events |
+| `limits` | see `server.ts` | Body size, event rate, page rate per client, upload bytes and files, sessions per visitor and per program |
+
+`Program.snapshotDeps` (on the program, not an option) names the session's own state; outside events, snapshots are written only when it, or the intake position, changes.
+
+Snapshots go to the `KeyValueStore` the app provides:
+- `fileStore(directory)` keeps them in files, for development and for processes on one machine. Its writes replace a file whole (Effect's `KeyValueStore.layerFileSystem` writes in place, and a process killed mid-write leaves a snapshot that cannot be read).
+- `sqlStore({ table, ttl, purgeEvery })` keeps them in a SQL database through Effect's `SqlClient` (the app provides the driver, such as `@effect/sql-pg`), for processes on several machines. Writes are one upsert; rows expire `ttl` after their last write, are never read after, and are purged periodically, which deletes the snapshots of sessions whose process failed.
+
+Event streams carry `X-Accel-Buffering: no`, so nginx and proxies that honour it pass patches through at once; see [docs/deployment.md](../../docs/deployment.md).
+
+Environment: `NODE_ENV=production` turns off markup validation, the region deps and id checks, and stack capture in views (`HYPER_VIEW_STACKS=1` keeps the latter).
+
+Tests: `test/` (vitest), against the crease-free fixture in `test/fixtures/greeter.ts`.

package/dist/binding.d.ts

@@ -0,0 +1,84 @@
+import { Option } from 'effect';
+import type { Attribute, ChildAttribute, HtmlBuilder, KeyboardModifiers } from 'foldkit/html';
+export type Handler<Message> = Readonly<{
+    _tag: 'Value';
+    f: (value: string) => Message;
+    /** Set when the handler belongs to a client-owned input. */
+    inputId?: string;
+}> | Readonly<{
+    _tag: 'Key';
+    f: (key: string, modifiers: KeyboardModifiers) => Option.Option<Message>;
+}> | Readonly<{
+    _tag: 'Number';
+    f: (value: number) => Message;
+}> | Readonly<{
+    _tag: 'Custom';
+    name: string;
+    f: (event: CustomEvent<unknown>) => Option.Option<Message>;
+}>
+/** Event data posted as an array (pointer and beforeinput events). */
+ | Readonly<{
+    _tag: 'Args';
+    f: (args: ReadonlyArray<unknown>) => Option.Option<Message>;
+}>
+/** A constant Message that is not JSON-encodable, so it cannot be a token. */
+ | Readonly<{
+    _tag: 'Message';
+    message: Message;
+}>
+/** Files chosen or dropped, uploaded to the session (`OnFileChange`,
+ *  `OnDropFiles`). */
+ | Readonly<{
+    _tag: 'Files';
+    f: (files: ReadonlyArray<File>) => Message;
+}>;
+export interface Binder<Message> {
+    /** Path the browser posts events to. */
+    readonly endpoint: string;
+    /** Binds a Message-valued event: returns the payload fields to post
+     *  (`m: '<token>'`, or `h: '<id>'` for a Message that is not
+     *  JSON-encodable). Throws for Messages outside `ClientMessage`. */
+    readonly bindMessage: (message: Message) => string;
+    /** Registers a function-valued handler for this render and returns its id. */
+    readonly registerHandler: (handler: Handler<Message>) => string;
+    /** Registers a client-owned input and the value the Model holds for it. */
+    readonly registerInput: (inputId: string, value: string) => void;
+}
+/** Maps a child binder's Messages into the parent's, for `h.submodel`. */
+export declare const mapBinder: <Child, Parent>(parent: Binder<Parent>, toParent: (message: Child) => Parent) => Binder<Child>;
+/** Signal backing a client-owned input. Datastar camel-cases the attribute
+ *  key, so `data-bind:_hv-name` binds the signal `_hvName`. The leading
+ *  underscore keeps it out of requests. */
+export declare const inputSignal: (inputId: string) => {
+    key: string;
+    name: string;
+};
+/** Signal holding the page's event sequence number. */
+export declare const SEQUENCE_SIGNAL = "_hq";
+/** Signal holding the session's event endpoint. Keeping the session id out
+ *  of every binding makes markup that binds only Messages identical across
+ *  sessions, so it can be rendered once and shared (see `shared.ts`). */
+export declare const ENDPOINT_SIGNAL = "_he";
+/** Page-script functions the bindings call (see `server.ts`). */
+export declare const PENDING_INPUTS = "hyperPendingInputs";
+export declare const FRESH_VALUE = "hyperFreshValue";
+export declare const FOCUS = "hyperFocus";
+/** Page script function that uploads files to the session. */
+export declare const UPLOAD = "hyperUpload";
+/** Path of a session's upload endpoint, below its event endpoint. */
+export declare const UPLOAD_PATH = "/upload";
+export declare const FOCUS_KEY = "hyperFocusKey";
+export declare const COPY_TEXT = "hyperCopyText";
+/** Page script function matching key bindings (`keys.ts`). */
+export declare const KEYS = "hyperKeys";
+/** Marks a client-owned input with its value handler id. */
+export declare const INPUT_HANDLER_ATTRIBUTE = "data-hyper-input";
+export declare class UnsupportedEventError extends Error {
+    readonly tag: string;
+    constructor(tag: string);
+}
+type AnyAttribute<Message> = Attribute<Message> | ChildAttribute;
+/** Rewrites one element's attributes. */
+export declare const rewriteAttributes: <Message>(attributes: ReadonlyArray<AnyAttribute<Message>>, binder: Binder<Message>, h: HtmlBuilder<Message>, rootBinder?: Binder<unknown>) => ReadonlyArray<AnyAttribute<Message>>;
+export declare const rewriteAttribute: <Message>(attribute: AnyAttribute<Message>, binder: Binder<Message>, h: HtmlBuilder<Message>, inputId?: string, rootBinder?: Binder<unknown>) => AnyAttribute<Message>;
+export {};

package/dist/binding.js

@@ -0,0 +1,465 @@
+import { Option } from 'effect';
+import { LOCAL, LOCAL_ATTRIBUTE, eventOfBinding } from "./local.js";
+/** Maps a child binder's Messages into the parent's, for `h.submodel`. */
+export const mapBinder = (parent, toParent) => ({
+    endpoint: parent.endpoint,
+    bindMessage: message => parent.bindMessage(toParent(message)),
+    registerHandler: handler => parent.registerHandler(mapHandler(handler, toParent)),
+    registerInput: parent.registerInput,
+});
+const mapHandler = (handler, toParent) => {
+    switch (handler._tag) {
+        case 'Value': {
+            const f = (value) => toParent(handler.f(value));
+            return handler.inputId === undefined
+                ? { _tag: 'Value', f }
+                : { _tag: 'Value', f, inputId: handler.inputId };
+        }
+        case 'Number':
+            return { _tag: 'Number', f: (value) => toParent(handler.f(value)) };
+        case 'Key':
+            return {
+                _tag: 'Key',
+                f: (key, modifiers) => Option.map(handler.f(key, modifiers), toParent),
+            };
+        case 'Custom':
+            return {
+                _tag: 'Custom',
+                name: handler.name,
+                f: (event) => Option.map(handler.f(event), toParent),
+            };
+        case 'Args':
+            return {
+                _tag: 'Args',
+                f: (args) => Option.map(handler.f(args), toParent),
+            };
+        case 'Message':
+            return { _tag: 'Message', message: toParent(handler.message) };
+        case 'Files':
+            return { _tag: 'Files', f: (files) => toParent(handler.f(files)) };
+    }
+};
+/** Signal backing a client-owned input. Datastar camel-cases the attribute
+ *  key, so `data-bind:_hv-name` binds the signal `_hvName`. The leading
+ *  underscore keeps it out of requests. */
+export const inputSignal = (inputId) => {
+    const slug = inputId.toLowerCase().replace(/[^a-z0-9]/g, '');
+    return {
+        key: `_hv-${slug}`,
+        name: `_hv${slug.charAt(0).toUpperCase()}${slug.slice(1)}`,
+    };
+};
+/** Signal holding the page's event sequence number. */
+export const SEQUENCE_SIGNAL = '_hq';
+/** Signal holding the session's event endpoint. Keeping the session id out
+ *  of every binding makes markup that binds only Messages identical across
+ *  sessions, so it can be rendered once and shared (see `shared.ts`). */
+export const ENDPOINT_SIGNAL = '_he';
+/** Page-script functions the bindings call (see `server.ts`). */
+export const PENDING_INPUTS = 'hyperPendingInputs';
+export const FRESH_VALUE = 'hyperFreshValue';
+export const FOCUS = 'hyperFocus';
+/** Page script function that uploads files to the session. */
+export const UPLOAD = 'hyperUpload';
+/** Path of a session's upload endpoint, below its event endpoint. */
+export const UPLOAD_PATH = '/upload';
+export const FOCUS_KEY = 'hyperFocusKey';
+export const COPY_TEXT = 'hyperCopyText';
+/** Page script function matching key bindings (`keys.ts`). */
+export const KEYS = 'hyperKeys';
+/** Marks a client-owned input with its value handler id. */
+export const INPUT_HANDLER_ATTRIBUTE = 'data-hyper-input';
+export class UnsupportedEventError extends Error {
+    tag;
+    constructor(tag) {
+        super(`hyper-effect: the Foldkit event attribute "${tag}" has no server binding. ` +
+            'Render this part as a Foldkit island or use a supported event.');
+        this.tag = tag;
+    }
+}
+/** A value embedded in an expression, decoded by the page script. */
+const literal = (value) => `'${Buffer.from(JSON.stringify(value), 'utf8').toString('base64url')}'`;
+const THROTTLE = '__throttle.100ms';
+const LEAVES_ELEMENT = '!el.contains(evt.relatedTarget)';
+const MESSAGE_EVENTS = {
+    OnClick: { event: 'click' },
+    OnDoubleClick: { event: 'dblclick' },
+    OnMouseDown: { event: 'mousedown' },
+    OnMouseUp: { event: 'mouseup' },
+    OnMouseEnter: { event: 'mouseenter' },
+    OnMouseLeave: { event: 'mouseleave' },
+    OnMouseOver: { event: 'mouseover' },
+    OnMouseOut: { event: 'mouseout' },
+    OnMouseMove: { event: 'mousemove', modifiers: THROTTLE },
+    OnFocus: { event: 'focus' },
+    OnBlur: { event: 'blur' },
+    OnFocusEnter: { event: 'focusin', guard: LEAVES_ELEMENT },
+    OnFocusLeave: { event: 'focusout', guard: LEAVES_ELEMENT },
+    OnSubmit: { event: 'submit', modifiers: '__prevent' },
+    OnReset: { event: 'reset' },
+    OnWheel: { event: 'wheel', modifiers: THROTTLE },
+    OnCopy: { event: 'copy' },
+    OnCut: { event: 'cut' },
+    OnPaste: { event: 'paste' },
+    OnCancel: { event: 'cancel' },
+    OnContextMenu: { event: 'contextmenu' },
+    OnDragStart: { event: 'dragstart' },
+    OnDrag: { event: 'drag', modifiers: THROTTLE },
+    OnDragEnd: { event: 'dragend' },
+    OnDragEnter: { event: 'dragenter' },
+    OnDragLeave: { event: 'dragleave' },
+    OnDragOver: { event: 'dragover', modifiers: THROTTLE },
+    OnDrop: { event: 'drop', modifiers: '__prevent' },
+    OnTouchStart: { event: 'touchstart' },
+    OnTouchEnd: { event: 'touchend' },
+    OnTouchMove: { event: 'touchmove', modifiers: THROTTLE },
+    OnTouchCancel: { event: 'touchcancel' },
+    OnAnimationStart: { event: 'animationstart' },
+    OnAnimationEnd: { event: 'animationend' },
+    OnAnimationIteration: { event: 'animationiteration' },
+    OnTransitionEnd: { event: 'transitionend' },
+    OnLoad: { event: 'load' },
+    OnError: { event: 'error' },
+    OnPlay: { event: 'play' },
+    OnPause: { event: 'pause' },
+    OnEnded: { event: 'ended' },
+    OnSelect: { event: 'select' },
+};
+const VALUE_EVENTS = {
+    OnInput: 'input',
+    OnChange: 'change',
+};
+/** Keyboard handlers returning a Message for every key. */
+const KEY_EVENTS = {
+    OnKeyDown: 'keydown',
+    OnKeyDownSelf: 'keydown',
+    OnKeyUp: 'keyup',
+    OnKeyPress: 'keypress',
+};
+/** Keyboard handlers returning `Option<Message>` and preventing the default
+ *  for the keys they handle. The browser cannot ask the server synchronously,
+ *  but views are pure, so the handler is probed at render time with every
+ *  common key; the page listens for exactly the keys that produced a Message. */
+const KEY_OPTION_EVENTS = {
+    OnKeyDownPreventDefault: 'keydown',
+    OnKeyDownSelfPreventDefault: 'keydown',
+    OnKeyUpPreventDefault: 'keyup',
+};
+/** File events: the files are uploaded as multipart, not posted as JSON. The
+ *  sequence number is taken here, so an upload keeps its place among the
+ *  page's events. */
+const FILE_EVENTS = {
+    OnFileChange: { event: 'change', files: 'evt.target.files' },
+    OnDropFiles: { event: 'drop__prevent', files: 'evt.dataTransfer?.files' },
+};
+/** Pointer events, posted with their data as an argument array. The array
+ *  layout is the same for all; each handler picks its own arguments. */
+const POINTER_ARGS = 'x: [evt.pointerType, evt.button, evt.screenX, evt.screenY, evt.timeStamp, evt.clientX, evt.clientY, evt.pointerId]';
+const POINTER_EVENTS = {
+    OnPointerDown: {
+        event: 'pointerdown',
+        call: (f, [type, button, screenX, screenY, time, clientX, clientY, id]) => f(type, button, screenX, screenY, time, clientX, clientY, id, null),
+    },
+    OnPointerUp: {
+        event: 'pointerup',
+        call: (f, [type, , screenX, screenY, time]) => f(screenX, screenY, type, time),
+    },
+    OnPointerMove: {
+        event: 'pointermove',
+        modifiers: '__throttle.50ms',
+        call: (f, [type, , screenX, screenY]) => f(screenX, screenY, type),
+    },
+    OnPointerLeave: {
+        event: 'pointerleave',
+        call: (f, [type]) => f(type),
+    },
+};
+const PROBED_KEYS = [
+    'Enter',
+    'Escape',
+    ' ',
+    'Tab',
+    'ArrowUp',
+    'ArrowDown',
+    'ArrowLeft',
+    'ArrowRight',
+    'Home',
+    'End',
+    'PageUp',
+    'PageDown',
+    'Backspace',
+    'Delete',
+    // Printable ASCII, except characters Datastar treats as expression syntax.
+    ...Array.from({ length: 94 }, (_, index) => String.fromCharCode(33 + index)).filter(key => key !== '$' && key !== '@'),
+];
+const NO_MODIFIERS = {
+    shiftKey: false,
+    ctrlKey: false,
+    altKey: false,
+    metaKey: false,
+};
+const INPUT_DEBOUNCE = '__debounce.200ms';
+const SCROLL_THROTTLE = '__throttle.150ms';
+const clickModifiers = (options) => (options?.defaultAction === 'Prevent' ? '__prevent' : '') +
+    (options?.propagation === 'Stop' ? '__stop' : '');
+/** Every post also carries `p`: values typed into client-owned inputs whose
+ *  debounced post has not gone out yet (collected by the page script), so a
+ *  submit can never overtake the last keystrokes. */
+const post = (payload) => `@post($${ENDPOINT_SIGNAL}, {payload: {${payload}, q: ++$${SEQUENCE_SIGNAL}, p: window.${PENDING_INPUTS}?.() ?? {}}, requestCancellation: 'disabled'})`;
+const KEY_PAYLOAD = 'k: evt.key, s: evt.shiftKey, c: evt.ctrlKey, a: evt.altKey, mt: evt.metaKey';
+const CHILD_ATTRIBUTE_BRAND = '__childAttribute';
+const tagOf = (attribute) => typeof attribute === 'object' && attribute !== null && '_tag' in attribute
+    ? String(attribute._tag)
+    : undefined;
+const valueOf = (attributes, tag) => {
+    const found = attributes.find(attribute => tagOf(attribute) === tag);
+    /* eslint-disable-next-line @typescript-eslint/consistent-type-assertions */
+    return found === undefined ? undefined : found.value;
+};
+/** Rewrites one element's attributes. */
+export const rewriteAttributes = (attributes, binder, h, rootBinder = binder) => {
+    const id = valueOf(attributes, 'Id');
+    const value = valueOf(attributes, 'Value');
+    const sendsValue = attributes.some(attribute => {
+        const tag = tagOf(attribute);
+        return tag !== undefined && tag in VALUE_EVENTS;
+    });
+    const inputId = id !== undefined && value !== undefined && sendsValue ? id : undefined;
+    // Remember the id of the input's value handler, for the pending-input flush.
+    let valueHandlerId;
+    const elementBinder = inputId === undefined
+        ? binder
+        : {
+            ...binder,
+            registerHandler: handler => {
+                const handlerId = binder.registerHandler(handler);
+                if (handler._tag === 'Value')
+                    valueHandlerId ??= handlerId;
+                return handlerId;
+            },
+        };
+    const rewritten = withLocalEffects(attributes, attributes.map(attribute => rewriteAttribute(attribute, elementBinder, h, inputId, rootBinder)), h);
+    if (inputId === undefined || value === undefined) {
+        return rewritten;
+    }
+    binder.registerInput(inputId, value);
+    return [
+        ...rewritten,
+        h.Attribute(`data-bind:${inputSignal(inputId).key}`, ''),
+        h.Attribute('data-preserve-attr', 'value'),
+        ...(valueHandlerId === undefined
+            ? []
+            : [h.Attribute(INPUT_HANDLER_ATTRIBUTE, valueHandlerId)]),
+    ];
+};
+/** An element with local effects (`local.ts`): each binding of an event that
+ *  has effects runs them first, with the sequence number its post takes. */
+const withLocalEffects = (original, rewritten, h) => {
+    const declared = original.find(attribute => tagOf(attribute) === 'Attribute' && keyOf(attribute) === LOCAL_ATTRIBUTE);
+    if (declared === undefined)
+        return rewritten;
+    /* eslint-disable-next-line @typescript-eslint/consistent-type-assertions */
+    const events = Object.keys(JSON.parse(declared.value));
+    return rewritten.map(attribute => {
+        const key = tagOf(attribute) === 'Attribute' ? keyOf(attribute) : undefined;
+        const event = key === undefined ? undefined : eventOfBinding(key);
+        if (key === undefined || event === undefined || !events.includes(event))
+            return attribute;
+        /* eslint-disable-next-line @typescript-eslint/consistent-type-assertions */
+        const expression = attribute.value;
+        return h.Attribute(key, `(window.${LOCAL}?.(el, evt, $${SEQUENCE_SIGNAL} + 1), ${expression})`);
+    });
+};
+const keyOf = (attribute) => typeof attribute === 'object' && attribute !== null && 'key' in attribute
+    ? String(attribute.key)
+    : undefined;
+/** Lifecycle hooks that only exist in a browser runtime (focus management,
+ *  measuring, third-party widgets). The server drops them; a widget that
+ *  depends on them belongs in an island. */
+const BROWSER_ONLY = new Set(['OnMount', 'OnUnmount']);
+const warnedBrowserOnly = new Set();
+const dropBrowserOnly = (tag, h) => {
+    if (!warnedBrowserOnly.has(tag)) {
+        warnedBrowserOnly.add(tag);
+        console.warn(`hyper-effect: dropped ${tag}; it needs a browser runtime. Use an island where it matters.`);
+    }
+    return h.Attribute('data-hyper-dropped', tag);
+};
+/** Applies a ChildAttribute's `toParentMessage` chain (innermost first) to
+ *  whatever its event attribute produces, giving an attribute in the root
+ *  Message universe. */
+const liftToRoot = (attribute, mappers) => {
+    const lift = (message) => mappers.reduce((current, toParent) => toParent(current), message);
+    // OnKeyDownFocus produces `{ focusSelector, message }`; lift the message.
+    const liftValue = (value) => attribute['_tag'] === 'OnKeyDownFocus' && typeof value === 'object' && value !== null
+        ? { ...value, message: lift(value.message) }
+        : lift(value);
+    const liftResult = (result) => Option.isOption(result) ? Option.map(result, liftValue) : lift(result);
+    const f = attribute['f'];
+    const maybeCustom = attribute['maybeCustomEventMessage'];
+    return {
+        ...attribute,
+        ...('message' in attribute ? { message: lift(attribute['message']) } : {}),
+        ...(Option.isOption(maybeCustom) ? { maybeCustomEventMessage: Option.map(maybeCustom, lift) } : {}),
+        ...(typeof f === 'function'
+            ? { f: (...args) => liftResult(f(...args)) }
+            : {}),
+    };
+};
+export const rewriteAttribute = (attribute, binder, h, inputId, rootBinder = binder) => {
+    if (typeof attribute === 'object' && attribute !== null && CHILD_ATTRIBUTE_BRAND in attribute) {
+        // A Submodel's attribute placed on an element its parent builds. Its
+        // Message is the child's; lift it to the root and bind it there.
+        const inner = tagOf(attribute.attribute);
+        if (inner === undefined || !(inner.startsWith('On') || inner === 'AllowDrop')) {
+            /* eslint-disable-next-line @typescript-eslint/consistent-type-assertions */
+            return attribute.attribute;
+        }
+        if (BROWSER_ONLY.has(inner)) {
+            return dropBrowserOnly(inner, h);
+        }
+        const lifted = liftToRoot(
+        /* eslint-disable-next-line @typescript-eslint/consistent-type-assertions */
+        attribute.attribute, attribute.boundaryMappers);
+        /* eslint-disable-next-line @typescript-eslint/consistent-type-assertions */
+        return rewriteAttribute(lifted, rootBinder, h, inputId);
+    }
+    const tag = tagOf(attribute);
+    if (tag === 'AllowDrop') {
+        return h.Attribute('data-on:dragover__prevent', 'void 0');
+    }
+    if (tag === undefined || !tag.startsWith('On')) {
+        return attribute;
+    }
+    if (BROWSER_ONLY.has(tag)) {
+        return dropBrowserOnly(tag, h);
+    }
+    /* eslint-disable-next-line @typescript-eslint/consistent-type-assertions */
+    const event = attribute;
+    const bindEvent = (name, expression) => h.Attribute(`data-on:${name}`, expression);
+    const messageEvent = MESSAGE_EVENTS[tag];
+    if (messageEvent !== undefined && event.message !== undefined) {
+        const modifiers = tag === 'OnClick' ? clickModifiers(event.options) : (messageEvent.modifiers ?? '');
+        const guard = messageEvent.guard === undefined ? '' : `${messageEvent.guard} && `;
+        return bindEvent(`${messageEvent.event}${modifiers}`, `${guard}${post(binder.bindMessage(event.message))}`);
+    }
+    if (tag === 'OnCancelPreventDefault' && event.maybeCustomEventMessage !== undefined) {
+        return bindEvent('cancel__prevent', Option.match(event.maybeCustomEventMessage, {
+            onNone: () => 'void 0',
+            onSome: message => post(binder.bindMessage(message)),
+        }));
+    }
+    if (tag === 'OnClickFocus' && event.message !== undefined && event.focusSelector !== undefined) {
+        return bindEvent('click', `(window.${FOCUS}?.(${literal(event.focusSelector)}), ${post(binder.bindMessage(event.message))})`);
+    }
+    if (tag === 'OnCopyText' && event.text !== undefined) {
+        return bindEvent('copy', `window.${COPY_TEXT}?.(evt, ${literal(event.text)})`);
+    }
+    if (tag === 'OnCutText' && event.text !== undefined && event.message !== undefined) {
+        return bindEvent('cut', `(window.${COPY_TEXT}?.(evt, ${literal(event.text)}), ${post(binder.bindMessage(event.message))})`);
+    }
+    if (event.f === undefined) {
+        throw new UnsupportedEventError(tag);
+    }
+    const valueEvent = VALUE_EVENTS[tag];
+    if (valueEvent !== undefined) {
+        /* eslint-disable-next-line @typescript-eslint/consistent-type-assertions */
+        const f = event.f;
+        const id = binder.registerHandler(inputId === undefined ? { _tag: 'Value', f } : { _tag: 'Value', f, inputId });
+        return bindEvent(`${valueEvent}${tag === 'OnInput' ? INPUT_DEBOUNCE : ''}`, 
+        // A value that already went out with another event (see `p`) is not
+        // sent again: a late duplicate would undo what the server did since.
+        `window.${FRESH_VALUE}?.(el) !== false && ${post(`h: '${id}', v: evt.target.value`)}`);
+    }
+    const keyEvent = KEY_EVENTS[tag];
+    if (keyEvent !== undefined) {
+        /* eslint-disable-next-line @typescript-eslint/consistent-type-assertions */
+        const f = event.f;
+        const id = binder.registerHandler({
+            _tag: 'Key',
+            f: (key, modifiers) => Option.some(f(key, modifiers)),
+        });
+        const self = tag === 'OnKeyDownSelf' ? 'evt.target === el && ' : '';
+        return bindEvent(keyEvent, `${self}${post(`h: '${id}', ${KEY_PAYLOAD}`)}`);
+    }
+    const keyOptionEvent = KEY_OPTION_EVENTS[tag];
+    if (keyOptionEvent !== undefined) {
+        /* eslint-disable-next-line @typescript-eslint/consistent-type-assertions */
+        const f = event.f;
+        const keys = PROBED_KEYS.filter(key => Option.isSome(f(key, NO_MODIFIERS)));
+        if (keys.length === 0) {
+            return h.Attribute('data-hyper-no-keys', '');
+        }
+        const id = binder.registerHandler({ _tag: 'Key', f });
+        const self = tag === 'OnKeyDownSelfPreventDefault' ? 'evt.target === el && ' : '';
+        return bindEvent(keyOptionEvent, `${self}${JSON.stringify(keys)}.includes(evt.key) && (evt.preventDefault(), ${post(`h: '${id}', ${KEY_PAYLOAD}`)})`);
+    }
+    if (tag === 'OnKeyDownFocus') {
+        // Probing also yields where focus goes for each key, so the browser moves
+        // focus at once and the server only learns the Message.
+        /* eslint-disable-next-line @typescript-eslint/consistent-type-assertions */
+        const f = event.f;
+        const targets = {};
+        for (const key of PROBED_KEYS) {
+            const result = f(key, NO_MODIFIERS);
+            if (Option.isSome(result))
+                targets[key] = result.value.focusSelector;
+        }
+        if (Object.keys(targets).length === 0) {
+            return h.Attribute('data-hyper-no-keys', '');
+        }
+        const id = binder.registerHandler({
+            _tag: 'Key',
+            f: (key, modifiers) => Option.map(f(key, modifiers), result => result.message),
+        });
+        return bindEvent('keydown', `window.${FOCUS_KEY}?.(evt, ${literal(targets)}) && ${post(`h: '${id}', ${KEY_PAYLOAD}`)}`);
+    }
+    const pointerEvent = POINTER_EVENTS[tag];
+    if (pointerEvent !== undefined) {
+        /* eslint-disable-next-line @typescript-eslint/consistent-type-assertions */
+        const f = event.f;
+        const id = binder.registerHandler({
+            _tag: 'Args',
+            /* eslint-disable-next-line @typescript-eslint/consistent-type-assertions */
+            f: args => pointerEvent.call(f, args),
+        });
+        return bindEvent(`${pointerEvent.event}${pointerEvent.modifiers ?? ''}`, post(`h: '${id}', ${POINTER_ARGS}`));
+    }
+    if (tag === 'OnBeforeInput') {
+        /* eslint-disable-next-line @typescript-eslint/consistent-type-assertions */
+        const f = event.f;
+        const id = binder.registerHandler({
+            _tag: 'Args',
+            f: ([inputType, data]) => Option.some(f(String(inputType), Option.fromNullishOr(data))),
+        });
+        return bindEvent('beforeinput', post(`h: '${id}', x: [evt.inputType, evt.data]`));
+    }
+    if (tag === 'OnToggle') {
+        /* eslint-disable-next-line @typescript-eslint/consistent-type-assertions */
+        const f = event.f;
+        const id = binder.registerHandler({ _tag: 'Number', f: value => f(value === 1) });
+        return bindEvent('toggle', post(`h: '${id}', n: el.open ? 1 : 0`));
+    }
+    if (tag === 'OnScroll') {
+        /* eslint-disable-next-line @typescript-eslint/consistent-type-assertions */
+        const f = event.f;
+        const id = binder.registerHandler({ _tag: 'Number', f });
+        return bindEvent(`scroll${SCROLL_THROTTLE}`, post(`h: '${id}', n: el.scrollTop`));
+    }
+    const fileEvent = FILE_EVENTS[tag];
+    if (fileEvent !== undefined) {
+        /* eslint-disable-next-line @typescript-eslint/consistent-type-assertions */
+        const f = event.f;
+        const id = binder.registerHandler({ _tag: 'Files', f });
+        return bindEvent(fileEvent.event, 
+        // The handler id is written `h: '<id>'`, as in every other binding.
+        `window.${UPLOAD}?.(el, ${fileEvent.files}, {h: '${id}'}, ++$${SEQUENCE_SIGNAL}, $${ENDPOINT_SIGNAL})`);
+    }
+    if (tag === 'OnCustomEvent' && event.name !== undefined) {
+        /* eslint-disable-next-line @typescript-eslint/consistent-type-assertions */
+        const f = event.f;
+        const id = binder.registerHandler({ _tag: 'Custom', name: event.name, f });
+        return bindEvent(event.name, post(`h: '${id}', d: evt.detail`));
+    }
+    throw new UnsupportedEventError(tag);
+};

package/dist/builder.d.ts

@@ -0,0 +1,21 @@
+import type { Html, HtmlBuilder } from 'foldkit/html';
+import { type Binder } from './binding.ts';
+/** Runs `f` where a server builder may be used but nothing it builds is kept.
+ *  Event handlers run at event time, outside any render, and some call view
+ *  code: crease's menus resolve their items, icons included, to find which
+ *  items a key can move to. */
+export declare const withDiscardedRender: <A>(f: () => A) => A;
+/** Renders `view` with `binder` as the page's binder. */
+export declare const withBinder: <Message, A>(binder: Binder<Message>, render: () => A) => A;
+/** The binder of the render in progress, when `h` is a server builder.
+ *  Server-aware helpers (islands) use it to bind events themselves. */
+export declare const binderOf: <Message>(h: HtmlBuilder<Message>) => Binder<Message> | undefined;
+/** The server builder for a Foldkit builder; use it inside `withBinder`. */
+export declare const serverBuilder: <Message>(base: HtmlBuilder<Message>) => HtmlBuilder<Message>;
+/** Convenience for one-off renders (tests): the server builder bound to
+ *  `binder` for the duration of `render`. */
+export declare const renderWith: <Message, A>(base: HtmlBuilder<Message>, binder: Binder<Message>, render: (h: HtmlBuilder<Message>) => A) => A;
+/** Foldkit's serializer silently skips DOM listeners. A listener left on a
+ *  vnode means an element was built outside the server builder, and its
+ *  behavior would vanish from the page, so fail loudly instead. */
+export declare const assertNoDroppedHandlers: (root: Html) => void;