things-api 0.10.0 → 0.12.0

package/dist/read/views.js

@@ -4,7 +4,9 @@ import { mapProject, mapTodo } from "../model/mappers.js";
 import { projectOccurrences } from "../model/occurrences.js";
 import { decodeRecurrenceRule } from "../model/recurrence.js";
 import { directTagScopeSql, directUntaggedScopeSql, fetchTagsForTasks, fetchTaskRows, makeHeadingProjectResolver, makeRefResolver, NOT_TEMPLATE, resolveAreaUuid, resolveProjectUuid, resolveTagUuid, tagScopeBinds, tagScopeSql, tagWithDescendants, untaggedScopeSql, } from "./queries.js";
-import { ANYTIME_SELF, CONTAINER_UNTRASHED, EFF_PROJECT, LIVE, OPEN, OPEN_OR_UNSWEPT, OVERDUE, PROJECT_ANYTIME_ACTIVE, } from "./predicates.js";
+import { ANYTIME_SELF, CONTAINER_UNTRASHED, DEADLINE_PULLED, EFF_PROJECT, LIVE, OPEN, OPEN_OR_UNSWEPT, OVERDUE, PROJECT_ANYTIME_ACTIVE, } from "./predicates.js";
+import { isLooseRef } from "./pseudo-area.js";
+import { CANDIDATE_CAP } from "./shape.js";
 import { groupBySidebar } from "./sidebar-order.js";
 import { areasView } from "./tags.js";
 import { compareSearchMatches } from "./search-rank.js";
@@ -80,14 +82,17 @@ function overdueFilter(filter, packedToday) {
 // view's injected `now` via logBoundary(db, now) so the `logged` flag it stamps
 // honors the same clock as the SQL membership filter (a pinned test clock, a
 // lab run) — nothing here silently reaches for real time.
-function materialize(db, rows, boundary) {
+// `packedToday` (the view's injected clock, encodePackedDate(localToday(now)))
+// is threaded so the mapper can gate `todaySection` to Today members only —
+// the same clock the SQL membership filter uses.
+function materialize(db, rows, boundary, packedToday) {
     const refs = makeRefResolver(db);
     const headingProject = makeHeadingProjectResolver(db);
     const tags = fetchTagsForTasks(db, rows.map((r) => r.uuid));
     const items = rows.map((row) => {
         if (row.type === 1)
-            return mapProject(row, refs, tags.get(row.uuid) ?? []);
-        const todo = mapTodo(row, refs, tags.get(row.uuid) ?? []);
+            return mapProject(row, refs, tags.get(row.uuid) ?? [], packedToday);
+        const todo = mapTodo(row, refs, tags.get(row.uuid) ?? [], packedToday);
         if (todo.heading !== null) {
             const p = headingProject(todo.heading.uuid);
             if (p !== null)
@@ -102,8 +107,8 @@ function materialize(db, rows, boundary) {
 }
 /** Badge = OPEN members only (the GUI badge counts remaining work). */
 const isOpen = (i) => i.status === "open";
-export function todayView(db, now, filter) {
-    const todayIso = localToday(now);
+export function todayView(db, now, filter, zone) {
+    const todayIso = localToday(now, zone);
     const packedToday = encodePackedDate(todayIso);
     const tf = tagFilter(db, filter);
     const of = overdueFilter(filter, packedToday);
@@ -122,16 +127,15 @@ export function todayView(db, now, filter) {
     // has not yet passed keeps its comparator slot in place (GUI-parity ruling
     // 2026-07-14). The boundary is threaded into both the SQL filter and
     // materialize so the row's presence and its `logged` flag agree.
-    const boundary = logBoundary(db, now);
+    const boundary = logBoundary(db, now, zone);
     const rows = fetchTaskRows(db, `${OPEN_OR_UNSWEPT} AND ${CONTAINER_UNTRASHED} AND (
        (t.startDate IS NOT NULL AND t.startDate <= ? AND t.start IN (1, 2))
-       OR (t.deadline IS NOT NULL AND t.deadline <= ? AND t.startDate IS NULL
-           AND (t.deadlineSuppressionDate IS NULL OR t.deadlineSuppressionDate < t.deadline))
+       OR ${DEADLINE_PULLED}
      )${tf.sql}${of.sql}
      ORDER BY t.startBucket ASC,
               COALESCE(t.todayIndexReferenceDate, t.startDate, t.deadline) DESC,
               t.todayIndex ASC, t.uuid ASC`, [boundary.getTime() / 1000, packedToday, packedToday, ...tf.binds, ...of.binds]);
-    const items = materialize(db, rows, boundary);
+    const items = materialize(db, rows, boundary, packedToday);
     // Evening membership expires daily: raw startBucket=1 counts only while
     // startDate is exactly today; stale evening items belong to Today proper.
     const isEvening = (i) => i.todaySection === "evening" && i.startDate === todayIso;
@@ -159,11 +163,13 @@ export function todayView(db, now, filter) {
         badge: { dueOrOverdue, other: openItems.length - dueOrOverdue },
     };
 }
-export function inboxView(db, now, filter) {
+export function inboxView(db, now, filter, zone) {
     const tf = tagFilter(db, filter);
-    // `now` is threaded only for the `--overdue` boundary (the inbox order and
-    // the since/until window key on epoch creationDate, not on today).
-    const of = overdueFilter(filter, encodePackedDate(localToday(now)));
+    // `now` is threaded for the `--overdue` boundary AND for the deadline-pull
+    // exclusion below (the inbox order and the since/until window key on epoch
+    // creationDate, not on today).
+    const packedToday = encodePackedDate(localToday(now, zone));
+    const of = overdueFilter(filter, packedToday);
     const where = [OPEN, "t.start = 0"];
     const binds = [];
     // creationDate is an epoch REAL (Unix seconds) — mirror the changes/logbook
@@ -176,11 +182,19 @@ export function inboxView(db, now, filter) {
         where.push("t.creationDate <= ?");
         binds.push(filter.until.getTime() / 1000);
     }
+    // R13 (BANNER1 Q1b, law L-A): a due/overdue un-dismissed deadline pulls an
+    // undated Inbox row into Today AND removes it from the GUI Inbox list — even
+    // while its raw `start` still reads 0. EXCLUDE the pulled rows so the flat
+    // inbox view stays GUI-faithful; reuse the Today deadline arm verbatim so the
+    // exclusion can never drift from the pull todayView claims. A SUPPRESSED
+    // deadline (guard inside DEADLINE_PULLED) is not a pull, so it stays in Inbox.
+    where.push(`NOT ${DEADLINE_PULLED}`);
+    binds.push(packedToday);
     const rows = fetchTaskRows(db, `${where.join(" AND ")}${tf.sql}${of.sql} ORDER BY t."index" ASC`, [...binds, ...tf.binds, ...of.binds]);
-    return materialize(db, rows, logBoundary(db, now));
+    return materialize(db, rows, logBoundary(db, now, zone), encodePackedDate(localToday(now, zone)));
 }
-export function anytimeView(db, now, filter) {
-    const packedToday = encodePackedDate(localToday(now));
+export function anytimeView(db, now, filter, zone) {
+    const packedToday = encodePackedDate(localToday(now, zone));
     const tf = tagFilter(db, filter);
     const of = overdueFilter(filter, packedToday);
     // Mirrors UI membership: every active item, including Today members
@@ -191,18 +205,27 @@ export function anytimeView(db, now, filter) {
     // the parent project be open, so a closed-but-unswept project's children stay
     // cascade-excluded — the checked project row represents them. The boundary is
     // threaded into the SQL filter and materialize so presence and `logged` agree.
-    const boundary = logBoundary(db, now);
-    const rows = fetchTaskRows(db, `${OPEN_OR_UNSWEPT} AND ${ANYTIME_SELF("t")}
+    //
+    // R13 (BANNER1b, law L-A): Anytime is a SUPERSET of Today's to-dos — a
+    // due-deadline pull re-files an undated Inbox/Someday row into Anytime (out of
+    // its origin bucket) even while its raw `start` still reads 0/2. So the
+    // membership arm is ANYTIME_SELF *OR* the Today deadline-pull arm (reused
+    // verbatim from todayView, never re-derived). The container cascade still
+    // applies (a pulled child of a non-active project is represented by that
+    // project row).
+    const boundary = logBoundary(db, now, zone);
+    const rows = fetchTaskRows(db, `${OPEN_OR_UNSWEPT} AND (${ANYTIME_SELF("t")} OR ${DEADLINE_PULLED})
      AND ${PROJECT_ANYTIME_ACTIVE}${tf.sql}${of.sql} ORDER BY t."index" ASC`, [
         boundary.getTime() / 1000,
-        packedToday,
-        packedToday,
-        packedToday,
-        packedToday,
+        packedToday, // ANYTIME_SELF arm 1
+        packedToday, // ANYTIME_SELF arm 2
+        packedToday, // DEADLINE_PULLED
+        packedToday, // PROJECT_ANYTIME_ACTIVE arm 1
+        packedToday, // PROJECT_ANYTIME_ACTIVE arm 2
         ...tf.binds,
         ...of.binds,
     ]);
-    return groupBySidebar(db, materialize(db, rows, boundary));
+    return groupBySidebar(db, materialize(db, rows, boundary, packedToday));
 }
 /**
  * The UI's star marker in Anytime: the item is also a Today member. Mirrors
@@ -217,8 +240,8 @@ export function anytimeView(db, now, filter) {
  * deadline (deadlineSuppressionDate >= deadline); that column is not surfaced
  * on the entity, so a suppressed unscheduled overdue row is over-starred here.
  */
-export function isTodayMember(item, now) {
-    const today = localToday(now);
+export function isTodayMember(item, now, zone) {
+    const today = localToday(now, zone);
     if (item.startDate !== null)
         return item.startDate <= today;
     return item.deadline !== null && item.deadline <= today;
@@ -228,9 +251,9 @@ export function isTodayMember(item, now) {
  * scheduled row groups under its when-date, a forecast row under its deadline.
  */
 const groupKey = (i) => i.startDate ?? i.deadline ?? "";
-export function upcomingView(db, now, filter) {
-    const packedToday = encodePackedDate(localToday(now));
-    const boundary = logBoundary(db, now);
+export function upcomingView(db, now, filter, zone) {
+    const packedToday = encodePackedDate(localToday(now, zone));
+    const boundary = logBoundary(db, now, zone);
     const until = filter?.until;
     const since = filter?.since;
     const untilBinds = until === undefined ? [] : [encodePackedDate(until)];
@@ -258,8 +281,8 @@ export function upcomingView(db, now, filter) {
      AND t.deadline IS NOT NULL AND t.deadline > ?
      AND (t.deadlineSuppressionDate IS NULL OR t.deadlineSuppressionDate < t.deadline)${fcUntilSql}${fcSinceSql}${tf.sql}
      ORDER BY t.deadline ASC, t."index" ASC`, [packedToday, ...untilBinds, ...sinceBinds, ...tf.binds]);
-    const scheduled = materialize(db, rows, boundary);
-    const forecast = materialize(db, forecastRows, boundary);
+    const scheduled = materialize(db, rows, boundary, packedToday);
+    const forecast = materialize(db, forecastRows, boundary, packedToday);
     // The merged date-ordered stream keys on COALESCE(startDate, deadline) — a
     // scheduled row groups under its when-date, a forecast row under its deadline
     // — then the UI's within-day drag order (todayIndex ASC; live-verified
@@ -289,7 +312,7 @@ export function upcomingView(db, now, filter) {
      ORDER BY t.rt1_nextInstanceStartDate ASC, t."index" ASC`, [packedToday, ...untilBinds, ...sinceBinds, ...tf.binds]);
     const horizon = Math.max(1, Math.min(10, Math.trunc(filter?.horizon ?? 1)));
     const rawByUuid = new Map(templateRows.map((r) => [r.uuid, r.rt1_recurrenceRule]));
-    const occurrences = materialize(db, templateRows, boundary).flatMap((template) => {
+    const occurrences = materialize(db, templateRows, boundary, packedToday).flatMap((template) => {
         const startDate = template.repeating.nextOccurrence ?? null;
         if (startDate === null)
             return [];
@@ -342,7 +365,7 @@ export function upcomingView(db, now, filter) {
      AND (t.rt1_nextInstanceStartDate IS NULL OR t.rt1_nextInstanceStartDate <= ?
           OR t.rt1_instanceCreationPaused = 1)${tf.sql}
      ORDER BY t.todayIndex ASC, t."index" ASC`, [packedToday, ...tf.binds]);
-    const resting = materialize(db, restingRows, boundary).map((item) => {
+    const resting = materialize(db, restingRows, boundary, packedToday).map((item) => {
         const raw = restingRows.find((r) => r.uuid === item.uuid)?.rt1_recurrenceRule;
         if (raw !== null && raw !== undefined) {
             try {
@@ -358,9 +381,9 @@ export function upcomingView(db, now, filter) {
 }
 /** A someday to-do nested under a project (directly or via a heading). */
 const isChild = (i) => i.type === "to-do" && (i.project !== null || i.headingProject !== null);
-export function somedayView(db, now, filter) {
+export function somedayView(db, now, filter, zone) {
     const tf = tagFilter(db, filter);
-    const packedToday = encodePackedDate(localToday(now));
+    const packedToday = encodePackedDate(localToday(now, zone));
     const of = overdueFilter(filter, packedToday);
     // Default membership excludes ALL project children (the UI shows only
     // container-less someday to-dos, area members, and someday project rows);
@@ -370,9 +393,20 @@ export function somedayView(db, now, filter) {
         ? `EXISTS (SELECT 1 FROM TMTask p WHERE p.uuid = ${EFF_PROJECT}
          AND p.trashed = 0 AND p.status = 0 AND ${ANYTIME_SELF("p")})`
         : "0";
+    // R13 (BANNER1 Q1b, law L-A): a due/overdue un-dismissed deadline pulls an
+    // undated Someday row into Today AND removes it from the GUI Someday list —
+    // even while its raw `start` still reads 2. EXCLUDE the pulled rows so the flat
+    // someday view stays GUI-faithful; reuse the Today deadline arm verbatim so the
+    // exclusion can never drift from the pull todayView claims. A SUPPRESSED
+    // deadline (guard inside DEADLINE_PULLED) is not a pull, so it stays in Someday.
     const rows = fetchTaskRows(db, `${OPEN} AND t.start = 2 AND t.startDate IS NULL
-     AND (${EFF_PROJECT} IS NULL OR ${childArm})${tf.sql}${of.sql} ORDER BY t."index" ASC`, [...(withActiveChildren ? [packedToday, packedToday] : []), ...tf.binds, ...of.binds]);
-    const sections = groupBySidebar(db, materialize(db, rows, logBoundary(db, now)));
+     AND (${EFF_PROJECT} IS NULL OR ${childArm}) AND NOT ${DEADLINE_PULLED}${tf.sql}${of.sql} ORDER BY t."index" ASC`, [
+        ...(withActiveChildren ? [packedToday, packedToday] : []),
+        packedToday, // DEADLINE_PULLED exclusion
+        ...tf.binds,
+        ...of.binds,
+    ]);
+    const sections = groupBySidebar(db, materialize(db, rows, logBoundary(db, now, zone), encodePackedDate(localToday(now, zone))));
     // GUI order within a Someday group (live side-by-side, 2026-07-12):
     // PROJECT rows first (their sidebar order preserved), then direct to-dos in
     // drag order. Someday children of active projects (the activeProjectItems
@@ -387,7 +421,7 @@ export function somedayView(db, now, filter) {
         ],
     }));
 }
-export function logbookView(db, now, options) {
+export function logbookView(db, now, options, zone) {
     const cap = options?.limit === null ? null : (options?.limit ?? 100);
     const tf = tagFilter(db, options);
     const where = [];
@@ -397,9 +431,17 @@ export function logbookView(db, now, options) {
         binds.push(resolveProjectUuid(db, options.project));
     }
     if (options?.area !== undefined) {
-        const areaUuid = resolveAreaUuid(db, options.area);
-        where.push(`(t.area = ? OR EXISTS (SELECT 1 FROM TMTask p WHERE p.uuid = ${EFF_PROJECT} AND p.area = ?))`);
-        binds.push(areaUuid, areaUuid);
+        if (isLooseRef(options.area)) {
+            // `--area loose`: the area-less logged rows — effective area is null (own
+            // area null AND no area-carrying containing project). The inversion of the
+            // real-area subtree keep-rule below.
+            where.push(`t.area IS NULL AND (${EFF_PROJECT} IS NULL OR NOT EXISTS (SELECT 1 FROM TMTask p WHERE p.uuid = ${EFF_PROJECT} AND p.area IS NOT NULL))`);
+        }
+        else {
+            const areaUuid = resolveAreaUuid(db, options.area);
+            where.push(`(t.area = ? OR EXISTS (SELECT 1 FROM TMTask p WHERE p.uuid = ${EFF_PROJECT} AND p.area = ?))`);
+            binds.push(areaUuid, areaUuid);
+        }
     }
     if (options?.since !== undefined) {
         where.push("t.stopDate >= ?");
@@ -414,21 +456,40 @@ export function logbookView(db, now, options) {
     // checked in their original lists, exactly like the GUI's Logbook. The
     // membership boundary rides the injected clock (threaded into both the SQL
     // filter and materialize so presence and the `logged` flag agree).
-    const boundary = logBoundary(db, now);
+    const boundary = logBoundary(db, now, zone);
     const rows = fetchTaskRows(db, `${LIVE} AND t.status IN (2, 3) AND t.stopDate <= ?${extra}${tf.sql} ORDER BY t.stopDate DESC${cap === null ? "" : " LIMIT ?"}`, [boundary.getTime() / 1000, ...binds, ...tf.binds, ...(cap === null ? [] : [cap])]);
-    return materialize(db, rows, boundary);
+    return materialize(db, rows, boundary, encodePackedDate(localToday(now, zone)));
 }
-export function trashView(db, now, options) {
+/**
+ * A cheap COUNT of one area's logged rows — the SAME subtree-inclusive scope
+ * (own area OR containing project's area) and log-move boundary logbookView
+ * applies, without materializing a single row. Feeds the `area show` TTY card's
+ * live logbook-footer count; real areas only (the loose pseudo-area accumulates
+ * no `logbook --area` archive).
+ */
+export function areaLoggedCount(db, areaUuid, now, zone) {
+    const boundary = logBoundary(db, now, zone);
+    const row = db
+        .prepare(`SELECT COUNT(*) AS n FROM TMTask t
+       WHERE ${LIVE} AND t.status IN (2, 3) AND t.stopDate <= ?
+         AND (t.area = ? OR EXISTS (SELECT 1 FROM TMTask p WHERE p.uuid = ${EFF_PROJECT} AND p.area = ?))`)
+        .get(boundary.getTime() / 1000, areaUuid, areaUuid);
+    return row.n;
+}
+export function trashView(db, now, options, zone) {
     const cap = options?.limit === null ? null : (options?.limit ?? 200);
     const rows = fetchTaskRows(db, `t.type IN (0, 1) AND t.trashed = 1 AND ${NOT_TEMPLATE}
      ORDER BY t.userModificationDate DESC${cap === null ? "" : " LIMIT ?"}`, cap === null ? [] : [cap]);
-    return materialize(db, rows, logBoundary(db, now));
+    return materialize(db, rows, logBoundary(db, now, zone), encodePackedDate(localToday(now, zone)));
 }
 export function projectsView(db, options) {
     // areaUuid accepts a uuid OR a unique (case-insensitive) title; ambiguous
-    // or unknown references throw like every other ref resolver.
-    const area = options?.areaUuid === undefined ? null : resolveAreaUuid(db, options.areaUuid);
-    const packedToday = encodePackedDate(localToday(options?.now));
+    // or unknown references throw like every other ref resolver. The reserved
+    // `loose` ref scopes to the NULL area (area-less projects) — the sidebar's
+    // leading loose block — with no uuid to resolve.
+    const loose = options?.areaUuid !== undefined && isLooseRef(options.areaUuid);
+    const area = options?.areaUuid === undefined || loose ? null : resolveAreaUuid(db, options.areaUuid);
+    const packedToday = encodePackedDate(localToday(options?.now, options?.zone));
     // Tag scope (§9a): the projects LIST is a FLAT view (like `anytime` restricted
     // to project rows), NOT a single-container view — projects sit in different
     // areas with heterogeneous inheritance, there is no universally-inherited tag
@@ -457,8 +518,11 @@ export function projectsView(db, options) {
     // (area-less) projects first in their own drag order — the GUI lists them
     // above the areas — then each area by ITS sidebar rank (TMArea."index"),
     // projects within an area by their drag order.
-    const where = area
-        ? `${OPEN} AND t.type = 1 AND t.area = ?${laterSql}${overdueSql}${tf.sql}
+    // A single-group flat listing (loose OR a real area) shares one ORDER shape;
+    // only the unscoped sidebar catalogue interleaves areas by their rank.
+    const areaClause = loose ? " AND t.area IS NULL" : area ? " AND t.area = ?" : "";
+    const where = loose || area
+        ? `${OPEN} AND t.type = 1${areaClause}${laterSql}${overdueSql}${tf.sql}
        ORDER BY ${activeFirst}t."index" ASC`
         : `${OPEN} AND t.type = 1${laterSql}${overdueSql}${tf.sql} ORDER BY (t.area IS NOT NULL) ASC,
        (SELECT a."index" FROM TMArea a WHERE a.uuid = t.area) ASC, ${activeFirst}t."index" ASC`;
@@ -469,7 +533,7 @@ export function projectsView(db, options) {
         ...tf.binds,
         ...activeFirstBinds,
     ]);
-    const items = materialize(db, rows, logBoundary(db, options?.now));
+    const items = materialize(db, rows, logBoundary(db, options?.now, options?.zone), packedToday);
     if (options?.later !== true)
         return items;
     // Each group's later sub-block reads like Upcoming: SCHEDULED projects
@@ -477,7 +541,7 @@ export function projectsView(db, options) {
     // hidden on entities but present on the raw rows) — then someday in drag
     // order. The SQL already made group runs contiguous with actives leading,
     // so only the later runs are re-sorted (stable within someday).
-    const todayIso = localToday(options?.now);
+    const todayIso = localToday(options?.now, options?.zone);
     const ti = new Map(rows.map((r) => [r.uuid, r.todayIndex ?? 0]));
     const isLater = (p) => p.startDate !== null ? p.startDate > todayIso : p.start === "someday";
     const out = [];
@@ -523,13 +587,14 @@ export function projectsView(db, options) {
  * carry no modification dates, and checklist-item edits do not bump the
  * parent task — those changes are invisible here.
  */
-export function changesView(db, now, options) {
+export function changesView(db, now, options, zone) {
     const cap = options.limit === null ? null : (options.limit ?? 200);
     const sinceEpoch = options.since.getTime() / 1000;
     const rows = fetchTaskRows(db, `t.type IN (0, 1) AND t.userModificationDate > ?
      ORDER BY t.userModificationDate DESC${cap === null ? "" : " LIMIT ?"}`, [sinceEpoch, ...(cap === null ? [] : [cap])]);
+    const changed = materialize(db, rows, logBoundary(db, now, zone), encodePackedDate(localToday(now, zone)));
     // oxlint-disable-next-line no-map-spread -- building fresh change objects, not mutating
-    return materialize(db, rows, logBoundary(db, now)).map((item, i) => ({
+    return changed.map((item, i) => ({
         ...item,
         changeKind: (rows[i]?.creationDate ?? 0) > sinceEpoch ? "created" : "modified",
     }));
@@ -541,16 +606,16 @@ export function changesView(db, now, options) {
  * doctrine: containers (areas, then projects) first, then to-dos; within a
  * group active rows precede someday rows, then most-recently-modified. `type`
  * scopes to a single class (the typed-namespace paths). Results are capped
- * (default 10); `total` reports the pre-cap match count so the caller can
- * append a "… n more" tail.
+ * (default {@link CANDIDATE_CAP}); `total` reports the pre-cap match count so the
+ * caller can append a "… n more" tail.
  */
 const somedayRank = (i) => (i.start === "someday" ? 1 : 0);
 /** Lite-search order within a task group: active before someday, then most-recently-modified. */
 function byStatusThenRecent(a, b) {
     return somedayRank(a) - somedayRank(b) || b.modified.getTime() - a.modified.getTime();
 }
-export function liteTitleSearch(db, query, options, now) {
-    const cap = options?.limit ?? 10;
+export function liteTitleSearch(db, query, options, now, zone) {
+    const cap = options?.limit ?? CANDIDATE_CAP;
     const type = options?.type;
     const needle = query.toLowerCase();
     const areas = type === undefined || type === "area"
@@ -562,7 +627,7 @@ export function liteTitleSearch(db, query, options, now) {
     if (type === undefined || type === "to-do" || type === "project") {
         const typeSql = type === "to-do" ? "t.type = 0" : type === "project" ? "t.type = 1" : "t.type IN (0, 1)";
         const rows = fetchTaskRows(db, `${OPEN} AND ${CONTAINER_UNTRASHED} AND ${typeSql} AND t.title LIKE ?${LIKE_ESCAPE}`, [`%${escapeLike(query)}%`]);
-        tasks = materialize(db, rows, logBoundary(db, now));
+        tasks = materialize(db, rows, logBoundary(db, now, zone), encodePackedDate(localToday(now, zone)));
     }
     const projects = tasks.filter((t) => t.type === "project").toSorted(byStatusThenRecent);
     const todos = tasks.filter((t) => t.type === "to-do").toSorted(byStatusThenRecent);
@@ -571,18 +636,56 @@ export function liteTitleSearch(db, query, options, now) {
         ...projects.map((task) => ({ kind: "task", task })),
         ...todos.map((task) => ({ kind: "task", task })),
     ];
-    return { candidates: ordered.slice(0, cap), total: ordered.length };
+    // Zero LIVE matches: probe whether the name matches DEAD rows (trashed, or
+    // swept to the logbook) so the caller gets an honest hint instead of a bare
+    // miss — the dead rows themselves never become candidates (areas can be
+    // neither trashed nor logged, so only tasks are counted).
+    let deadMatches;
+    if (ordered.length === 0 && type !== "area") {
+        const typeSql = type === "to-do" ? "t.type = 0" : type === "project" ? "t.type = 1" : "t.type IN (0, 1)";
+        const boundary = logBoundary(db, now, zone).getTime() / 1000;
+        const row = db
+            .prepare(`SELECT
+           SUM(CASE WHEN t.trashed = 1 THEN 1 ELSE 0 END) AS trashed,
+           SUM(CASE WHEN t.trashed = 0 AND t.status IN (2, 3) AND t.stopDate IS NOT NULL AND t.stopDate <= ? THEN 1 ELSE 0 END) AS logbook
+         FROM TMTask t
+         WHERE ${NOT_TEMPLATE} AND ${typeSql} AND t.title LIKE ?${LIKE_ESCAPE}`)
+            .get(boundary, `%${escapeLike(query)}%`);
+        const trashed = row.trashed ?? 0;
+        const logbook = row.logbook ?? 0;
+        if (trashed > 0 || logbook > 0)
+            deadMatches = { trashed, logbook };
+    }
+    return {
+        candidates: ordered.slice(0, cap),
+        total: ordered.length,
+        ...(deadMatches !== undefined && { deadMatches }),
+    };
+}
+/** A one-line notes snippet (~80 chars) centered on the first occurrence of the needle. */
+const SNIPPET_MAX = 80;
+function notesSnippet(notes, needleLower) {
+    const flat = notes.replace(/\s+/g, " ").trim();
+    if (flat.length <= SNIPPET_MAX)
+        return flat;
+    const hit = Math.max(0, flat.toLowerCase().indexOf(needleLower));
+    const half = Math.max(0, Math.floor((SNIPPET_MAX - needleLower.length) / 2));
+    let end = Math.min(flat.length, Math.max(hit - half, 0) + SNIPPET_MAX);
+    const start = Math.max(0, end - SNIPPET_MAX);
+    const core = flat.slice(start, end);
+    return `${start > 0 ? "…" : ""}${core}${end < flat.length ? "…" : ""}`;
 }
-export function searchView(db, query, options, now) {
+export function searchView(db, query, options, now, zone) {
     const cap = options?.limit === null ? null : (options?.limit ?? 50);
     const needle = `%${escapeLike(query)}%`;
     // `--overdue` narrows to OPEN, past-deadline matches. Its open-only predicate
     // is contradictory with the status-widening flags (logged/trashed/all); the
     // CLI/MCP surfaces reject that combination, so here it simply intersects.
-    const of = overdueFilter(options, encodePackedDate(localToday(now)));
+    const packedToday = encodePackedDate(localToday(now, zone));
+    const of = overdueFilter(options, packedToday);
     // Threaded into every materialize so the `logged` flag (--logged widens to
     // closed rows) honors the injected clock, not wall time.
-    const boundary = logBoundary(db, now);
+    const boundary = logBoundary(db, now, zone);
     // The scope predicates (everything except the match needle), reused verbatim
     // for the needle query AND the heading-credited-project query so both honor
     // the same type/status/scope constraints.
@@ -609,24 +712,49 @@ export function searchView(db, query, options, now) {
         scopeBinds.push(uuid, uuid);
     }
     if (options?.area !== undefined) {
-        const uuid = resolveAreaUuid(db, options.area);
-        scope.push("t.area = ?");
-        scopeBinds.push(uuid);
+        if (isLooseRef(options.area)) {
+            // `--area loose`: the area-less hits — effective area is null (own area
+            // null AND no area-carrying containing project). The inversion of the
+            // real-area subtree keep-rule below; inbox captures (area-less) are
+            // legitimately included.
+            scope.push(`t.area IS NULL AND (${EFF_PROJECT} IS NULL OR NOT EXISTS (SELECT 1 FROM TMTask p WHERE p.uuid = ${EFF_PROJECT} AND p.area IS NOT NULL))`);
+        }
+        else {
+            // Real-area filter is SUBTREE-INCLUSIVE (own area OR containing project's
+            // area) — the same effective-area shape logbookView uses, so every --area
+            // view scopes to the whole subtree, not just an area's direct members.
+            const uuid = resolveAreaUuid(db, options.area);
+            scope.push(`(t.area = ? OR EXISTS (SELECT 1 FROM TMTask p WHERE p.uuid = ${EFF_PROJECT} AND p.area = ?))`);
+            scopeBinds.push(uuid, uuid);
+        }
     }
     const tf = tagFilter(db, options);
     // Needle matches: title OR notes. No SQL LIMIT — ranking runs before the cap.
     const rows = fetchTaskRows(db, `${scope.join(" AND ")} AND (t.title LIKE ?${LIKE_ESCAPE} OR t.notes LIKE ?${LIKE_ESCAPE})${tf.sql}${of.sql}`, [...scopeBinds, needle, needle, ...tf.binds, ...of.binds]);
     const needleLower = query.toLowerCase();
     const matches = new Map();
-    for (const item of materialize(db, rows, boundary)) {
-        // Field credit: title beats notes when both carry the substring.
+    /** Attach a match annotation to a materialized hit (title matches carry none). */
+    const annotate = (item, ann) => {
+        if (ann !== undefined)
+            item.match = ann;
+    };
+    for (const item of materialize(db, rows, boundary, packedToday)) {
+        // Field credit: title beats notes when both carry the substring. A notes-only
+        // hit is annotated with a bounded snippet centered on the match; a title hit
+        // carries no annotation (presence-keyed — matched where you'd expect).
         const field = item.title.toLowerCase().includes(needleLower) ? "title" : "notes";
+        if (field === "notes") {
+            annotate(item, { field: "notes", text: notesSnippet(item.notes ?? "", needleLower) });
+        }
         matches.set(item.uuid, { item, field });
     }
     // Heading titles are treated as if they lived in the parent PROJECT's notes:
     // a heading-title match surfaces the parent project (never a bare heading
-    // row), credited at the heading-via-project field rank. A to-do-only search
-    // has no project rows, so headings do not apply there.
+    // row), credited at the heading field rank. A to-do-only search has no project
+    // rows, so headings do not apply there. Heading OUTRANKS notes for the
+    // annotation (precedence title > heading > notes): a project matched by its
+    // own notes AND by a child heading shows the heading annotation, though it
+    // keeps its notes rank; a title-matched project keeps NO annotation.
     if (options?.type !== "to-do") {
         const headingRows = db
             .prepare(`SELECT project AS projectUuid, title FROM TMTask
@@ -637,21 +765,51 @@ export function searchView(db, query, options, now) {
             if (!headingTitleFor.has(h.projectUuid))
                 headingTitleFor.set(h.projectUuid, h.title ?? "");
         }
-        // Surface only the projects NOT already matched by their own title/notes
-        // (a higher-ranked field already represents them), and only those passing
-        // the view's scope.
-        const wanted = [...headingTitleFor.keys()].filter((uuid) => !matches.has(uuid));
+        // Projects ALREADY matched: re-credit a notes annotation to the heading
+        // (title stays annotation-free). Projects NOT yet matched: materialize and
+        // add them at the heading rank. Both only where the view's scope allows.
+        const wanted = [];
+        for (const [uuid, headingTitle] of headingTitleFor) {
+            const existing = matches.get(uuid);
+            if (existing === undefined) {
+                wanted.push(uuid);
+            }
+            else if (existing.item.type === "project" && existing.field === "notes") {
+                annotate(existing.item, { field: "heading", text: headingTitle });
+            }
+        }
         if (wanted.length > 0) {
             const placeholders = wanted.map(() => "?").join(", ");
             const projectRows = fetchTaskRows(db, `${scope.join(" AND ")} AND t.type = 1 AND t.uuid IN (${placeholders})${tf.sql}${of.sql}`, [...scopeBinds, ...wanted, ...tf.binds, ...of.binds]);
-            for (const item of materialize(db, projectRows, boundary)) {
-                const matchedVia = {
-                    kind: "heading",
-                    title: headingTitleFor.get(item.uuid) ?? "",
-                };
-                // Annotate the freshly materialized entity in place (owned here).
-                item.matchedVia = matchedVia;
-                matches.set(item.uuid, { item, field: "heading", matchedVia });
+            for (const item of materialize(db, projectRows, boundary, packedToday)) {
+                annotate(item, { field: "heading", text: headingTitleFor.get(item.uuid) ?? "" });
+                matches.set(item.uuid, { item, field: "heading" });
+            }
+        }
+    }
+    // Checklist-item titles are treated as properties of the parent TO-DO (like
+    // notes): a checklist-body match surfaces the parent to-do (deduped — one to-do
+    // no matter how many of its rows match), annotated with the FIRST matching
+    // row's title. Checklist is the lowest-precedence field, so it only adds to-dos
+    // not already matched by their own title/notes (those keep the higher credit).
+    // Checklist-item uuids appear on NO surface — the join reads titles only.
+    if (options?.type !== "project") {
+        const checklistRows = db
+            .prepare(`SELECT task AS todoUuid, title FROM TMChecklistItem
+         WHERE task IS NOT NULL AND title LIKE ?${LIKE_ESCAPE} ORDER BY "index" ASC`)
+            .all(needle);
+        const checklistTitleFor = new Map();
+        for (const c of checklistRows) {
+            if (!checklistTitleFor.has(c.todoUuid))
+                checklistTitleFor.set(c.todoUuid, c.title ?? "");
+        }
+        const wanted = [...checklistTitleFor.keys()].filter((uuid) => !matches.has(uuid));
+        if (wanted.length > 0) {
+            const placeholders = wanted.map(() => "?").join(", ");
+            const todoRows = fetchTaskRows(db, `${scope.join(" AND ")} AND t.type = 0 AND t.uuid IN (${placeholders})${tf.sql}${of.sql}`, [...scopeBinds, ...wanted, ...tf.binds, ...of.binds]);
+            for (const item of materialize(db, todoRows, boundary, packedToday)) {
+                annotate(item, { field: "checklist", text: checklistTitleFor.get(item.uuid) ?? "" });
+                matches.set(item.uuid, { item, field: "checklist" });
             }
         }
     }