@dybai/dsh-editor 0.4.0 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,6 +1,22 @@
1
1
  # @dybai/dsh-editor
2
2
 
3
- DSH Web 分栏的可扩展**编辑器框架**:让会话工作区里的文本文件可以就地编辑、保存(Ctrl+S),并把工具栏、状态栏、空态区、编辑区(模式)、状态快照、命令全部开放为稳定的第三方集成面。
3
+ **@dybai/dsh-editor** 让 DeepSeek Harness(DSH)工作区里的文本文件可以直接在对话旁就地编辑、保存(`Ctrl+S`)。DSH 原本只能只读预览工作区文件,想改就得跳出对话换外部工具;本插件补上「改文件」这一环:打开即编辑、保存写回磁盘,外部修改和误删都有保护。
4
+
5
+ 它同时是可扩展的**编辑器框架**:工具栏、状态栏、编辑模式、键位等全部开放给第三方插件,契约见 [docs/contracts.md](docs/contracts.md)。
6
+
7
+ ## 安装
8
+
9
+ 前置要求:DSH 引擎 `dsh >= 0.2.1-rc.5`;安装完成后浏览器 **Ctrl+F5** 刷新生效。
10
+
11
+ **插件市场(推荐)**:
12
+
13
+ 1. DSH 设置 → 插件 → 安装官方可选 bundle `@deepseek-ai/dsh-experimental-plugin-market-bundle`(实验性插件市场,提供 Discover 标签页);
14
+ 2. 在市场设置里**添加索引源**:`https://raw.githubusercontent.com/dybai/dsh-editor/main/market-index.json`;
15
+ 3. Discover 里找到「DSH 编辑器」→ 安装 → 刷新页面。
16
+
17
+ **npm 直接安装**:`plugin_manager` → `install_bundle`,spec 填 `@dybai/dsh-editor@0.4.0`(新版本号以 npm 页面或市场索引为准)。
18
+
19
+ **本地开发**:`install_bundle` 的目标为本仓库目录的绝对路径;开发循环见 [docs/deploy.zh-CN.md](docs/deploy.zh-CN.md) §3。
4
20
 
5
21
  ## 框架概述
6
22
 
@@ -14,7 +30,7 @@ DSH Web 分栏的可扩展**编辑器框架**:让会话工作区里的文本
14
30
 
15
31
  ## 快速开始
16
32
 
17
- **安装**:`plugin_manager` → `install_bundle`,目标为本目录的绝对路径(引擎要求 `dsh >= 0.2.1-rc.5`)。
33
+ **安装**:见上方[「安装」](#安装)章节(插件市场 / npm 包 / 本地目录三条渠道)。
18
34
 
19
35
  **打开**:
20
36
 
@@ -42,6 +58,12 @@ DSH Web 分栏的可扩展**编辑器框架**:让会话工作区里的文本
42
58
  - 设置面板新增「高亮光标所在行」开关(默认开,全局持久化,对所有已挂载编辑器立即生效);
43
59
  - 第三方模式可在描述符声明 `activeLine: true` 接入同一契约:经组件 prop `highlightActiveLine` 接收偏好、以快照 `selection.lineStart`/`lineEnd` 为高亮范围自行绘制(见 [docs/contracts.md](docs/contracts.md) §5.1 / §5.5)。
44
60
 
61
+ **行号列**(0.5.0):
62
+
63
+ - 编辑区内容左侧显示行号列:宽度随最大行号位数自适应(跨 100/1000 行等进位时自动加宽),随滚动、编辑、行导航实时同步;
64
+ - 设置面板新增「显示行号」开关(默认开,全局持久化,对所有已挂载编辑器立即生效)。开关只控制数字显隐:分界竖线与左侧预留带常驻,切换不会移动正文位置;
65
+ - 无描述符声明字段:`showLineNumbers` 偏好经组件 prop 直接送达到每个挂载的模式组件,第三方模式可自行接入(绘制行号列)或安全忽略(见 [docs/contracts.md](docs/contracts.md) §5.1 / §5.5)。
66
+
45
67
  ## 集成接口摘要
46
68
 
47
69
  | 契约面 | 入口 | 一句话 |
package/client.js CHANGED
@@ -920,6 +920,119 @@ window.__ModuleLoader__.load({
920
920
  return module.exports;
921
921
  })();
922
922
 
923
+ /* src/line-numbers.js */
924
+ const lineNumbers = (function () {
925
+ var module = { exports: {} };
926
+ var exports = module.exports;
927
+ /**
928
+ * Line-number gutter math — the pure model behind the editor's
929
+ * "show line numbers beside the content" affordance.
930
+ *
931
+ * Three functions, no DOM:
932
+ *
933
+ * - `lineNumbersText(lineCount)` — the gutter's whole content as ONE text
934
+ * block (`"1\n2\n…\nN"`), rendered into a pre-styled element whose
935
+ * line-height matches the textarea's. Valid only because the plain-text
936
+ * textarea never wraps (`wrap: 'off'` + `white-space: pre`), so logical
937
+ * line k sits exactly k lineHeights down — the same precondition as
938
+ * src/active-line.js.
939
+ * - `lineNumberDigits(lineCount)` — the widest number's digit count, clamped
940
+ * to the minimum 2-column gutter so a one-line file doesn't jump width.
941
+ * - `gutterWidthCh(lineCount)` — the gutter's total width in `ch` units
942
+ * (digits + the inter-column gap), the number the DOM layer applies to
943
+ * both the gutter element and the textarea's extra `padding-left`. `ch`
944
+ * is exact here: the editor area is monospace, so one ch is one digit.
945
+ *
946
+ * All three normalize defensively (floor fractional counts, clamp to ≥ 1,
947
+ * degrade invalid input to the one-line / two-column minimum) so the DOM
948
+ * layer can pipe untrusted values straight in — malformed input can never
949
+ * crash or shrink the editor.
950
+ *
951
+ * Zero imports: pure functions only, unit-testable without DOM.
952
+ *
953
+ * @module @dybai/dsh-editor/line-numbers
954
+ */
955
+
956
+ /** Gap between the numbers and the boundary rule, in `ch` units. MUST stay
957
+ * in sync with `.dsh-editor-gutter-text`'s `padding-right` (src/client-entry.js
958
+ * STYLES) — the CSS value positions the digits inside the gutter, this value
959
+ * places the rule. */
960
+ const GUTTER_GAP_CH = 1.5;
961
+
962
+ /** Gap between the boundary rule and the first content column, in `ch`
963
+ * units. The textarea's `padding-left` exceeds the gutter width by exactly
964
+ * this amount, so the content keeps its distance from the rule — and the
965
+ * opaque gutter covers the whole band, so horizontally-scrolled glyphs can
966
+ * never touch it. */
967
+ const CONTENT_GAP_CH = 2;
968
+
969
+ /** Minimum gutter columns so a short file keeps a stable width. */
970
+ const MIN_DIGITS = 2;
971
+
972
+ /**
973
+ * Normalize a line count into a usable integer (≥ 1); anything invalid
974
+ * degrades to 1.
975
+ * @param {any} lineCount - the caller's count (usually the draft's line total).
976
+ * @returns {number} a positive integer.
977
+ */
978
+ function normalizedLineCount(lineCount) {
979
+ const count = typeof lineCount === 'number' && Number.isFinite(lineCount) ? Math.floor(lineCount) : 1;
980
+ return count >= 1 ? count : 1;
981
+ }
982
+
983
+ /**
984
+ * The gutter's content: one number per line, 1 through N.
985
+ * @param {any} lineCount - the draft's line total (invalid degrades to 1).
986
+ * @returns {string} the text block for the pre-styled gutter element.
987
+ */
988
+ function lineNumbersText(lineCount) {
989
+ const count = normalizedLineCount(lineCount);
990
+ if (count === 1) return '1';
991
+ const numbers = new Array(count);
992
+ for (let index = 0; index < count; index += 1) numbers[index] = String(index + 1);
993
+ return numbers.join('\n');
994
+ }
995
+
996
+ /**
997
+ * The widest number's digit count, clamped to the two-column minimum.
998
+ * @param {any} lineCount - the draft's line total (invalid degrades to 1).
999
+ * @returns {number} columns, at least 2.
1000
+ */
1001
+ function lineNumberDigits(lineCount) {
1002
+ const count = normalizedLineCount(lineCount);
1003
+ return Math.max(MIN_DIGITS, String(count).length);
1004
+ }
1005
+
1006
+ /**
1007
+ * The gutter's width in `ch` units: the digit columns plus the
1008
+ * numbers-to-rule gap. The DOM layer places the boundary rule at this exact
1009
+ * offset inside the (wider) gutter band — the rule does NOT sit at the
1010
+ * band's right edge.
1011
+ * @param {any} lineCount - the draft's line total (invalid degrades to 1).
1012
+ * @returns {number} the width in ch units.
1013
+ */
1014
+ function gutterWidthCh(lineCount) {
1015
+ return lineNumberDigits(lineCount) + GUTTER_GAP_CH;
1016
+ }
1017
+
1018
+ /**
1019
+ * The whole reserved band's width in `ch` units — the textarea's matching
1020
+ * `padding-left`, and the gutter element's width: digit columns plus BOTH
1021
+ * gaps (numbers-to-rule and rule-to-content). Exceeding `gutterWidthCh` by
1022
+ * the rule-to-content gap is what keeps the content away from the rule; the
1023
+ * DOM layer applies this to BOTH the gutter element and the textarea so the
1024
+ * opaque band covers every pixel of the reservation.
1025
+ * @param {any} lineCount - the draft's line total (invalid degrades to 1).
1026
+ * @returns {number} the width in ch units.
1027
+ */
1028
+ function contentPaddingCh(lineCount) {
1029
+ return lineNumberDigits(lineCount) + GUTTER_GAP_CH + CONTENT_GAP_CH;
1030
+ }
1031
+
1032
+ Object.assign(module.exports, { lineNumbersText, lineNumberDigits, gutterWidthCh, contentPaddingCh });
1033
+ return module.exports;
1034
+ })();
1035
+
923
1036
  /* src/tab-machine.js */
924
1037
  const tabMachine = (function () {
925
1038
  var module = { exports: {} };
@@ -2000,6 +2113,7 @@ window.__ModuleLoader__.load({
2000
2113
  var exports = module.exports;
2001
2114
  const { basenameOf, isEditablePath, parseFileAddress } = address;
2002
2115
  const { activeLineBar, lineHeightPxOf } = activeLine;
2116
+ const { gutterWidthCh, contentPaddingCh, lineNumbersText } = lineNumbers;
2003
2117
  const { lineOfOffset, lineOfOffsetFast, caretOffsetOfSelection, offsetOfLine } = lines;
2004
2118
  const { createTabController } = tabMachine;
2005
2119
  const { createDiskWatch } = diskWatch;
@@ -2032,8 +2146,8 @@ window.__ModuleLoader__.load({
2032
2146
  * - `KeymapPopover` — the status-bar keyboard button's panel: record /
2033
2147
  * restore-default for the three self-managed bindings (spec §6).
2034
2148
  * - `SettingsPopover` — the status-bar gear button's panel: the behavior
2035
- * toggles (v0.3 `autoReloadClean`, v0.4 `highlightActiveLine`), persisted
2036
- * via `dshEditor/get|setSettings`.
2149
+ * toggles (v0.3 `autoReloadClean`, v0.4 `highlightActiveLine`, v0.5
2150
+ * `showLineNumbers`), persisted via `dshEditor/get|setSettings`.
2037
2151
  * - `EditorTabTitle` — the `sidebar.right.pane.tab.title` occupant: paints
2038
2152
  * the tab's file name red + strikethrough while the file is externally
2039
2153
  * deleted.
@@ -2247,7 +2361,7 @@ window.__ModuleLoader__.load({
2247
2361
 
2248
2362
  /**
2249
2363
  * The built-in `plain-text` mode: one controlled textarea over an
2250
- * active-line highlight backdrop.
2364
+ * active-line highlight backdrop and a line-number gutter.
2251
2365
  *
2252
2366
  * Obligations (spec §5.5): renders the draft, reports edits via
2253
2367
  * `controller.applyEdit` and selections via `controller.applySelection`
@@ -2268,10 +2382,29 @@ window.__ModuleLoader__.load({
2268
2382
  * the React effect fallback are the only other writers. The mark stays
2269
2383
  * visible without focus: it shows where the caret is, not where the
2270
2384
  * keyboard is.
2385
+ *
2386
+ * Line-number gutter (0.5.0, the `showLineNumbers` preference): an
2387
+ * absolutely-positioned band beside the content carrying a 1px gray hairline
2388
+ * (the boundary rule, ALWAYS painted) and — while the preference is on — ONE
2389
+ * text block (`1\n2\n…\nN`, src/line-numbers.js) whose line-height and top
2390
+ * padding match the textarea's (exact for the same no-wrap reason the
2391
+ * highlight is). Geometry, in exact `ch` of the shared monospace font:
2392
+ * [digits] --1.5ch--> [rule] --2ch--> [content]. The band spans the whole
2393
+ * reservation and the textarea's matching `padding-left` never changes with
2394
+ * the preference, so toggling shows/hides ONLY the numbers — the rule, the
2395
+ * band and the content position are constant. The band paints above BOTH
2396
+ * the highlight backdrop and the overlay textarea (z-index 2 vs 1 — with
2397
+ * wrap:'off' a horizontal scroll would otherwise sweep glyphs across it),
2398
+ * and ignores pointer events (clicks fall through to the textarea); the
2399
+ * text block follows vertical scroll by translating against `scrollTop` in
2400
+ * the same onScroll handler the highlight uses. Width tracks the widest
2401
+ * line number so crossing a power of ten reflows once, not per keystroke
2402
+ * (the text block memoizes on the line count).
2271
2403
  */
2272
2404
  function PlainTextMode(props) {
2273
2405
  const controller = props.controller;
2274
2406
  const highlightEnabled = props.highlightActiveLine !== false;
2407
+ const gutterEnabled = props.showLineNumbers !== false;
2275
2408
  const state = useControllerState(controller);
2276
2409
  // Attached to the textarea below — the single DOM handle every selection
2277
2410
  // path reads (reportSelection, onNavigate, the mirror effect, and the
@@ -2282,6 +2415,33 @@ window.__ModuleLoader__.load({
2282
2415
  const areaRef = React.useRef(null);
2283
2416
  const barRef = React.useRef(null);
2284
2417
  const metricsRef = React.useRef(null);
2418
+ // Gutter scroll sync: the inner text block translates against scrollTop.
2419
+ const gutterTextRef = React.useRef(null);
2420
+
2421
+ // The gutter's content and width, re-derived only when the line total
2422
+ // actually changes — typing within a line (the common keystroke) reuses
2423
+ // the memoized text block even on a 100k-line draft.
2424
+ // The reservation is CONSTANT: both widths derive from the line total
2425
+ // whether or not the gutter renders, and the textarea keeps its matching
2426
+ // padding-left either way — toggling the preference never shifts the
2427
+ // content sideways; only the numbers and the boundary rule appear/disappear.
2428
+ // Geometry: [digits] --1.5ch--> [rule] --2ch--> [content]; the gutter band
2429
+ // spans the WHOLE reservation (digits + both gaps) so its opaque
2430
+ // background also covers the rule-to-content strip against glyph sweeps.
2431
+ const lineCount = state.draft.length === 0 ? 1 : state.draft.split('\n').length;
2432
+ const gutterText = React.useMemo(() => (gutterEnabled ? lineNumbersText(lineCount) : ''), [gutterEnabled, lineCount]);
2433
+ const ruleOffset = gutterWidthCh(lineCount);
2434
+ const bandWidth = contentPaddingCh(lineCount);
2435
+
2436
+ // Vertical scroll sync for the gutter: translate the text block against
2437
+ // the textarea's scrollTop. Same trigger points as the highlight's scroll
2438
+ // handling — one onScroll handler drives both.
2439
+ const syncGutter = React.useCallback(() => {
2440
+ const area = areaRef.current;
2441
+ const text = gutterTextRef.current;
2442
+ if (area === null || text === null) return;
2443
+ text.style.transform = `translateY(${-area.scrollTop}px)`;
2444
+ }, []);
2285
2445
 
2286
2446
  // Measure the textarea's highlight geometry, at most once per rendered
2287
2447
  // mount. Every input is a computed value (rendering-independent — the
@@ -2378,11 +2538,17 @@ window.__ModuleLoader__.load({
2378
2538
  }, [controller, paintCaretLine]);
2379
2539
 
2380
2540
  // The latest sync for passive observers — the ResizeObserver below must
2381
- // not be torn down and rebuilt on every selection change.
2541
+ // not be torn down and rebuilt on every selection change. One sync for
2542
+ // both paint surfaces: the caret-line bar AND the gutter's scroll
2543
+ // translation (a hidden subtree can discard scrollTop without firing a
2544
+ // scroll event on re-show — the observer retry must heal the gutter too).
2382
2545
  const syncRef = React.useRef(paintCaretLine);
2383
2546
  React.useEffect(() => {
2384
- syncRef.current = paintCaretLine;
2385
- }, [paintCaretLine]);
2547
+ syncRef.current = () => {
2548
+ paintCaretLine();
2549
+ syncGutter();
2550
+ };
2551
+ }, [paintCaretLine, syncGutter]);
2386
2552
 
2387
2553
  // Reposition in the LAYOUT phase on mount/toggle only. Deliberately NOT
2388
2554
  // re-keyed on machine selection publishes: state.selection is normalized
@@ -2397,6 +2563,14 @@ window.__ModuleLoader__.load({
2397
2563
  paintCaretLine();
2398
2564
  }, [highlightEnabled, paintCaretLine]);
2399
2565
 
2566
+ // The gutter mounts (or re-mounts on toggle-on) against a possibly
2567
+ // already-scrolled textarea: land its transform on the CURRENT scrollTop
2568
+ // in the layout phase, before the first paint shows stale numbers.
2569
+ useLayoutEffectSafe(() => {
2570
+ if (!gutterEnabled) return;
2571
+ syncGutter();
2572
+ }, [gutterEnabled, syncGutter]);
2573
+
2400
2574
  // Size/visibility restoration: an editor mounted (or toggled on) inside a
2401
2575
  // hidden session subtree caches no metrics (the guard above), so the
2402
2576
  // observer fires the retry the moment the textarea gains a real box —
@@ -2404,13 +2578,13 @@ window.__ModuleLoader__.load({
2404
2578
  // observe() also dispatches an initial notification, doubling as a
2405
2579
  // post-layout resync on the very first mount.
2406
2580
  React.useEffect(() => {
2407
- if (!highlightEnabled) return undefined;
2581
+ if (!highlightEnabled && !gutterEnabled) return undefined;
2408
2582
  const area = areaRef.current;
2409
2583
  if (area === null || typeof ResizeObserver !== 'function') return undefined;
2410
2584
  const observer = new ResizeObserver(() => syncRef.current());
2411
2585
  observer.observe(area);
2412
2586
  return () => observer.disconnect();
2413
- }, [highlightEnabled]);
2587
+ }, [highlightEnabled, gutterEnabled]);
2414
2588
 
2415
2589
  // THE caret-follower: document-level `selectionchange` fires synchronously
2416
2590
  // with EVERY caret move — arrow keys included. The element-level events
@@ -2473,9 +2647,47 @@ window.__ModuleLoader__.load({
2473
2647
  h('div', { className: `${CLASS}-highlight-bar`, ref: barRef })
2474
2648
  )
2475
2649
  : null,
2650
+ // The band ALWAYS paints — opaque cover + boundary rule persist
2651
+ // regardless of the preference, so toggling shows/hides ONLY the
2652
+ // numbers and never moves the layout. The band paints above the
2653
+ // highlight backdrop AND the overlay textarea (z-index 2 vs 1) so
2654
+ // horizontally-scrolled glyphs cannot sweep across it; pointer-events
2655
+ // none keeps clicks falling through to the textarea's padding region.
2656
+ // The rule sits INSIDE the band at the digits+gap offset, so the
2657
+ // strip right of it stays covered background too.
2658
+ h(
2659
+ 'div',
2660
+ {
2661
+ className: `${CLASS}-gutter`,
2662
+ 'aria-hidden': true,
2663
+ style: { width: `${bandWidth}ch` }
2664
+ },
2665
+ h('div', {
2666
+ className: `${CLASS}-gutter-rule`,
2667
+ 'aria-hidden': true,
2668
+ style: { left: `${ruleOffset}ch` }
2669
+ }),
2670
+ gutterEnabled
2671
+ ? h(
2672
+ 'div',
2673
+ {
2674
+ className: `${CLASS}-gutter-text`,
2675
+ ref: gutterTextRef,
2676
+ // The digits' sub-band: border-box width = ruleOffset so
2677
+ // the CSS padding-right (1.5ch) sits INSIDE the box and
2678
+ // the right-aligned digits end exactly GUTTER_GAP_CH
2679
+ // left of the rule. (Content-box would push the digits'
2680
+ // right edge TO the rule — width + padding, not width.)
2681
+ style: { width: `${ruleOffset}ch`, boxSizing: 'border-box' }
2682
+ },
2683
+ gutterText
2684
+ )
2685
+ : null
2686
+ ),
2476
2687
  h('textarea', {
2477
2688
  ref: areaRef,
2478
2689
  className: highlightEnabled ? `${CLASS}-area ${CLASS}-area-overlay` : `${CLASS}-area`,
2690
+ style: { paddingLeft: `${bandWidth}ch` },
2479
2691
  value: state.draft,
2480
2692
  spellCheck: false,
2481
2693
  wrap: 'off',
@@ -2485,7 +2697,10 @@ window.__ModuleLoader__.load({
2485
2697
  onSelect: reportSelection,
2486
2698
  onClick: reportSelection,
2487
2699
  onKeyUp: reportSelection,
2488
- onScroll: paintCaretLine
2700
+ onScroll: () => {
2701
+ paintCaretLine();
2702
+ syncGutter();
2703
+ }
2489
2704
  })
2490
2705
  );
2491
2706
  }
@@ -2862,8 +3077,8 @@ window.__ModuleLoader__.load({
2862
3077
  * `dshEditor/get|setSettings` bridge (Host KV table `settings`, SHARED
2863
3078
  * `updatedAt` CAS token — a conflicting write refetches and surfaces the
2864
3079
  * retry notice, exactly like the keymap recorder). One row per known setting
2865
- * (`SETTINGS_ROWS`); the note line explains the one setting whose reach
2866
- * crosses modes.
3080
+ * (`SETTINGS_ROWS`); a row may carry its own explanatory note (`noteKey`,
3081
+ * rendered under it — currently the one setting whose reach crosses modes).
2867
3082
  */
2868
3083
 
2869
3084
  /** The popover's rows, in display order: setting key + locale stems. */
@@ -2872,7 +3087,13 @@ window.__ModuleLoader__.load({
2872
3087
  {
2873
3088
  key: 'highlightActiveLine',
2874
3089
  labelKey: 'settings.highlightActiveLine',
2875
- titleKey: 'settings.highlightActiveLineTitle'
3090
+ titleKey: 'settings.highlightActiveLineTitle',
3091
+ noteKey: 'settings.highlightActiveLineNote'
3092
+ },
3093
+ {
3094
+ key: 'showLineNumbers',
3095
+ labelKey: 'settings.showLineNumbers',
3096
+ titleKey: 'settings.showLineNumbersTitle'
2876
3097
  }
2877
3098
  ];
2878
3099
 
@@ -2937,31 +3158,32 @@ window.__ModuleLoader__.load({
2937
3158
  : `${t('settings.writeFailed')}: ${error.message}`
2938
3159
  )
2939
3160
  : null,
2940
- SETTINGS_ROWS.map((row) => {
3161
+ SETTINGS_ROWS.flatMap((row) => {
2941
3162
  const on = settings[row.key] === true;
2942
- return h(
2943
- 'div',
2944
- { key: row.key, className: `${CLASS}-settings-row` },
2945
- h('span', { className: `${CLASS}-settings-label`, title: t(row.titleKey) }, t(row.labelKey)),
3163
+ const cells = [
2946
3164
  h(
2947
- 'button',
2948
- {
2949
- className: `${CLASS}-settings-toggle${on ? ' on' : ''}`,
2950
- type: 'button',
2951
- disabled: busy,
2952
- title: t(row.titleKey),
2953
- 'aria-pressed': on ? 'true' : 'false',
2954
- onClick: () => runToggle(row.key, on)
2955
- },
2956
- on ? t('settings.on') : t('settings.off')
3165
+ 'div',
3166
+ { key: row.key, className: `${CLASS}-settings-row` },
3167
+ h('span', { className: `${CLASS}-settings-label`, title: t(row.titleKey) }, t(row.labelKey)),
3168
+ h(
3169
+ 'button',
3170
+ {
3171
+ className: `${CLASS}-settings-toggle${on ? ' on' : ''}`,
3172
+ type: 'button',
3173
+ disabled: busy,
3174
+ title: t(row.titleKey),
3175
+ 'aria-pressed': on ? 'true' : 'false',
3176
+ onClick: () => runToggle(row.key, on)
3177
+ },
3178
+ on ? t('settings.on') : t('settings.off')
3179
+ )
2957
3180
  )
2958
- );
2959
- }),
2960
- h(
2961
- 'div',
2962
- { key: 'note', className: `${CLASS}-settings-note` },
2963
- t('settings.highlightActiveLineNote')
2964
- )
3181
+ ];
3182
+ if (typeof row.noteKey === 'string') {
3183
+ cells.push(h('div', { key: `${row.key}-note`, className: `${CLASS}-settings-note` }, t(row.noteKey)));
3184
+ }
3185
+ return cells;
3186
+ })
2965
3187
  );
2966
3188
  }
2967
3189
 
@@ -3465,7 +3687,10 @@ window.__ModuleLoader__.load({
3465
3687
  // handed to every mounted mode; modes that declared
3466
3688
  // `activeLine` (contracts §5.1) draw the highlight, others
3467
3689
  // ignore the prop harmlessly.
3468
- highlightActiveLine: runtime.getSettings().highlightActiveLine !== false
3690
+ highlightActiveLine: runtime.getSettings().highlightActiveLine !== false,
3691
+ // The line-numbers contract (0.5.0): same shape, same reach —
3692
+ // modes honoring the preference draw the gutter, others ignore.
3693
+ showLineNumbers: runtime.getSettings().showLineNumbers !== false
3469
3694
  })
3470
3695
  ];
3471
3696
  }
@@ -3747,6 +3972,10 @@ window.__ModuleLoader__.load({
3747
3972
  * off). Modes honoring the active-line contract (descriptor `activeLine`,
3748
3973
  * contracts §5.1) read the same preference via their `highlightActiveLine`
3749
3974
  * component prop.
3975
+ * - `showLineNumbers` — render the line-number gutter beside the content
3976
+ * (default `true`: a presentation affordance, on unless the user turns it
3977
+ * off). Modes honoring the line-numbers contract (contracts §5.1) read the
3978
+ * same preference via their `showLineNumbers` component prop.
3750
3979
  *
3751
3980
  * `normalizeSettings` accepts the wire payload `{ [name]: boolean }` (the
3752
3981
  * Host reports only stored settings) and merges it over the defaults.
@@ -3760,14 +3989,14 @@ window.__ModuleLoader__.load({
3760
3989
  */
3761
3990
 
3762
3991
  /** Setting names this build knows (mirrors the Host validator's allow-list). */
3763
- const SETTINGS_KEYS = ['autoReloadClean', 'highlightActiveLine'];
3992
+ const SETTINGS_KEYS = ['autoReloadClean', 'highlightActiveLine', 'showLineNumbers'];
3764
3993
 
3765
3994
  /**
3766
3995
  * The built-in settings: behavior opt-ins off, presentation defaults on.
3767
3996
  * @returns a fresh settings object (callers may mutate their copy).
3768
3997
  */
3769
3998
  function defaultSettings() {
3770
- return { autoReloadClean: false, highlightActiveLine: true };
3999
+ return { autoReloadClean: false, highlightActiveLine: true, showLineNumbers: true };
3771
4000
  }
3772
4001
 
3773
4002
  /**
@@ -3831,7 +4060,8 @@ window.__ModuleLoader__.load({
3831
4060
  * refetched on every menu open), the self-managed keymap cache, the
3832
4061
  * behavior settings cache (read by every tab machine at notice time and
3833
4062
  * by the mode components at render time — the active-line highlight
3834
- * preference, 0.4.0), and per-tab disk watches (Host
4063
+ * preference, 0.4.0, and the line-number gutter preference, 0.5.0), and
4064
+ * per-tab disk watches (Host
3835
4065
  * `workspaceFiles/changes` push; manual `stat` fallback swept on
3836
4066
  * focus/visibility);
3837
4067
  * 8. the one remaining shortcuts command (`dshEditor.modeMenu`, unbound);
@@ -3851,7 +4081,7 @@ window.__ModuleLoader__.load({
3851
4081
  const NS = 'dshEditor';
3852
4082
  const EDITOR_KIND = 'editor';
3853
4083
  const SERVICE_KEY = 'dshEditor';
3854
- const VERSION = '0.4.0';
4084
+ const VERSION = '0.5.0';
3855
4085
  const STYLE_ID = 'dsh-editor-styles';
3856
4086
 
3857
4087
  /* ---------------------------------------------------------- locale -- */
@@ -3925,6 +4155,8 @@ window.__ModuleLoader__.load({
3925
4155
  'settings.highlightActiveLine': '高亮光标所在行',
3926
4156
  'settings.highlightActiveLineTitle': '在光标(或选区触及)的行背后绘制高亮色带',
3927
4157
  'settings.highlightActiveLineNote': '内置纯文本模式始终支持;其他编辑模式可经描述符 activeLine 声明遵循同一开关。',
4158
+ 'settings.showLineNumbers': '显示行号',
4159
+ 'settings.showLineNumbersTitle': '在内容左侧显示行号列',
3928
4160
  'settings.on': '开',
3929
4161
  'settings.off': '关',
3930
4162
  'settings.writeFailed': '保存设置失败',
@@ -4003,6 +4235,8 @@ window.__ModuleLoader__.load({
4003
4235
  'settings.highlightActiveLine': 'Highlight active line',
4004
4236
  'settings.highlightActiveLineTitle': 'Draw a highlight band behind the caret line (or every line the selection touches)',
4005
4237
  'settings.highlightActiveLineNote': 'The built-in plain-text mode always honors this; other editor modes may declare support via their descriptor.',
4238
+ 'settings.showLineNumbers': 'Show line numbers',
4239
+ 'settings.showLineNumbersTitle': 'Draw the line-number column beside the content',
4006
4240
  'settings.on': 'On',
4007
4241
  'settings.off': 'Off',
4008
4242
  'settings.writeFailed': 'Failed to save settings',
@@ -4100,6 +4334,31 @@ window.__ModuleLoader__.load({
4100
4334
  .dsh-editor-settings-toggle:disabled { opacity: 0.45; cursor: default; }
4101
4335
  .dsh-editor-settings-note { padding: 4px 6px 2px; font-size: 11px; color: var(--dsw-alias-label-secondary); opacity: 0.8; }
4102
4336
  .dsh-editor-settings-error { padding: 6px; font-size: 11px; color: var(--dsw-alias-state-error-primary); overflow: hidden; text-overflow: ellipsis; }
4337
+ /* Line-number gutter (0.5.0): the MONO 13px font lives on the container so
4338
+ * its inline 'ch' widths (src/line-numbers.js) resolve in the SAME font as
4339
+ * the textarea's matching 'padding-left' — a sans-inherited ch clips the
4340
+ * numbers' leading digits. font-size / line-height / padding-top stay
4341
+ * identical to .dsh-editor-area's (13px / 1.5 / 10px) so number k sits
4342
+ * exactly k lines down, same precondition as the highlight backdrop.
4343
+ * z-index 2 paints ABOVE the overlay textarea (z-index 1): with wrap:'off'
4344
+ * a horizontal scroll sweeps glyphs across the padding band and the opaque
4345
+ * gutter must cover them; pointer-events:none keeps clicks falling through
4346
+ * to the textarea (tradeoff: it also covers the scrollbar's left strip).
4347
+ * Geometry: the band spans digits + 1.5 + 2 (ch); the rule
4348
+ * (.dsh-editor-gutter-rule) sits INSIDE the band at digits + 1.5 — the 2ch
4349
+ * right of the rule is covered background keeping the content away from it.
4350
+ * -gutter-text's inline width equals that same rule offset (the digits'
4351
+ * sub-band): right-aligned inside it with the 1.5ch padding-right below
4352
+ * (= GUTTER_GAP_CH, src/line-numbers.js), the widest number ends exactly
4353
+ * 1.5ch left of the rule. CONTENT_GAP_CH (2ch) has no CSS twin — it exists
4354
+ * only as band width minus rule offset.
4355
+ * The RESERVATION is constant: the textarea keeps its padding-left and the
4356
+ * rule and band ALWAYS paint — toggling the preference shows/hides only the
4357
+ * numbers, never moving content or the boundary.
4358
+ * The text block translates against scrollTop at the DOM layer. */
4359
+ .dsh-editor-gutter { position: absolute; left: 0; top: 0; bottom: 0; z-index: 2; overflow: hidden; background: var(--dsw-alias-bg-base); pointer-events: none; font-family: var(--dsw-font-mono, ui-monospace, monospace); font-size: 13px; line-height: 1.5; }
4360
+ .dsh-editor-gutter-rule { position: absolute; top: 0; bottom: 0; width: 1px; background: var(--dsw-alias-border-l1); }
4361
+ .dsh-editor-gutter-text { padding: 10px 1.5ch 0 0; text-align: right; white-space: pre; color: var(--dsw-alias-label-secondary); opacity: 0.8; }
4103
4362
  `;
4104
4363
 
4105
4364
  /**
@@ -72,7 +72,7 @@ const KEYMAP_TABLE = 'keymap';
72
72
  const SETTINGS_TABLE = 'settings';
73
73
 
74
74
  /** Setting names this build knows; unknown keys in a payload are rejected. */
75
- const SETTINGS_KEYS = new Set(['autoReloadClean', 'highlightActiveLine']);
75
+ const SETTINGS_KEYS = new Set(['autoReloadClean', 'highlightActiveLine', 'showLineNumbers']);
76
76
 
77
77
  /** Keymap action ids the editor framework owns (spec §6). */
78
78
  const KEYMAP_ACTIONS = new Set(['save', 'saveAll', 'deleteLines']);
package/locale/en.json CHANGED
@@ -85,6 +85,8 @@
85
85
  "highlightActiveLine": "Highlight active line",
86
86
  "highlightActiveLineTitle": "Draw a highlight band behind the caret line (or every line the selection touches)",
87
87
  "highlightActiveLineNote": "The built-in plain-text mode always honors this; other editor modes may declare support via their descriptor.",
88
+ "showLineNumbers": "Show line numbers",
89
+ "showLineNumbersTitle": "Draw the line-number column beside the content",
88
90
  "on": "On",
89
91
  "off": "Off",
90
92
  "writeFailed": "Failed to save settings",
package/locale/zh.json CHANGED
@@ -85,6 +85,8 @@
85
85
  "highlightActiveLine": "高亮光标所在行",
86
86
  "highlightActiveLineTitle": "在光标(或选区触及)的行背后绘制高亮色带",
87
87
  "highlightActiveLineNote": "内置纯文本模式始终支持;其他编辑模式可经描述符 activeLine 声明遵循同一开关。",
88
+ "showLineNumbers": "显示行号",
89
+ "showLineNumbersTitle": "在内容左侧显示行号列",
88
90
  "on": "开",
89
91
  "off": "关",
90
92
  "writeFailed": "保存设置失败",
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@dybai/dsh-editor",
3
- "version": "0.4.0",
3
+ "version": "0.5.0",
4
4
  "type": "module",
5
5
  "scripts": {
6
6
  "test": "node --test src/**/*.test.js host/**/*.test.js",