@kidli1412/dsh-token-heatmap 0.1.6 → 0.4.2

package/lib/config.js

@@ -2,8 +2,12 @@
  * dsh-token-heatmap — config model.
  *
  * Pure validation/coercion for the plugin's user-facing settings:
- *   enabled      — master switch for the hero-screen heatmap card (default true)
  *   colorScheme  — cell palette name (default "green")
+ *   defaultView  — view the card opens with: "year" | "month" (default "year")
+ *
+ * The 0.1.x `enabled` master switch was dropped in 0.2.0 (the card is always
+ * rendered on the hero screen); a stored `enabled` key is ignored and never
+ * rewritten.
  *
  * The server half persists the raw JSON document under
  * `<DSH_HOME>/storages/token-heatmap-config.json` and serves it over the
@@ -16,16 +20,21 @@
  * server still running older code; the client renders any unknown scheme with
  * its green fallback. The server bounds only the SHAPE (a short non-blank
  * string) so a foreign or hand-edited document still degrades to sane values.
+ * `defaultView` IS bounded to the known modes: an unknown mode has no
+ * renderer to fall back to.
  *
  * @module dsh-token-heatmap/config
  */
 
 /** Default configuration (also what a corrupt or absent document resolves to). */
-export const DEFAULT_CONFIG = Object.freeze({ enabled: true, colorScheme: "green" });
+export const DEFAULT_CONFIG = Object.freeze({ colorScheme: "green", defaultView: "year" });
 
 /** Canonical color schemes, in display order (informational; not enforced). */
 export const COLOR_SCHEMES = Object.freeze(["green", "blue", "orange", "red", "purple", "teal"]);
 
+/** Canonical view modes, in display order. */
+export const VIEW_MODES = Object.freeze(["year", "month"]);
+
 /** Upper bound on a stored scheme name; anything longer is treated as junk. */
 const SCHEME_MAX_LENGTH = 32;
 
@@ -38,17 +47,21 @@ function isPlainObject(value) {
  * Validate and coerce one raw config document into the canonical shape.
  * Unknown fields are dropped; missing or invalid fields fall back to the
  * default. `colorScheme` is preserved verbatim (any short non-blank string),
- * so a newer client's scheme survives an older server between restarts.
+ * so a newer client's scheme survives an older server between restarts;
+ * `defaultView` is coerced to a known mode instead, and the retired `enabled`
+ * key is ignored.
  * @param raw - parsed JSON document, or undefined for an absent file.
  * @returns the canonical config.
  */
 export function parseConfig(raw) {
 	const config = { ...DEFAULT_CONFIG };
 	if (!isPlainObject(raw)) return config;
-	if (typeof raw.enabled === "boolean") config.enabled = raw.enabled;
 	if (typeof raw.colorScheme === "string") {
 		const scheme = raw.colorScheme.trim();
 		if (scheme.length > 0 && scheme.length <= SCHEME_MAX_LENGTH) config.colorScheme = scheme;
 	}
+	if (typeof raw.defaultView === "string" && VIEW_MODES.includes(raw.defaultView.trim())) {
+		config.defaultView = raw.defaultView.trim();
+	}
 	return config;
 }

package/lib/index.js

@@ -36,7 +36,7 @@ import { homedir } from "node:os";
 import { join, dirname } from "node:path";
 import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
 import { applyUsageDelta, createUsageState, mergeInto, renderUsage, zeroBuckets } from "./usage.js";
-import { DEFAULT_CONFIG, parseConfig } from "./config.js";
+import { DEFAULT_CONFIG, VIEW_MODES, parseConfig } from "./config.js";
 import z from "@deepseek-ai/schemastery";
 
 /** Stable Cordis plugin name. */
@@ -66,17 +66,26 @@ const SETTINGS_NAMESPACE = "token-heatmap";
  * validates against. Scheme membership is deliberately NOT enforced (a newer
  * client may know a palette the server does not — the client falls back to
  * green); only the same shape bounds parseConfig applies: a short, non-blank
- * string.
+ * string. `defaultView` is bounded to the rendered view modes (year/month).
+ *
+ * The 0.1.x `enabled` master switch is gone: the card is always rendered on
+ * the hero screen, so the field is neither accepted nor served (an old
+ * settings.yaml keeps its dead `enabled` key, and nothing reads it).
  */
 const TokenHeatmapSettingsSchema = z.object({
-	enabled: z.boolean().default(true),
-	colorScheme: z.string().min(1).max(32).default("green")
+	colorScheme: z.string().min(1).max(32).default("green"),
+	defaultView: z.union(VIEW_MODES.map((mode) => z.const(mode))).default("year")
 });
 //#endregion
 
 const USAGE_PATH = "/api/token-heatmap/usage";
 const CONFIG_PATH = "/api/token-heatmap/config";
-const CACHE_VERSION = 1;
+/**
+ * Cache format version. 2 folds every session from its fork cut (see
+ * `forkCutOf`): a version-1 cache may hold a forked child's inherited prefix —
+ * the parent's tokens, already folded under the parent — so it is rebuilt.
+ */
+const CACHE_VERSION = 2;
 
 /** Write a JSON response. */
 function json(res, status, value) {
@@ -198,6 +207,7 @@ function serializeSession(state) {
 	return {
 		kind: state.kind ?? "persisted",
 		consumed: state.consumed ?? 0,
+		...(state.skipUntil === void 0 || state.skipUntil === 0 ? {} : { skipUntil: state.skipUntil }),
 		...(state.revision === void 0 ? {} : { revision: state.revision }),
 		days,
 		lastSample: state.lastSample === null ? null : {
@@ -216,6 +226,9 @@ function parseSession(raw) {
 	if (raw === null || typeof raw !== "object") return state;
 	state.kind = typeof raw.kind === "string" ? raw.kind : "persisted";
 	state.consumed = Number.isSafeInteger(raw.consumed) ? raw.consumed : 0;
+	// Missing in a hand-edited or legacy entry: 0 means "no fork cut known",
+	// which only re-folds the inherited prefix once, on the next pass.
+	state.skipUntil = Number.isSafeInteger(raw.skipUntil) && raw.skipUntil > 0 ? raw.skipUntil : 0;
 	if (typeof raw.revision === "string") state.revision = raw.revision;
 	if (raw.days !== null && typeof raw.days === "object") {
 		for (const [date, entry] of Object.entries(raw.days)) {
@@ -346,8 +359,10 @@ async function migrateLegacyConfig(ctx) {
 		const userExists = descriptor !== void 0 && descriptor.user !== void 0;
 		if (!userExists) {
 			const patch = {};
-			if (legacy.enabled !== DEFAULT_CONFIG.enabled) patch.enabled = legacy.enabled;
+			// The legacy document's `enabled` switch died with 0.2.0: import only
+			// what the card still owns.
 			if (legacy.colorScheme !== DEFAULT_CONFIG.colorScheme) patch.colorScheme = legacy.colorScheme;
+			if (legacy.defaultView !== DEFAULT_CONFIG.defaultView) patch.defaultView = legacy.defaultView;
 			if (Object.keys(patch).length > 0) await ctx.settings.update(SETTINGS_NAMESPACE, patch);
 		}
 		await rm(path, { force: true });
@@ -356,10 +371,17 @@ async function migrateLegacyConfig(ctx) {
 	}
 }
 
-/** Serve the resolved settings section (schema defaults + user layer). */
+/**
+ * Serve the resolved settings section (schema defaults + user layer).
+ * `enabled` stays in the payload as a constant true: the legacy loopback
+ * endpoint is a back-compat API, and a pre-0.2.0 client that reads it must not
+ * lose the card over a switch this version no longer has.
+ */
 function serveConfig(ctx) {
 	const section = ctx.settings.get(SETTINGS_NAMESPACE);
-	return { enabled: section?.enabled !== false, colorScheme: typeof section?.colorScheme === "string" && section.colorScheme.length > 0 ? section.colorScheme : DEFAULT_CONFIG.colorScheme };
+	const scheme = typeof section?.colorScheme === "string" && section.colorScheme.length > 0 ? section.colorScheme : DEFAULT_CONFIG.colorScheme;
+	const view = typeof section?.defaultView === "string" && VIEW_MODES.includes(section.defaultView) ? section.defaultView : DEFAULT_CONFIG.defaultView;
+	return { enabled: true, colorScheme: scheme, defaultView: view };
 }
 
 async function handleConfig(ctx, req, res) {
@@ -414,6 +436,60 @@ function liveSessionEvents(session, from) {
 	return { count: session.seq, events };
 }
 
+/**
+ * Fork-inherited prefix length of a live session: the number of leading
+ * events copied from its parent at fork time. Those events carry the PARENT's
+ * usage and are folded when the parent is folded, so a seeded child must skip
+ * them or the same tokens are counted twice (measured 2026-09-14: 13.15e8
+ * instead of 8.34e8).
+ *
+ * `header.isSeeded` marks fork lineage and `inheritedEventCount` is the exact
+ * cut (both are official Session state on 0.1.2+, the cut is what
+ * `Session.ownEvents()` starts from). `isSeeded` alone is NOT enough: a
+ * resumed session also carries a constructor seed, but that seed is its OWN
+ * history and must be folded in full.
+ * @returns the inherited prefix length, or 0 when the session is not a fork.
+ */
+function forkCutOf(session) {
+	if (session === null || typeof session !== "object") return 0;
+	if (session.header?.isSeeded !== true) return 0;
+	const inherited = session.inheritedEventCount;
+	return typeof inherited === "number" && Number.isSafeInteger(inherited) && inherited > 0 ? inherited : 0;
+}
+
+/**
+ * Fork-inherited prefix length read from a STORED event log. DSH projects the
+ * in-process `inheritedEventCount` into the log as the LAST `session/end-seed`
+ * event carrying `{ inherited: true }` (an UNMARKED `session/end-seed` is a
+ * compaction boundary, not a fork cut), so that event's seq + 1 is the cut.
+ * This mirrors `dsh-session-format-v2-to-v3`, which derives the restored cut
+ * from that same marker.
+ * @returns the inherited prefix length, or 0 when the log carries no fork cut.
+ */
+function forkCutOfEvents(events) {
+	let cut = 0;
+	for (const event of events) {
+		if (event?.type === "session/end-seed" && event.data?.inherited === true && typeof event.seq === "number") {
+			cut = Math.max(cut, event.seq + 1);
+		}
+	}
+	return cut;
+}
+
+/** First seq a session's fold may read: its fork cut, never past its cursor. */
+function liveFoldFrom(consumed, cut) {
+	return Math.max(consumed, cut);
+}
+
+/** Drop a session's folded days so the next fold starts at its fork cut. */
+function resetFold(state, cut) {
+	state.days = new Map();
+	state.lastSample = null;
+	state.currentModel = null;
+	state.consumed = 0;
+	state.skipUntil = cut;
+}
+
 /**
  * Read one stored session's events from `fromSeq` onward, across the two
  * `sessionPersistence` generations this plugin declares compatibility with:
@@ -458,6 +534,12 @@ async function readSessionEvents(persistence, id, fromSeq) {
  * this plugin was first adapted to) cannot be read at all: its already-folded
  * days are kept untouched and the session/event listener covers everything
  * appended from now on.
+ *
+ * FORKED sessions (`header.isSeeded`) start their log with a copy of the
+ * parent's events. That prefix belongs to the parent and is folded there, so
+ * both the live and the stored path fold from the session's fork cut
+ * (`skipUntil`) instead of seq 0; discovering or moving a cut refolds the
+ * session from it.
  */
 export async function collectUsage(ctx) {
 	return withLock(async () => {
@@ -473,15 +555,16 @@ export async function collectUsage(ctx) {
 			for (const session of live.list()) {
 				attached.add(session.id);
 				const state = cache.sessions[session.id] ?? createUsageState();
-				if (state.kind !== "live") {
-					// Live/persisted transition: refold the whole in-memory log.
-					state.days = new Map();
-					state.lastSample = null;
-					state.currentModel = null;
-					state.consumed = 0;
+				const cut = forkCutOf(session);
+				if (state.kind !== "live" || (state.skipUntil ?? 0) !== cut) {
+					// Live/persisted transition, or the fork cut was (re)discovered:
+					// refold from the cut. The inherited prefix stays folded under
+					// the parent, so starting at the cut avoids double counting it.
+					resetFold(state, cut);
 				}
-				const { count, events } = liveSessionEvents(session, state.consumed ?? 0);
-				if ((state.consumed ?? 0) < count) {
+				const from = liveFoldFrom(state.consumed ?? 0, cut);
+				const { count, events } = liveSessionEvents(session, from);
+				if (from < count) {
 					applyUsageDelta(state, events);
 					state.consumed = count;
 				}
@@ -537,23 +620,33 @@ export async function collectUsage(ctx) {
 							state.currentModel = null;
 							state.consumed = 0;
 						}
+						// Fork-inherited prefix: discovered from the log on the first
+						// read, reused from the cache afterwards (both read paths yield
+						// the whole log, so the marker is always in view).
+						const cut = wasPersisted ? (state.skipUntil ?? 0) : forkCutOfEvents(events);
+						const start = Math.max(fromSeq, cut);
+						if (!wasPersisted || start !== fromSeq) resetFold(state, cut);
 						// `consumed` is the seq of the last folded event; both read paths
 						// yield events carrying their own seq, so the delta filter and the
 						// contiguity check below stay index-agnostic.
-						const fresh = wasPersisted ? events.filter((event) => event.seq > (state.consumed ?? 0)) : events;
-						const contiguous = fresh.length === 0 ? state.consumed === 0 : fresh[0].seq === state.consumed + 1;
-						if (!contiguous && state.consumed > 0) {
-							// Log truncated or rewritten: refold the whole log.
-							state.days = new Map();
-							state.lastSample = null;
-							state.currentModel = null;
-							state.consumed = 0;
-							applyUsageDelta(state, events);
-							state.consumed = events.length > 0 ? events[events.length - 1].seq : 0;
+						const fresh = events.filter((event) => typeof event.seq === "number" && event.seq >= Math.max(state.consumed ?? 0, cut));
+						const contiguous = fresh.length === 0
+							? (state.consumed ?? 0) <= cut
+							: fresh[0].seq === (state.consumed ?? 0) + 1 || fresh[0].seq === cut;
+						if (!contiguous && (state.consumed ?? 0) > cut) {
+							// Log truncated or rewritten: refold the whole log from the cut.
+							resetFold(state, cut);
+							const { events: allEvents } = await readSessionEvents(persistence, meta.id, cut) ?? { events: [] };
+							const owned = allEvents.filter((event) => typeof event.seq === "number" && event.seq >= cut);
+							applyUsageDelta(state, owned);
+							state.consumed = owned.length > 0 ? owned[owned.length - 1].seq : cut;
 						} else if (fresh.length > 0) {
 							applyUsageDelta(state, fresh);
 							state.consumed = fresh[fresh.length - 1].seq;
+						} else {
+							state.consumed = Math.max(state.consumed ?? 0, cut);
 						}
+						state.skipUntil = cut;
 						state.kind = "persisted";
 						if (revision !== void 0) state.revision = revision;
 					} catch (error) {
@@ -621,8 +714,14 @@ function apply(ctx) {
 			loadCache().then((cache) => {
 				if (disposed) return;
 				const state = cache.sessions[session.id] ?? createUsageState();
+				const cut = forkCutOf(session);
+				if ((state.skipUntil ?? 0) !== cut) state.skipUntil = cut;
 				const seq = typeof event.seq === "number" ? event.seq : void 0;
-				if (seq !== void 0 && seq < (state.consumed ?? 0)) return;
+				// Constructor seeds (a fork's inherited prefix, or a resume's own
+				// stored log) are never published here, so a live event at or after
+				// the cut is the only thing this feed carries; the guard keeps a
+				// stray replay of the parent's prefix from re-counting it.
+				if (seq !== void 0 && seq < liveFoldFrom(state.consumed ?? 0, cut)) return;
 				applyUsageDelta(state, [event]);
 				if (seq !== void 0) state.consumed = Math.max(state.consumed ?? 0, seq + 1);
 				state.kind = "live";
@@ -653,14 +752,11 @@ function apply(ctx) {
 			for (const session of sessions.list()) {
 				if (disposed) return;
 				const state = cache.sessions[session.id] ?? createUsageState();
-				if (state.kind !== "live") {
-					state.days = new Map();
-					state.lastSample = null;
-					state.currentModel = null;
-					state.consumed = 0;
-				}
-				const { count, events } = liveSessionEvents(session, state.consumed ?? 0);
-				if ((state.consumed ?? 0) < count) {
+				const cut = forkCutOf(session);
+				if (state.kind !== "live" || (state.skipUntil ?? 0) !== cut) resetFold(state, cut);
+				const from = liveFoldFrom(state.consumed ?? 0, cut);
+				const { count, events } = liveSessionEvents(session, from);
+				if (from < count) {
 					applyUsageDelta(state, events);
 					state.consumed = count;
 				}

package/lib/usage.js

@@ -131,14 +131,18 @@ function entryOf(byDay, day) {
  * One session's incremental fold state. `days` holds the already-folded
  * per-day entries; `lastSample`/`currentModel` let a later event slice keep
  * the replace-last-sample semantics and model attribution across fold
- * boundaries without replaying the whole log.
+ * boundaries without replaying the whole log. `skipUntil` is the session's
+ * fork-inherited prefix length — the events before it are the fork PARENT's
+ * usage, folded when the parent is folded, so folding starts there and the
+ * same tokens are never counted twice. 0 for a session that is not a fork.
  */
 export function createUsageState() {
 	return {
 		days: new Map(),
 		lastSample: null,
 		currentModel: null,
-		consumed: 0
+		consumed: 0,
+		skipUntil: 0
 	};
 }
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@kidli1412/dsh-token-heatmap",
-  "version": "0.1.6",
-  "description": "DSH web plugin: GitHub-style daily token-usage heatmap on the new-session screen with a selectable calendar-year view, green/blue color schemes and a display switch (设置 → 插件 → 插件配置), plus today / this-month / all-time totals.",
+  "version": "0.4.2",
+  "description": "DSH web plugin: GitHub-style daily token-usage heatmap on the new-session screen with switchable year/month views and six color schemes. The card configures itself through a floating ⚙ panel (palette + default view) — no DSH settings card — and shows today / this-month / all-time totals.",
   "type": "module",
   "main": "lib/index.js",
   "exports": {