forgebook 0.1.8 → 0.3.0

package/dist/src/frame/touchCaret.js

@@ -0,0 +1,195 @@
+/** The input types with a caret: the others (a checkbox, a range, a date…) keep the browser's own reaction. */
+const CARET_INPUT_TYPES = new Set([
+    "text",
+    "search",
+    "url",
+    "tel",
+    "email",
+    "password",
+    "number"
+]);
+/** What is interactive by itself inside a label: a tap on it does not activate the label. */
+const LABEL_INTERACTIVE = "a[href], button, input, select, textarea, summary, [tabindex]";
+/**
+ * Whether a field is an input or a textarea.
+ *
+ * @param field - the field.
+ */
+const isTextControl = (field) => field instanceof HTMLInputElement || field instanceof HTMLTextAreaElement;
+/**
+ * The editable field a node is in, the one a finger on it would focus: an input with a caret or a textarea, not
+ * disabled (a read-only one still takes the caret, as under a real finger), or a contenteditable's editing host.
+ *
+ * @param node - the node (a contenteditable's text, for one).
+ * @returns the field; none when the node is in no such field.
+ */
+export const editableFieldOf = (node) => {
+    const element = node instanceof Element ? node : node.parentElement;
+    if (!(element instanceof HTMLElement))
+        return undefined;
+    if (element instanceof HTMLTextAreaElement)
+        return element.matches(":disabled") ? undefined : element;
+    if (element instanceof HTMLInputElement)
+        return CARET_INPUT_TYPES.has(element.type) && !element.matches(":disabled") ? element : undefined;
+    if (!element.isContentEditable)
+        return undefined;
+    // only the editing host takes the focus: what is inside it is edited through it
+    let host = element;
+    while (host.parentElement?.isContentEditable === true)
+        host = host.parentElement;
+    return host;
+};
+/**
+ * The element under a point, inside the open shadow roots on the way (`elementFromPoint` stops at their hosts).
+ *
+ * @param document - the frame's document.
+ * @param point - the point.
+ */
+export const deepElementAt = (document, point) => {
+    let element = document.elementFromPoint(point.x, point.y);
+    while (element?.shadowRoot) {
+        const inner = element.shadowRoot.elementFromPoint(point.x, point.y);
+        if (inner === null || inner === element)
+            break;
+        element = inner;
+    }
+    return element ?? undefined;
+};
+/**
+ * The shadow roots a field is inside: the caret's lookup does not enter one it is not given.
+ *
+ * @param field - the field.
+ */
+const shadowRootsAround = (field) => {
+    const roots = [];
+    let root = field.getRootNode();
+    while (root instanceof ShadowRoot) {
+        roots.push(root);
+        root = root.host.getRootNode();
+    }
+    return roots;
+};
+/**
+ * Where the browser would put the caret at a point, when that is in the field.
+ *
+ * @param document - the frame's document.
+ * @param point - the point.
+ * @param field - the field.
+ * @returns the place; none when the browser cannot tell.
+ */
+const caretSpotAt = (document, point, field) => {
+    let spot;
+    if (typeof document.caretPositionFromPoint === "function") {
+        const position = document.caretPositionFromPoint(point.x, point.y, {
+            shadowRoots: shadowRootsAround(field)
+        });
+        if (position !== null)
+            spot = { node: position.offsetNode, offset: position.offset };
+    }
+    else if (!isTextControl(field)) {
+        const range = document.caretRangeFromPoint(point.x, point.y);
+        if (range !== null)
+            spot = { node: range.startContainer, offset: range.startOffset };
+    }
+    return spot !== undefined && field.contains(spot.node) ? spot : undefined;
+};
+/**
+ * Puts the caret in an input or a textarea, at the end without an offset.
+ *
+ * @param document - the frame's document.
+ * @param control - the field, focused.
+ * @param offset - how far into its value.
+ */
+const placeInControl = (document, control, offset) => {
+    if (control.selectionStart !== null) {
+        const place = offset ?? control.value.length;
+        control.setSelectionRange(place, place);
+        return;
+    }
+    // an email or a number field has no selection range to set, but the document's selection walks through it, focused:
+    // it lands on the place in Chromium and WebKit, not in Firefox
+    const selection = document.getSelection();
+    if (selection === null)
+        return;
+    if (offset === undefined) {
+        selection.modify("move", "forward", "lineboundary");
+        return;
+    }
+    selection.modify("move", "backward", "lineboundary");
+    // the offset counts UTF-16 code units, the steps whole characters
+    const before = control.value.slice(0, offset);
+    const steps = Array.from(new Intl.Segmenter().segment(before)).length;
+    for (let step = 0; step < steps; step += 1)
+        selection.modify("move", "forward", "character");
+};
+/**
+ * Puts the caret in a contenteditable, at its end without a place.
+ *
+ * @param document - the frame's document.
+ * @param host - the editing host, focused.
+ * @param spot - the place.
+ */
+const placeInEditable = (document, host, spot) => {
+    const selection = document.getSelection();
+    if (selection === null)
+        return;
+    // the spot was read before the focus: a focus handler may have changed the text since
+    if (spot !== undefined && host.contains(spot.node)) {
+        const { node } = spot;
+        const length = node instanceof CharacterData ? node.length : node.childNodes.length;
+        selection.collapse(node, Math.min(spot.offset, length));
+        return;
+    }
+    selection.selectAllChildren(host);
+    selection.collapseToEnd();
+};
+/**
+ * Whether a field holds the focus: a story's focus handler may have moved it on.
+ *
+ * @param field - the field.
+ */
+const holdsFocus = (field) => {
+    const root = field.getRootNode();
+    return (root instanceof Document || root instanceof ShadowRoot) && root.activeElement === field;
+};
+/**
+ * A tap lands at a point: the editable field under it, if any, takes the focus and the caret.
+ *
+ * @param document - the frame's document.
+ * @param point - where the finger tapped.
+ */
+export const tapField = (document, point) => {
+    const element = deepElementAt(document, point);
+    const field = element === undefined ? undefined : editableFieldOf(element);
+    if (field === undefined)
+        return;
+    // read before the focus, which may scroll a long field's text from under the finger
+    const spot = caretSpotAt(document, point, field);
+    field.focus();
+    if (!holdsFocus(field))
+        return;
+    if (isTextControl(field))
+        placeInControl(document, field, spot?.offset);
+    else
+        placeInEditable(document, field, spot);
+};
+/**
+ * A tap's click reached a label: the editable field it names takes the focus, which a dispatched click does not give it.
+ * The caret stays where the field had it, as under a real finger. A tap on what is interactive inside the label (the
+ * field itself, a button) does not activate the label.
+ *
+ * @param origin - where the click began, inside any shadow root.
+ */
+export const tapLabel = (origin) => {
+    if (!(origin instanceof Element))
+        return;
+    const label = origin.closest("label");
+    if (label === null)
+        return;
+    const interactive = origin.closest(LABEL_INTERACTIVE);
+    if (interactive !== null && label.contains(interactive))
+        return;
+    const { control } = label;
+    if (control instanceof HTMLElement && editableFieldOf(control) !== undefined)
+        control.focus();
+};

package/dist/src/frame/touchDots.d.ts

@@ -29,4 +29,3 @@ export type TouchDots = {
  * @param document - the frame's document.
  */
 export declare const touchDots: (document: Document) => TouchDots;
-//# sourceMappingURL=touchDots.d.ts.map

package/dist/src/frame/touchDots.js

@@ -49,4 +49,3 @@ export const touchDots = (document) => {
         }
     };
 };
-//# sourceMappingURL=touchDots.js.map

package/dist/src/frame/touchEvents.d.ts

@@ -4,7 +4,7 @@
  *
  * @remarks
  * A page cannot make trusted events, so these are dispatched ones: the story's handlers see a finger, the browser's
- * own reactions (scrolling, focus) do not follow them. A touch pointer is captured by the element it went down on,
+ * own reactions (scrolling, focus) do not follow them: the layer makes up for a tap's focus (`touchCaret.ts`). A touch pointer is captured by the element it went down on,
  * as the browser does; a story that captures it elsewhere moves it there (`touchLayer.ts` patches the capture calls
  * for the simulated pointers' ids).
  *
@@ -61,6 +61,6 @@ export declare const sendMouse: (type: string, finger: Finger) => boolean;
  *
  * @param target - the real click's target.
  * @param finger - the finger that tapped.
+ * @returns whether no handler cancelled it.
  */
-export declare const sendClick: (target: EventTarget, finger: Finger) => void;
-//# sourceMappingURL=touchEvents.d.ts.map
+export declare const sendClick: (target: EventTarget, finger: Finger) => boolean;

package/dist/src/frame/touchEvents.js

@@ -130,23 +130,21 @@ export const sendMouse = (type, finger) => {
  *
  * @param target - the real click's target.
  * @param finger - the finger that tapped.
+ * @returns whether no handler cancelled it.
  */
-export const sendClick = (target, finger) => {
-    target.dispatchEvent(new PointerEvent("click", {
-        bubbles: true,
-        cancelable: true,
-        composed: true,
-        view: finger.startTarget.ownerDocument.defaultView,
-        detail: 1,
-        pointerId: finger.id,
-        pointerType: "touch",
-        isPrimary: true,
-        clientX: finger.point.x,
-        clientY: finger.point.y,
-        screenX: finger.point.x,
-        screenY: finger.point.y,
-        width: CONTACT_PX,
-        height: CONTACT_PX
-    }));
-};
-//# sourceMappingURL=touchEvents.js.map
+export const sendClick = (target, finger) => target.dispatchEvent(new PointerEvent("click", {
+    bubbles: true,
+    cancelable: true,
+    composed: true,
+    view: finger.startTarget.ownerDocument.defaultView,
+    detail: 1,
+    pointerId: finger.id,
+    pointerType: "touch",
+    isPrimary: true,
+    clientX: finger.point.x,
+    clientY: finger.point.y,
+    screenX: finger.point.x,
+    screenY: finger.point.y,
+    width: CONTACT_PX,
+    height: CONTACT_PX
+}));

package/dist/src/frame/touchGesture.d.ts

@@ -77,4 +77,3 @@ export declare const allowedPan: (touchActions: readonly string[]) => PanAxes;
  * @param ms - the time passed.
  */
 export declare const flungSpeed: (speed: number, ms: number) => number;
-//# sourceMappingURL=touchGesture.d.ts.map

package/dist/src/frame/touchGesture.js

@@ -84,4 +84,3 @@ export const flungSpeed = (speed, ms) => {
     const next = speed * FLING_KEPT ** (ms / 16);
     return Math.abs(next) < FLING_STOP ? 0 : next;
 };
-//# sourceMappingURL=touchGesture.js.map

package/dist/src/frame/touchLayer.d.ts

@@ -1,7 +1,7 @@
 /**
- * Follows the root's touch attribute from now on: the simulation runs while it is set.
+ * Starts the simulation in a frame.
  *
  * @param document - the frame's document.
+ * @returns what stops it.
  */
-export declare const followTouch: (document: Document) => void;
-//# sourceMappingURL=touchLayer.d.ts.map
+export declare const startTouch: (document: Document) => (() => void);

package/dist/src/frame/touchLayer.js

@@ -1,6 +1,7 @@
 /**
- * The frame's simulated touch, on while the root has `data-forgebook-touch` (the Touch switch): the real mouse's
- * events are caught before the story and sent again as a finger, or as two with Shift held.
+ * The frame's simulated touch, started and stopped by `followTouch.ts` while the root has `data-forgebook-touch` (the
+ * Touch switch), and loaded the first time it is: the real mouse's events are caught before the story and sent again
+ * as a finger, or as two with Shift held.
  *
  * @remarks
  * A press sends `pointerdown` (touch) and `touchstart`; a move sends `touchmove`, and `pointermove` until a drag
@@ -10,18 +11,18 @@
  * no button down sends nothing: a finger does not hover. Shift fixes a centre beside the mouse (the second finger shows 80 px to its left); a press then puts a
  * second finger mirrored around it, so dragging pinches and rotates. The real cursor is hidden and the fingers are
  * dots (`touchDots.ts`). While it is on, `navigator.maxTouchPoints` and `ontouchstart` say touch, and capturing a
- * simulated pointer works. A simulation: the events are not trusted, so the browser's own scrolling, focus from a
- * touch, a virtual keyboard and real Safari stay a device's (or `forgebook dev --touch`'s).
+ * simulated pointer works. A tap on an editable field focuses it and puts the caret there (`touchCaret.ts`), the real
+ * press on one doing nothing: a finger that drags or holds there must not focus it. A simulation: the events are not
+ * trusted, so the browser's own scrolling, a virtual keyboard and real Safari stay a device's (or
+ * `forgebook dev --touch`'s).
  *
  * @module
  */
-import { isRealTouchWindow } from "../realTouch.js";
+import { deepElementAt, editableFieldOf, tapField, tapLabel } from "./touchCaret.js";
 import { touchDots } from "./touchDots.js";
 import { sendClick, sendMouse, sendPointer, sendTouch } from "./touchEvents.js";
 import { dragAxis, isDragging, LONG_PRESS_MS, mirroredFinger } from "./touchGesture.js";
 import { endPan, panBy, panOf } from "./touchScroll.js";
-/** The root's attribute that turns the simulation on. */
-const TOUCH_ATTRIBUTE = "data-forgebook-touch";
 /** The simulated pointers' ids: apart from the real mouse's, so the browser never confuses them. */
 const FINGER_IDS = [100, 101];
 /** How far apart two fingers start, in CSS px: Shift fixes the centre half of it to the left of the mouse. */
@@ -168,6 +169,18 @@ const pressMove = (state, press, event) => {
             sendPointer("pointermove", finger, true);
     drawDots(state);
 };
+/**
+ * A tap's compatibility mouse events, and the focus on an editable field a real finger's comes with: a handler that
+ * cancels the `mousedown` leaves the field without it.
+ *
+ * @param document - the frame's document.
+ * @param finger - the finger that tapped.
+ */
+const sendTapMouse = (document, finger) => {
+    if (sendMouse("mousedown", finger))
+        tapField(document, finger.point);
+    sendMouse("mouseup", finger);
+};
 /**
  * A press ends: the fingers lift, a scroll flings on, a tap sends the mouse's compatibility events and readies its
  * click.
@@ -200,12 +213,19 @@ const pressUp = (state, press, isCancel, time) => {
     const isTap = !isCancel && !press.isDrag && !press.isLongPress && press.fingers.length === 1;
     const isClicking = isTap && !press.isTouchCancelled && !isEndCancelled;
     state.tapper = isClicking ? first : undefined;
-    if (isClicking && !press.isDownCancelled && first !== undefined) {
-        sendMouse("mousedown", first);
-        sendMouse("mouseup", first);
-    }
+    if (isClicking && !press.isDownCancelled && first !== undefined)
+        sendTapMouse(state.document, first);
     drawDots(state);
 };
+/**
+ * Whether a real event began in an editable field.
+ *
+ * @param event - the event.
+ */
+const isInField = (event) => {
+    const [origin] = event.composedPath();
+    return origin instanceof Node && editableFieldOf(origin) !== undefined;
+};
 /**
  * A real event the layer handles apart from the pointer's, before the story: the mouse's click (a tap's is sent again as
  * a finger's, a drag's or a long press's is none), a text selection or an image dragged by the finger, the right
@@ -228,10 +248,12 @@ const handledApart = (state, event) => {
         state.tapper = undefined;
         // after the real click's dispatch: cancelling it undoes a checkbox's toggle at its end, a click sent inside it too
         const { target } = event;
+        const [origin] = event.composedPath();
         if (finger !== undefined && target !== null)
             state.clickTimer = window.setTimeout(() => {
                 state.clickTimer = undefined;
-                sendClick(target, finger);
+                if (sendClick(target, finger))
+                    tapLabel(origin);
             }, 0);
         return true;
     }
@@ -239,6 +261,9 @@ const handledApart = (state, event) => {
         return true;
     if (event.type !== "selectstart" && event.type !== "dragstart" && event.type !== "contextmenu")
         return false;
+    // inside a field the keyboard selects (Shift and an arrow): only the finger's selection of the page stays out
+    if (event.type === "selectstart" && isInField(event))
+        return true;
     event.preventDefault();
     event.stopImmediatePropagation();
     return true;
@@ -292,6 +317,18 @@ const pointerInput = (state, event) => {
         pressUp(state, press, event.type === "pointercancel", event.timeStamp);
     }
 };
+/**
+ * A real press on an editable field does nothing there: the browser would focus it and start a selection at once, when
+ * a finger's reaction waits for its lift (`touchCaret.ts`) and never comes from a drag or a long press.
+ *
+ * @param state - the simulation's state.
+ * @param event - the real press.
+ */
+const keepFieldForTap = (state, event) => {
+    const element = deepElementAt(state.document, { x: event.clientX, y: event.clientY });
+    if (element !== undefined && editableFieldOf(element) !== undefined)
+        event.preventDefault();
+};
 /**
  * What the simulation does with one real event, before the story sees it: the story never sees a real one.
  *
@@ -304,6 +341,8 @@ const intercept = (state, event) => {
     event.stopImmediatePropagation();
     if (event instanceof PointerEvent)
         pointerInput(state, event);
+    else if (event.type === "mousedown" && event instanceof MouseEvent)
+        keepFieldForTap(state, event);
 };
 /**
  * Makes the frame say it is a touch device, and lets the story capture a simulated pointer.
@@ -381,7 +420,7 @@ const CAUGHT = [
  * @param document - the frame's document.
  * @returns what stops it.
  */
-const startTouch = (document) => {
+export const startTouch = (document) => {
     const state = {
         document,
         dots: touchDots(document),
@@ -423,27 +462,3 @@ const startTouch = (document) => {
         state.dots.remove();
     };
 };
-/**
- * Follows the root's touch attribute from now on: the simulation runs while it is set.
- *
- * @param document - the frame's document.
- */
-export const followTouch = (document) => {
-    let stop;
-    // in Chromium's real touch window the pages see real touch: simulating it on top would send every touch twice
-    const view = document.defaultView;
-    if (view !== null && isRealTouchWindow(view))
-        return;
-    const update = () => {
-        const isOn = document.documentElement.hasAttribute(TOUCH_ATTRIBUTE);
-        if (isOn && stop === undefined)
-            stop = startTouch(document);
-        else if (!isOn && stop !== undefined) {
-            stop();
-            stop = undefined;
-        }
-    };
-    new MutationObserver(update).observe(document.documentElement, { attributeFilter: [TOUCH_ATTRIBUTE] });
-    update();
-};
-//# sourceMappingURL=touchLayer.js.map

package/dist/src/frame/touchScroll.d.ts

@@ -48,4 +48,3 @@ export declare const panBy: (pan: Pan, from: Point, to: Point) => void;
  * @param speed - the finger's last speed, in CSS px per ms, per axis.
  */
 export declare const endPan: (pan: Pan, speed: Point) => (() => void);
-//# sourceMappingURL=touchScroll.d.ts.map

package/dist/src/frame/touchScroll.js

@@ -151,4 +151,3 @@ export const endPan = (pan, speed) => {
     // a new touch stops the smooth scroll where it is, as a finger stops a scrolling list
     return () => scroller.scrollTo({ left: scroller.scrollLeft, top: scroller.scrollTop, behavior: "instant" });
 };
-//# sourceMappingURL=touchScroll.js.map

package/dist/src/frameOrigins.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Where a catalogue's frames run, and the two origins the shell and the frames talk on: the shell sends only to the
+ * frames' origin and listens only to it, a frame the same with the catalogue's.
+ *
+ * @remarks
+ * A story's frame runs on an origin of its own wherever one can be had, so what runs in it (the story's code, a value a
+ * shared link put in a prop) cannot read or act on the catalogue's page, the dev server's agent API or the files Vite
+ * serves. The dev server gives the frames a second port (`ports`); a static build gets a second host only when the
+ * configuration names it (`origins`); otherwise they share the catalogue's (`same-origin`).
+ *
+ * Each side works out the other's origin from the placement and its own address, never from a value in the address:
+ * a page that framed a story while naming itself the catalogue could otherwise send it values.
+ *
+ * @module
+ */
+/** Where the frames run, as the pages read it from the configuration's data. */
+export type FramesPlacement = {
+    /** On the catalogue's own origin. */
+    readonly kind: "same-origin";
+} | {
+    /** On another port of the same host: the dev server's second port. */
+    readonly kind: "ports";
+    /** The catalogue's port. */
+    readonly catalogue: number;
+    /** The frames' port. */
+    readonly frames: number;
+} | {
+    /** On origins the configuration names, as the browser reaches them. */
+    readonly kind: "origins";
+    /** The catalogue's origin (`https://catalogue.example.com`). */
+    readonly catalogue: string;
+    /** The frames' origin (`https://frames.example.com`). */
+    readonly frames: string;
+};
+/** The frames on the catalogue's own origin. */
+export declare const SAME_ORIGIN: FramesPlacement;
+/** The two origins of a catalogue's page and its frames. */
+export type PageOrigins = {
+    /** The catalogue page's origin. */
+    readonly catalogue: string;
+    /** The frames' origin. */
+    readonly frames: string;
+};
+/** What a page knows of its own address. */
+export type PageLocation = Pick<Location, "protocol" | "hostname" | "origin">;
+/**
+ * The two origins, seen from one of the pages.
+ *
+ * @param placement - where the frames run.
+ * @param location - the page's own address.
+ * @param side - which page asks: the catalogue's, or a frame.
+ */
+export declare const pageOrigins: (placement: FramesPlacement, location: PageLocation, side: "catalogue" | "frame") => PageOrigins;
+/**
+ * The frame page's address, for the catalogue's page: the page named relative to the catalogue's path, on the frames'
+ * origin, so a catalogue served under a sub-path (`/pr-12/`) finds its frames under the same one.
+ *
+ * @param framePage - the frame page, relative to the catalogue's (`frame.html`).
+ * @param framesOrigin - the frames' origin.
+ * @param pathname - the catalogue page's path (`/pr-12/`).
+ */
+export declare const framePageAddress: (framePage: string, framesOrigin: string, pathname: string) => string;

package/dist/src/frameOrigins.js

@@ -0,0 +1,49 @@
+/**
+ * Where a catalogue's frames run, and the two origins the shell and the frames talk on: the shell sends only to the
+ * frames' origin and listens only to it, a frame the same with the catalogue's.
+ *
+ * @remarks
+ * A story's frame runs on an origin of its own wherever one can be had, so what runs in it (the story's code, a value a
+ * shared link put in a prop) cannot read or act on the catalogue's page, the dev server's agent API or the files Vite
+ * serves. The dev server gives the frames a second port (`ports`); a static build gets a second host only when the
+ * configuration names it (`origins`); otherwise they share the catalogue's (`same-origin`).
+ *
+ * Each side works out the other's origin from the placement and its own address, never from a value in the address:
+ * a page that framed a story while naming itself the catalogue could otherwise send it values.
+ *
+ * @module
+ */
+/** The frames on the catalogue's own origin. */
+export const SAME_ORIGIN = { kind: "same-origin" };
+/**
+ * An origin on a host and a port: the default port left out, as a browser writes an origin.
+ *
+ * @param location - the page's address, whose scheme and host it keeps.
+ * @param port - the port.
+ */
+const originOnPort = (location, port) => new URL(`${location.protocol}//${location.hostname}:${port}`).origin;
+/**
+ * The two origins, seen from one of the pages.
+ *
+ * @param placement - where the frames run.
+ * @param location - the page's own address.
+ * @param side - which page asks: the catalogue's, or a frame.
+ */
+export const pageOrigins = (placement, location, side) => {
+    if (placement.kind === "origins")
+        return { catalogue: placement.catalogue, frames: placement.frames };
+    if (placement.kind === "same-origin")
+        return { catalogue: location.origin, frames: location.origin };
+    return side === "catalogue"
+        ? { catalogue: location.origin, frames: originOnPort(location, placement.frames) }
+        : { catalogue: originOnPort(location, placement.catalogue), frames: location.origin };
+};
+/**
+ * The frame page's address, for the catalogue's page: the page named relative to the catalogue's path, on the frames'
+ * origin, so a catalogue served under a sub-path (`/pr-12/`) finds its frames under the same one.
+ *
+ * @param framePage - the frame page, relative to the catalogue's (`frame.html`).
+ * @param framesOrigin - the frames' origin.
+ * @param pathname - the catalogue page's path (`/pr-12/`).
+ */
+export const framePageAddress = (framePage, framesOrigin, pathname) => new URL(framePage, `${framesOrigin}${pathname}`).href;

package/dist/src/hotModules.d.ts

@@ -0,0 +1,48 @@
+/**
+ * How an edited module reaches the open pages of a dev server without a reload: the module accepts its own edit and
+ * hands its successor to the page, which swaps what it drew from the one before.
+ *
+ * @remarks
+ * A story file accepts its edit and asks, with a cancelable event, whether a frame draws its stories; the frame that
+ * does draws them anew in place, and the reader keeps what they did in the story (a typed field, an open menu). A file
+ * no frame draws hands its edit on to the files that import it: a story file that re-exports its stories draws them.
+ * A story file's docs, code and page modules hand their successor to the shell, which shows the new value. The frame's
+ * entry takes the edits of its previews and of what they import (a library's whole index, often): the frame draws its
+ * story anew with the new previews instead of the page reloading. The code each module runs is written by the plugin
+ * (`vite/hotSnippets.ts`); the events are read here, by the frame and the shell.
+ *
+ * @module
+ */
+/** The event a story file sends when it was edited, cancelled by the frame that draws its stories. */
+export declare const STORY_FILE_EVENT = "forgebook:story-file";
+/** The event a story file's docs, code or page module sends when it was renewed. */
+export declare const RENEWED_MODULE_EVENT = "forgebook:module-renewed";
+/**
+ * The event the frame's entry sends when a preview, or a module one imports, was edited: the previews that changed,
+ * by their place in the list, in a `CustomEvent` whose detail is `PreviewsRenewal`.
+ */
+export declare const PREVIEWS_EVENT = "forgebook:previews";
+/** The previews an edit renewed: each one's new module, or `undefined` for one it did not change. */
+export type PreviewsRenewal = {
+    /** The previews' modules, in the catalogue's order. */
+    readonly next: readonly unknown[];
+};
+/**
+ * The previews an event carries, when it is the previews' event.
+ *
+ * @param event - the event.
+ */
+export declare const previewsRenewalOf: (event: Event) => PreviewsRenewal | undefined;
+/** A module and the one that replaced it. */
+export type ModuleSuccession = {
+    /** What the module before gave: a story file's exports, or another module's default export. */
+    readonly previous: unknown;
+    /** What its successor gives. */
+    readonly next: unknown;
+};
+/**
+ * The module and its successor an event carries, when it is one of these events.
+ *
+ * @param event - the event.
+ */
+export declare const successionOf: (event: Event) => ModuleSuccession | undefined;