things-api 0.9.0 → 0.11.0

package/dist/cli/width.js

@@ -0,0 +1,313 @@
+/**
+ * Width-aware TTY row fitting (docs/design/width-aware-tty.md). Terminal list
+ * rows never wrap: like the Things GUI, an over-long row truncates its title
+ * with a trailing `…` and folds its tags, keeping the always-present metadata
+ * (uuid, box, chips, tail markers, the full deadline token) intact. Everything
+ * here is pure and takes the target width explicitly, so it is unit-testable
+ * without a TTY and byte-stable off one: fitting engages ONLY when the driver
+ * resolves a positive width (setFitWidth) — the default is null (no fitting),
+ * so pipes, grep, and `--json` are untouched by construction.
+ *
+ * No runtime dependency (guest e2e bundles ship node + dist + commander only),
+ * so the display-width math is a small vendored wcwidth: SGR escapes strip to
+ * zero, East-Asian-Wide + emoji-presentation codepoints count two cells, the
+ * rest count one. ZWJ-sequence emoji can be off by a cell (accepted — worst
+ * case a row runs a hair short); the glyph vocabulary (★ ⏾ ⚑ ↻ ⍾ ≡ ◷) is all
+ * ambiguous/narrow class and counts one, so the layout math matches the render.
+ */
+const SGR = new RegExp(`${String.fromCharCode(27)}\\[[0-9;]*m`, "g");
+/** Drop every SGR (color/dim/bold/…) escape, leaving the visible characters. */
+export function stripSgr(s) {
+    return s.replace(SGR, "");
+}
+// Codepoint ranges that occupy TWO terminal cells: the East-Asian Wide/Fullwidth
+// core plus the default-emoji-presentation set (so "⭐️" counts 2 while the
+// ambiguous-class "★" counts 1 — the property that keeps our glyph set narrow).
+const WIDE_RANGES = [
+    [0x1100, 0x115f], // Hangul Jamo
+    [0x2e80, 0x303e], // CJK radicals … Kangxi
+    [0x3041, 0x33ff], // Hiragana … CJK compat
+    [0x3400, 0x4dbf], // CJK Ext A
+    [0x4e00, 0x9fff], // CJK Unified
+    [0xa000, 0xa4cf], // Yi
+    [0xac00, 0xd7a3], // Hangul Syllables
+    [0xf900, 0xfaff], // CJK Compat Ideographs
+    [0xfe30, 0xfe4f], // CJK Compat Forms
+    [0xff00, 0xff60], // Fullwidth Forms
+    [0xffe0, 0xffe6], // Fullwidth signs
+    // Emoji-presentation (default-wide) — the codepoints Unicode marks
+    // Emoji_Presentation=Yes outside the SMP blocks below.
+    [0x231a, 0x231b],
+    [0x23e9, 0x23ec],
+    [0x23f0, 0x23f0],
+    [0x23f3, 0x23f3],
+    [0x25fd, 0x25fe],
+    [0x2614, 0x2615],
+    [0x2648, 0x2653],
+    [0x267f, 0x267f],
+    [0x2693, 0x2693],
+    [0x26a1, 0x26a1],
+    [0x26aa, 0x26ab],
+    [0x26bd, 0x26be],
+    [0x26c4, 0x26c5],
+    [0x26ce, 0x26ce],
+    [0x26d4, 0x26d4],
+    [0x26ea, 0x26ea],
+    [0x26f2, 0x26f3],
+    [0x26f5, 0x26f5],
+    [0x26fa, 0x26fa],
+    [0x26fd, 0x26fd],
+    [0x2705, 0x2705],
+    [0x270a, 0x270b],
+    [0x2728, 0x2728],
+    [0x274c, 0x274c],
+    [0x274e, 0x274e],
+    [0x2753, 0x2755],
+    [0x2757, 0x2757],
+    [0x2795, 0x2797],
+    [0x27b0, 0x27b0],
+    [0x27bf, 0x27bf],
+    [0x2b1b, 0x2b1c],
+    [0x2b50, 0x2b50], // ⭐ WHITE MEDIUM STAR (Emoji_Presentation — 2 cells)
+    [0x2b55, 0x2b55],
+    [0x1f000, 0x1faff], // SMP emoji blocks (mahjong … symbols & pictographs ext)
+    [0x20000, 0x3fffd], // CJK Ext B+ (SIP/TIP)
+];
+// Zero-width: combining marks, ZW(SP/NJ/J), and variation selectors. Treating
+// VS16 (FE0F) as zero-width means an emoji-presentation base already counted 2
+// stays 2 (rather than 3) — the "⭐️" case.
+const ZERO_RANGES = [
+    [0x0300, 0x036f], // combining diacritics
+    [0x200b, 0x200f], // ZWSP … RLM (incl. ZWJ 200d)
+    [0xfe00, 0xfe0f], // variation selectors
+];
+function inRanges(cp, ranges) {
+    for (const [lo, hi] of ranges)
+        if (cp >= lo && cp <= hi)
+            return true;
+    return false;
+}
+/** Terminal cells a single codepoint occupies: 0 (combining/zero-width), 2 (wide), else 1. */
+export function charWidth(cp) {
+    if (cp === 0)
+        return 0;
+    if (inRanges(cp, ZERO_RANGES))
+        return 0;
+    if (inRanges(cp, WIDE_RANGES))
+        return 2;
+    return 1;
+}
+/** Visible terminal width of a string: SGR-stripped, summed per codepoint. */
+export function visibleWidth(s) {
+    let w = 0;
+    for (const ch of stripSgr(s))
+        w += charWidth(ch.codePointAt(0) ?? 0);
+    return w;
+}
+/**
+ * Truncate PLAIN text (no SGR) to at most `cols` terminal cells, never splitting
+ * a wide codepoint across the boundary. Used to clip a raw title before its
+ * styling wrappers are re-applied, so the ellipsis/clip boundary lands OUTSIDE
+ * the SGR runs (the fitter never cuts an escape sequence).
+ */
+export function clipPlain(s, cols) {
+    if (cols <= 0)
+        return "";
+    let w = 0;
+    let out = "";
+    for (const ch of s) {
+        const cw = charWidth(ch.codePointAt(0) ?? 0);
+        if (w + cw > cols)
+            break;
+        out += ch;
+        w += cw;
+    }
+    return out;
+}
+// ── Row fitting ─────────────────────────────────────────────────────────────
+/**
+ * TITLE : TAGS relative max-width ratio (tunable — ONE place). It arbitrates the
+ * collapsible budget ONLY under contention — when BOTH segments' natural widths
+ * exceed their shares. Otherwise the fit is lazy: the side within its share keeps
+ * its natural width and the other takes everything left (see {@link fitRow}). 4:1
+ * keeps the title dominant when they do genuinely contend.
+ */
+const TITLE_RATIO = 4;
+const TAGS_RATIO = 1;
+/**
+ * The title's protected minimum, in columns. NOT a per-row clamp: it is the
+ * input to the derived floors (render.ts FULL_FIT_FLOOR / COMPACT_FIT_FLOOR =
+ * worst-case furniture + TITLE_MIN) and the threshold the sacrifice order
+ * protects the title down to. Because the driver fits every row to at least the
+ * compact floor (max(width, COMPACT_FIT_FLOOR)),
+ * the worst-furniture row's title lands at exactly TITLE_MIN and every lighter
+ * row's title is automatically wider — so this floor is always satisfiable and
+ * there is no sub-floor clip (below the floor the terminal wraps, losing nothing).
+ */
+export const TITLE_MIN = 16;
+/** Overflow marker for folded tags (dim styling applied by the row's styleTags). */
+const TAG_OVERFLOW = "#…";
+/**
+ * Plain form (no styling, no leading space) of the tag run showing the first `k`
+ * real tags; when `k` is below the total, the dropped tags fold into the dim
+ * `#…` marker. `k === 0` is the bare marker.
+ */
+function tagForm(names, k) {
+    const shown = names.slice(0, k).map((n) => `#${n}`);
+    if (k < names.length)
+        shown.push(TAG_OVERFLOW);
+    return shown.join(" ");
+}
+/** Visible width of the rendered tag run at level `k` (its leading space + form). */
+function tagWidth(names, k) {
+    if (names.length === 0)
+        return 0;
+    return 1 + visibleWidth(tagForm(names, k));
+}
+/** Widest tag level (most real tags) whose render fits `cap`, floored at `floorK`. */
+function pickTagLevel(names, cap, floorK) {
+    for (let k = names.length; k >= floorK; k--) {
+        if (tagWidth(names, k) <= cap)
+            return k;
+    }
+    return floorK;
+}
+/**
+ * EXPERIMENTAL — the right-aligned deadline gutter (GUI flag-column parity). When
+ * fitting is active, every fitted row's `⚑` token is pushed flush to the effective
+ * width so all deadlines in a view line up in one gutter, exactly like the app's
+ * right-pinned flag column. `body` is the composed row WITHOUT its deadline and
+ * `deadline` the pre-styled ` ⚑ …` segment (its leading space + token) or "".
+ * The padding is plain spaces OUTSIDE the styled token, and there is always ≥ 1
+ * space — so a row that already fills the width is byte-identical to the inline
+ * (unguttered) form, and a row with no deadline is returned untouched (ragged
+ * right, as the GUI leaves flag-less rows). This is only ever reached from
+ * {@link fitRow} (fitting active), so the byte-stable null path never sees it.
+ * Reverting the experiment is deleting this function and its two `fitRow` calls.
+ */
+function alignDeadline(body, deadline, width) {
+    if (deadline === "")
+        return body;
+    // deadline = " " + token; swap that single inline space for the gutter run.
+    const pad = width - visibleWidth(body) - visibleWidth(deadline) + 1;
+    return `${body}${" ".repeat(Math.max(1, pad))}${deadline.slice(1)}`;
+}
+/**
+ * Fit one row into `width` terminal cells per the ratified collapse order. The
+ * always-present parts (uuid, box, meta chips, tail markers, full deadline)
+ * never shrink; title and tags divvy up what remains LAZILY — tags fold to the
+ * widest progressive level that fits and the 4:1 ratio arbitrates only when both
+ * genuinely contend (slack an under-share side leaves flows to the other). Then
+ * the CLI-only container is sacrificed WHOLE (before the last tag folds), then
+ * the last tag folds to bare `#…`, and the title bottoms at TITLE_MIN. `width` is
+ * the caller's effective width (already max'd with COMPACT_FIT_FLOOR), so the final
+ * stage always satisfies the floor; a sub-floor width would simply let the
+ * terminal wrap (the title is kept whole rather than clipped). A row that already
+ * fits keeps its full content; the only always-applied transform is the
+ * experimental deadline gutter ({@link alignDeadline}), which right-pins the `⚑`.
+ */
+export function fitRow(seg, width) {
+    const names = seg.tagNames;
+    const wLeft = visibleWidth(seg.left) + 1; // + the space before the title
+    const wTail = visibleWidth(seg.tail);
+    const wCtx = visibleWidth(seg.context);
+    const wDead = visibleWidth(seg.deadline);
+    const wTitle = visibleWidth(seg.rawTitle);
+    // A naturally short title never floors at TITLE_MIN — it simply fits whole.
+    const titleNeed = Math.min(TITLE_MIN, wTitle);
+    const fixed = (ctx) => wLeft + wTail + wDead + (ctx ? wCtx : 0);
+    const fitTitle = (budget) => wTitle <= budget
+        ? seg.styleTitle(seg.rawTitle)
+        : seg.styleTitle(`${clipPlain(seg.rawTitle, budget - 1)}…`);
+    const renderRow = (title, k, ctx) => {
+        const tags = names.length > 0 ? seg.styleTags(tagForm(names, k)) : "";
+        const body = `${seg.left} ${title}${seg.tail}${tags}${ctx ? seg.context : ""}`;
+        return alignDeadline(body, seg.deadline, width);
+    };
+    // Stage "full": everything fits with tags whole and the container present.
+    // (The deadline is still pushed to the gutter — GUI flags pin right even on a
+    // short row — but the null path returns seg.full before reaching the fitter.)
+    const budgetFull = width - fixed(true);
+    if (wTitle + tagWidth(names, names.length) <= budgetFull) {
+        const body = seg.full.slice(0, seg.full.length - seg.deadline.length);
+        return alignDeadline(body, seg.deadline, width);
+    }
+    // Stage "both-shrink": tags fold LAZILY — to the WIDEST progressive level that
+    // fits, not an eager 1/5 cap. The 4:1 ratio arbitrates ONLY under contention
+    // (both natural widths exceed their shares of the collapsible budget). When the
+    // title is within its 4/5 share it keeps its natural width and the tags get
+    // everything left (their widest fitting level); when instead the tags are
+    // within their 1/5 share they stay whole and the title gets the rest. Either
+    // way, slack a discrete tag level does not consume flows BACK to the title, and
+    // neither side is shrunk below what the budget actually forces. Container kept.
+    const tagShare = Math.floor((budgetFull * TAGS_RATIO) / (TITLE_RATIO + TAGS_RATIO));
+    const titleShare = budgetFull - tagShare;
+    const tagCap = wTitle <= titleShare ? budgetFull - wTitle : tagShare;
+    const k = pickTagLevel(names, tagCap, 1);
+    const titleBudgetB = budgetFull - tagWidth(names, k);
+    if (titleBudgetB >= titleNeed)
+        return renderRow(fitTitle(titleBudgetB), k, true);
+    // Stage "container-drop": the CLI-only container yields WHOLE (a truncated
+    // parenthetical is worse than none) BEFORE the last tag folds — tags hold at
+    // `#first #…`, the reclaimed width goes to the title.
+    const budgetNoCtx = width - fixed(false);
+    const titleBudgetC = budgetNoCtx - tagWidth(names, 1);
+    if (titleBudgetC >= titleNeed)
+        return renderRow(fitTitle(titleBudgetC), 1, false);
+    // Stage "tags-bare": the last tag folds to the bare `#…` marker (container
+    // already gone), the title floors at TITLE_MIN. No end-clip: at an effective
+    // width this budget clears the floor; a sub-floor width keeps the title whole
+    // and lets the terminal wrap (never dropping the deadline).
+    const titleBudgetD = budgetNoCtx - tagWidth(names, 0);
+    const dTitle = titleBudgetD >= 1 ? fitTitle(titleBudgetD) : seg.styleTitle(seg.rawTitle);
+    return renderRow(dTitle, 0, false);
+}
+/**
+ * Resolve the effective fit from the once-resolved fit width and the two
+ * glyph-derived floors (`render.ts`: FULL_FIT_FLOOR / COMPACT_FIT_FLOOR). This
+ * is the SINGLE decision point for the full-vs-compact deadline form:
+ *   - `width ≥ full`        → full forms, fit to width (today's behavior);
+ *   - `compact ≤ width < full` → all deadlines compact, fit to width;
+ *   - `width < compact`     → clamp to the compact floor and wrap (sub-floor
+ *                             rule at the lower floor), still compact.
+ * The floors live in render.ts because their derivation needs the glyph
+ * inventory; the branching lives here so it is pure and unit-testable.
+ */
+export function resolveFit(fitWidth, fullFloor, compactFloor) {
+    const width = Math.max(fitWidth, compactFloor);
+    return { width, compact: width < fullFloor };
+}
+// ── Width resolution + the module-level fit width ────────────────────────────
+let fitWidth = null;
+/**
+ * Set the process-wide fit width (columns), resolved ONCE by the CLI driver at
+ * startup. `null` disables fitting (the default — every non-TTY path stays
+ * byte-stable). Tests set this explicitly and reset it afterward.
+ */
+export function setFitWidth(width) {
+    fitWidth = width;
+}
+/** The current fit width, or null when fitting is disabled. */
+export function getFitWidth() {
+    return fitWidth;
+}
+/**
+ * Resolve the fit width from the environment and stdout: `THINGS_WIDTH` wins
+ * when set (a positive integer forces that width; `0` disables fitting), else
+ * the terminal's column count when stdout is a TTY, else null (pipes, grep,
+ * captured output — no fitting, byte-stable). A malformed `THINGS_WIDTH` is
+ * ignored (falls through to the TTY/null resolution).
+ */
+export function resolveWidth(opts) {
+    const raw = opts.env["THINGS_WIDTH"];
+    if (raw !== undefined) {
+        const n = Number(raw);
+        if (Number.isInteger(n) && n >= 0)
+            return n === 0 ? null : n;
+        // malformed — fall through to the TTY resolution
+    }
+    if (opts.isTTY && typeof opts.columns === "number" && opts.columns > 0)
+        return opts.columns;
+    return null;
+}
+//# sourceMappingURL=width.js.map

package/dist/cli/width.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"width.js","sourceRoot":"","sources":["../../src/cli/width.ts"],"names":[],"mappings":"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"}

package/dist/client.d.ts

@@ -4,14 +4,16 @@
  */
 import type { AuditWriter } from "./audit/log.ts";
 import { type ThingsApiConfig } from "./config.ts";
-import { type FingerprintStatus } from "./db/fingerprint.ts";
+import { type ClockMeta } from "./model/clock.ts";
+import { type GroupedTruncation, type Truncation } from "./contracts.ts";
+import { type FingerprintStatus, type SchemaStatus } from "./db/fingerprint.ts";
 import type { AnyTask, Area, Project, Tag } from "./model/entities.ts";
 import { type AreaView } from "./read/area-view.ts";
 import { type ProjectView } from "./read/project-view.ts";
 import { type Snapshot } from "./read/snapshot.ts";
 import { type ShowTarget } from "./read/show-target.ts";
-import { type ChangedItem, type LiteSearchResult, type ListItem, type LogbookFilter, type SearchOptions, type SearchResultItem, type SidebarSection, type SomedayFilter, type TodayView, type UpcomingFilter, type ViewFilter } from "./read/views.ts";
-import type { AreaAddParams, AreaUpdateParams, ContainerRef, ProjectCancelParams, OperationKind, OperationParamsMap, ProjectAddParams, ProjectCompleteParams, ProjectUpdateParams, ReorderParams, TagAddParams, TagUpdateParams, HeadingArchiveParams, HeadingUnarchiveParams, TodoAddLoggedParams, TodoAddParams, TodoBackdateParams, TodoMoveParams, TodoUpdateParams } from "./write/operations.ts";
+import { type ChangedItem, type InboxFilter, type LiteSearchResult, type ListItem, type LogbookFilter, type SearchOptions, type SearchResultItem, type SidebarSection, type SomedayFilter, type TodayFilter, type TodayView, type UpcomingFilter, type ViewFilter } from "./read/views.ts";
+import type { AreaAddParams, AreaUpdateParams, ContainerRef, ProjectCancelParams, OperationKind, OperationParamsMap, ProjectAddParams, ProjectCompleteParams, ProjectCreateRepeatingParams, ProjectUpdateParams, RepeatRuleParams, ReorderParams, TagAddParams, TagUpdateParams, HeadingArchiveParams, HeadingUnarchiveParams, TodoAddLoggedParams, TodoAddParams, TodoBackdateParams, TodoMoveParams, TodoUpdateParams } from "./write/operations.ts";
 import { type MutationResult, type WriteOptions } from "./write/pipeline.ts";
 import { type BatchItemResult, type BatchOp, type BatchOptions } from "./write/batch.ts";
 import { type EnvironmentTracker } from "./write/environment.ts";
@@ -26,6 +28,12 @@ export interface OpenOptions {
     dbPath?: string;
     /** Injectable clock (tests, pinned-clock lab runs). */
     now?: () => Date;
+    /**
+     * Default consumer IANA zone for every date boundary (tests / explicit
+     * embedding). Overrides `THINGS_TZ` from the environment; a per-read `zone`
+     * still overrides this. Absent uses `THINGS_TZ`, else the host zone.
+     */
+    zone?: string;
     /** Injectable write vectors (tests: FakeVector; lab: probe vectors). */
     vectors?: WriteVector[];
     /** Env for config/state-dir resolution (tests). */
@@ -40,20 +48,109 @@ export interface OpenOptions {
         environment?: EnvironmentTracker;
     };
 }
+/**
+ * Row cap for a bounded FLAT view (inbox/today/upcoming/logbook/trash/search/
+ * changes). Resolution follows resolveCap: omitted → the 50-row default,
+ * an explicit number caps at it, `null` or `all: true` returns every row.
+ */
+export interface ListBound {
+    limit?: number | null;
+    all?: boolean;
+}
+/**
+ * Per-read consumer-zone override (the MCP `tz` argument). Overrides the
+ * process default (`THINGS_TZ` / the `OpenOptions.zone` embedding / the host)
+ * for THIS read only. Absent uses that default; an invalid zone is rejected by
+ * the calling surface before it reaches here.
+ */
+export interface ClockScopedRead {
+    zone?: string;
+}
+/**
+ * Per-block caps for a bounded GROUPED view (anytime/someday) or the composite
+ * area card. Each omitted cap falls back to the view's own default (anytime:
+ * 30 per area, 3 per project; someday: 30 per area, every active-project item;
+ * area card: 30 per section); `null` on a cap, or `all: true`, lifts it.
+ */
+export interface GroupedBound {
+    areaLimit?: number | null;
+    projectLimit?: number | null;
+    all?: boolean;
+}
+/** A bounded flat view: the shown rows plus the exact truncation counts. */
+export interface BoundedList<T> {
+    items: T[];
+    truncation: Truncation;
+}
+/**
+ * A bounded Today view: `view` is the shown split (capped in render order —
+ * Today, then This Evening) and `truncation` the exact counts, including the
+ * per-section (`today`/`evening`) breakdown a renderer needs to stay honest.
+ */
+export interface BoundedTodayView {
+    view: TodayView;
+    truncation: Truncation;
+}
+/**
+ * A bounded sidebar catalogue (anytime/someday): `view` is the
+ * per-block-capped sections and `grouped` the per-block counts (identity-
+ * carrying, project blocks nested under their area/loose block).
+ */
+export interface BoundedSectionsView {
+    view: SidebarSection[];
+    grouped: GroupedTruncation;
+}
+/** A bounded composite area card: the per-section-capped view and the per-block counts. */
+export interface BoundedAreaView {
+    view: AreaView;
+    grouped: GroupedTruncation;
+}
 export interface ThingsClient {
     dbPath: string;
     config: ThingsApiConfig;
     fingerprint(): FingerprintStatus;
+    /**
+     * The read-path schema check: the cached fingerprint comparison reduced to a
+     * warn-or-not verdict (ok / drift / unknown-version) with detail. Reuses the
+     * SAME lazily-built fingerprint the write path gates on — computed at most
+     * once per client, so it costs nothing after the first read.
+     */
+    schemaStatus(): SchemaStatus;
+    /**
+     * The additive `meta.clock` honesty field for this client's effective clock,
+     * or undefined when the host clock is in force (no `THINGS_TZ`/`THINGS_NOW`
+     * and no per-read override). `zoneOverride` reflects a per-read zone (the MCP
+     * `tz` argument) so the reported `today` matches what that read computed.
+     */
+    clockMeta(zoneOverride?: string): ClockMeta | undefined;
     read: {
-        today(filter?: ViewFilter): TodayView;
-        inbox(filter?: ViewFilter): ListItem[];
-        anytime(filter?: ViewFilter): SidebarSection[];
-        upcoming(filter?: UpcomingFilter): ListItem[];
-        someday(filter?: SomedayFilter): SidebarSection[];
-        logbook(options?: LogbookFilter): ListItem[];
-        trash(options?: {
-            limit?: number | null;
-        }): ListItem[];
+        /**
+         * The Today list (Today + This Evening split) with the sidebar badge,
+         * bounded to `limit` rows (default 50) counted in render order — Today
+         * first, then This Evening. `all`/`limit: null` returns every row; the
+         * `truncation` metadata carries the per-section (`today`/`evening`) counts.
+         */
+        today(options?: TodayFilter & ListBound & ClockScopedRead): BoundedTodayView;
+        /** Inbox captures, bounded (default 50). */
+        inbox(options?: InboxFilter & ListBound & ClockScopedRead): BoundedList<ListItem>;
+        /**
+         * Anytime catalogue: every area header and project row is always present;
+         * `areaLimit` (default 30) caps each area/loose block, `projectLimit`
+         * (default 3) each project block. `all` lifts both.
+         */
+        anytime(options?: ViewFilter & GroupedBound & ClockScopedRead): BoundedSectionsView;
+        /** Future-scheduled items in date order, bounded (default 50). */
+        upcoming(options?: UpcomingFilter & ListBound & ClockScopedRead): BoundedList<ListItem>;
+        /**
+         * Someday catalogue: `areaLimit` (default 30) caps each group; with
+         * `activeProjectItems`, `projectLimit` (default: every item) caps each
+         * active project's trailing child list. `all` lifts both.
+         */
+        someday(options?: SomedayFilter & GroupedBound & ClockScopedRead): BoundedSectionsView;
+        /** Logbook entries (most recent first), bounded (default 50). */
+        logbook(options?: Omit<LogbookFilter, "limit"> & ListBound & ClockScopedRead): BoundedList<ListItem>;
+        /** Trashed items (most recently modified first), bounded (default 50). */
+        trash(options?: ListBound & ClockScopedRead): BoundedList<ListItem>;
         /**
          * Projects in sidebar order. LATER (someday + future-scheduled) projects
          * are excluded by default — `later: true` appends them after the active
@@ -62,14 +159,32 @@ export interface ThingsClient {
         projects(options?: {
             areaUuid?: string;
             later?: boolean;
-        }): Project[];
-        /** Composite project view. Targets by uuid, unique name, or uuid prefix. */
-        projectView(ref: string): ProjectView;
-        /** Composite area view: direct to-dos, projects in sidebar order, later, logged. */
-        areaView(ref: string): AreaView;
+            overdue?: boolean;
+        } & ViewFilter & ClockScopedRead): Project[];
+        /**
+         * Composite project view. Targets by uuid, unique name, or uuid prefix.
+         * `overdue: true` keeps only child to-dos whose own deadline is overdue
+         * (open, before today); the tag filters (`tags`/`untagged`) keep only the
+         * child to-dos carrying the tag DIRECTLY (the container semantics — tags
+         * inherited from this project are ignored). Any content scope collapses
+         * headings left with no surviving child.
+         */
+        projectView(ref: string, options?: ViewFilter & ClockScopedRead): ProjectView;
+        /**
+         * Composite area view: direct to-dos, projects in sidebar order, later,
+         * logged. `overdue: true` keeps only the loose to-dos AND child projects
+         * whose OWN deadline is overdue; the tag filters keep only the rows
+         * matching by their own tags — no descent into project contents. Bounded
+         * per section: `projectLimit`/`areaLimit` (default 30 each) cap the ACTIVE
+         * project-rows and direct-to-dos sections (scheduled/someday project rows
+         * always survive, routed to the card's later sections); `all` lifts both.
+         * The `grouped` metadata carries the per-section counts.
+         */
+        areaView(ref: string, options?: ViewFilter & GroupedBound & ClockScopedRead): BoundedAreaView;
         areas(): Area[];
         tags(): Tag[];
-        search(query: string, options?: SearchOptions): SearchResultItem[];
+        /** Title/notes substring search, ranked, bounded (default 50). */
+        search(query: string, options?: SearchOptions & ClockScopedRead): BoundedList<SearchResultItem>;
         /**
          * Did-you-mean fallback: case-insensitive title-only substring match over
          * areas/projects/to-dos (open + untrashed), ordered and capped. `type`
@@ -79,11 +194,10 @@ export interface ThingsClient {
             type?: "to-do" | "project" | "area";
             limit?: number;
         }): LiteSearchResult;
-        /** Rows created/modified since a moment — incl. trashed/logged/templates. */
+        /** Rows created/modified since a moment — incl. trashed/logged/templates — bounded (default 50). */
         changes(options: {
             since: Date;
-            limit?: number | null;
-        }): ChangedItem[];
+        } & ListBound & ClockScopedRead): BoundedList<ChangedItem>;
         byUuid(uuid: string): AnyTask | null;
         /**
          * Classify a loose reference (uuid, >=6-char prefix, share link, or
@@ -176,6 +290,24 @@ export interface ThingsClient {
         /** Duplicate a project INCLUDING its children; the copy's uuid is on the result. */
         duplicateProject(uuid: string, options?: WriteOptions): Promise<MutationResult>;
         deleteProject(uuid: string, options?: WriteOptions): Promise<MutationResult>;
+        /**
+         * Turn an existing project into a repeating series. Drives the local Things
+         * app through the Accessibility API (two-key gated: `ui.enabled` config +
+         * `dangerouslyDriveGui`). This REPLACES the project with a new repeating
+         * template (its area is kept, its schedule is normalized to Someday); the
+         * original's identity is gone and it cannot be undone. The new template's
+         * uuid is on the result. An area-less Anytime project is moved to Someday
+         * first — a cleanup-free intermediate step surfaced in the plan.
+         */
+        makeRepeatingProject(uuid: string, rule: Omit<RepeatRuleParams, "uuid">, options?: WriteOptions): Promise<MutationResult>;
+        /**
+         * Create a project and, in the same call, turn it into a repeating series.
+         * TWO operations: the project is created first (and persists even if the
+         * make-repeating step refuses); then it is promoted (which drives the GUI —
+         * two-key gated, same as makeRepeatingProject). Give an `area` to place it,
+         * or omit it to create in Someday. The new template's uuid is on the result.
+         */
+        createRepeatingProject(params: ProjectCreateRepeatingParams, options?: WriteOptions): Promise<MutationResult>;
         /** Replace a project's full tag set (an empty list clears all tags). */
         setProjectTags(uuid: string, tags: string[], options?: WriteOptions): Promise<MutationResult>;
         /** Merge: current project tags + new ones, then replace. */
@@ -198,9 +330,13 @@ export interface ThingsClient {
          */
         batch(ops: BatchOp[], options?: BatchOptions, onResult?: (result: BatchItemResult) => void): Promise<BatchItemResult[]>;
         /**
-         * Undo the last N changes made through this client, newest first, by
-         * applying the inverse change. Irreversible changes are reported as
-         * such, never guessed at.
+         * Undo changes made through this client, newest first, by applying the
+         * inverse change. Selection: `last` trailing changes (default 1), narrowed
+         * to author `by` (exact actor, or `*`/undefined for all), or `txn` for one
+         * exact change by its `undoToken`. Irreversible changes are reported as
+         * such, never guessed at. An inverse is refused when the item changed
+         * outside things-api since (its container, status, schedule, trashed state,
+         * or a content field moved); `acknowledgeOutOfBandChanges` overwrites anyway.
          */
         undo(options?: UndoOptions, onItem?: (item: UndoItemResult) => void): Promise<UndoItemResult[]>;
     };