@cam5/baby-bird 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,648 @@
+import { z } from 'zod';
+
+/**
+ * Core data model for baby-bird. Everything here is plain, serializable data so
+ * that any renderer (CLI today, curses/web later) can consume a Tour without
+ * touching git or an LLM.
+ */
+type LineType = 'add' | 'del' | 'ctx';
+interface HunkLine {
+    type: LineType;
+    /** Line number in the old file (absent for added lines). */
+    oldNo?: number;
+    /** Line number in the new file (absent for deleted lines). */
+    newNo?: number;
+    /** Line content without the leading +/-/space. */
+    text: string;
+}
+interface Hunk {
+    /** Stable id used in prompts, e.g. "F3.H2". */
+    id: string;
+    oldStart: number;
+    oldLines: number;
+    newStart: number;
+    newLines: number;
+    /** Text after the second @@ (function context), may be empty. */
+    header: string;
+    lines: HunkLine[];
+}
+type FileStatus = 'added' | 'deleted' | 'modified' | 'renamed';
+interface DiffFile {
+    /** Stable id used in prompts, e.g. "F3". */
+    id: string;
+    /** New path (or old path for deletions). */
+    path: string;
+    /** Old path when renamed. */
+    oldPath?: string;
+    status: FileStatus;
+    binary: boolean;
+    additions: number;
+    deletions: number;
+    hunks: Hunk[];
+}
+interface ParsedDiff {
+    files: DiffFile[];
+}
+interface CommitInfo {
+    sha: string;
+    subject: string;
+}
+interface PullRequestInfo {
+    number: number;
+    title: string;
+    body: string;
+    url: string;
+    baseRefName: string;
+    headRefName: string;
+}
+type RangeResolvedBy = 'explicit' | 'pull-request' | 'ancestor-branch' | 'default-branch';
+type WorkingResolvedBy = 'explicit' | 'dirty-tree';
+type TourSource = {
+    kind: 'range';
+    /** Human label for the base, e.g. "main" or "origin/main". */
+    base: string;
+    /** Human label for the head, e.g. "feat/x" or "HEAD". */
+    head: string;
+    baseSha: string;
+    headSha: string;
+    /** Set when the base was taken at the merge-base (three-dot semantics). */
+    mergeBase?: string;
+    resolvedBy: RangeResolvedBy;
+} | {
+    kind: 'working';
+    headSha: string;
+    staged: boolean;
+    resolvedBy: WorkingResolvedBy;
+};
+interface TourStats {
+    files: number;
+    additions: number;
+    deletions: number;
+}
+interface Excerpt {
+    file: string;
+    /** The hunk this excerpt was sliced from. */
+    hunkId: string;
+    /** One-line caption from the model. */
+    note?: string;
+    oldStart: number;
+    newStart: number;
+    lines: HunkLine[];
+}
+interface Section {
+    id: string;
+    title: string;
+    description: string;
+    /** Paths this section is about. Sections may share files. */
+    files: string[];
+    stats: TourStats;
+    excerpts: Excerpt[];
+}
+interface TourGenerator {
+    preset: string | null;
+    command: string[];
+}
+interface Tour {
+    version: 1;
+    generatedAt: string;
+    source: TourSource;
+    generator: TourGenerator;
+    pullRequest?: {
+        number: number;
+        title: string;
+        url: string;
+    };
+    title: string;
+    summary: string;
+    stats: TourStats;
+    sections: Section[];
+}
+/** Everything gathered from git/code host before we talk to the model. */
+interface TourContext {
+    source: TourSource;
+    branch: string | null;
+    diff: ParsedDiff;
+    commits: CommitInfo[];
+    pullRequest?: PullRequestInfo;
+}
+
+declare const LlmTourOutputSchema: z.ZodObject<{
+    title: z.ZodString;
+    summary: z.ZodString;
+    sections: z.ZodArray<z.ZodObject<{
+        title: z.ZodString;
+        description: z.ZodString;
+        files: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        excerpts: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            hunk: z.ZodString;
+            lines: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
+            note: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+type LlmTourOutput = z.infer<typeof LlmTourOutputSchema>;
+declare const TourSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    generatedAt: z.ZodString;
+    source: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"range">;
+        base: z.ZodString;
+        head: z.ZodString;
+        baseSha: z.ZodString;
+        headSha: z.ZodString;
+        mergeBase: z.ZodOptional<z.ZodString>;
+        resolvedBy: z.ZodEnum<{
+            explicit: "explicit";
+            "pull-request": "pull-request";
+            "ancestor-branch": "ancestor-branch";
+            "default-branch": "default-branch";
+        }>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"working">;
+        headSha: z.ZodString;
+        staged: z.ZodBoolean;
+        resolvedBy: z.ZodEnum<{
+            explicit: "explicit";
+            "dirty-tree": "dirty-tree";
+        }>;
+    }, z.core.$strip>], "kind">;
+    generator: z.ZodObject<{
+        preset: z.ZodNullable<z.ZodString>;
+        command: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>;
+    pullRequest: z.ZodOptional<z.ZodObject<{
+        number: z.ZodNumber;
+        title: z.ZodString;
+        url: z.ZodString;
+    }, z.core.$strip>>;
+    title: z.ZodString;
+    summary: z.ZodString;
+    stats: z.ZodObject<{
+        files: z.ZodNumber;
+        additions: z.ZodNumber;
+        deletions: z.ZodNumber;
+    }, z.core.$strip>;
+    sections: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        title: z.ZodString;
+        description: z.ZodString;
+        files: z.ZodArray<z.ZodString>;
+        stats: z.ZodObject<{
+            files: z.ZodNumber;
+            additions: z.ZodNumber;
+            deletions: z.ZodNumber;
+        }, z.core.$strip>;
+        excerpts: z.ZodArray<z.ZodObject<{
+            file: z.ZodString;
+            hunkId: z.ZodString;
+            note: z.ZodOptional<z.ZodString>;
+            oldStart: z.ZodNumber;
+            newStart: z.ZodNumber;
+            lines: z.ZodArray<z.ZodObject<{
+                type: z.ZodEnum<{
+                    add: "add";
+                    del: "del";
+                    ctx: "ctx";
+                }>;
+                oldNo: z.ZodOptional<z.ZodNumber>;
+                newNo: z.ZodOptional<z.ZodNumber>;
+                text: z.ZodString;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+declare function formatIssues(error: z.ZodError): string;
+
+type PromptVia = 'stdin' | 'arg';
+interface LlmPreset {
+    /** argv; when promptVia is "arg", any "{prompt}" token is replaced with the prompt. */
+    command: string[];
+    promptVia?: PromptVia;
+    description?: string;
+}
+declare const BUILTIN_PRESETS: Readonly<Record<string, LlmPreset>>;
+declare const ConfigSchema: z.ZodObject<{
+    llm: z.ZodObject<{
+        preset: z.ZodString;
+        presets: z.ZodRecord<z.ZodString, z.ZodObject<{
+            command: z.ZodArray<z.ZodString>;
+            promptVia: z.ZodOptional<z.ZodEnum<{
+                stdin: "stdin";
+                arg: "arg";
+            }>>;
+            description: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        args: z.ZodArray<z.ZodString>;
+        command: z.ZodNullable<z.ZodArray<z.ZodString>>;
+        promptVia: z.ZodNullable<z.ZodEnum<{
+            stdin: "stdin";
+            arg: "arg";
+        }>>;
+        timeoutMs: z.ZodNumber;
+        maxPromptBytes: z.ZodNumber;
+        env: z.ZodRecord<z.ZodString, z.ZodString>;
+    }, z.core.$strip>;
+    codehost: z.ZodObject<{
+        provider: z.ZodEnum<{
+            gh: "gh";
+            none: "none";
+        }>;
+    }, z.core.$strip>;
+    git: z.ZodObject<{
+        defaultBranch: z.ZodNullable<z.ZodString>;
+        exclude: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>;
+    render: z.ZodObject<{
+        color: z.ZodEnum<{
+            never: "never";
+            auto: "auto";
+            always: "always";
+        }>;
+        pager: z.ZodEnum<{
+            never: "never";
+            auto: "auto";
+            always: "always";
+        }>;
+        maxExcerptLines: z.ZodNumber;
+        width: z.ZodNullable<z.ZodNumber>;
+    }, z.core.$strip>;
+    cache: z.ZodObject<{
+        enabled: z.ZodBoolean;
+        dir: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+type Config = z.infer<typeof ConfigSchema>;
+declare const PartialConfigSchema: z.ZodObject<{
+    llm: z.ZodOptional<z.ZodObject<{
+        preset: z.ZodOptional<z.ZodString>;
+        presets: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+            command: z.ZodArray<z.ZodString>;
+            promptVia: z.ZodOptional<z.ZodEnum<{
+                stdin: "stdin";
+                arg: "arg";
+            }>>;
+            description: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>>;
+        args: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        command: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString>>>;
+        promptVia: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+            stdin: "stdin";
+            arg: "arg";
+        }>>>;
+        timeoutMs: z.ZodOptional<z.ZodNumber>;
+        maxPromptBytes: z.ZodOptional<z.ZodNumber>;
+        env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    }, z.core.$strip>>;
+    codehost: z.ZodOptional<z.ZodObject<{
+        provider: z.ZodOptional<z.ZodEnum<{
+            gh: "gh";
+            none: "none";
+        }>>;
+    }, z.core.$strip>>;
+    git: z.ZodOptional<z.ZodObject<{
+        defaultBranch: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        exclude: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+    render: z.ZodOptional<z.ZodObject<{
+        color: z.ZodOptional<z.ZodEnum<{
+            never: "never";
+            auto: "auto";
+            always: "always";
+        }>>;
+        pager: z.ZodOptional<z.ZodEnum<{
+            never: "never";
+            auto: "auto";
+            always: "always";
+        }>>;
+        maxExcerptLines: z.ZodOptional<z.ZodNumber>;
+        width: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    }, z.core.$strip>>;
+    cache: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodOptional<z.ZodBoolean>;
+        dir: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+type PartialConfig = z.infer<typeof PartialConfigSchema>;
+declare const DEFAULT_CONFIG: Config;
+declare function userConfigPath(env?: NodeJS.ProcessEnv): string;
+declare function defaultCacheDir(env?: NodeJS.ProcessEnv): string;
+declare function projectConfigPath(gitRoot: string): string;
+type LayerName = 'defaults' | 'user' | 'project' | 'env' | 'flags';
+interface ConfigLayer {
+    name: LayerName;
+    /** File path for file-backed layers. */
+    path?: string;
+    /** Whether the layer contributed anything (file existed, env vars set, flags passed). */
+    found: boolean;
+    /** Short human description of what was applied (e.g. env var names). */
+    detail?: string;
+    data: PartialConfig;
+}
+interface LoadConfigOptions {
+    /** Git root for project-level config; null/undefined skips the project layer. */
+    gitRoot?: string | null;
+    env?: NodeJS.ProcessEnv;
+    /** CLI flag overrides, applied last. */
+    overrides?: PartialConfig;
+}
+interface LoadedConfig {
+    config: Config;
+    layers: ConfigLayer[];
+    cacheDir: string;
+}
+/** Objects merge recursively; arrays and scalars replace. `undefined` never overrides. */
+declare function deepMerge<T>(base: T, patch: unknown): T;
+declare function loadConfig(opts?: LoadConfigOptions): Promise<LoadedConfig>;
+interface ResolvedLlm {
+    command: string[];
+    promptVia: PromptVia;
+    /** Preset name, or null when a custom command is in use. */
+    preset: string | null;
+    timeoutMs: number;
+    maxPromptBytes: number;
+    env: Record<string, string>;
+}
+declare function allPresets(config: Config): Record<string, LlmPreset>;
+declare function resolveLlm(config: Config): ResolvedLlm;
+/** Minimal POSIX-ish shell splitting: whitespace separated, single/double quotes, backslash escapes. */
+declare function shellSplit(input: string): string[];
+
+declare class BbError extends Error {
+    readonly exitCode: number;
+    readonly hint: string | undefined;
+    constructor(message: string, opts?: {
+        exitCode?: number;
+        hint?: string;
+        cause?: unknown;
+    });
+}
+declare class UsageError extends BbError {
+    constructor(message: string, hint?: string);
+}
+declare class ConfigError extends BbError {
+    constructor(message: string, hint?: string);
+}
+declare class NotARepoError extends BbError {
+    constructor(cwd: string);
+}
+declare class GitError extends BbError {
+    constructor(message: string, opts?: {
+        hint?: string;
+        cause?: unknown;
+    });
+}
+declare class NoChangesError extends BbError {
+    constructor(message: string, hint?: string);
+}
+declare class LlmFailedError extends BbError {
+    constructor(message: string, opts?: {
+        hint?: string;
+        cause?: unknown;
+    });
+}
+declare class BadLlmOutputError extends BbError {
+    readonly raw: string;
+    constructor(message: string, raw: string, hint?: string);
+}
+
+interface CacheEntry {
+    key: string;
+    path: string;
+    tour: Tour;
+}
+/** Content-addressed store of generated tours: <dir>/tours/<sha256>.json */
+declare class TourCache {
+    readonly dir: string;
+    readonly toursDir: string;
+    constructor(dir: string);
+    static keyFor(prompt: string, command: string[]): string;
+    pathFor(key: string): string;
+    get(key: string): Promise<Tour | null>;
+    put(key: string, tour: Tour): Promise<string>;
+    list(): Promise<CacheEntry[]>;
+    clear(): Promise<number>;
+}
+
+/**
+ * Pull a JSON object out of model output that may be wrapped in prose, code
+ * fences, or a CLI's own JSON envelope (e.g. `claude --output-format json`).
+ */
+declare function extractJson(text: string): unknown;
+
+interface MaterializeInput {
+    output: LlmTourOutput;
+    diff: ParsedDiff;
+    source: TourSource;
+    generator: TourGenerator;
+    pullRequest?: PullRequestInfo;
+    maxExcerptLines: number;
+    warn?: (msg: string) => void;
+    now?: () => Date;
+}
+declare const OTHER_CHANGES_TITLE = "Other changes";
+/**
+ * Turn the model's section/reference output into a self-contained Tour by
+ * slicing excerpts out of the real diff and computing all counts locally.
+ */
+declare function materializeTour(input: MaterializeInput): Tour;
+/**
+ * Narrow a hunk to a [start, end] range of new-file line numbers. Deleted lines
+ * are attributed to the new-file position where they would have been, so a
+ * range keeps the removals that sit inside it.
+ */
+declare function sliceHunk(hunk: Hunk, range: [number, number] | undefined, maxLines: number): HunkLine[];
+
+interface PromptInput {
+    source: TourSource;
+    branch: string | null;
+    diff: ParsedDiff;
+    commits: CommitInfo[];
+    pullRequest?: PullRequestInfo;
+    /** Soft budget for the whole prompt, in bytes. */
+    maxBytes: number;
+}
+interface TruncationReport {
+    /** Files whose diff was cut down to the start of their first hunk. */
+    truncated: string[];
+    /** Files whose diff was left out entirely (names and stats only). */
+    omitted: string[];
+}
+interface BuiltPrompt {
+    prompt: string;
+    truncation: TruncationReport;
+}
+declare function buildPrompt(input: PromptInput): BuiltPrompt;
+declare function describeSource(source: TourSource, branch: string | null): string;
+
+/** Bump whenever the prompt text or its assembly changes materially; it is part of the cache key. */
+declare const PROMPT_VERSION = 2;
+
+interface CodeHost {
+    readonly name: string;
+    /** The pull request for the current branch, or null when there is none (or the host is unavailable). */
+    currentPullRequest(cwd: string): Promise<PullRequestInfo | null>;
+}
+
+interface GhOptions {
+    timeoutMs?: number;
+    debug?: (msg: string) => void;
+}
+/** Reads the current branch's PR through the `gh` CLI. Never throws: any failure means "no PR". */
+declare class GhCodeHost implements CodeHost {
+    readonly name = "gh";
+    private readonly timeoutMs;
+    private readonly debug;
+    constructor(opts?: GhOptions);
+    currentPullRequest(cwd: string): Promise<PullRequestInfo | null>;
+}
+
+declare class NoCodeHost implements CodeHost {
+    readonly name = "none";
+    currentPullRequest(): Promise<null>;
+}
+
+declare function createCodeHost(config: Config, opts?: {
+    debug?: (msg: string) => void;
+}): CodeHost;
+
+interface RangeRequest {
+    /** Explicit range argument: "A..B", "A...B" or a single ref. */
+    arg?: string;
+    working?: boolean;
+    staged?: boolean;
+}
+interface ResolveOptions {
+    cwd: string;
+    exclude: string[];
+    /** Configured default branch; null means auto-detect. */
+    defaultBranch: string | null;
+    codehost: CodeHost;
+    debug?: (msg: string) => void;
+}
+interface ResolvedRange {
+    source: TourSource;
+    branch: string | null;
+    pullRequest?: PullRequestInfo;
+}
+declare function resolveRange(req: RangeRequest, opts: ResolveOptions): Promise<ResolvedRange>;
+declare function detectDefaultBranch(configured: string | null, cwd: string): Promise<string | null>;
+
+interface LlmProvider {
+    /** Human-readable description of how the model is invoked, for headers and debug output. */
+    describe(): string;
+    /** Send a prompt and return the raw text the model produced. */
+    complete(prompt: string): Promise<string>;
+}
+
+interface CommandProviderOptions {
+    command: string[];
+    promptVia: 'stdin' | 'arg';
+    timeoutMs: number;
+    env?: Record<string, string>;
+    cwd?: string;
+    debug?: (msg: string) => void;
+}
+/** Runs any CLI as the model: prompt in via stdin (or a {prompt} argv token), completion out via stdout. */
+declare class CommandProvider implements LlmProvider {
+    private readonly opts;
+    constructor(opts: CommandProviderOptions);
+    describe(): string;
+    complete(prompt: string): Promise<string>;
+}
+
+declare function createProvider(llm: ResolvedLlm, opts?: {
+    cwd?: string;
+    debug?: (msg: string) => void;
+}): LlmProvider;
+
+interface TourOptions {
+    /** Git root (or any directory inside the repository). */
+    cwd: string;
+    config: Config;
+    cacheDir: string;
+    range?: RangeRequest;
+    /** Ignore a cached tour but still store the new one. */
+    refresh?: boolean;
+    /** Neither read nor write the cache. */
+    noCache?: boolean;
+    debug?: (msg: string) => void;
+    warn?: (msg: string) => void;
+    /** Injectable for tests. */
+    provider?: LlmProvider;
+    codehost?: CodeHost;
+}
+interface PreparedTour {
+    context: TourContext;
+    built: BuiltPrompt;
+    command: string[];
+    preset: string | null;
+    cacheKey: string;
+}
+interface TourResult {
+    tour: Tour;
+    fromCache: boolean;
+    cacheKey: string | null;
+    cachePath: string | null;
+    prompt: string;
+}
+/** Everything up to (but not including) the model call: git, code host, prompt, cache key. */
+declare function prepareTour(opts: TourOptions): Promise<PreparedTour>;
+declare function generateTour(opts: TourOptions, prepared?: PreparedTour): Promise<TourResult>;
+
+interface CollectOptions {
+    cwd: string;
+    exclude: string[];
+    warn?: (msg: string) => void;
+}
+/** Collect and parse the diff for a resolved source. */
+declare function collectDiff(source: TourSource, opts: CollectOptions): Promise<ParsedDiff>;
+declare function collectCommits(source: TourSource, cwd: string, limit?: number): Promise<CommitInfo[]>;
+
+declare function gitRoot(cwd: string): Promise<string>;
+/** Resolve a ref to a full commit sha; null when it doesn't resolve. */
+declare function revParse(ref: string, cwd: string): Promise<string | null>;
+/** Current branch name, or null when HEAD is detached. */
+declare function currentBranch(cwd: string): Promise<string | null>;
+
+/**
+ * Parse `git diff` output (with a/ b/ prefixes) into files, hunks and numbered lines.
+ * Tolerant of mode-only changes, pure renames, binary files and "\ No newline" markers.
+ */
+declare function parseDiff(raw: string): ParsedDiff;
+declare function diffStats(diff: ParsedDiff): {
+    files: number;
+    additions: number;
+    deletions: number;
+};
+
+interface RenderOptions {
+    /** Emit ANSI colors. */
+    color: boolean;
+    /** Target width in columns. */
+    width: number;
+    /** Render only this 1-based section (header still included). */
+    section?: number;
+    /** Whether the tour came from the cache, for the header note. */
+    fromCache?: boolean;
+}
+interface Renderer {
+    render(tour: Tour, opts: RenderOptions): string;
+}
+
+/** Static, pager-friendly rendering of a Tour for a terminal. */
+declare class CliRenderer implements Renderer {
+    render(tour: Tour, opts: RenderOptions): string;
+}
+declare function wrap(text: string, width: number): string[];
+declare function relativeTime(iso: string, now?: Date): string;
+
+interface PagerOptions {
+    mode: 'auto' | 'always' | 'never';
+    isTTY: boolean;
+    rows: number;
+    env?: NodeJS.ProcessEnv;
+}
+/** Write output to stdout, through $PAGER (default `less -RFX`) when it would not fit the screen. */
+declare function writeMaybePaged(output: string, opts: PagerOptions): Promise<void>;
+
+export { BUILTIN_PRESETS, BadLlmOutputError, BbError, type BuiltPrompt, type CacheEntry, CliRenderer, type CodeHost, CommandProvider, type CommitInfo, type Config, ConfigError, type ConfigLayer, ConfigSchema, DEFAULT_CONFIG, type DiffFile, type Excerpt, type FileStatus, GhCodeHost, GitError, type Hunk, type HunkLine, type LineType, LlmFailedError, type LlmPreset, type LlmProvider, type LlmTourOutput, LlmTourOutputSchema, type LoadedConfig, NoChangesError, NoCodeHost, NotARepoError, OTHER_CHANGES_TITLE, PROMPT_VERSION, type ParsedDiff, type PartialConfig, PartialConfigSchema, type PreparedTour, type PromptInput, type PullRequestInfo, type RangeRequest, type RangeResolvedBy, type RenderOptions, type Renderer, type ResolveOptions, type ResolvedLlm, type ResolvedRange, type Section, type Tour, TourCache, type TourContext, type TourGenerator, type TourOptions, type TourResult, TourSchema, type TourSource, type TourStats, type TruncationReport, UsageError, type WorkingResolvedBy, allPresets, buildPrompt, collectCommits, collectDiff, createCodeHost, createProvider, currentBranch, deepMerge, defaultCacheDir, describeSource, detectDefaultBranch, diffStats, extractJson, formatIssues, generateTour, gitRoot, loadConfig, materializeTour, parseDiff, prepareTour, projectConfigPath, relativeTime, resolveLlm, resolveRange, revParse, shellSplit, sliceHunk, userConfigPath, wrap, writeMaybePaged };