@blamejs/core 0.11.34 → 0.11.36

package/CHANGELOG.md

@@ -8,6 +8,10 @@ upgrading across more than a few patches at a time.
 
 ## v0.11.x
 
+- v0.11.36 (2026-05-21) — **`b.calendar.expandRecurrence` picks up BYWEEKNO / BYYEARDAY / BYHOUR / BYMINUTE / BYSECOND filters (RFC 5545 §3.3.10).** Closes the v0.11.31 deferral on the time-of-day and year-relative BY* filters. `expandRecurrence` now honours `byWeekNo` (ISO 8601 1..53 with negative-from-end semantics), `byYearDay` (1..366 with negative-from-end), `byHour` (0..23), `byMinute` (0..59), and `bySecond` (0..60 — covers POSIX leap-second representation). The expansion still operates as a per-step filter (stepping at the rule's FREQ, then dropping candidates that fail the BY* predicates) — BYSETPOS remains deferred-with-condition because it requires expanding ALL candidates within a FREQ interval and picking the Nth, which is a structural restructure of the expand loop. Operators with `last weekday of month`-style needs continue to see the same defer note from v0.11.31. **Added:** *`byWeekNo` filter — ISO 8601 week numbers* — `recurrenceRules[i].byWeekNo: [1, 53, -1]` filters candidates to the named ISO 8601 weeks. Negative values count from the end of the year (`-1` = last ISO week, which may be week 52 or week 53 depending on the year). The ISO week-of-year calculation matches the canonical algorithm — week 1 is the week containing the first Thursday of the year. · *`byYearDay` filter — day-of-year (1..366 / -1..-366)* — `recurrenceRules[i].byYearDay: [1, 366, -1]` filters by ordinal day-of-year. Negative values count from the end of the year, accounting for leap-year length (366 vs 365). With a `frequency: "daily"` rule + `byYearDay: [1]` the expander emits Jan 1 of each year. · *`byHour` / `byMinute` / `bySecond` time-of-day filters* — `byHour: [9, 17]` filters candidates by UTC hour-of-day (0..23). `byMinute: [0, 30]` (0..59). `bySecond: [0, 30, 60]` (0..60 — the leap-second representation in POSIX time). Most useful with sub-day frequencies — `frequency: "hourly"` + `byHour: [9, 17]` emits twice-daily at 9am and 5pm. · *Negative BY* semantics per RFC 5545 §3.3.10* — `byWeekNo: [-1]` matches the last ISO week of the year (computed via the Dec-28 anchor — Dec 28 always falls in the last ISO week). `byYearDay: [-1]` matches the last day of the year (uses the Gregorian leap-year rule to determine whether 365 or 366 is the correct ordinal). Both negative-value paths covered by tests. **Security:** *Same step-budget cap from v0.11.31 applies* — Sparse BY* filters (e.g. `byYearDay: [1]` with `frequency: "daily"` — only 1 in 365 candidates matches) still loop within the `MAX_EXPAND_INSTANCES * 366` step budget; the 10-year `MAX_EXPAND_SPAN_MS` window cap also applies. Operators can't construct a BY*-filter that loops past the bounded budget. · *Integer-range validation on every BY* value* — `byWeekNo` rejects values outside ±53. `byYearDay` rejects outside ±366. `byHour` 0..23. `byMinute` 0..59. `bySecond` 0..60. Adversarial-shape values silently drop from the set (no error — the rule continues with the surviving values per RFC 5545's tolerant grammar). **References:** [RFC 5545 §3.3.10 (RRULE — BYWEEKNO / BYYEARDAY / BYHOUR / BYMINUTE / BYSECOND)](https://www.rfc-editor.org/rfc/rfc5545.html#section-3.3.10) · [RFC 8984 §4.3.2 (JSCalendar RecurrenceRule)](https://www.rfc-editor.org/rfc/rfc8984.html#section-4.3.2) · [ISO 8601 (Week numbering)](https://www.iso.org/iso-8601-date-and-time-format.html)
+
+- v0.11.35 (2026-05-21) — **`b.calendar` VTODO ↔ JSCalendar Task (RFC 8984 §6).** Closes the v0.11.31 deferral. `b.calendar.fromIcal` now recognises VTODO components and maps them to JSCalendar Task objects per RFC 8984 §6. `b.calendar.toIcal` emits a VTODO envelope (with DUE / STATUS / PERCENT-COMPLETE / COMPLETED iCalendar properties) when the input `@type` is `Task`. `b.calendar.validate` picks up Task-specific shape rules: `due` as LocalDateTime, `estimatedDuration` as PnYnMnDTnHnMnS, `progress` from the RFC 8984 §6.4.3 vocabulary (`needs-action` | `in-process` | `completed` | `cancelled` | `failed`), `percentComplete` ∈ [0..100], `progressUpdated` as UTCDateTime. A VCALENDAR carrying both VEVENT and VTODO components now returns an array of mixed `Event` + `Task` shapes. **Added:** *`b.calendar.fromIcal` maps VTODO → JSCalendar Task* — VTODO components in the VCALENDAR are mapped to `@type: "Task"` objects with the same `uid` / `updated` / `title` / `description` / `start` / `timeZone` / `locations` / `recurrenceRules` slots Event uses, plus the Task-specific fields: `due` (DUE → LocalDateTime), `estimatedDuration` (DURATION), `progress` (STATUS lowercased), `percentComplete` (PERCENT-COMPLETE 0..100), `progressUpdated` (COMPLETED → UTCDateTime). UTC DUE values map to `timeZone: "Etc/UTC"` the same way DTSTART does. · *`b.calendar.toIcal` emits VTODO when `@type === "Task"`* — The envelope is `BEGIN:VTODO` / `END:VTODO` instead of `BEGIN:VEVENT`. Task-specific properties round-trip: `DUE` (with `;TZID=` parameter or `Z` suffix or floating local time per the same RFC 8984 §1.4.4 timeZone mapping as DTSTART), `STATUS` (uppercased), `PERCENT-COMPLETE`, `COMPLETED` (UTC). `estimatedDuration` maps to `DURATION` (RFC 5545 doesn't distinguish Event vs Task duration on the wire). · *`b.calendar.validate` learns Task-specific shape rules (RFC 8984 §6.4)* — `due` must be a LocalDateTime, `estimatedDuration` must match the same PnYnMnDTnHnMnS Duration grammar Event uses, `progress` must be in the `JSCAL_TASK_PROGRESS` catalogue (also exposed as a new top-level export), `percentComplete` must be a finite number in 0..100, `progressUpdated` must be a UTCDateTime. Structured `CalendarError` codes: `calendar/bad-due`, `calendar/bad-progress`, `calendar/bad-percent`, `calendar/bad-progress-updated`. · *Mixed-component VCALENDAR returns an array of Event + Task shapes* — When a VCALENDAR contains both VEVENT and VTODO children, `fromIcal` returns an Array — events first, tasks second, in their declared order. The single-component shortcut (returning the bare object) still applies when only one component is present. · *`calendar/no-vevent` error code renamed to `calendar/no-component`* — The refusal that fires when a VCALENDAR has no parseable child component now uses the more accurate `calendar/no-component` code (since VTODO is also valid). Operators that grep on the prior `calendar/no-vevent` code need to update the match; the human-facing error message also updates. **References:** [RFC 8984 §6 (JSCalendar Task)](https://www.rfc-editor.org/rfc/rfc8984.html#section-6) · [RFC 5545 §3.6.2 (iCalendar VTODO component)](https://www.rfc-editor.org/rfc/rfc5545.html#section-3.6.2) · [RFC 5545 §3.8.2.3 (DUE date-time)](https://www.rfc-editor.org/rfc/rfc5545.html#section-3.8.2.3) · [RFC 5545 §3.8.1.11 (STATUS — needs-action/in-process/completed/cancelled)](https://www.rfc-editor.org/rfc/rfc5545.html#section-3.8.1.11)
+
 - v0.11.34 (2026-05-21) — **JMAP WebSocket transport (RFC 8887) on `b.mail.server.jmap`.** Closes the v0.11.29 deferral. The JMAP listener now exposes `webSocketHandler(req, socket, head)` — a turnkey RFC 8887 transport built on the framework's `b.websocket.handleUpgrade`. Clients connect with the `jmap` subprotocol; bidirectional JSON frames carry `{ "@type": "Request" }` / `{ "@type": "WebSocketPushEnable" }` / `{ "@type": "WebSocketPushDisable" }` from the client, and `{ "@type": "Response" }` / `{ "@type": "StateChange" }` / `{ "@type": "RequestError" }` from the server. `Request` frames flow through the same `dispatch(actor, request)` path the HTTP `apiHandler` uses; `WebSocketPushEnable` hooks the operator's `mailStore.subscribePush(actor, types, emitFn)` and converts backend StateChange events into outbound WebSocket frames.
 
 The session resource picks up `webSocketUrl` so clients discover the endpoint via the same JMAP session-discovery flow they use for `apiUrl` / `eventSourceUrl` / `uploadUrl` / `downloadUrl`. permessage-deflate is OFF by default — same CRIME-class compression-oracle threat model as the v0.11.28 IMAP COMPRESS=DEFLATE intentional skip — operators opt in via `opts.webSocketPermessageDeflate`. **Added:** *`webSocketHandler(req, socket, head)` on the listener handle* — Mount on the operator's HTTP server's `'upgrade'` event. Auth is delegated to the surrounding HTTP middleware (the handler expects `req.user` / `req.actor` to be populated by upstream auth); unauthenticated requests write `HTTP/1.1 401 Unauthorized` to the raw socket per the WebSocket spec's pre-handshake error shape. RFC 8887 §3.1 requires the `jmap` subprotocol; the handler refuses the upgrade with close-code 1002 if `Sec-WebSocket-Protocol: jmap` is missing. · *Bidirectional JSON-framed transport* — Client → server `@type`: `Request` (same body as HTTP POST — `{ using, methodCalls, createdIds? }`), `WebSocketPushEnable` (`{ dataTypes?, pushState? }`), `WebSocketPushDisable`. Server → client `@type`: `Response` (`{ requestId, methodResponses, sessionState, createdIds }`), `StateChange` (`{ changed, pushed? }`), `RequestError` (`{ requestId, type, description }`). Unknown `@type` frames trigger a `RequestError` rather than tearing down the channel. · *Push integration shares the operator hook with EventSource* — `WebSocketPushEnable` forwards `(actor, dataTypes, emitFn)` to `mailStore.subscribePush` — the same backend hook the EventSource handler (v0.11.29) consumes. Operators wire push once and both transports surface the same `StateChange` events. Per-connection `WebSocketPushDisable` calls the unsubscribe function the backend returned from `subscribePush`. Connection close cleans up implicitly. · *Session resource carries `webSocketUrl`* — The session JSON now includes `webSocketUrl: opts.webSocketUrl || "/jmap/ws"` per RFC 8887 §3. Operators discoverable-by-default — clients using a stock JMAP library find the WS endpoint via the session resource the same way they find `apiUrl` today. **Security:** *Binary frames refused* — JMAP is JSON-only over WebSocket. Binary frames trigger a `RequestError` with `type: "notJSON"`; the connection stays open so the next text frame can be valid. Prevents a misbehaving client from sneaking opaque bytes past the JSON parser. · *JSON parse routed through `b.safeJson.parse`* — WebSocket text frames are parsed through `b.safeJson.parse` with the per-connection `maxBytes` cap (default 10 MiB; operator-tunable via `opts.webSocketMaxMessageBytes`). Catches CVE-2020-7660-class prototype-pollution payloads + adversarial-depth JSON before they reach the JMAP method dispatcher. · *permessage-deflate OFF by default (CRIME-class threat)* — RFC 7692 permessage-deflate enables compression-oracle attacks (CVE-2012-4929 CRIME class) when the operator pipes JSON containing both attacker-controlled and confidential data through the same connection. Default is OFF; operators with explicit threat-model justification opt in via `opts.webSocketPermessageDeflate = true`. Mirrors the v0.11.28 IMAP COMPRESS=DEFLATE intentional refusal. · *Subprotocol negotiation refuses non-`jmap` clients* — If the client's `Sec-WebSocket-Protocol` header doesn't include `jmap`, the listener refuses the upgrade with close-code 1002 (protocol error). RFC 8887 §3.1 — the JMAP-WS connection is identified by the subprotocol; refusing here prevents the connection from being misinterpreted as a generic WebSocket channel by middleware downstream. **References:** [RFC 8887 (JMAP over WebSocket)](https://www.rfc-editor.org/rfc/rfc8887.html) · [RFC 8620 (JMAP Core)](https://www.rfc-editor.org/rfc/rfc8620.html) · [RFC 6455 (The WebSocket Protocol)](https://www.rfc-editor.org/rfc/rfc6455.html) · [RFC 7692 (Compression Extensions for WebSocket — NOT enabled)](https://www.rfc-editor.org/rfc/rfc7692.html) · [CVE-2012-4929 (CRIME — compression-oracle attack on TLS)](https://nvd.nist.gov/vuln/detail/CVE-2012-4929)

package/lib/calendar.js

@@ -61,6 +61,18 @@ var JSCAL_ALERT_ACTIONS = Object.freeze({
   display: 1, email: 1,
 });
 
+// RFC 8984 §6.4.3 — Task progress vocabulary. Mirrors RFC 5545 STATUS
+// values for VTODO (`NEEDS-ACTION` / `IN-PROCESS` / `COMPLETED` /
+// `CANCELLED`); JSCalendar lower-cases them. `failed` is NOT included
+// — RFC 5545 STATUS does not define a `FAILED` value, so the iCal
+// round-trip path could not safely emit it (strict consumers refuse
+// the unknown STATUS token). Operators with a "failed" semantic
+// model it via `progress: "cancelled"` + a vendor-namespaced
+// extension property instead.
+var JSCAL_TASK_PROGRESS = Object.freeze({
+  "needs-action": 1, "in-process": 1, "completed": 1, "cancelled": 1,
+});
+
 // Recurrence-expansion caps. Mirror b.safeIcal's RRULE limits so the
 // expand path can't outpace what the parser already permitted.
 var MAX_EXPAND_INSTANCES = 4096;                                                                       // allow:raw-byte-literal — instance count cap, not bytes
@@ -120,6 +132,44 @@ function validate(jsCal) {
         "b.calendar.validate: Event.duration MUST be an RFC 8601 PnYnMnDTnHnMnS Duration");
     }
   }
+  if (t === JSCAL_TYPES.Task) {
+    if (jsCal.start !== undefined && (typeof jsCal.start !== "string" || !_isLocalDateTime(jsCal.start))) {
+      throw new CalendarError("calendar/bad-start",
+        "b.calendar.validate: Task.start MUST be a LocalDateTime (RFC 8984 §6.4)");
+    }
+    if (jsCal.due !== undefined && (typeof jsCal.due !== "string" || !_isLocalDateTime(jsCal.due))) {
+      throw new CalendarError("calendar/bad-due",
+        "b.calendar.validate: Task.due MUST be a LocalDateTime (RFC 8984 §6.4.4)");
+    }
+    if (jsCal.estimatedDuration !== undefined &&
+        (typeof jsCal.estimatedDuration !== "string" || !_isDuration(jsCal.estimatedDuration))) {
+      throw new CalendarError("calendar/bad-duration",
+        "b.calendar.validate: Task.estimatedDuration MUST be an RFC 8601 PnYnMnDTnHnMnS Duration");
+    }
+    if (jsCal.progress !== undefined &&
+        !Object.prototype.hasOwnProperty.call(JSCAL_TASK_PROGRESS, jsCal.progress)) {
+      throw new CalendarError("calendar/bad-progress",
+        "b.calendar.validate: Task.progress MUST be one of " +
+        Object.keys(JSCAL_TASK_PROGRESS).join(" | ") + " (RFC 8984 §6.4.3)");
+    }
+    if (jsCal.percentComplete !== undefined) {
+      // RFC 8984 §6.4.4 specifies `UnsignedInt` (integer). RFC 5545
+      // §3.8.1.16 PERCENT-COMPLETE is also integer-typed. A float
+      // would emit as `PERCENT-COMPLETE:12.5` which strict parsers
+      // refuse.
+      if (typeof jsCal.percentComplete !== "number" || !isFinite(jsCal.percentComplete) ||
+          !Number.isInteger(jsCal.percentComplete) ||
+          jsCal.percentComplete < 0 || jsCal.percentComplete > 100) {                                  // allow:raw-byte-literal — RFC 8984 §6 percent range
+        throw new CalendarError("calendar/bad-percent",
+          "b.calendar.validate: Task.percentComplete MUST be an integer in 0..100 (RFC 8984 §6.4.4 UnsignedInt)");
+      }
+    }
+    if (jsCal.progressUpdated !== undefined &&
+        (typeof jsCal.progressUpdated !== "string" || !_isUtcDateTime(jsCal.progressUpdated))) {
+      throw new CalendarError("calendar/bad-progress-updated",
+        "b.calendar.validate: Task.progressUpdated MUST be a UTCDateTime");
+    }
+  }
   if (jsCal.recurrenceRules !== undefined) {
     if (!Array.isArray(jsCal.recurrenceRules)) {
       throw new CalendarError("calendar/bad-recurrence",
@@ -185,11 +235,13 @@ function validate(jsCal) {
 function fromIcal(text, opts) {
   var ast = safeIcal.parse(text, opts || {});
   var events = (ast && ast.vcalendar && ast.vcalendar.vevent) || [];
-  if (events.length === 0) {
-    throw new CalendarError("calendar/no-vevent",
-      "b.calendar.fromIcal: VCALENDAR has no VEVENT components");
+  var todos  = (ast && ast.vcalendar && ast.vcalendar.vtodo)  || [];
+  if (events.length === 0 && todos.length === 0) {
+    throw new CalendarError("calendar/no-component",
+      "b.calendar.fromIcal: VCALENDAR has no VEVENT or VTODO components");
   }
-  var converted = events.map(_veventToJsCalEvent);
+  var converted = events.map(_veventToJsCalEvent)
+    .concat(todos.map(_vtodoToJsCalTask));
   return converted.length === 1 ? converted[0] : converted;
 }
 
@@ -220,11 +272,16 @@ function fromIcal(text, opts) {
 function toIcal(jsCal, opts) {
   validate(jsCal);
   var prodid = (opts && opts.prodid) || "-//blamejs//Calendar//EN";
+  // RFC 8984 §6 — JSCalendar Task maps to RFC 5545 §3.6.2 VTODO; Event
+  // maps to VEVENT. The wrapper + most properties are identical; the
+  // wrapping component tag + Task-specific fields (DUE / STATUS /
+  // PERCENT-COMPLETE / COMPLETED) diverge.
+  var component = jsCal["@type"] === "Task" ? "VTODO" : "VEVENT";
   var lines = [
     "BEGIN:VCALENDAR",
     "VERSION:2.0",
     "PRODID:" + prodid,
-    "BEGIN:VEVENT",
+    "BEGIN:" + component,
     "UID:" + _foldLine(jsCal.uid),
     "DTSTAMP:" + _utcDateTimeToIcal(jsCal.updated),
   ];
@@ -244,7 +301,35 @@ function toIcal(jsCal, opts) {
       lines.push("DTSTART:" + dtStartIcal);
     }
   }
-  if (jsCal.duration) lines.push("DURATION:" + jsCal.duration);
+  // RFC 5545 §3.8.2.3 — DUE is Task-only; same TZID/UTC handling as DTSTART.
+  if (component === "VTODO" && jsCal.due) {
+    var dueIcal = _localDateTimeToIcal(jsCal.due);
+    if (jsCal.timeZone === "Etc/UTC" || jsCal.timeZone === "UTC") {
+      lines.push("DUE:" + dueIcal + "Z");
+    } else if (jsCal.timeZone) {
+      lines.push("DUE;TZID=" + jsCal.timeZone + ":" + dueIcal);
+    } else {
+      lines.push("DUE:" + dueIcal);
+    }
+  }
+  // RFC 8984 §6 — Task carries `estimatedDuration` (RFC 5545 DURATION).
+  // Event uses `duration`. Both map to the same iCalendar property.
+  var icalDuration = component === "VTODO"
+    ? (jsCal.estimatedDuration || jsCal.duration)
+    : jsCal.duration;
+  if (icalDuration) lines.push("DURATION:" + icalDuration);
+  // RFC 5545 §3.8.1.11 STATUS — Task progress maps directly; the four
+  // RFC 8984 §6.4.3 progress values (`needs-action` / `in-process` /
+  // `completed` / `cancelled`) are the same wire strings.
+  if (component === "VTODO" && jsCal.progress) {
+    lines.push("STATUS:" + String(jsCal.progress).toUpperCase());
+  }
+  if (component === "VTODO" && typeof jsCal.percentComplete === "number") {
+    lines.push("PERCENT-COMPLETE:" + jsCal.percentComplete);
+  }
+  if (component === "VTODO" && jsCal.progressUpdated) {
+    lines.push("COMPLETED:" + _utcDateTimeToIcal(jsCal.progressUpdated));
+  }
   if (Array.isArray(jsCal.locations) || (jsCal.locations && typeof jsCal.locations === "object")) {
     var locValues = Array.isArray(jsCal.locations) ? jsCal.locations : Object.values(jsCal.locations);
     for (var li = 0; li < locValues.length; li += 1) {
@@ -259,7 +344,7 @@ function toIcal(jsCal, opts) {
       lines.push("RRULE:" + _recurrenceRuleToIcal(jsCal.recurrenceRules[rri]));
     }
   }
-  lines.push("END:VEVENT", "END:VCALENDAR");
+  lines.push("END:" + component, "END:VCALENDAR");
   return lines.join("\r\n") + "\r\n";
 }
 
@@ -364,11 +449,100 @@ function expandRecurrence(event, opts) {
       if (isFinite(mdn) && mdn !== 0 && mdn >= -31 && mdn <= 31) byMonthDaySet[mdn] = true;            // allow:raw-byte-literal — calendar day-of-month bounds
     }
   }
+  // RFC 5545 §3.3.10 — BYWEEKNO refines yearly recurrences to specific
+  // ISO 8601 week numbers (1..53 or -1..-53). Implementation
+  // computes the ISO week of each candidate instance + compares.
+  var byWeekNoSet = null;
+  if (Array.isArray(rule.byWeekNo) && rule.byWeekNo.length > 0) {
+    byWeekNoSet = Object.create(null);
+    for (var wni = 0; wni < rule.byWeekNo.length; wni += 1) {
+      var wn = parseInt(rule.byWeekNo[wni], 10);
+      if (isFinite(wn) && wn !== 0 && wn >= -53 && wn <= 53) byWeekNoSet[wn] = true;                   // allow:raw-byte-literal — ISO 8601 week-number bounds
+    }
+  }
+  // BYYEARDAY — day-of-year (1..366 or -1..-366; negative counts from
+  // the end of the year per RFC 5545 §3.3.10).
+  var byYearDaySet = null;
+  if (Array.isArray(rule.byYearDay) && rule.byYearDay.length > 0) {
+    byYearDaySet = Object.create(null);
+    for (var ydi = 0; ydi < rule.byYearDay.length; ydi += 1) {
+      var yd = parseInt(rule.byYearDay[ydi], 10);
+      if (isFinite(yd) && yd !== 0 && yd >= -366 && yd <= 366) byYearDaySet[yd] = true;                // allow:raw-byte-literal — day-of-year bounds
+    }
+  }
+  // BYHOUR / BYMINUTE / BYSECOND — time-of-day filters. RFC 5545 §3.3.10
+  // bounds: hours 0..23, minutes 0..59, seconds 0..60 (60 covers
+  // POSIX leap-second representation).
+  function _bySet(arr, lo, hi) {
+    if (!Array.isArray(arr) || arr.length === 0) return null;
+    var s = Object.create(null);
+    var hasAny = false;
+    for (var i = 0; i < arr.length; i += 1) {
+      var n = parseInt(arr[i], 10);
+      if (isFinite(n) && n >= lo && n <= hi) { s[n] = true; hasAny = true; }
+    }
+    // Codex P2 — when every value in the BY* list is out of range,
+    // return null instead of an empty set. An empty truthy set would
+    // cause `_matchesBy` to reject every candidate (`!set[n]` is
+    // true) and silently turn malformed input into a "match nothing"
+    // rule. Returning null lets the rule fall through to the next
+    // unfiltered candidate per RFC 5545's tolerant grammar.
+    return hasAny ? s : null;
+  }
+  var byHourSet   = _bySet(rule.byHour,   0, 23);                                                      // allow:raw-byte-literal — RFC 5545 hour range
+  var byMinuteSet = _bySet(rule.byMinute, 0, 59);                                                      // allow:raw-byte-literal — RFC 5545 minute range
+  var bySecondSet = _bySet(rule.bySecond, 0, 60);                                                      // allow:raw-byte-literal — RFC 5545 second range incl. leap second // allow:raw-time-literal — second-of-minute bound, not a duration
+
+  function _isoWeekParts(d) {
+    // ISO 8601 week-of-year + week-year. The week-YEAR can differ
+    // from the Gregorian year for early-Jan / late-Dec boundary
+    // dates (e.g. 2021-01-01 is ISO week 53 of WEEK-YEAR 2020).
+    // Returns { week, year }.
+    var tmp = new Date(Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate()));
+    var dayOfWeek = tmp.getUTCDay() || 7;
+    tmp.setUTCDate(tmp.getUTCDate() + 4 - dayOfWeek);                                                  // allow:raw-byte-literal — ISO week-year anchor (Thursday)
+    var weekYear = tmp.getUTCFullYear();
+    var yearStart = new Date(Date.UTC(weekYear, 0, 1));
+    var week = Math.ceil((((tmp - yearStart) / 86400000) + 1) / 7);                                    // allow:raw-time-literal — 86400000 ms/day, 7 days/week // allow:raw-byte-literal
+    return { week: week, year: weekYear };
+  }
+  function _isoWeekOf(d) {
+    return _isoWeekParts(d).week;
+  }
+  function _yearDayOf(d) {
+    var startOfYear = new Date(Date.UTC(d.getUTCFullYear(), 0, 1));
+    return Math.floor((d - startOfYear) / 86400000) + 1;                                               // allow:raw-time-literal — 86400000 ms/day // allow:raw-byte-literal
+  }
+  function _daysInYear(year) {
+    return ((year % 4 === 0 && year % 100 !== 0) || year % 400 === 0) ? 366 : 365;                      // allow:raw-byte-literal — Gregorian leap-year rule
+  }
   function _matchesBy(t) {
     var d = new Date(t);
     if (byDaySet && !byDaySet[d.getUTCDay()]) return false;
     if (byMonthSet && !byMonthSet[d.getUTCMonth() + 1]) return false;
     if (byMonthDaySet && !byMonthDaySet[d.getUTCDate()]) return false;
+    if (byWeekNoSet) {
+      // Codex P1 — ISO week-year vs Gregorian year. 2021-01-01 is ISO
+      // week 53 of WEEK-YEAR 2020 (since 2021 only has 52 ISO weeks).
+      // Comparing only the numeric week would let a Jan 1 2021 date
+      // match a BYWEEKNO=53 rule whose implicit year is 2021. Refuse
+      // when the candidate's ISO week-year doesn't match the
+      // candidate's Gregorian year (the most common operator-intent
+      // alignment); operators with boundary-crossing rules opt in via
+      // a future explicit knob if demand surfaces.
+      var iso = _isoWeekParts(d);
+      if (iso.year !== d.getUTCFullYear()) return false;
+      var lastWeek = _isoWeekOf(new Date(Date.UTC(d.getUTCFullYear(), 11, 28)));                       // allow:raw-byte-literal — Dec 28 always in last ISO week
+      if (!byWeekNoSet[iso.week] && !byWeekNoSet[-(lastWeek - iso.week + 1)]) return false;
+    }
+    if (byYearDaySet) {
+      var yd = _yearDayOf(d);
+      var dayCount = _daysInYear(d.getUTCFullYear());
+      if (!byYearDaySet[yd] && !byYearDaySet[-(dayCount - yd + 1)]) return false;
+    }
+    if (byHourSet   && !byHourSet[d.getUTCHours()])     return false;
+    if (byMinuteSet && !byMinuteSet[d.getUTCMinutes()]) return false;
+    if (bySecondSet && !bySecondSet[d.getUTCSeconds()]) return false;
     return true;
   }
   var t = startMs;
@@ -432,6 +606,64 @@ function _veventToJsCalEvent(ve) {
   return jsCal;
 }
 
+// RFC 8984 §6 — JSCalendar Task. The VTODO mapping is structurally
+// similar to VEVENT but adds Task-specific properties:
+//   DUE       → due (LocalDateTime)
+//   STATUS    → progress ("needs-action"|"in-process"|"completed"|"cancelled")
+//   PERCENT-COMPLETE → percentComplete (0..100)
+//   COMPLETED → progressUpdated (UTCDateTime)
+function _vtodoToJsCalTask(vt) {
+  var props = (vt && vt.properties) || {};
+  var jsCal = {
+    "@type":  "Task",
+    uid:      _firstValue(props.UID) || "",
+    updated:  _icalDateTimeToUtc(_firstValue(props.DTSTAMP) || ""),
+  };
+  var summary = _firstValue(props.SUMMARY);
+  if (summary) jsCal.title = _unescapeText(summary);
+  var description = _firstValue(props.DESCRIPTION);
+  if (description) jsCal.description = _unescapeText(description);
+  var dtstart = _firstValue(props.DTSTART);
+  if (dtstart) jsCal.start = _icalDateTimeToLocal(dtstart);
+  var due = _firstValue(props.DUE);
+  if (due) jsCal.due = _icalDateTimeToLocal(due);
+  var duration = _firstValue(props.DURATION);
+  if (duration) jsCal.estimatedDuration = duration;
+  var tzid = _firstParamValue(props.DTSTART, "TZID") ||
+             _firstParamValue(props.DUE, "TZID");
+  if (tzid) {
+    jsCal.timeZone = tzid;
+  } else if ((typeof dtstart === "string" && /Z$/.test(dtstart)) ||
+             (typeof due === "string" && /Z$/.test(due))) {
+    jsCal.timeZone = "Etc/UTC";
+  }
+  var status = _firstValue(props.STATUS);
+  if (status) {
+    var statusLower = String(status).toLowerCase();
+    var statusMap = {
+      "needs-action": "needs-action",
+      "in-process":   "in-process",
+      "completed":    "completed",
+      "cancelled":    "cancelled",
+    };
+    if (statusMap[statusLower]) jsCal.progress = statusMap[statusLower];
+  }
+  var percent = _firstValue(props["PERCENT-COMPLETE"]);
+  if (percent !== null && percent !== undefined) {
+    var pn = parseInt(percent, 10);
+    if (isFinite(pn) && pn >= 0 && pn <= 100) jsCal.percentComplete = pn;                              // allow:raw-byte-literal — RFC 8984 §6 percent range
+  }
+  var completed = _firstValue(props.COMPLETED);
+  if (completed) jsCal.progressUpdated = _icalDateTimeToUtc(completed);
+  var location = _firstValue(props.LOCATION);
+  if (location) {
+    jsCal.locations = { L1: { "@type": "Location", name: _unescapeText(location) } };
+  }
+  var rrule2 = _firstValue(props.RRULE);
+  if (rrule2) jsCal.recurrenceRules = [_icalRruleToJscal(rrule2)];
+  return jsCal;
+}
+
 function _firstValue(prop) {
   if (!prop) return null;
   if (Array.isArray(prop)) {
@@ -576,6 +808,7 @@ module.exports = {
   JSCAL_TYPES:            JSCAL_TYPES,
   JSCAL_FREQUENCIES:      JSCAL_FREQUENCIES,
   JSCAL_ALERT_ACTIONS:    JSCAL_ALERT_ACTIONS,
+  JSCAL_TASK_PROGRESS:    JSCAL_TASK_PROGRESS,
   MAX_EXPAND_INSTANCES:   MAX_EXPAND_INSTANCES,
   MAX_EXPAND_SPAN_MS:     MAX_EXPAND_SPAN_MS,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.11.34",
+  "version": "0.11.36",
   "description": "The Node framework that owns its stack.",
   "license": "Apache-2.0",
   "author": "blamejs contributors",

package/sbom.cdx.json

@@ -2,10 +2,10 @@
   "$schema": "http://cyclonedx.org/schema/bom-1.5.schema.json",
   "bomFormat": "CycloneDX",
   "specVersion": "1.5",
-  "serialNumber": "urn:uuid:ae6b3d2c-59a3-48d1-ade0-1b48f59dfdef",
+  "serialNumber": "urn:uuid:7efc7160-930c-489d-ad69-8455a414189a",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-21T19:31:15.355Z",
+    "timestamp": "2026-05-21T21:48:29.730Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.11.34",
+      "bom-ref": "@blamejs/core@0.11.36",
       "type": "application",
       "name": "blamejs",
-      "version": "0.11.34",
+      "version": "0.11.36",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.11.34",
+      "purl": "pkg:npm/%40blamejs/core@0.11.36",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.11.34",
+      "ref": "@blamejs/core@0.11.36",
       "dependsOn": []
     }
   ]