@wardic/dom 0.0.0-stage → 1.0.0-rc.2

package/src/ProjectionSystem.ts

@@ -0,0 +1,51 @@
+/**
+ * The Projection system: what runs the DOM's layout animations, one per Environment a binding builds. A binding registers
+ * each layout element with it, and when a layout changes it measures their boxes, draws each where it was
+ * with a transform, and animates it to where it is now; elements that share a `layoutId` fly one into the
+ * other. This module is its key and its types, which every element's code reads: the engine itself is
+ * `DomProjectionSystem`'s, so a page that never lays out ships none of it. `toJSON()` gives its tree as
+ * plain data, for a diagnostic view. A server render builds none.
+ *
+ * @example
+ * import * as ProjectionSystem from "@wardic/dom/ProjectionSystem"
+ *
+ * const system = yield* ProjectionSystem.ProjectionSystem
+ * const node = system.register({ id: "card", element: card, transition: () => Option.none() })
+ * system.animateLayout(() => expand(card)) // measured before and after, and animated between
+ */
+// The **Projection system**, the DOM's engine for the **Projection** (ADR-0009, ADR-0010, ADR-0018): it
+// holds every Projection node, runs the Measure pass and the per-frame projection pass, and owns `layoutId`
+// matching. `@wardic/dom/ProjectionSystem` (#132, ADR-0041). The key apart from the engine: #548, ADR-0067
+// *Amendment (#548)*. An Effect `Inspectable` (#384): `console.log(system)` shows the tree, as `Tree`,
+// each node with its parent, its `layoutId` twin's part and what it's doing; the layout lab draws it. A
+// server render builds none (ADR-0021).
+import * as Context from "effect/Context"
+import type * as internal from "./internal/projection.ts"
+
+export {
+  type RegisterNodeOptions,
+  type ProjectionNodeHandle as NodeHandle,
+  type DragProjectionHandle as DragHandle,
+  type AnimateLayoutOptions,
+  type Tree,
+  type TreeNode,
+} from "./internal/projection.ts"
+export { DEFAULT_DRAG_TRANSITION, DEFAULT_LAYOUT_TRANSITION, type DragTransition, type LayoutTransition } from "./internal/projection-defaults.ts"
+export type { ScaleCorrectorEntry as ScaleCorrector, CorrectorInfo } from "./internal/scale-correction.ts"
+export { dragBoundsWithin, measureLayoutBox } from "./internal/measure.ts"
+
+/** The engine: what a binding registers its layout elements with. */
+export type Shape = Omit<internal.ProjectionSystem, "dispose" | "onPassEnd">
+
+/** What the engine writes each node's projection through: a `FlushGate`'s `write` and `flushPass`. */
+export type Sink = internal.ProjectionSink
+
+/** What a binding hands its engine: whether reduced motion applies now, and the app's scale correctors. */
+// ADR-0029; #443.
+export type Options = internal.ProjectionSystemOptions
+
+/** The services the engine needs from its Environment. */
+export type Services = internal.ProjectionServices
+
+/** The Environment's Projection system. */
+export class ProjectionSystem extends /*#__PURE__*/ Context.Service<ProjectionSystem, Shape>()("@wardic/dom/ProjectionSystem") {}

package/src/ReorderController.ts

@@ -0,0 +1,72 @@
+/**
+ * A Reorder group on the DOM: the group, its items' drags, its keyboard and its announcements, one
+ * controller a group. `make` builds one over the context's Projection system and `Announcer`; a binding
+ * attaches its group element, gets a driver for each item, and closing the Scope ends the controller. A
+ * server render gets `inert`.
+ *
+ * @example
+ * import * as ReorderController from "@wardic/dom/ReorderController"
+ *
+ * const controller = yield* ReorderController.make({ values: () => items, onReorder: (next) => (items = next) })
+ * controller.attach(list)
+ * const driver = controller.item(item, () => Option.some(element))
+ */
+// A **Reorder group**'s controller (ADR-0019 *Amendment (Reorder)*, ADR-0037); a server render's `inert`
+// (ADR-0021). `@wardic/dom/ReorderController` (#132, ADR-0041). A scoped constructor, one per group (#132's
+// PR 3): `make` logs its `wardic.reorder:` events through the context's Logger, and ends with its Scope,
+// which stops its listening to Measure passes, resets its Auto-scroll and clears a pending announcement.
+// Its items' drivers stay plain, each with its own `dispose`, since one is made per element.
+import * as Announcer from "@wardic/core/Announcer"
+import * as Effect from "effect/Effect"
+import type * as Scope from "effect/Scope"
+import { PassEnds } from "./internal/pass-ends.ts"
+import * as internal from "./internal/reorder.ts"
+import { makeRunner } from "./internal/runner.ts"
+import * as ProjectionSystem from "./ProjectionSystem.ts"
+
+export {
+  type ReorderEnd as End,
+  type ReorderHoldEnd as HoldEnd,
+  type ReorderHoldHow as HoldHow,
+  type ReorderHoldStart as HoldStart,
+  type ReorderItemDriver as ItemDriver,
+  DEFAULT_REORDER_INSTRUCTIONS as DEFAULT_INSTRUCTIONS,
+  REORDER_GROUP_STYLE as GROUP_STYLE,
+} from "./internal/reorder.ts"
+
+/** A **Reorder group** on the DOM: what a binding attaches its group element and items to. */
+export type ReorderController<V> = Omit<internal.ReorderController<V>, "dispose">
+
+/** What a binding hands its group: the app's values, its axis, its keyboard and its announcements. */
+export type Options<V> = internal.ReorderControllerOptions<V>
+
+/**
+ * The services a controller takes from its context: the projection system its items are nodes of,
+ * with what tells it each Measure pass's end (`DomProjectionSystem`'s Layer provides both), and the
+ * Environment's `Announcer`.
+ */
+export type Services = ProjectionSystem.ProjectionSystem | PassEnds | Announcer.Announcer
+
+/**
+ * Build a group's controller over the context's projection system, announcing through its
+ * `Announcer`, in the current Scope: closing it ends the controller.
+ */
+export const make: <V>(options: Options<V>) => Effect.Effect<ReorderController<V>, never, Services | Scope.Scope> = Effect.fnUntraced(
+  function* <V>(options: Options<V>) {
+    const projection = yield* ProjectionSystem.ProjectionSystem
+    const passEnds = yield* PassEnds
+    const announcer = yield* Announcer.Announcer
+    const controller = internal.makeReorderController(
+      { runtime: yield* makeRunner<never>(), projection, announce: announcer.announce, onPassEnd: passEnds.onPassEnd },
+      options,
+    )
+    yield* Effect.addFinalizer(() => Effect.sync(controller.dispose))
+    return controller
+  })
+
+/**
+ * The controller a server render gets: its group has no values, so every operation on it does nothing,
+ * its axis is `"y"`, and an item's driver does nothing too.
+ */
+// ADR-0021.
+export const inert: ReorderController<never> = internal.INERT_REORDER_CONTROLLER

package/src/Report.ts

@@ -0,0 +1,17 @@
+/**
+ * Reporting a failure where a fiber stops: logged at Error and handed to the Environment's
+ * `ErrorReporter`s, so an app's error tracking sees it. An interruption is neither: it's how a run is
+ * removed.
+ *
+ * @example
+ * import * as Report from "@wardic/dom/Report"
+ *
+ * yield* Report.failure("wardic: an animation failed", cause)
+ */
+// `@wardic/dom/Report` (#132, ADR-0041): ADR-0030, decision 4.
+export {
+  reportFailure as failure,
+  debugKept,
+  debugOf,
+  type DebugLog,
+} from "./internal/report.ts"

package/src/ScrollOffset.ts

@@ -0,0 +1,54 @@
+/**
+ * Scroll offsets, the DOM's: Motion's syntax for where a target's progress through its scroll container
+ * runs, from 0 to 1, which the DOM's `Probe.scroll` resolves. Core takes an offset as its Environment's
+ * own and passes it through, so its syntax, its names and its units are the DOM's.
+ *
+ * - **An edge** is a name (`start`, `center`, `end`), a fraction of a length (`0.5`), or a CSS length:
+ *   `"100px"` a distance, `"50%"` a fraction, `"10vw"` or `"10vh"` a share of the viewport.
+ * - **A stop** is a pair of edges, `[target, container]`: the scroll position where the target's edge
+ *   meets the container's. A string holds both (`"start end"`); one edge alone is both for a name or a
+ *   number (`"end"`, `0.5`), else the target's against the container's start (`"100px"`).
+ * - **An offset** is two stops or more: progress runs from 0 at the first to 1 at the last, evenly
+ *   between them, and holds past them.
+ *
+ * @example
+ * import * as ScrollOffset from "@wardic/dom/ScrollOffset"
+ *
+ * // From the target's top meeting the container's bottom, to its bottom meeting the container's top:
+ * const across: ScrollOffset.ScrollOffset = ["start end", "end start"]
+ */
+// #234, ADR-0043 *Amendment (#233, #234)*; resolved in `internal/scroll.ts`. `@wardic/dom/ScrollOffset`
+// (ADR-0041): the type a binding gives its `scroll` helper's `offset`.
+
+/** One edge of a stop: a name, a fraction, or a CSS length (see the module's doc). */
+export type Edge = string | number
+
+/** One stop: `[target edge, container edge]`, a string of both, or one edge. */
+export type Stop = Edge | readonly [Edge, Edge]
+
+/** Where a target's progress runs: two stops or more. */
+export type ScrollOffset = ReadonlyArray<Stop>
+
+/** Motion's presets: while the target comes into the container. */
+export const Enter: ScrollOffset = [
+  [0, 1],
+  [1, 1],
+]
+
+/** While the target leaves the container. */
+export const Exit: ScrollOffset = [
+  [0, 0],
+  [1, 0],
+]
+
+/** While any of the target is in the container. */
+export const Any: ScrollOffset = [
+  [1, 0],
+  [0, 1],
+]
+
+/** While all of the target is in the container: the offset with a target and none given. */
+export const All: ScrollOffset = [
+  [0, 0],
+  [1, 1],
+]

package/src/Style.ts

@@ -0,0 +1,37 @@
+/**
+ * An element's style as a binding builds it: its starting style, what it's drawn with before any
+ * animation runs, from its `initial` (or its `animate`, with `initial: false`); how an app's own style and
+ * Wardic's are layered (`over`, `without`); and a drag element's default style. A server render draws the
+ * starting style, so an element is drawn where it starts before any code runs.
+ *
+ * @example
+ * import * as Style from "@wardic/dom/Style"
+ *
+ * const start = Style.resolveInitial({ initial: { opacity: 0, y: 8 }, animate: { opacity: 1, y: 0 } })
+ * Style.starting(undefined, start) // { style: { transform: "translateY(8px)", opacity: 0 }, attrs: {} }
+ */
+// `@wardic/dom/Style` (#132, ADR-0041): the **Starting style**, the merges of an app's style with
+// Wardic's, and a drag element's defaults (ADR-0019, ADR-0021, ADR-0034).
+export {
+  startingStyle as starting,
+  resolveInitial,
+  type InitialConfig,
+  keyframesOf,
+  splitValues,
+  type SplitValues,
+  type StopAt,
+  type Stops,
+  toValues,
+  valuesAt,
+  type StyleInput as Input,
+  type StyleRecord as Style,
+  over,
+  without,
+  heldTouches,
+} from "./internal/starting-style.ts"
+export {
+  dragDefaultStyle as dragDefaults,
+  type DragDefaultStyle as DragDefaults,
+  DRAG_DEFAULT_ATTRIBUTES,
+  reorderTouchAction,
+} from "./internal/drag-defaults.ts"

package/src/Svg.ts

@@ -0,0 +1,21 @@
+/**
+ * SVG: which elements are SVG's, and a style patch split into the CSS an SVG element takes and the
+ * attributes it takes instead. An `<svg>` root is styled as HTML is; an element inside it takes most keys
+ * as attributes, and a transform about its own centre, as an HTML element's is.
+ *
+ * @example
+ * import * as Svg from "@wardic/dom/Svg"
+ *
+ * Svg.splitPatchForTag("circle", { r: 10, opacity: 0.5, transform: "scale(2)" })
+ * // style: transform, transform-box and transform-origin; attrs: { r: "10", opacity: "0.5" }
+ */
+// `@wardic/dom/Svg` (#132, ADR-0041): ADR-0014.
+export {
+  isSvgRoot as isRoot,
+  isSvgInner as isInner,
+  isSvgInnerTag as isInnerTag,
+  setSvgAttrs as setAttrs,
+  splitPatch,
+  splitPatchForTag,
+  type SplitPatch,
+} from "./internal/svg.ts"

package/src/Variables.ts

@@ -0,0 +1,17 @@
+/**
+ * CSS variables in animated values: a value that's wholly a `var()` is resolved against an element, so
+ * `var(--accent)` animates from or to the colour it stands for. `values` is the Key rule a binding adds
+ * for an element's own animations.
+ *
+ * @example
+ * import * as Variables from "@wardic/dom/Variables"
+ *
+ * Variables.isValue("var(--gap)") // true
+ * Variables.resolve(element, "var(--gap)") // what `--gap` computes to on `element`
+ */
+// `@wardic/dom/Variables` (#132, ADR-0041): #55, ADR-0035.
+export {
+  isVariableValue as isValue,
+  resolveVariable as resolve,
+  variableValues as values,
+} from "./internal/variables.ts"

package/src/index.ts

@@ -0,0 +1,106 @@
+/**
+ * `@wardic/dom`: the browser Environment, and the framework-free pieces a binding builds on. It's for
+ * binding authors, Wardic's own and any other, and it's Effect-typed.
+ *
+ * - **An app** imports {@link DomLive}, the composed Environment it hands its binding, and
+ *   {@link CheckFrames}, to check its Frames in development.
+ * - **A binding** imports each module by its subpath, as a namespace
+ *   (`import * as FlushGate from "@wardic/dom/FlushGate"`), and the root re-exports each one:
+ *   - the DOM's implementations of core's services, each with its `layer` (Effect's platform
+ *     convention: `DomRenderer`, `DomInput`, `DomProbe`, `DomClock`, `DomAnnouncer`,
+ *     `DomInterpolators`, `DomPositionalKeys`, `DomDefaultTransition`), and `DomKeyRules`, the Key
+ *     rules `DomInterpolators.layer` installs, which has none of its own;
+ *   - dom's own concepts, by the glossary's names: `FlushGate`, `ProjectionSystem`,
+ *     `ReorderController`, `Style`, `Svg`, `Color`, `Variables`, `ScrollOffset`, `Appear`, `OwnValues`
+ *     and `Report`.
+ *
+ * Everything under `internal/` is dom's own and not exported.
+ */
+// `@wardic/dom` (#132, ADR-0041), Tier 2 (ADR-0008); CheckFrames re-exported for an app (#586).
+import type * as Clock from "@wardic/core/Clock"
+import * as FrameLoop from "@wardic/core/FrameLoop"
+import type * as InterpolatorRegistry from "@wardic/core/InterpolatorRegistry"
+import type * as Announcer from "@wardic/core/Announcer"
+import type * as DefaultTransition from "@wardic/core/DefaultTransition"
+import type * as ReducedMotion from "@wardic/core/ReducedMotion"
+import type * as Probe from "@wardic/core/Probe"
+import type * as RefreshFrameSource from "@wardic/core/RefreshFrameSource"
+import type * as Renderer from "@wardic/core/Renderer"
+import * as Layer from "effect/Layer"
+import { AtomRegistry } from "effect/reactivity"
+import * as DomAnnouncer from "./DomAnnouncer.ts"
+import * as DomClock from "./DomClock.ts"
+import * as DomDefaultTransition from "./DomDefaultTransition.ts"
+import * as DomInterpolators from "./DomInterpolators.ts"
+import * as DomPositionalKeys from "./DomPositionalKeys.ts"
+import * as DomProbe from "./DomProbe.ts"
+import * as DomRenderer from "./DomRenderer.ts"
+
+export const VERSION = "1.0.0-rc.2"
+
+export * as DomClock from "./DomClock.ts"
+export * as DomInput from "./DomInput.ts"
+export * as DomProbe from "./DomProbe.ts"
+export * as DomRenderer from "./DomRenderer.ts"
+export * as DomAnnouncer from "./DomAnnouncer.ts"
+export * as DomInterpolators from "./DomInterpolators.ts"
+export * as DomPositionalKeys from "./DomPositionalKeys.ts"
+export * as DomDefaultTransition from "./DomDefaultTransition.ts"
+export * as DomKeyRules from "./DomKeyRules.ts"
+export * as FlushGate from "./FlushGate.ts"
+export * as ProjectionSystem from "./ProjectionSystem.ts"
+export * as DomProjectionSystem from "./DomProjectionSystem.ts"
+export * as ReorderController from "./ReorderController.ts"
+export * as Style from "./Style.ts"
+export * as Svg from "./Svg.ts"
+export * as Color from "./Color.ts"
+export * as Variables from "./Variables.ts"
+export * as ScrollOffset from "./ScrollOffset.ts"
+export * as Appear from "./Appear.ts"
+export * as OwnValues from "./OwnValues.ts"
+export * as Report from "./Report.ts"
+
+/**
+ * Core's development check for Frames that aren't finite (`FrameLoop.CheckFrames`), here for an app,
+ * which installs `@wardic/dom` and not `@wardic/core`. Off by default; merged beside {@link DomLive} as
+ * `Layer.succeed(CheckFrames, true)`, it fails an animation whose Frame holds a NaN or an Infinity,
+ * naming its key and value, where the page would drop it without a word. It checks every Frame, so
+ * it's for development: see https://wardic.dev/guides/observability.
+ */
+// ADR-0030 decision 7; re-exported here for an app (#586).
+export { CheckFrames } from "@wardic/core/FrameLoop"
+
+/**
+ * The browser Environment, composed: the DOM's services, core's interpolators with the DOM's Key
+ * rules, and the Frame loop over the DOM's Clock, needing nothing else. Hand it to `WardicProvider`'s
+ * `env` to run the engine on the page.
+ *
+ * It has no input: a binding's gestures build `DomInput.layer` with the first one an app uses, so an
+ * app with none ships no input code.
+ *
+ * Client-only: a server render builds no runtime, and building DomLive on a server fails with an
+ * error naming the service and the missing global: see https://wardic.dev/guides/server-rendering.
+ */
+// Key rules: ADR-0035. Frame loop: ADR-0027. `DomClock.layer` also provides the `RefreshFrameSource`
+// the flush gate requests its flushes from (ADR-0031). `DomProbe.layer` writes the `viewport` and
+// `prefersReducedMotion` Atoms through the Environment's `AtomRegistry`, and consumers read them
+// through the same registry, so `AtomRegistry` is provided to the Layers with `Layer.provideMerge` and
+// kept in the output, as the headless `testLayer` (packages/test) does: R = never. No InputSource:
+// #511, ADR-0067 decision 14. Client-only: ADR-0021, decision 7.
+export const DomLive: Layer.Layer<
+  | Clock.Clock
+  | RefreshFrameSource.RefreshFrameSource
+  | FrameLoop.FrameLoop
+  | Renderer.Renderer
+  | Probe.Probe
+  | InterpolatorRegistry.InterpolatorRegistry
+  | ReducedMotion.PositionalKeys
+  | DefaultTransition.DefaultTransition
+  | Announcer.Announcer
+  | AtomRegistry.AtomRegistry
+> = FrameLoop.layer.pipe(
+  Layer.provideMerge(
+    Layer.mergeAll(DomClock.layer, DomRenderer.layer, DomProbe.layer, DomInterpolators.layer, DomPositionalKeys.layer, DomDefaultTransition.layer, DomAnnouncer.layer),
+  ),
+  Layer.provideMerge(AtomRegistry.layer),
+)

package/src/internal/announcer.ts

@@ -0,0 +1,132 @@
+/**
+ * The DOM's **Announcement** channel (ADR-0037): `AnnouncerDomLive`, core's `Announcer.Announcer` as
+ * one visually hidden live region per document, `aria-live="assertive"` and `aria-atomic`, shared by
+ * every Reorder group on the page. Assertive, because each announcement answers a key just pressed;
+ * the caller thins a held arrow's repeats to the last. Each announcement replaces the last, and one
+ * that repeats the last (an arrow at an end re-announcing the position) gets a trailing no-break
+ * space, so a screen reader sees a change and speaks it again.
+ *
+ * A screen reader watches a live region from when it's in the page, so the region has to be there
+ * before the first announcement: {@link prepareAnnouncer} adds it (a Reorder group's controller calls
+ * it when its element attaches), and an announcement adds it too if nothing did.
+ *
+ * {@link instructionsId} gives the id of a hidden element holding a group's instructions, one per
+ * distinct text per document, for its items' `aria-describedby`. {@link instructionsIdOf} gives the
+ * id alone, and {@link showInstructions} adds its element.
+ *
+ * Client-only (ADR-0021, decision 7): building the layer on a server fails with the client-only error.
+ *
+ * Tier 2 (ADR-0008): for DOM binding authors.
+ */
+import * as Announcer from "@wardic/core/Announcer"
+import * as Bool from "effect/Boolean"
+import * as Effect from "effect/Effect"
+import * as Layer from "effect/Layer"
+import * as Option from "effect/Option"
+import * as Predicate from "effect/Predicate"
+import { requireGlobal } from "./require-global.ts"
+
+/** The attribute that marks the live region, for a test or a stylesheet to find it. */
+export const ANNOUNCER_ATTRIBUTE = "data-wardic-announcer"
+
+/** Hidden from sight, not from assistive technology: the usual visually hidden rule. */
+const VISUALLY_HIDDEN =
+  "position:absolute;width:1px;height:1px;margin:-1px;padding:0;border:0;overflow:hidden;clip:rect(0 0 0 0);clip-path:inset(50%);white-space:nowrap"
+
+/** Each document's live region, once added. */
+// Module state (#460, Q7): each document's live region, held weakly by the document.
+const regions = new WeakMap<Document, HTMLElement>()
+
+/** `doc`'s live region, added to its body when it has none. */
+const regionOf = (doc: Document): HTMLElement =>
+  Option.getOrElse(
+    Option.filter(Option.fromUndefinedOr(regions.get(doc)), (region) => region.isConnected),
+    () => addRegion(doc),
+  )
+
+/** Add `doc`'s live region to its body. */
+const addRegion = (doc: Document): HTMLElement => {
+  const region = doc.createElement("div")
+  region.setAttribute(ANNOUNCER_ATTRIBUTE, "")
+  region.setAttribute("aria-live", "assertive")
+  region.setAttribute("aria-atomic", "true")
+  region.setAttribute("style", VISUALLY_HIDDEN)
+  doc.body.appendChild(region)
+  regions.set(doc, region)
+  return region
+}
+
+/**
+ * The live document `node` is in: its own when that has a window, else the page's. A Solid ref
+ * runs while a new element still belongs to its template's inert document (no window, no body),
+ * before it's inserted.
+ */
+export const documentOf = (node: Node): Document => {
+  const doc = node.ownerDocument
+  if (doc === null || doc.defaultView === null) return document
+  return doc
+}
+
+/** Adds `doc`'s live region now, before its first announcement, so a screen reader is already watching it. */
+export const prepareAnnouncer = (doc: Document): void => {
+  regionOf(doc)
+}
+
+/**
+ * Speaks `message` in `doc`'s live region, replacing the last. A repeat of the last gets a trailing
+ * no-break space, so it's read out again.
+ */
+export const announceIn = (doc: Document, message: string): void => {
+  const region = regionOf(doc)
+  region.textContent = Bool.match(region.textContent === message, { onTrue: () => `${message}\u00A0`, onFalse: () => message })
+}
+
+/** Each document's instructions ids, by text. */
+// Module state (#460, Q7): each document's instructions, held weakly by the document.
+const instructions = new WeakMap<Document, Map<string, string>>()
+// Module state (#460, Q7): an id counter; an id need only be unique in its document.
+let nextInstructions = 1
+
+/**
+ * The id of `doc`'s hidden element holding `text`, one per distinct text, for the `aria-describedby` of
+ * every item that shows it. Given here, with no element added: a binding works it out as it renders, and
+ * adds the element with `showInstructions` in an effect.
+ */
+// #320.
+export const instructionsIdOf = (doc: Document, text: string): string => {
+  const byText = Option.getOrElse(Option.fromUndefinedOr(instructions.get(doc)), () => {
+    const added = new Map<string, string>()
+    instructions.set(doc, added)
+    return added
+  })
+  return Option.getOrElse(Option.fromUndefinedOr(byText.get(text)), () => {
+    const id = `wardic-instructions-${nextInstructions++}`
+    byText.set(text, id)
+    return id
+  })
+}
+
+/** Adds `doc`'s hidden element holding `text`, under `instructionsIdOf`'s id, unless it's there already. */
+export const showInstructions = (doc: Document, text: string): void => {
+  const id = instructionsIdOf(doc, text)
+  if (Predicate.isNotNull(doc.getElementById(id))) return
+  const el = doc.createElement("div")
+  el.id = id
+  el.hidden = true
+  el.textContent = text
+  doc.body.appendChild(el)
+}
+
+/** `instructionsIdOf`, with its element added now: added again if it was removed. */
+export const instructionsId = (doc: Document, text: string): string => {
+  showInstructions(doc, text)
+  return instructionsIdOf(doc, text)
+}
+
+/** Core's `Announcer`, speaking in the page's `document`'s live region. */
+export const AnnouncerDomLive: Layer.Layer<Announcer.Announcer> = Layer.effect(Announcer.Announcer)(
+  Effect.gen(function* () {
+    yield* requireGlobal("DomAnnouncer.layer", "document")
+    return Announcer.Announcer.of({ announce: (message) => announceIn(document, message) })
+  }),
+)