browser-debugger-cli 0.12.0 → 0.14.0

package/dist/ui/messages/commands.js

@@ -26,6 +26,15 @@ export function chromeClosedMessage(pid) {
 export function orphanedDaemonsCleanedMessage(count) {
     return `Cleaned up ${count} orphaned daemon process${count === 1 ? '' : 'es'}`;
 }
+/**
+ * Where `bdg install-skill` kept the copy it replaced.
+ *
+ * @param path - Backup path, as the user would type it
+ * @returns One line
+ */
+export function skillBackupMessage(path) {
+    return `previous copy kept in ${path}`;
+}
 /**
  * Warning shown when a click falls back from mouse events to `el.click()`.
  *
@@ -184,16 +193,53 @@ export function valueMismatchWarning(mismatch) {
  */
 export const CLICK_NOT_RECEIVED_WARNING = 'The click may not have reached the element: the page saw no mouse press (the browser may be showing a dialog or bubble that captures input)';
 /**
- * Note under a shortened list of matches.
+ * Note under a shortened human list whose JSON output lists more, up to a cap.
  *
- * @param hidden - Matches not listed
- * @param jsonLimit - How many JSON output lists, when it leaves some out too
- * @returns e.g. "... and 1174 more (use --json for all)",
- *   "... and 8980 more (--json lists the first 100)"
+ * @param hidden - Items not listed
+ * @param jsonLimit - Most items the JSON output lists
+ * @returns e.g. "... and 8980 more (--json lists up to 100)"
  */
 export function moreMatchesNote(hidden, jsonLimit) {
-    const where = jsonLimit === undefined ? 'use --json for all' : `--json lists the first ${jsonLimit}`;
-    return `... and ${hidden} more (${where})`;
+    return `... and ${hidden} more (--json lists up to ${jsonLimit})`;
+}
+/**
+ * Note under `dom query` matches cut by `--limit`.
+ *
+ * @param omitted - Matches not listed
+ * @param indexed - Matches usable by index, when not all of them
+ * @returns e.g. `... and 49953 more (--limit 0 lists all; indices 0-999 work with other commands)`
+ */
+export function queryMoreMatchesNote(omitted, indexed) {
+    const indices = indexed === undefined ? '' : `; indices 0-${indexed - 1} work with other commands`;
+    return `... and ${omitted} more (--limit 0 lists all${indices})`;
+}
+/**
+ * Note under `dom query` matches listed past those whose viewport position
+ * was checked.
+ *
+ * @param checked - First matches checked
+ * @returns e.g. `Visibility is checked for the first 100 matches only; bdg dom layout <index> checks any of them`
+ */
+export function queryViewportCheckedNote(checked) {
+    return `Visibility is checked for the first ${checked} matches only; ${sessionCommand('bdg dom layout <index>')} checks any of them`;
+}
+/**
+ * First line under an accessibility tree cut by `--limit` or `--depth`.
+ *
+ * @param listed - Nodes listed
+ * @returns e.g. "Showing the first 50 nodes (text boxes and repeated text left out)"
+ */
+export function a11yTreeShownNote(listed) {
+    return `Showing the first ${listed} nodes (text boxes and repeated text left out)`;
+}
+/**
+ * How to see the rest of an accessibility tree cut by `--limit` or `--depth`.
+ *
+ * @param omitted - Nodes left out
+ * @returns e.g. "51391 more: --limit 0 lists all, --depth <n> limits the levels, or search with bdg dom a11y query \"role:<role>\""
+ */
+export function a11yTreeMoreNote(omitted) {
+    return `${omitted} more: --limit 0 lists all, --depth <n> limits the levels, or search with bdg dom a11y query "role:<role>"`;
 }
 /**
  * Note under a list of a11y query matches cut by `--limit`.
@@ -253,6 +299,37 @@ export const LAYOUT_REASONS = {
     /** Joins an invisible reason to the ancestor causing it */
     on: ' on ',
 };
+/** Why an out-of-view text's contrast in `dom audit` is approximate: none of its ancestors paints a background */
+export const AUDIT_OUT_OF_VIEW_RISK = 'only its ancestors were checked';
+/**
+ * `dom audit contrast` note for text that looks below the level but cannot
+ * be measured exactly (over an image, blended, under or over another layer).
+ *
+ * @param count - How many such texts
+ * @returns e.g. `(+12 more may be below it but cannot be measured: text over images or blended layers; check them with bdg dom inspect)`
+ */
+export function auditUncertainContrastNote(count) {
+    return `(+${count} more may be below it but cannot be measured: text over images or blended layers; check them with ${sessionCommand('bdg dom inspect <element>')})`;
+}
+/**
+ * `dom audit animations` note for canvas elements, whose script-drawn
+ * animations it cannot see.
+ *
+ * @param count - Visible canvas elements
+ * @returns e.g. `(+ 2 canvas elements: animations drawn by scripts on them are not listed)`
+ */
+export function auditCanvasNote(count) {
+    return `(+ ${count} canvas ${count === 1 ? 'element' : 'elements'}: animations drawn by scripts on ${count === 1 ? 'it are' : 'them are'} not listed)`;
+}
+/**
+ * A mask over an element, for `dom layout` and `dom inspect`.
+ *
+ * @param masked - The mask, e.g. `mask-image on div.hero`
+ * @returns e.g. `masked by mask-image on div.hero`
+ */
+export function maskedText(masked) {
+    return `masked by ${masked}`;
+}
 /** Start of the off-screen reason of an element a scroll-locked page hides ({@link scrollLockedReason}) */
 const SCROLL_LOCKED_PREFIX = 'page scrolling is locked';
 /**
@@ -391,16 +468,63 @@ export function colorSchemeLabel(scheme, emulated) {
     const source = emulated ? 'emulated' : 'from the system setting';
     return `prefers-color-scheme: ${scheme} (${source})`;
 }
+/**
+ * Suggestion for an action that failed on a page that replaced built-ins
+ * bdg's page scripts use.
+ *
+ * @param replaced - Their dotted names (all are named)
+ * @returns Suggestion naming them and a way around
+ */
+export function brokenByReplacedBuiltinsSuggestion(replaced) {
+    return `The page replaced built-ins bdg's action script uses (${replaced.join(', ')}), which may have broken it; if so, act on the element with ${sessionCommand("bdg dom eval '…'")} instead`;
+}
+/**
+ * Warning on an action when the page replaced built-ins bdg's page scripts
+ * use (polyfills, old frameworks, anti-bot scripts). Names the first four;
+ * the action's `replacedBuiltins` (JSON) lists them all.
+ *
+ * @param replaced - Their dotted names
+ * @returns e.g. `the page replaced built-ins bdg's scripts use (Element.prototype.querySelectorAll); bdg found the element in its own world, but the action runs in the page's and may misbehave`
+ */
+export function replacedBuiltinsWarning(replaced) {
+    const shown = replaced.slice(0, 4).join(', ') +
+        (replaced.length > 4 ? `, +${replaced.length - 4} more (see --json)` : '');
+    return `the page replaced built-ins bdg's scripts use (${shown}); bdg found the element in its own world, but the action runs in the page's and may misbehave`;
+}
 /**
  * First line of `bdg status` for a running session.
  *
- * @param page - URL and title of the page, when the session reported them
- * @returns e.g. `Session active: https://example.com/ — Example Domain`
+ * @param page - URL and title of the page, when the session reported them,
+ *   and when it crashed
+ * @returns e.g. `Session active: https://example.com/ — Example Domain`, with
+ *   a crash warning on a second line
  */
 export function sessionActiveLine(page) {
     if (!page)
         return 'Session active';
-    return `Session active: ${page.url}${page.title ? ` — ${page.title}` : ''}`;
+    const line = `Session active: ${page.url}${page.title ? ` — ${page.title}` : ''}`;
+    return page.crashedAt === undefined ? line : `${line}\n${pageCrashedNote(page.crashedAt)}`;
+}
+/**
+ * Warning that the session's page crashed, for `bdg status`, `bdg peek`,
+ * `bdg console` and `bdg network list`.
+ *
+ * @param crashedAt - When it crashed (epoch ms)
+ * @returns e.g. `⚠ The page crashed at 18:42:10 (renderer gone); bdg page reload brings it back`
+ */
+export function pageCrashedNote(crashedAt) {
+    return `⚠ The page crashed at ${new Date(crashedAt).toLocaleTimeString()} (renderer gone); ${sessionCommand('bdg page reload')} brings it back`;
+}
+/**
+ * Put the page-crashed warning before a view of collected data, when the
+ * page crashed (what is shown was collected before).
+ *
+ * @param body - The view
+ * @param crashedAt - When the page crashed (epoch ms), if it did
+ * @returns The view, after the warning when the page crashed
+ */
+export function withPageCrashedNote(body, crashedAt) {
+    return crashedAt === undefined ? body : `${pageCrashedNote(crashedAt)}\n\n${body}`;
 }
 /**
  * Page dimensions line of `bdg dom layout`.
@@ -477,10 +601,13 @@ export function coverText(cover, transparent) {
  * Note when `bdg dom inspect` could not read the element's matched rules, so
  * no hints, rules or why were computed.
  *
- * @param reason - `timeout` (very large stylesheets) or `failed` (Chrome reported an error)
+ * @param reason - `timeout` (very large stylesheets), `failed` (Chrome reported
+ *   an error) or `skipped` (hints not read: an earlier read on this page timed out)
  * @returns Note
  */
 export function inspectCascadeNote(reason) {
+    if (reason === 'skipped')
+        return "hints skipped: this page's stylesheets are slow to read (--rules waits 5 s)";
     return reason === 'timeout'
         ? "CSS rules not read: the page's stylesheets took too long (hints wait 1 s; --rules and --why 5 s)"
         : 'CSS rules not read: Chrome could not report the rules matching this element';
@@ -524,6 +651,7 @@ export function inspectVisibilityBadges(visibility) {
         visibility.hidden && `[hidden: ${visibility.hidden}]`,
         visibility.offscreen && `[offscreen: ${visibility.offscreen}]`,
         visibility.coveredBy && `[${coverText(visibility.coveredBy, visibility.coverTransparent)}]`,
+        visibility.masked && `[${maskedText(visibility.masked)}]`,
     ].filter((badge) => Boolean(badge));
 }
 /**
@@ -674,6 +802,19 @@ export function dialogConsoleText(dialog) {
     const kind = dialog.type === 'beforeunload' ? 'beforeunload' : `${dialog.type}()`;
     return `${kind} dialog accepted${dialog.message ? `: "${dialog.message}"` : ''}`;
 }
+/**
+ * How far a pointer action scrolled the page to reach its element.
+ *
+ * @param scrolledBy - Page scroll (CSS px)
+ * @returns e.g. `page down 1240px to reach it`, `page right 300px, up 80px to reach it`
+ */
+export function pointerScrollText(scrolledBy) {
+    const parts = [
+        scrolledBy.y !== 0 && `${scrolledBy.y > 0 ? 'down' : 'up'} ${Math.abs(scrolledBy.y)}px`,
+        scrolledBy.x !== 0 && `${scrolledBy.x > 0 ? 'right' : 'left'} ${Math.abs(scrolledBy.x)}px`,
+    ].filter(Boolean);
+    return `page ${parts.join(', ')} to reach it`;
+}
 /** Headline of each pointer action, e.g. "Element Double-clicked" */
 export const POINTER_ACTION_DONE = {
     click: 'Clicked',
@@ -912,13 +1053,17 @@ export function elementTextLine(text) {
  *
  * @param children - First child elements, e.g. `iframe#app`
  * @param count - Number of child elements
- * @returns e.g. `No text; holds 1 element: iframe (see its HTML with --raw)`
+ * @param inShadowRoot - The children are those of its shadow root (`--raw` does not show them)
+ * @returns e.g. `No text; holds 1 element: iframe (see its HTML with --raw)`,
+ *   `No text; its shadow root holds 1 element: button "Close" (see it with bdg dom inspect)`
  */
-export function emptyElementLine(children, count) {
+export function emptyElementLine(children, count, inShadowRoot = false) {
+    const holder = inShadowRoot ? 'its shadow root holds' : 'holds';
     if (count === 0)
-        return 'No text and no child elements';
+        return `No text and no child elements${inShadowRoot ? ' in its shadow root' : ''}`;
     const more = count > children.length ? `, … ${count - children.length} more` : '';
-    return `No text; holds ${pluralize(count, 'element')}: ${children.join(', ')}${more} (see its HTML with --raw)`;
+    const hint = inShadowRoot ? 'see it with bdg dom inspect' : 'see its HTML with --raw';
+    return `No text; ${holder} ${pluralize(count, 'element')}: ${children.join(', ')}${more} (${hint})`;
 }
 /**
  * Note on a screenshot scaled down to keep its image token cost bounded.
@@ -969,6 +1114,27 @@ export function queryNextSteps(index) {
 export function evalFrameLine(url) {
     return `Frame: ${frameUrlLabel(url)}`;
 }
+/**
+ * Warning on a `dom eval` result the browser copied because the page
+ * replaced built-ins bdg's own copy uses.
+ *
+ * @param replaced - Their dotted names (all are named)
+ * @returns e.g. `the page replaced Object.keys, so the browser copied the result: undefined, NaN, functions, DOM nodes, dates, maps and sets inside it show as null or {}`
+ */
+export function evalCopiedByBrowserWarning(replaced) {
+    return `the page replaced ${replaced.join(', ')}, so the browser copied the result: undefined, NaN, functions, DOM nodes, dates, maps and sets inside it show as null or {}`;
+}
+/**
+ * Warning on a `dom eval` result shown as its preview: the page replaced
+ * built-ins bdg's copy uses and the browser could not copy it either (a
+ * cycle or a BigInt inside).
+ *
+ * @param replaced - Their dotted names (all are named)
+ * @returns Warning that the value is a shortened preview
+ */
+export function evalPreviewWarning(replaced) {
+    return `the page replaced ${replaced.join(', ')}, and the result could not be copied (it holds a cycle or a BigInt), so it is shown as a shortened preview string; return a JSON-safe value (e.g. pick the fields you need)`;
+}
 /**
  * Generate warning message.
  *
@@ -1124,4 +1290,21 @@ Examples:
                                   bdg css search --limit 50 -- --brand)
   bdg css search "oklch("         Rules that use oklch colors
   bdg css search ".btn-primary"   Rules of a class, in every stylesheet`;
+/**
+ * `details` field of `bdg --help --json`: where the full help is.
+ *
+ * @returns Note
+ */
+export function helpJsonDetailsNote() {
+    return 'Option behaviors, defaults, choices and examples: bdg <command> --help --json (e.g. bdg dom query --help --json). Everything at once: bdg --help --json --full';
+}
+/**
+ * Pointer after a value cut for human output.
+ *
+ * @param count - Characters left out
+ * @returns e.g. `… 299800 more chars (use --full)`
+ */
+export function moreCharsNote(count) {
+    return `… ${count} more chars (use --full)`;
+}
 //# sourceMappingURL=commands.js.map

package/dist/ui/messages/consoleMessages.d.ts

@@ -25,4 +25,28 @@ export declare function stoppedFollowingConsoleMessage(): string;
  * @returns e.g. `[n] are positions in the session's message list; not listed in between: 1 message from another page load (-H lists all)`
  */
 export declare function consoleIndexGapNote(skipped: ConsoleSkipped): string;
+/**
+ * Note that the session dropped its oldest console messages at the limit.
+ *
+ * @param dropped - Messages dropped
+ * @returns e.g. `⚠ 2000 older console messages were dropped: bdg keeps the newest 10000`
+ */
+export declare function consoleDroppedNote(dropped: number): string;
+/**
+ * Error for `bdg details console <n>` with the index of a dropped message.
+ *
+ * @param index - Index asked for
+ * @param dropped - Messages dropped (the first kept has this index)
+ * @returns Message
+ */
+export declare function consoleMessageDroppedError(index: number, dropped: number): string;
+/**
+ * Note under the console summary when it lists only the newest distinct
+ * errors or warnings.
+ *
+ * @param more - Distinct messages not listed
+ * @param level - `error` or `warning`
+ * @returns e.g. `(+120 earlier distinct errors; bdg console --level error --last 0 lists every one)`
+ */
+export declare function consoleMoreGroupsNote(more: number, level: 'error' | 'warning'): string;
 //# sourceMappingURL=consoleMessages.d.ts.map

package/dist/ui/messages/consoleMessages.js

@@ -3,7 +3,9 @@
  *
  * User-facing messages for the console command output and formatting.
  */
+import { MAX_CONSOLE_MESSAGES } from '../../constants.js';
 import { pluralize } from '../formatting.js';
+import { sessionCommand } from './sessionCommand.js';
 /**
  * Generate message for following console output.
  *
@@ -36,4 +38,34 @@ export function consoleIndexGapNote(skipped) {
     ].filter(Boolean);
     return `[n] are positions in the session's message list; not listed in between: ${reasons.join(', ')}`;
 }
+/**
+ * Note that the session dropped its oldest console messages at the limit.
+ *
+ * @param dropped - Messages dropped
+ * @returns e.g. `⚠ 2000 older console messages were dropped: bdg keeps the newest 10000`
+ */
+export function consoleDroppedNote(dropped) {
+    return `⚠ ${pluralize(dropped, 'older console message')} ${dropped === 1 ? 'was' : 'were'} dropped: bdg keeps the newest ${MAX_CONSOLE_MESSAGES}`;
+}
+/**
+ * Error for `bdg details console <n>` with the index of a dropped message.
+ *
+ * @param index - Index asked for
+ * @param dropped - Messages dropped (the first kept has this index)
+ * @returns Message
+ */
+export function consoleMessageDroppedError(index, dropped) {
+    return `Console message ${index} was dropped: bdg keeps the newest ${MAX_CONSOLE_MESSAGES} messages (the oldest kept is ${dropped})`;
+}
+/**
+ * Note under the console summary when it lists only the newest distinct
+ * errors or warnings.
+ *
+ * @param more - Distinct messages not listed
+ * @param level - `error` or `warning`
+ * @returns e.g. `(+120 earlier distinct errors; bdg console --level error --last 0 lists every one)`
+ */
+export function consoleMoreGroupsNote(more, level) {
+    return `(+${more} earlier distinct ${more === 1 ? level : `${level}s`}; ${sessionCommand(`bdg console --level ${level} --last 0`)} lists every one)`;
+}
 //# sourceMappingURL=consoleMessages.js.map

package/dist/ui/messages/networkMessages.d.ts

@@ -3,6 +3,30 @@
  *
  * User-facing messages for the network list command output and formatting.
  */
+/**
+ * Why a stored response body was replaced by a placeholder (shown by
+ * `bdg details network <id>` as `bodyNotCaptured`).
+ *
+ * @param budgetBytes - Total body budget of the session
+ * @returns e.g. `evicted: total body budget (bdg keeps the newest 100 MB of response bodies)`
+ */
+export declare function bodyEvictedReason(budgetBytes: number): string;
+/** What a session's network capture let go at its limits */
+export interface NetworkEvictionCounts {
+    /** Oldest finished requests dropped at the request cap */
+    requestsDropped: number;
+    /** Oldest response bodies evicted at the body budget */
+    bodiesEvicted: number;
+}
+/**
+ * Note that the session dropped its oldest requests or evicted its oldest
+ * response bodies at its limits.
+ *
+ * @param counts - Requests dropped and bodies evicted
+ * @returns e.g. `⚠ 2000 older network requests were dropped: bdg keeps the newest 10000`;
+ *   undefined when nothing was let go
+ */
+export declare function networkEvictedNote(counts: NetworkEvictionCounts): string | undefined;
 /**
  * Generate message for following network output.
  *

package/dist/ui/messages/networkMessages.js

@@ -3,6 +3,51 @@
  *
  * User-facing messages for the network list command output and formatting.
  */
+import { MAX_NETWORK_REQUESTS, MAX_TOTAL_BODY_BYTES } from '../../constants.js';
+import { pluralize } from '../formatting.js';
+/**
+ * A byte budget in whole megabytes.
+ *
+ * @param bytes - Budget
+ * @returns e.g. `100 MB`
+ */
+function megabytes(bytes) {
+    return `${Math.round(bytes / (1024 * 1024))} MB`;
+}
+/**
+ * Why a stored response body was replaced by a placeholder (shown by
+ * `bdg details network <id>` as `bodyNotCaptured`).
+ *
+ * @param budgetBytes - Total body budget of the session
+ * @returns e.g. `evicted: total body budget (bdg keeps the newest 100 MB of response bodies)`
+ */
+export function bodyEvictedReason(budgetBytes) {
+    return `evicted: total body budget (bdg keeps the newest ${megabytes(budgetBytes)} of response bodies)`;
+}
+/**
+ * Note that the session dropped its oldest requests or evicted its oldest
+ * response bodies at its limits.
+ *
+ * @param counts - Requests dropped and bodies evicted
+ * @returns e.g. `⚠ 2000 older network requests were dropped: bdg keeps the newest 10000`;
+ *   undefined when nothing was let go
+ */
+export function networkEvictedNote(counts) {
+    const { requestsDropped, bodiesEvicted } = counts;
+    const requests = pluralize(requestsDropped, 'older network request');
+    const bodies = pluralize(bodiesEvicted, 'older response body', 'older response bodies');
+    const budget = megabytes(MAX_TOTAL_BODY_BYTES);
+    if (requestsDropped > 0 && bodiesEvicted > 0) {
+        return `⚠ ${requests} dropped, ${bodies} evicted: bdg keeps the newest ${MAX_NETWORK_REQUESTS} requests and ${budget} of bodies`;
+    }
+    if (requestsDropped > 0) {
+        return `⚠ ${requests} ${requestsDropped === 1 ? 'was' : 'were'} dropped: bdg keeps the newest ${MAX_NETWORK_REQUESTS}`;
+    }
+    if (bodiesEvicted > 0) {
+        return `⚠ ${bodies} ${bodiesEvicted === 1 ? 'was' : 'were'} evicted: bdg keeps the newest ${budget} of bodies`;
+    }
+    return undefined;
+}
 /**
  * Generate message for following network output.
  *

package/dist/ui/messages/preview.d.ts

@@ -55,6 +55,12 @@ export declare function stoppedFollowingPreviewMessage(): string;
  * @param retryLabel - Human-readable retry interval (e.g. "1s", "500ms")
  */
 export declare function connectionLostRetryMessage(timestamp: string, retryLabel: string): string;
+/**
+ * Follow mode stops because the session it followed ended.
+ *
+ * @returns Message
+ */
+export declare function followedSessionEndedMessage(): string;
 /**
  * Generate follow-mode stop hint.
  *

package/dist/ui/messages/preview.js

@@ -19,7 +19,7 @@ export const PREVIEW_HEADERS = {
  * @returns Single-line tip for basic peek usage
  */
 export function compactTipsMessage() {
-    return `Tip: ${sessionCommand('bdg peek --last 50')} | ${sessionCommand('bdg peek --verbose')}`;
+    return `Tip: ${sessionCommand('bdg peek --last 50')} or ${sessionCommand('bdg peek --verbose')}`;
 }
 /**
  * Generate verbose mode commands section.
@@ -71,6 +71,14 @@ export function stoppedFollowingPreviewMessage() {
 export function connectionLostRetryMessage(timestamp, retryLabel) {
     return `\n[${timestamp}] ⚠️  Connection lost, retrying every ${retryLabel}...`;
 }
+/**
+ * Follow mode stops because the session it followed ended.
+ *
+ * @returns Message
+ */
+export function followedSessionEndedMessage() {
+    return 'The session ended; stopped following';
+}
 /**
  * Generate follow-mode stop hint.
  *

package/dist/ui/messages/session.d.ts

@@ -78,7 +78,18 @@ export declare function lastSessionEndText(end: {
     endedAt: number;
 }): string;
 /**
- * Note after a failed start whose daemon had not exited when bdg stopped waiting.
+ * A session that ended without `bdg stop`, for `bdg sessions`.
+ *
+ * @param label - Session name as listed
+ * @param end - How and when it ended
+ * @returns One line
+ */
+export declare function endedSessionText(label: string, end: {
+    reason: string;
+    endedAt: number;
+}): string;
+/**
+ * Note after a failed start or a stop whose daemon had not exited when bdg stopped waiting.
  *
  * @param pid - Daemon PID, when known
  * @param waitedMs - How long bdg waited
@@ -86,7 +97,7 @@ export declare function lastSessionEndText(end: {
  */
 export declare function daemonStillExitingHint(pid: number | undefined, waitedMs: number): string;
 /**
- * What to do about a daemon still shutting down after a failed start.
+ * What to do about a daemon still shutting down after a failed start or a stop.
  *
  * @returns Suggestion
  */

package/dist/ui/messages/session.js

@@ -89,16 +89,35 @@ export function stopFailedError(reason) {
  * @returns One line
  */
 export function lastSessionEndText(end) {
+    return `The last session ended ${sessionEndText(end)}`;
+}
+/**
+ * A session that ended without `bdg stop`, for `bdg sessions`.
+ *
+ * @param label - Session name as listed
+ * @param end - How and when it ended
+ * @returns One line
+ */
+export function endedSessionText(label, end) {
+    return `${label} ended ${sessionEndText(end)}`;
+}
+/**
+ * When and why a session ended without `bdg stop`.
+ *
+ * @param end - How and when it ended
+ * @returns `at <time>: <why>`
+ */
+function sessionEndText(end) {
     const why = {
         crash: 'Chrome crashed or was closed',
         closed: 'its page was closed',
         timeout: 'the --timeout was reached',
     };
     const at = new Date(end.endedAt).toLocaleTimeString();
-    return `The last session ended at ${at}: ${why[end.reason] ?? end.reason}`;
+    return `at ${at}: ${why[end.reason] ?? end.reason}`;
 }
 /**
- * Note after a failed start whose daemon had not exited when bdg stopped waiting.
+ * Note after a failed start or a stop whose daemon had not exited when bdg stopped waiting.
  *
  * @param pid - Daemon PID, when known
  * @param waitedMs - How long bdg waited
@@ -109,7 +128,7 @@ export function daemonStillExitingHint(pid, waitedMs) {
     return `${daemon} was still shutting down after ${waitedMs / 1000}s`;
 }
 /**
- * What to do about a daemon still shutting down after a failed start.
+ * What to do about a daemon still shutting down after a failed start or a stop.
  *
  * @returns Suggestion
  */

package/dist/utils/directories.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Checks for a directory bdg is about to create and write (the session
+ * directory, a Chrome profile) before it touches it: `fs.mkdirSync` with
+ * `recursive` spins forever on Linux pseudo-filesystems (`/proc/x` kept a
+ * start at full CPU until SIGKILL), and a profile Chrome cannot use wedges
+ * the session.
+ */
+/** Why a directory cannot be used, and whether it is a permission problem */
+export interface DirectoryProblem {
+    /** e.g. `/proc is a pseudo-filesystem`, `/tmp/x is a file`, `EACCES` */
+    reason: string;
+    /** Permission denied (or a read-only file system) rather than a wrong path */
+    denied: boolean;
+}
+/**
+ * Why `dir` cannot be created or written: it (or the path to it) is on a
+ * pseudo-filesystem, a part of it is a file, or its nearest existing
+ * directory is not writable.
+ *
+ * @param dir - Directory path (resolved against the working directory)
+ * @returns The problem, or null when the directory can be used
+ */
+export declare function directoryProblem(dir: string): DirectoryProblem | null;
+/**
+ * Create a directory (and its parents) after {@link directoryProblem} found
+ * nothing wrong, so a pseudo-filesystem fails at once instead of spinning.
+ *
+ * @param dir - Directory to create
+ * @param mode - Permissions of the directories created
+ * @throws Error with `code` `EPSEUDOFS` (pseudo-filesystem), `ENOTDIR` (a
+ *   file on the path), `EACCES` (not writable), or the `mkdir` error
+ */
+export declare function makeDirectory(dir: string, mode?: number): void;
+//# sourceMappingURL=directories.d.ts.map