Turn any idea, plan, or codebase into a beautiful interactive diagram. An agent skill for Claude Code, Codex, and more.
HTML agent-skillsai-agentsarchitecture-diagramclaude-codeclaude-skillscodexcoding-agentsdeepseek-harnessdeveloper-toolsdiagramsdiagrams-as-codedsh-pluginflowchartllmmermaidopencodesequence-diagramsoftware-architecturesystem-designvisualization
fix(timeline): align ticks across timezone offset changes
To3akaRin3872418b27d8
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 73100ee9..f88605c2 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -12,6 +12,7 @@ All notable changes are documented here. Format loosely follows [Keep a Changelo### Fixed+- **Timeline 时区刻度(#926)。** 刻度按显示时区在各真实时刻的 UTC 偏移对齐,修复跨夏令时后日刻度漂移到 01:00/23:00、半小时跳变后小时刻度漂移的问题。回拨的重复时刻保持独立,跳过的小时或日期不生成虚构刻度;事件时间、标签精度、时间轴比例与断轴规则保持不变。- **WebM 录制失败清理 (#622)。** 画布、捕获流、编码器启动、逐帧绘制或停止失败时,录制 Promise 现在会拒绝并释放已创建的流、临时 URL、动画帧和定时器;晚到的编码事件不能再将失败录制报告为成功。正常编码与最佳努力的最终片段 flush 行为保持不变。- **类图混合关系的主干冲突(#791)。** 自动继承/实现主干会检查组外路线的端口、走廊和交叉;冲突组回退到独立路由,避免依赖箭头被继承三角覆盖或实线覆盖实现虚线。无冲突主干、显式几何及关系语义保持不变;空 `via: []` 与省略路径点统一处理,避免合法输入在回退后产生非法斜线。diff --git a/archify.zip b/archify.zipindex 00baeb4d..c6cfd9cd 100644Binary files a/archify.zip and b/archify.zip differdiff --git a/archify/renderers/timeline/README.md b/archify/renderers/timeline/README.mdindex 392996b0..893a4b31 100644--- a/archify/renderers/timeline/README.md+++ b/archify/renderers/timeline/README.md@@ -26,6 +26,10 @@ events (with their millisecond timestamps and x positions) instead of HTML.- `meta.timezone` is an IANA zone (default `UTC`) used for every tick and label;ticks fall on that zone's wall clock, so a `+05:30` zone ticks on its ownhours. An unknown zone fails `timeline/invalid-timezone`.+- 夏令时和时区调整不会把刻度固定在时间段起点的 UTC 偏移上:日刻度保持当地+ 午夜,小时刻度仅对应真实存在的当地时刻。回拨产生的两个相同墙钟时刻都保留;+ 跳过的小时或整天不补造刻度。事件时间与轴上的实际时间距离不变,因此相邻+ 日刻度之间可以是 23 或 25 小时;空间不足的刻度文字仍按原有规则隐藏。- `meta.evidence` (`observed` or `illustrative`) is required and drawn as abadge at the top-left of the canvas.- With `lanes`, every event names a declared lane (`timeline/unknown-lane`).diff --git a/archify/renderers/timeline/render-timeline.mjs b/archify/renderers/timeline/render-timeline.mjsindex 89999856..fc1925cd 100644--- a/archify/renderers/timeline/render-timeline.mjs+++ b/archify/renderers/timeline/render-timeline.mjs@@ -256,6 +256,24 @@ function xOf(time) {// on its own whole hours.const TICKS = [1000, 2000, 5000, 10_000, 15_000, 30_000, MINUTE, 2 * MINUTE, 5 * MINUTE, 10 * MINUTE, 15 * MINUTE, 30 * MINUTE,HOUR, 2 * HOUR, 3 * HOUR, 6 * HOUR, 12 * HOUR, DAY, 2 * DAY, 7 * DAY];++function wallClockTicks(start, end, interval) {+ // 日探测只收集时区偏移,不把一天当成固定长度的当地日历日。+ // 即使时间段两端的偏移相同,也不能漏掉段内先进入、再退出的夏令时。+ const offsets = new Set([zoneOffset(start), zoneOffset(end)]);+ for (let probe = start + DAY; probe < end; probe += DAY) offsets.add(zoneOffset(probe));+ const candidates = new Set();+ for (const offset of offsets) {+ const firstTick = Math.ceil((start + offset) / interval) * interval - offset;+ for (let t = firstTick; t <= end; t += interval) {+ // 同一个墙钟时刻可能对应两个真实瞬间,也可能不存在。按实际偏移回查,+ // 保留回拨小时的两个刻度,并排除跳时或跳日期产生的虚构时刻。+ if (offsets.size === 1 || zoneOffset(t) === offset) candidates.add(t);+ }+ }+ return [...candidates].sort((left, right) => left - right);+}+const ticks = [];for (const segment of segments) {const length = segment.end - segment.start;@@ -264,10 +282,8 @@ for (const segment of segments) {continue;}const interval = TICKS.find((candidate) => candidate * scale >= layout.minTickPx) ?? TICKS.at(-1);- const offset = zoneOffset(segment.start);- let t = Math.ceil((segment.start + offset) / interval) * interval - offset;const before = ticks.length;- for (; t <= segment.end; t += interval) ticks.push({ t, x: xOf(t), interval });+ for (const t of wallClockTicks(segment.start, segment.end, interval)) ticks.push({ t, x: xOf(t), interval });// A segment too short for a regular tick still states where it starts.if (ticks.length === before) ticks.push({ t: segment.start, x: segment.x0, interval });}diff --git a/test/timeline-dst-ticks.test.mjs b/test/timeline-dst-ticks.test.mjsnew file mode 100644index 00000000..6fa22c40--- /dev/null+++ b/test/timeline-dst-ticks.test.mjs@@ -0,0 +1,142 @@+import { test } from 'node:test';+import assert from 'node:assert/strict';+import fs from 'node:fs';+import os from 'node:os';+import path from 'node:path';+import { spawnSync } from 'node:child_process';+import { fileURLToPath } from 'node:url';++const cli = fileURLToPath(new URL('../archify/bin/archify.mjs', import.meta.url));+const renderer = fileURLToPath(new URL('../archify/renderers/timeline/render-timeline.mjs', import.meta.url));+const hour = 60 * 60 * 1000;++function fixture(timezone, first, last, width = 480) {+ return {+ schema_version: 1, diagram_type: 'timeline',+ meta: { title: 'Recorded local calendar boundaries', evidence: 'observed', timezone },+ layout: { width, breaks: 'none' },+ events: [+ { id: 'start', at: first, title: 'Start' },+ { id: 'end', at: last, title: 'End' },+ ],+ };+}++function run(t, document) {+ const directory = fs.mkdtempSync(path.join(os.tmpdir(), 'archify-timeline-dst-'));+ t.after(() => fs.rmSync(directory, { recursive: true, force: true }));+ const input = path.join(directory, 'input.timeline.json');+ const output = path.join(directory, 'output.html');+ const original = JSON.stringify(document);+ fs.writeFileSync(input, original);+ const command = (args) => {+ const result = spawnSync(process.execPath, args, {+ encoding: 'utf8', timeout: 15_000,+ env: { ...process.env, ARCHIFY_UPDATE_CHECK_DISABLED: '1' },+ });+ assert.equal(result.status, 0, `${result.error || ''}\n${result.stdout}\n${result.stderr}`);+ return result.stdout;+ };+ const report = JSON.parse(command([renderer, input, output, '--layout-json']));+ command([cli, 'render', 'timeline', input, output]);+ assert.equal(fs.readFileSync(input, 'utf8'), original, '时区刻度不能改写作者时间或布局要求');+ const svg = fs.readFileSync(output, 'utf8').match(/<svg\b[\s\S]*?<\/svg>/)[0];+ const labels = [...svg.matchAll(/<text\b[^>]*\btl-tick\b[^>]*>([^<]*)<\/text>/g)].map((match) => match[1]);+ const times = report.ticks.map(({ t: instant }) => instant);+ assert.ok(times.every((instant, index) => Number.isFinite(instant) && (!index || instant > times[index - 1])),+ '每个刻度必须对应唯一、递增的真实时刻');+ const expectedEvents = document.events.map(({ at }) => Date.parse(at)).sort((a, b) => a - b);+ assert.deepEqual(report.events.map(({ t: instant }) => instant), expectedEvents, '事件的绝对时间不能随刻度修复移动');+ for (const tick of report.ticks) {+ const segment = report.segments.find(({ start, end }) => tick.t >= start && tick.t <= end);+ assert.ok(segment, '刻度只能落在真实时间段内');+ if (segment.start !== segment.end) {+ const expected = segment.x0 + (tick.t - segment.start) / (segment.end - segment.start) * (segment.x1 - segment.x0);+ assert.ok(Math.abs(tick.x - expected) <= 0.011, '刻度位置仍按实际流逝时间线性计算');+ }+ }+ return { report, svg, labels, command, input };+}++for (const scenario of [+ {+ name: 'spring forward', first: '2026-03-07T00:00:00-05:00', last: '2026-03-10T00:00:00-04:00',+ expected: ['2026-03-07T00:00:00-05:00', '2026-03-08T00:00:00-05:00', '2026-03-09T00:00:00-04:00', '2026-03-10T00:00:00-04:00'],+ elapsed: [24, 23, 24],+ },+ {+ name: 'fall back', first: '2026-10-31T00:00:00-04:00', last: '2026-11-03T00:00:00-05:00',+ expected: ['2026-10-31T00:00:00-04:00', '2026-11-01T00:00:00-04:00', '2026-11-02T00:00:00-05:00', '2026-11-03T00:00:00-05:00'],+ elapsed: [24, 25, 24],+ },+]) {+ test(`timeline: daily local ticks survive ${scenario.name} without moving the time axis`, (t) => {+ const { report, labels, command, input } = run(t, fixture('America/New_York', scenario.first, scenario.last));+ assert.deepEqual(report.ticks.map(({ t: instant }) => instant), scenario.expected.map(Date.parse));+ assert.deepEqual(report.ticks.slice(1).map((tick, index) => (tick.t - report.ticks[index].t) / hour), scenario.elapsed);+ assert.ok(labels.length >= 2);+ assert.ok(labels.every((label) => label.endsWith('00:00')), labels.join(' | '));+ assert.equal(JSON.parse(command([cli, 'validate', 'timeline', input, '--quality', 'showcase', '--json'])).ok, true);+ });+}++for (const scenario of [+ {+ name: 'skips the nonexistent spring hour', timezone: 'America/New_York', width: 600,+ expected: ['2026-03-08T00:00:00-05:00', '2026-03-08T01:00:00-05:00', '2026-03-08T03:00:00-04:00', '2026-03-08T04:00:00-04:00', '2026-03-08T05:00:00-04:00'],+ labels: ['00:00', '01:00', '03:00', '04:00', '05:00'],+ },+ {+ name: 'retains both real occurrences of the repeated fall hour', timezone: 'America/New_York', width: 600,+ expected: ['2026-11-01T00:00:00-04:00', '2026-11-01T01:00:00-04:00', '2026-11-01T01:00:00-05:00', '2026-11-01T02:00:00-05:00', '2026-11-01T03:00:00-05:00'],+ labels: ['00:00', '01:00', '01:00', '02:00', '03:00'],+ },+ {+ name: 'aligns whole hours across the Lord Howe half-hour jump', timezone: 'Australia/Lord_Howe', width: 640,+ expected: ['2026-10-04T00:00:00+10:30', '2026-10-04T01:00:00+10:30', '2026-10-04T03:00:00+11:00', '2026-10-04T04:00:00+11:00', '2026-10-04T05:00:00+11:00'],+ labels: ['00:00', '01:00', '03:00', '04:00', '05:00'],+ },+]) {+ test(`timeline: hourly ticks ${scenario.name}`, (t) => {+ const { report, labels, svg } = run(t, fixture(scenario.timezone, scenario.expected[0], scenario.expected.at(-1), scenario.width));+ assert.deepEqual(report.ticks.map(({ t: instant }) => instant), scenario.expected.map(Date.parse));+ assert.deepEqual(labels, scenario.labels);+ if (scenario.name.includes('repeated')) {+ assert.match(svg, /data-node-id="start"[^>]*UTC-04:00/);+ assert.match(svg, /data-node-id="end"[^>]*UTC-05:00/);+ }+ });+}++test('timeline: a skipped civil date in Apia does not invent or duplicate an instant', (t) => {+ const expected = ['2011-12-28T00:00:00-10:00', '2011-12-29T00:00:00-10:00', '2011-12-31T00:00:00+14:00', '2012-01-01T00:00:00+14:00'];+ const { report, labels } = run(t, fixture('Pacific/Apia', expected[0], expected.at(-1)));+ assert.deepEqual(report.ticks.map(({ t: instant }) => instant), expected.map(Date.parse));+ assert.ok(labels.every((label) => !label.includes('12-30')), labels.join(' | '));+});++test('timeline: equal endpoint offsets do not hide the daylight-saving season inside a long segment', (t) => {+ const timezone = 'America/New_York';+ const { report } = run(t, fixture(timezone, '2026-01-01T00:00:00-05:00', '2026-12-31T00:00:00-05:00'));+ const local = new Intl.DateTimeFormat('en-GB', { timeZone: timezone, hour: '2-digit', minute: '2-digit', hourCycle: 'h23' });+ assert.ok(report.ticks.length > 2);+ assert.ok(report.ticks.every(({ t: instant }) => local.format(instant) === '00:00'));+ assert.deepEqual(new Set(report.ticks.map(({ t: instant }) => new Date(instant).getUTCHours())), new Set([4, 5]),+ '冬夏两个偏移都必须参与真实刻度生成');+});++test('timeline: a short segment keeps its start tick and automatic breaks retain real local dates', (t) => {+ const single = fixture('America/New_York', '2026-11-01T01:30:00-05:00', '2026-11-01T01:30:00-05:00');+ const short = run(t, single).report;+ assert.deepEqual(short.ticks.map(({ t: instant }) => instant), [Date.parse(single.events[0].at)]);+ const document = fixture('America/New_York', '2026-03-06T00:00:00-05:00', '2026-05-12T00:00:00-04:00', 960);+ document.layout.breaks = 'auto';+ document.events = [+ '2026-03-06T00:00:00-05:00', '2026-03-07T00:00:00-05:00', '2026-03-09T00:00:00-04:00',+ '2026-03-12T00:00:00-04:00', '2026-05-11T00:00:00-04:00', '2026-05-12T00:00:00-04:00',+ ].map((at, index) => ({ id: `event_${index}`, at, title: `Event ${index}` }));+ const { report } = run(t, document);+ assert.ok(report.breaks.length > 0);+ const clock = new Intl.DateTimeFormat('en-GB', { timeZone: document.meta.timezone, hour: '2-digit', minute: '2-digit', hourCycle: 'h23' });+ assert.ok(report.ticks.every(({ t: instant }) => clock.format(instant) === '00:00'), '压缩段内仍使用真实的当地午夜');+});