dsh-better-display 0.3.8 → 0.3.9

package/src/client/text-transform.ts

@@ -0,0 +1,265 @@
+import { useEffect, useMemo, useState } from 'react';
+import type { ReaderBlockOwner, ReaderBlockPresentation } from './types.js';
+
+/**
+ * Cordis service name. Another client plugin lists this in `inject` and
+ * registers a transformer. The reading view paints the result. The session
+ * block, transcript, and fold inputs stay on the original text.
+ */
+export const TEXT_TRANSFORM_SERVICE = 'dsh-better-display.text-transform';
+
+export type DisplayTextKind = 'reasoning' | 'body';
+
+export interface DisplayTextRequest {
+  /** Original block text. Registrants must not write it back onto the block. */
+  text: string;
+  streaming: boolean;
+  /** Opaque id of this mounted block. Stable until the block unmounts. */
+  blockKey: string;
+  kind: DisplayTextKind;
+  /** Assistant body and reasoning are the usual targets. Tool prose uses `tool`. */
+  source?: ReaderBlockOwner['source'];
+}
+
+export interface DisplayText {
+  text: string;
+  /**
+   * True when this string is the settled display for the current source.
+   * False keeps the live reveal open, including after the model has stopped
+   * but a translation batch is still outstanding.
+   */
+  final: boolean;
+}
+
+/**
+ * Sync `read` on every paint, plus `subscribe` when a later batch changes
+ * what `read` returns. `subscribe` may be called once per kind and must
+ * accept more than one listener.
+ */
+export interface DisplayTextTransformer {
+  read(request: DisplayTextRequest): DisplayText | string | undefined;
+  subscribe?(listener: () => void): () => void;
+}
+
+export interface DisplayCursor extends DisplayText {
+  /**
+   * Increments when the displayed string or its `final` bit changes.
+   * This is not the reveal clock. Passing it to the word timeline as the
+   * motion revision replays or snaps the paragraph.
+   */
+  transformRevision: number;
+  /**
+   * Reveal identity. Stays put when the new string extends the previous
+   * display string, so an appended translation batch continues the fade.
+   * Increments only when the string is replaced, which settles the new
+   * text instead of typing it again from the first grapheme.
+   */
+  motionRevision: number;
+}
+
+export interface TextTransformRegistry {
+  register(kind: DisplayTextKind | readonly DisplayTextKind[], transformer: DisplayTextTransformer): () => void;
+  has(kind: DisplayTextKind): boolean;
+  read(request: DisplayTextRequest): DisplayCursor;
+  subscribe(kind: DisplayTextKind, listener: () => void): () => void;
+  release(kind: DisplayTextKind, blockKey: string): void;
+}
+
+const KINDS = new Set<DisplayTextKind>(['reasoning', 'body']);
+
+function isKind(value: string): value is DisplayTextKind {
+  return KINDS.has(value as DisplayTextKind);
+}
+
+function reportTransformError(error: unknown): void {
+  console.warn('[dsh-better-display] text transform failed; showing original text', error);
+}
+
+function passthrough(request: DisplayTextRequest): DisplayCursor {
+  return { text: request.text, final: !request.streaming, transformRevision: 0, motionRevision: 0 };
+}
+
+function normalize(value: DisplayText | string | undefined, request: DisplayTextRequest): DisplayText {
+  if (typeof value === 'string') return { text: value, final: !request.streaming };
+  if (!value || typeof value.text !== 'string') return { text: request.text, final: !request.streaming };
+  return { text: value.text, final: typeof value.final === 'boolean' ? value.final : !request.streaming };
+}
+
+/**
+ * Appends keep the motion revision. A replacement gets a new one so the
+ * timeline treats the swapped string as already settled.
+ */
+export function nextDisplayCursor(previous: DisplayCursor | undefined, display: DisplayText): DisplayCursor {
+  if (!previous) return { ...display, transformRevision: 0, motionRevision: 0 };
+  if (previous.text === display.text && previous.final === display.final) return previous;
+  const appended = display.text.startsWith(previous.text);
+  return {
+    text: display.text,
+    final: display.final,
+    transformRevision: previous.transformRevision + 1,
+    motionRevision: appended ? previous.motionRevision : previous.motionRevision + 1,
+  };
+}
+
+/**
+ * Streaming flag fed to the reveal. With no transformer this is the model's
+ * flag. A transformer that reports `final: !streaming` produces the same flag.
+ */
+export function displayStreaming(sourceStreaming: boolean, shown: Pick<DisplayCursor, 'final'>, active: boolean): boolean {
+  return active ? !shown.final : sourceStreaming;
+}
+
+/** No registry, or none for this kind: the source string, and no cursor write. */
+export function readDisplayText(registry: TextTransformRegistry | undefined, request: DisplayTextRequest): DisplayCursor {
+  if (!registry?.has(request.kind)) return passthrough(request);
+  return registry.read(request);
+}
+
+interface StackEntry {
+  transformer: DisplayTextTransformer;
+  unsubscribe?: () => void;
+}
+
+class TextTransformRegistryImpl implements TextTransformRegistry {
+  private readonly stacks = new Map<DisplayTextKind, StackEntry[]>();
+  private readonly listeners = new Map<DisplayTextKind, Set<() => void>>();
+  private readonly cursors = new Map<string, DisplayCursor>();
+
+  register(kind: DisplayTextKind | readonly DisplayTextKind[], transformer: DisplayTextTransformer): () => void {
+    const requested = [...new Set(Array.isArray(kind) ? kind : [kind])];
+    for (const item of requested) {
+      if (!isKind(item)) throw new Error(`Unknown display text kind: ${String(item)}`);
+    }
+    const bound: { kind: DisplayTextKind; entry: StackEntry }[] = [];
+    for (const item of requested) {
+      const entry: StackEntry = { transformer };
+      try {
+        entry.unsubscribe = transformer.subscribe?.(() => { this.emit(item); });
+      } catch (error) {
+        reportTransformError(error);
+      }
+      const stack = this.stacks.get(item) ?? [];
+      stack.push(entry);
+      this.stacks.set(item, stack);
+      bound.push({ kind: item, entry });
+      this.emit(item);
+    }
+    return () => {
+      for (const { kind: item, entry } of bound) {
+        try { entry.unsubscribe?.(); } catch (error) { reportTransformError(error); }
+        const stack = this.stacks.get(item);
+        if (!stack) continue;
+        const next = stack.filter(candidate => candidate !== entry);
+        if (next.length > 0) this.stacks.set(item, next);
+        else this.stacks.delete(item);
+        this.emit(item);
+      }
+    };
+  }
+
+  has(kind: DisplayTextKind): boolean {
+    return (this.stacks.get(kind)?.length ?? 0) > 0;
+  }
+
+  read(request: DisplayTextRequest): DisplayCursor {
+    const transformer = this.stacks.get(request.kind)?.at(-1)?.transformer;
+    if (!transformer) return passthrough(request);
+    let display: DisplayText;
+    try {
+      display = normalize(transformer.read(request), request);
+    } catch (error) {
+      // A broken transformer must never hide the original text. Show it and
+      // ask again on the next text change or notify, so a recovered
+      // transformer takes over without a remount.
+      reportTransformError(error);
+      display = { text: request.text, final: !request.streaming };
+    }
+    const key = `${request.kind}\u0000${request.blockKey}`;
+    const next = nextDisplayCursor(this.cursors.get(key), display);
+    this.cursors.set(key, next);
+    return next;
+  }
+
+  subscribe(kind: DisplayTextKind, listener: () => void): () => void {
+    const set = this.listeners.get(kind) ?? new Set();
+    set.add(listener);
+    this.listeners.set(kind, set);
+    return () => { set.delete(listener); };
+  }
+
+  release(kind: DisplayTextKind, blockKey: string): void {
+    this.cursors.delete(`${kind}\u0000${blockKey}`);
+  }
+
+  private emit(kind: DisplayTextKind): void {
+    const set = this.listeners.get(kind);
+    if (!set) return;
+    for (const listener of [...set]) listener();
+  }
+}
+
+export function createTextTransformRegistry(): TextTransformRegistry {
+  return new TextTransformRegistryImpl();
+}
+
+let active: TextTransformRegistry | undefined;
+
+/** Points the reading view at the registry this client plugin provides. */
+export function installTextTransformRegistry(registry: TextTransformRegistry | undefined): () => void {
+  const previous = active;
+  active = registry;
+  return () => { active = previous; };
+}
+
+export function activeTextTransform(): TextTransformRegistry | undefined {
+  return active;
+}
+
+/**
+ * Subscribe while mounted. The reveal components call this only after
+ * `has(kind)`, so an empty registry adds no hook and no listener.
+ */
+export function useDisplayText(registry: TextTransformRegistry, request: DisplayTextRequest): DisplayCursor {
+  const [epoch, setEpoch] = useState(0);
+  const { text, streaming, blockKey, kind, source } = request;
+  useEffect(() => registry.subscribe(kind, () => { setEpoch(value => value + 1); }), [registry, kind]);
+  useEffect(() => () => { registry.release(kind, blockKey); }, [registry, kind, blockKey]);
+  return useMemo(
+    () => registry.read({ text, streaming, blockKey, kind, source }),
+    [registry, text, streaming, blockKey, kind, source, epoch],
+  );
+}
+
+/** Chain-slot owner. Extra fields are optional so older callers still type-check. */
+export function readerBlockOwner(
+  block: ReaderBlockOwner['block'],
+  streaming: boolean,
+  source: ReaderBlockOwner['source'],
+  presentation: ReaderBlockPresentation,
+  holdFormatting: boolean,
+): ReaderBlockOwner {
+  return {
+    block,
+    streaming,
+    source,
+    presentation: {
+      startedAt: presentation.startedAt,
+      interrupted: presentation.interrupted,
+      liveText: presentation.liveText,
+    },
+    holdFormatting,
+    liveText: presentation.liveText,
+  };
+}
+
+/** Copy actions read this. Display text never replaces it. */
+export function originalAnswerText(blocks: readonly { readonly kind: string; readonly text?: string }[]): string {
+  return blocks.flatMap(block => block.kind === 'text' && typeof block.text === 'string' ? [block.text] : []).join('\n\n');
+}
+
+declare module '@deepseek-ai/cordis' {
+  interface Context {
+    /** Display-only reader text transforms. Present after this client plugin applies. */
+    'dsh-better-display.text-transform'?: TextTransformRegistry;
+  }
+}

package/src/client/timeline.ts

@@ -1,5 +1,3 @@
-import type { TurnLocation } from '@deepseek-ai/dsh-client-ui-conversation/client';
-
 export interface TimelineItem {
   readonly turn: number;
   readonly prompt: string;

package/src/client/tool-activity.ts

@@ -2,6 +2,7 @@ import type { AssistantBlock, ToolCallBlock, TurnLocation } from '@deepseek-ai/d
 import type { ChatConversationViewNode } from '@deepseek-ai/dsh-client-ui-chat/client';
 import type {} from '@deepseek-ai/dsh-client-ui-conversation/client';
 import type { ReaderGroup } from './projection.js';
+import { anchorSeqOf, cutContains, rewindCutSpans, type CutChatNode } from './rewind-cut.js';
 
 export type ToolDraft = Extract<AssistantBlock, { kind: 'tool-call' }>;
 export type ToolPhase = 'preparing' | 'running' | 'returned' | 'succeeded' | 'failed' | 'interrupted';
@@ -12,11 +13,52 @@ export interface ToolActivityEntry {
 }
 export type ReaderFlowEntry = ToolActivityEntry | { kind: 'node'; key: string; nodeKey: string; order: number };
 
-/** Public Step data includes tool-only model output before a chat node exists. */
-export function readerFlow(group: ReaderGroup, turn: TurnLocation | undefined, get: (key: string) => ChatConversationViewNode | undefined): ReaderFlowEntry[] {
+/**
+ * callId of a tool-call chat node. Drafts for a call whose node was cut must
+ * not be reintroduced after `group.keys` has already dropped that node.
+ */
+function toolCallId(node: ChatConversationViewNode): string | undefined {
+  const callId = (node.data as { root?: { callId?: unknown } } | null)?.root?.callId;
+  return typeof callId === 'string' && callId.length > 0 ? callId : undefined;
+}
+
+/** callIds whose tool-call node sits inside a rewind cut. */
+function cutToolCallIds(
+  order: readonly string[],
+  get: (key: string) => ChatConversationViewNode | undefined,
+  spans: readonly { readonly start: number; readonly end: number }[],
+): Set<string> {
+  const ids = new Set<string>();
+  for (const key of order) {
+    const node = get(key);
+    if (node?.kind !== 'tool-call') continue;
+    const seq = anchorSeqOf(node as CutChatNode);
+    if (seq === undefined || !cutContains(spans, seq)) continue;
+    const callId = toolCallId(node);
+    if (callId !== undefined) ids.add(callId);
+  }
+  return ids;
+}
+
+/**
+ * Public Step data includes tool-only model output before a chat node exists.
+ *
+ * `sourceOrder` is the unfiltered chat order. Drafts that belong to a cut step,
+ * or to a call whose tool-call node was cut, are not put back. A draft that
+ * still has no tool-call node, on a step outside the cut, stays — that is the
+ * in-flight call the host has not published a node for yet.
+ */
+export function readerFlow(
+  group: ReaderGroup,
+  turn: TurnLocation | undefined,
+  get: (key: string) => ChatConversationViewNode | undefined,
+  sourceOrder?: readonly string[],
+): ReaderFlowEntry[] {
   const flow: ReaderFlowEntry[] = [];
   const calls = new Map<string, ToolActivityEntry>();
   const assistantOrder = new Map<number, number>();
+  const spans = sourceOrder === undefined ? [] : rewindCutSpans({ order: sourceOrder, nodes: { get } });
+  const cutCalls = spans.length === 0 || sourceOrder === undefined ? undefined : cutToolCallIds(sourceOrder, get, spans);
   for (const key of group.keys) {
     const node = get(key);
     if (!node || node.visibility === 'hidden') continue;
@@ -31,10 +73,15 @@ export function readerFlow(group: ReaderGroup, turn: TurnLocation | undefined, g
   }
   for (const step of turn?.steps ?? []) {
     const data = step.data.get('assistant-step');
+    const stepSeq = step.start?.seq;
+    const stepCut = typeof stepSeq === 'number' && spans.length > 0 && cutContains(spans, stepSeq);
     let index = 0;
     for (const draft of data?.blocks ?? []) {
       if (draft.kind !== 'tool-call' || !draft.callId) continue;
       const previous = calls.get(draft.callId);
+      // A visible tool row still receives its draft. A new row is the streaming
+      // case — unless this step, or this call's tool-call node, was cut.
+      if (!previous && (stepCut || cutCalls?.has(draft.callId) === true)) continue;
       calls.set(draft.callId, previous ? { ...previous, draft } : {
         kind: 'tool', key: `reader-tool:${draft.callId}`, callId: draft.callId, step: step.step, draft,
         order: (assistantOrder.get(step.step) ?? step.start?.seq ?? 0) + .01 + index++ / 10000,

package/src/client/turn-slots.ts

@@ -0,0 +1,80 @@
+/** One turn lane: `live` while it is still in the visible order. */
+export interface TurnSlot<T extends { readonly key: string }> {
+  readonly group: T;
+  readonly live: boolean;
+}
+
+/**
+ * Keep live turns in the incoming `groups` order, and keep a departing turn
+ * next to the live neighbour that preceded it.
+ *
+ * A rewind removes turn keys from the visible order. Unmounting them in that
+ * same commit snaps the transcript, so the lane retains the last group object
+ * until the collapse finishes. A re-render, a stream tick, or a reconnect that
+ * still contains the same keys only replaces the group object and leaves
+ * `live` true — those updates must not start a collapse. A key that returns
+ * is live again where `groups` places it. Loading older history therefore
+ * stays in transcript order instead of appending the older turns after the
+ * ones already on screen. A departing slot is inserted immediately after the
+ * nearest preceding slot that is still live, or at the front when it had none,
+ * so several departing neighbours keep their relative order.
+ *
+ * Returns `current` itself when nothing changed, so a React state update can
+ * bail out on `Object.is`.
+ */
+export function reconcileTurnSlots<T extends { readonly key: string }>(
+  current: readonly TurnSlot<T>[],
+  groups: readonly T[],
+): readonly TurnSlot<T>[] {
+  const incoming = new Map(groups.map(group => [group.key, group]));
+  const next: TurnSlot<T>[] = groups.map(group => ({ group, live: true }));
+  for (const slot of current) {
+    if (incoming.has(slot.group.key)) continue;
+    insertDeparting(next, { group: slot.group, live: false }, precedingLiveKey(current, incoming, slot.group.key));
+  }
+  const same =
+    next.length === current.length &&
+    next.every(
+      (slot, index) => slot.live === current[index]!.live && slot.group === current[index]!.group,
+    );
+  return same ? current : next;
+}
+
+/** Nearest preceding slot that is still in the incoming order, if any. */
+function precedingLiveKey<T extends { readonly key: string }>(
+  current: readonly TurnSlot<T>[],
+  incoming: ReadonlyMap<string, T>,
+  key: string,
+): string | undefined {
+  const index = current.findIndex(slot => slot.group.key === key);
+  for (let cursor = index - 1; cursor >= 0; cursor--) {
+    const candidate = current[cursor]!.group.key;
+    if (incoming.has(candidate)) return candidate;
+  }
+  return undefined;
+}
+
+/**
+ * Place a departing slot after `anchorKey`, or at the front when the slot had
+ * no preceding live neighbour. Slots that share an anchor keep `current` order
+ * because each one is inserted at the end of the departing run after that anchor.
+ */
+function insertDeparting<T extends { readonly key: string }>(
+  next: TurnSlot<T>[],
+  slot: TurnSlot<T>,
+  anchorKey: string | undefined,
+): void {
+  if (anchorKey === undefined) {
+    const firstLive = next.findIndex(item => item.live);
+    next.splice(firstLive < 0 ? next.length : firstLive, 0, slot);
+    return;
+  }
+  const anchorIndex = next.findIndex(item => item.group.key === anchorKey);
+  if (anchorIndex < 0) {
+    next.unshift(slot);
+    return;
+  }
+  let insertAt = anchorIndex + 1;
+  while (insertAt < next.length && next[insertAt]?.live === false) insertAt++;
+  next.splice(insertAt, 0, slot);
+}

package/src/client/types.ts

@@ -10,10 +10,29 @@ import type { OfficialSeat } from './official-slots.js';
 import type { OpenFileOptions, TurnTailOwnerProps } from '@deepseek-ai/dsh-client-ui-chat/client';
 import type {} from '@deepseek-ai/dsh-client-ui-tool/client';
 
+/**
+ * Display inputs the Reader already computed for this block.
+ * Older callers may omit the object. Registrants must tolerate that.
+ */
+export interface ReaderBlockPresentation {
+  /** Assistant step time, when the Reader has one. */
+  startedAt?: number;
+  /** True when this step was interrupted. */
+  interrupted?: boolean;
+  /** True when this block may run the live reveal. */
+  liveText?: boolean;
+}
+
 export interface ReaderBlockOwner {
   block: AssistantBlock;
   streaming: boolean;
   source: 'assistant' | 'user' | 'tool';
+  /** Viewport and motion inputs. Absent on owners built before this field existed. */
+  presentation?: ReaderBlockPresentation;
+  /** Selection is holding Markdown formatting in place. */
+  holdFormatting?: boolean;
+  /** Same value as `presentation.liveText`, repeated so a registrant can read it directly. */
+  liveText?: boolean;
 }
 
 declare module '@deepseek-ai/dsh-client-ui-slots' {

package/src/dsh-better-display.ts

@@ -1,8 +1,11 @@
 import type { IncomingMessage, ServerResponse } from 'node:http';
 import type { Context } from '@deepseek-ai/cordis';
+import { loadFlags, type Flags } from './flags.js';
+import { createLogger, requestIdOf } from './log.js';
+import { metricsPayload, recordRouteDuration, recordRouteHit, ROUTE_METRICS, ROUTE_REVEAL, ROUTE_SKILL_STATUS } from './metrics.js';
+import { createRevealHandler, revealRoots } from './reveal.js';
 import { scanGenerativeMcpappsStatus } from './skill-roots.js';
 import { skillsFromListResult, toPublicSkillStatus } from './skill-status.js';
-import { createRevealHandler, revealRoots } from './reveal.js';
 
 declare module '@deepseek-ai/cordis' {
   interface Context {
@@ -19,6 +22,8 @@ declare module '@deepseek-ai/cordis' {
 export const name = 'dsh-better-display';
 export const inject = ['webServer'];
 
+const log = createLogger({ base: { plugin: name } });
+
 function writeJson(res: ServerResponse, status: number, body: unknown): void {
   res.setHeader('Content-Type', 'application/json');
   res.statusCode = status;
@@ -31,20 +36,48 @@ function skillLister(ctx: Context): (() => Promise<readonly { readonly name?: st
   return async () => skillsFromListResult(await skills.list!({}));
 }
 
-export function apply(ctx: Context): void {
-  console.log('[my-plugins/dsh-better-display] loaded');
+function beginRequest(req: IncomingMessage, res: ServerResponse, route: string): string {
+  const requestId = requestIdOf(req);
+  res.setHeader('X-Request-ID', requestId);
+  recordRouteHit(route);
+  const started = performance.now();
+  res.on('finish', () => {
+    recordRouteDuration(route, performance.now() - started);
+  });
+  log.info('http request', {
+    requestId,
+    route,
+    method: req.method ?? '',
+    url: req.url ?? '',
+    headers: req.headers,
+  });
+  return requestId;
+}
+
+export function apply(ctx: Context, options?: { readonly flags?: Flags }): void {
+  const flags = options?.flags ?? loadFlags();
+  log.info('[my-plugins/dsh-better-display] loaded', { readerEnabled: flags.readerEnabled });
+  if (!flags.readerEnabled) {
+    log.info('route registration skipped', { readerEnabled: false });
+    return;
+  }
 
   if (ctx.webServer) {
     ctx.effect(() => {
+      const reveal = createRevealHandler({ roots: sessionId => revealRoots(ctx, sessionId) });
       const disposeReveal = ctx.webServer!.register({
         kind: 'exact',
-        path: '/better-display/reveal',
-        handler: createRevealHandler({ roots: sessionId => revealRoots(ctx, sessionId) }),
+        path: ROUTE_REVEAL,
+        handler: (req, res) => {
+          beginRequest(req, res, ROUTE_REVEAL);
+          reveal(req, res);
+        },
       });
       const disposeSkill = ctx.webServer!.register({
         kind: 'exact',
-        path: '/better-display/skill-status',
+        path: ROUTE_SKILL_STATUS,
         handler: async (req, res) => {
+          const requestId = beginRequest(req, res, ROUTE_SKILL_STATUS);
           if (req.method !== 'GET') {
             res.statusCode = 405;
             res.end();
@@ -59,14 +92,32 @@ export function apply(ctx: Context): void {
             });
             writeJson(res, 200, toPublicSkillStatus(status));
           } catch (err) {
+            log.error('skill-status failed', {
+              requestId,
+              error: err instanceof Error ? err.message : String(err),
+            });
             writeJson(res, 500, { ok: false, error: String(err) });
           }
         },
       });
+      const disposeMetrics = ctx.webServer!.register({
+        kind: 'exact',
+        path: ROUTE_METRICS,
+        handler: (req, res) => {
+          beginRequest(req, res, ROUTE_METRICS);
+          if (req.method !== 'GET') {
+            res.statusCode = 405;
+            res.end();
+            return;
+          }
+          writeJson(res, 200, metricsPayload());
+        },
+      });
       return () => {
         disposeReveal();
         disposeSkill();
+        disposeMetrics();
       };
-    }, 'dsh-better-display: reveal and skill-status routes');
+    }, 'dsh-better-display: reveal, skill-status, and metrics routes');
   }
 }

package/src/flags.ts

@@ -0,0 +1,40 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+/** Startup kill switch loaded from flags.json. This is not the reader glass setting. */
+export interface Flags {
+  readonly readerEnabled: boolean;
+}
+
+export const defaultFlags: Flags = { readerEnabled: true };
+
+function locateFlags(start = dirname(fileURLToPath(import.meta.url))): string | undefined {
+  let dir = start;
+  for (let depth = 0; depth < 6; depth += 1) {
+    const candidate = resolve(dir, 'flags.json');
+    if (existsSync(candidate)) return candidate;
+    const parent = dirname(dir);
+    if (parent === dir) return undefined;
+    dir = parent;
+  }
+  return undefined;
+}
+
+function normalize(value: unknown): Flags {
+  const record = value !== null && typeof value === 'object' ? value as { readerEnabled?: unknown } : {};
+  return {
+    readerEnabled: typeof record.readerEnabled === 'boolean' ? record.readerEnabled : defaultFlags.readerEnabled,
+  };
+}
+
+export function loadFlags(source?: string | Flags): Flags {
+  if (source !== undefined && typeof source !== 'string') return normalize(source);
+  try {
+    const path = typeof source === 'string' ? source : locateFlags();
+    if (path === undefined || !existsSync(path)) return { ...defaultFlags };
+    return normalize(JSON.parse(readFileSync(path, 'utf8')) as unknown);
+  } catch {
+    return { ...defaultFlags };
+  }
+}