@vinena/knobs 0.6.6 → 0.7.1

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.
Files changed (116) hide show
  1. package/CHANGELOG.md +26 -0
  2. package/README.md +13 -7
  3. package/THIRD_PARTY_NOTICES.md +3 -3
  4. package/dist/cli.d.ts +95 -0
  5. package/dist/cli.js +527 -0
  6. package/dist/{context-eawqn680.js → context-2r76ext7.js} +3 -3
  7. package/dist/{context-vd2xep5t.js → context-h1bdt8w3.js} +3 -3
  8. package/dist/early.global.js +7 -8
  9. package/dist/edit/html.d.ts +7 -3
  10. package/dist/edit/keep.d.ts +2 -2
  11. package/dist/{elementsview-n26sp8m7.js → elementsview-mcg6d5zp.js} +21 -19
  12. package/dist/{elementsview-dpm0xmb2.js → elementsview-mwr1s17z.js} +21 -19
  13. package/dist/engine/bezels.d.ts +2 -2
  14. package/dist/engine/check.d.ts +2 -2
  15. package/dist/engine/describe.d.ts +2 -2
  16. package/dist/engine/devices.d.ts +3 -3
  17. package/dist/engine/fit.d.ts +4 -4
  18. package/dist/engine/foldhand.d.ts +2 -2
  19. package/dist/engine/frame.d.ts +6 -6
  20. package/dist/engine/frames.d.ts +4 -4
  21. package/dist/engine/fresh.d.ts +12 -5
  22. package/dist/engine/header.d.ts +3 -1
  23. package/dist/engine/identity.d.ts +4 -4
  24. package/dist/engine/index.d.ts +7 -7
  25. package/dist/engine/locale.d.ts +2 -2
  26. package/dist/engine/morph.d.ts +2 -2
  27. package/dist/engine/native.d.ts +8 -8
  28. package/dist/engine/placeholder.d.ts +3 -3
  29. package/dist/engine/reload.d.ts +2 -2
  30. package/dist/engine/screen.d.ts +2 -2
  31. package/dist/engine/scrollkeep.d.ts +1 -1
  32. package/dist/engine/store.d.ts +11 -11
  33. package/dist/engine/storekeys.d.ts +34 -0
  34. package/dist/engine/style.d.ts +1 -1
  35. package/dist/engine/tabicon.d.ts +2 -2
  36. package/dist/engine/underneath.d.ts +1 -0
  37. package/dist/engine/width.d.ts +3 -3
  38. package/dist/{framekit-0as9t6a7.js → framekit-4v7nc3ea.js} +25 -20
  39. package/dist/{framekit-dknq662p.js → framekit-wyppj1se.js} +25 -20
  40. package/dist/grab/clipboard.d.ts +2 -0
  41. package/dist/{index-jfv7vavj.js → index-311fys81.js} +93 -29
  42. package/dist/index-3dcgysws.js +77 -0
  43. package/dist/{index-7vb2ct4s.js → index-3s4v7gw5.js} +11 -10
  44. package/dist/{index-ztnjefrh.js → index-585hs9tp.js} +5 -1
  45. package/dist/{index-za4ppxay.js → index-6t0w5s7p.js} +1 -1
  46. package/dist/{index-r1rdj05c.js → index-82y8x8vv.js} +14 -11
  47. package/dist/{index-dxga6h10.js → index-9targr2f.js} +26 -16
  48. package/dist/{index-x3sxssbs.js → index-a23nv5j4.js} +65 -45
  49. package/dist/{index-t4kssacm.js → index-abwqw8jh.js} +6 -1
  50. package/dist/{index-s6yzsvs4.js → index-bgzyc7rz.js} +22 -15
  51. package/dist/{index-t4wrs2a3.js → index-c1t6knbf.js} +20 -14
  52. package/dist/{index-7w0nm76e.js → index-cqymjce4.js} +20 -14
  53. package/dist/{index-69fvtkcm.js → index-dvtbh3c8.js} +24 -18
  54. package/dist/{index-ajs4na3f.js → index-k4w5v53q.js} +2 -2
  55. package/dist/{index-df35z48z.js → index-n31pn4ax.js} +20 -16
  56. package/dist/{index-ymqm185m.js → index-rps0bdq9.js} +1 -1
  57. package/dist/{index-a8ffw5ft.js → index-szd9bddn.js} +1 -1
  58. package/dist/{index-whehz74d.js → index-vhda420r.js} +32 -6
  59. package/dist/{index-xs29b55n.js → index-vmprrfwe.js} +5 -2
  60. package/dist/{index-20bc9yrj.js → index-vmz7htwn.js} +1 -1
  61. package/dist/index.d.ts +14 -8
  62. package/dist/index.global.js +176 -159
  63. package/dist/index.js +108 -43
  64. package/dist/instance.d.ts +7 -1
  65. package/dist/mark.d.ts +50 -0
  66. package/dist/{react-msn10fjb.js → react-4ezjf7mq.js} +24 -18
  67. package/dist/react-4qn9vsjw.js +78 -0
  68. package/dist/{react-73reavv4.js → react-4tcwpama.js} +1 -1
  69. package/dist/{react-k4pkm1p5.js → react-7eyps0cg.js} +2 -2
  70. package/dist/{react-10r2rczp.js → react-7tzwahsm.js} +14 -11
  71. package/dist/{react-yx3g9k55.js → react-amvrbng8.js} +5 -2
  72. package/dist/{react-5rq7bnsy.js → react-atw9y8ny.js} +5 -1
  73. package/dist/{react-4phtr2nd.js → react-dg4bjv3j.js} +1 -1
  74. package/dist/{react-vbk58f9m.js → react-hdneb4v3.js} +32 -6
  75. package/dist/{react-h9w04skh.js → react-j87bdhhe.js} +4 -1
  76. package/dist/{react-wtgvkf6g.js → react-mkafgzqf.js} +1 -1
  77. package/dist/{react-a1r0nr0g.js → react-ppyj3fg2.js} +65 -45
  78. package/dist/{react-0r5418av.js → react-rbmk30xk.js} +92 -29
  79. package/dist/{react-y9gr8yt2.js → react-rxw73n04.js} +1 -1
  80. package/dist/{react-5h7pxnax.js → react-tet7swk2.js} +22 -15
  81. package/dist/{react-5ekfj7g3.js → react-w94cfn87.js} +20 -16
  82. package/dist/{react-v08ywmtw.js → react-wzd3cfg8.js} +11 -10
  83. package/dist/{react-2b7725je.js → react-x209et38.js} +26 -16
  84. package/dist/react.d.ts +3 -1
  85. package/dist/react.js +111 -44
  86. package/dist/{replay-ehgxp9py.js → replay-3xqgt3xg.js} +8 -8
  87. package/dist/{replay-461gcdh1.js → replay-48gn27bj.js} +8 -8
  88. package/dist/storage/onload.d.ts +1 -1
  89. package/dist/{storageview-5p1y11b5.js → storageview-2rvwk0v7.js} +20 -17
  90. package/dist/{storageview-kxzpnfvr.js → storageview-6vq7nz02.js} +20 -17
  91. package/dist/styles/force.d.ts +3 -1
  92. package/dist/types.d.ts +4 -4
  93. package/dist/ui/actions.d.ts +3 -3
  94. package/dist/ui/bindings.d.ts +1 -1
  95. package/dist/ui/catalog.d.ts +14 -14
  96. package/dist/ui/changes.d.ts +1 -1
  97. package/dist/ui/colors.d.ts +1 -1
  98. package/dist/ui/deviceknobs.d.ts +2 -2
  99. package/dist/ui/editors.d.ts +3 -3
  100. package/dist/ui/foldslider.d.ts +2 -2
  101. package/dist/ui/icons.d.ts +5 -2
  102. package/dist/ui/keys.d.ts +1 -1
  103. package/dist/ui/list.d.ts +10 -10
  104. package/dist/ui/palette.d.ts +2 -2
  105. package/dist/ui/panel.d.ts +2 -0
  106. package/dist/ui/pin.d.ts +2 -2
  107. package/dist/ui/prefs.d.ts +1 -1
  108. package/dist/ui/rows.d.ts +3 -3
  109. package/dist/ui/settings.d.ts +11 -1
  110. package/dist/ui/storageview.d.ts +2 -2
  111. package/dist/ui/stylesview.d.ts +3 -3
  112. package/dist/ui/swatches.d.ts +2 -2
  113. package/package.json +5 -2
  114. package/skills/{devknobs → knobs}/SKILL.md +52 -51
  115. package/dist/index-5tv6sr74.js +0 -23
  116. package/dist/react-t2qnewz2.js +0 -24
@@ -1,51 +1,52 @@
1
1
  ---
2
- name: devknobs
3
- description: Test a web page under different conditions with devknobs and fix what breaks. Use when an agent needs to check a page in dark mode, with reduced motion or more contrast, in another locale or right to left, with larger text, offline or on a slow connection, on another device or width, in another time zone or at another time, and then find and fix the code behind anything that looks wrong.
2
+ name: knobs
3
+ description: Test a web page under different conditions with knobs and fix what breaks. Use when an agent needs to check a page in dark mode, with reduced motion or more contrast, in another locale or right to left, with larger text, offline or on a slow connection, on another device or width, in another time zone or at another time, and then find and fix the code behind anything that looks wrong.
4
4
  ---
5
5
 
6
- # devknobs
6
+ # knobs
7
7
 
8
- devknobs is a dev panel that emulates browser conditions from inside the page.
8
+ knobs is a dev panel that emulates browser conditions from inside the page.
9
9
  You drive it from any browser tool that can run JavaScript in the page:
10
10
  Playwright `page.evaluate`, Chrome DevTools MCP `evaluate_script`, or similar.
11
11
 
12
12
  ## Before you start
13
13
 
14
- devknobs must be installed in the app. See the install section of the
15
- devknobs README (`node_modules/@vinena/knobs/README.md`).
14
+ knobs must be installed in the app. See the install section of the
15
+ knobs README (`node_modules/@vinena/knobs/README.md`).
16
16
 
17
- Check that devknobs is mounted:
17
+ Check that knobs is mounted:
18
18
 
19
19
  ```js
20
- await window.devknobs.ready();
20
+ await window.knobs.ready();
21
21
  ```
22
22
 
23
- Every way of mounting devknobs puts the api on `window.devknobs`: the script
24
- tag, `mount()` and `<DevKnobs />`. Inside the width knob's frame the frame's own
25
- copy has it too. If `window.devknobs` is undefined, devknobs is not on this
26
- page. The script tag build keeps the api after `unmount()`, so the api alone
23
+ Every way of mounting knobs puts the api on `window.knobs`: the script
24
+ tag, `mount()` and `<Knobs />`. Inside the width knob's frame the frame's own
25
+ copy has it too. If neither `window.knobs` nor `window.devknobs` is set, knobs is not on this
26
+ page. Where `window.knobs` is not knobs' api (the page has a `knobs` of its own, or knobs is older than 0.7.1, such as an extension not yet on 0.7.1), use `window.devknobs`, which every copy sets. The script tag build keeps the api after `unmount()`, so the api alone
27
27
  does not prove a mount. `ready()` does: it rejects at once with
28
- `devknobs: not mounted` when nothing is mounted.
28
+ `knobs: not mounted` when nothing is mounted.
29
29
 
30
30
  Then note the panel as the user left it. Keep the result in your notes, as a
31
31
  later evaluate or a reload loses page variables:
32
32
 
33
33
  ```js
34
- JSON.stringify(window.devknobs.getState().panel);
34
+ JSON.stringify(window.knobs.getState().panel);
35
35
  ```
36
36
 
37
37
  This note comes from the tab's `sessionStorage`, so it is the user's layout
38
38
  only in a fresh tab. In a tab an earlier agent may have used, also read
39
39
  `localStorage.getItem("devknobs:place")`. It holds the place the user last
40
40
  gave the panel (`side`, `y`, `top`, `edge`, `tab`, `docked`). Use those fields
41
- over the ones in the note.
41
+ over the ones in the note. knobs 0.7.1 writes `knobs:place` too, with the same value. A later
42
+ release reads `knobs:place` instead.
42
43
 
43
44
  ## Learn the knobs
44
45
 
45
46
  Call `describe()` first. Never guess a key or a value.
46
47
 
47
48
  ```js
48
- window.devknobs.describe();
49
+ window.knobs.describe();
49
50
  ```
50
51
 
51
52
  It returns one entry per knob:
@@ -68,18 +69,18 @@ as `grabColor` and the panel's place. Do not compare the two key for key.
68
69
 
69
70
  1. Call `setState(patch)`. It is sync and returns the new state.
70
71
  A wrong key or value throws a TypeError, and then nothing changes:
71
- `devknobs: unknown knob <key>[.<field>]` or
72
- `devknobs: bad value for <key>[.<field>]: <value>`. Fix the patch from
72
+ `knobs: unknown knob <key>[.<field>]` or
73
+ `knobs: bad value for <key>[.<field>]: <value>`. Fix the patch from
73
74
  `describe()`. Combinations are not checked: `orientation` is dropped
74
75
  without a numeric width and height, and `posture` without a device that
75
76
  folds. Compare `getState()` with what you set.
76
77
  2. Wait for it to apply:
77
- - `reload` is `none` or `frame`: `await window.devknobs.ready()`.
78
- - `reload` is `page`: the page may reload, or it may not. devknobs skips a
78
+ - `reload` is `none` or `frame`: `await window.knobs.ready()`.
79
+ - `reload` is `page`: the page may reload, or it may not. knobs skips a
79
80
  reload that comes less than 5 seconds after the last one. Call
80
- `await window.devknobs.ready()` either way. If the page navigates
81
+ `await window.knobs.ready()` either way. If the page navigates
81
82
  instead, wait for the load in your browser tool and call
82
- `await window.devknobs.ready()` on the new page. A `ready()` from the old
83
+ `await window.knobs.ready()` on the new page. A `ready()` from the old
83
84
  page never settles. In Playwright or a DevTools tool, the reload ends the
84
85
  evaluate with an error such as `Execution context was destroyed` or
85
86
  `Inspected target navigated or closed`. That error is the expected sign
@@ -87,7 +88,7 @@ as `grabColor` and the panel's place. Do not compare the two key for key.
87
88
 
88
89
  `ready()` resolves with the state once the device frame has caught up, the
89
90
  pseudo text is in and the panel has finished its slide. After 10 seconds it rejects with the error
90
- `devknobs: not settled after 10 seconds`. A rejection is not success: check the
91
+ `knobs: not settled after 10 seconds`. A rejection is not success: check the
91
92
  page before you trust it.
92
93
 
93
94
  To leave a device, call `reset()` or set
@@ -96,23 +97,23 @@ To leave a device, call `reset()` or set
96
97
  stays up.
97
98
 
98
99
  ```js
99
- window.devknobs.setState({ scheme: "dark", motion: "reduce" });
100
- await window.devknobs.ready();
100
+ window.knobs.setState({ scheme: "dark", motion: "reduce" });
101
+ await window.knobs.ready();
101
102
  ```
102
103
 
103
104
  ```js
104
- window.devknobs.setState({ device: "iphone-17", locale: { lang: "ar", dir: "rtl" } });
105
- await window.devknobs.ready();
105
+ window.knobs.setState({ device: "iphone-17", locale: { lang: "ar", dir: "rtl" } });
106
+ await window.knobs.ready();
106
107
  // If the page navigates, the evaluate ends with it. Wait for the load, then on the new page:
107
- await window.devknobs.ready();
108
+ await window.knobs.ready();
108
109
  ```
109
110
 
110
111
  ## Check the page
111
112
 
112
113
  1. Close the panel, hide its handle and unpin it, so it stays out of
113
114
  screenshots and out of the page's width, then wait for it to slide away:
114
- `window.devknobs.setState({ panel: { open: false, handle: false, docked: false } })`,
115
- then `await window.devknobs.ready()`. `reset()` keeps this. Patch only
115
+ `window.knobs.setState({ panel: { open: false, handle: false, docked: false } })`,
116
+ then `await window.knobs.ready()`. `reset()` keeps this. Patch only
116
117
  `open`, `docked` and `handle`. The other panel fields are the user's
117
118
  layout and settings, such as `devIcon`, the DEV ribbon on the tab's icon. `panel.handle` is your layer. The user's own "show handle" setting
118
119
  can hide the handle too, and `getState()` does not show that setting.
@@ -126,16 +127,16 @@ await window.devknobs.ready();
126
127
 
127
128
  ```js
128
129
  const frame = document
129
- .querySelector('[data-devknobs="viewport"]')
130
- ?.shadowRoot?.querySelector("iframe[data-devknobs-frame]");
130
+ .querySelector('[data-knobs="viewport"]')
131
+ ?.shadowRoot?.querySelector("iframe[data-knobs-frame]");
131
132
  await frame?.contentWindow?.devknobs?.ready();
132
133
  frame?.contentDocument;
133
134
  ```
134
135
 
135
- Read the DOM there. The page in the frame runs its own devknobs, so call
136
- `grab` on `frame.contentWindow.devknobs` for elements in the frame. The top
136
+ Read the DOM there. The page in the frame runs its own knobs, so call
137
+ `grab` on `frame.contentWindow.knobs` for elements in the frame. The top
137
138
  page's `grab` on such an element gives component names with no file or line.
138
- After `ready()` the frame's devknobs is there if the app mounts devknobs on
139
+ After `ready()` the frame's knobs is there if the app mounts knobs on
139
140
  that page.
140
141
 
141
142
  ## Find the code
@@ -143,7 +144,7 @@ await window.devknobs.ready();
143
144
  For an element that looks wrong, call `grab`:
144
145
 
145
146
  ```js
146
- const payload = await window.devknobs.grab(document.querySelector("h1"));
147
+ const payload = await window.knobs.grab(document.querySelector("h1"));
147
148
  payload?.content;
148
149
  ```
149
150
 
@@ -152,8 +153,8 @@ payload?.content;
152
153
  `content` is one line per element: its html, the components that rendered it
153
154
  and their source files with line and column. `entries[i].source?.filePath`
154
155
  holds the file, relative to the app's dev server root (the vite root), not the
155
- repo. In a monorepo, find the app first. `source` is null when devknobs cannot
156
- find one. `source.lineNumber` and `columnNumber` are null when devknobs finds
156
+ repo. In a monorepo, find the app first. `source` is null when knobs cannot
157
+ find one. `source.lineNumber` and `columnNumber` are null when knobs finds
157
158
  the file but not the line, and `content` then names the file alone. Search
158
159
  that file for the element's tag and class names. A line that is there points
159
160
  at the element's tag in the file. Open that file and fix the code.
@@ -166,7 +167,7 @@ such as a `querySelector` that found nothing, and returns `null` when nothing
166
167
  is left or the elements give nothing.
167
168
 
168
169
  After a fix, reload the page. The knobs stay set across reloads. Call
169
- `await window.devknobs.ready()` and check again.
170
+ `await window.knobs.ready()` and check again.
170
171
 
171
172
  ## Apply the user's edits
172
173
 
@@ -174,7 +175,7 @@ The user can edit styles and the html in inspect's view (`⇧C`) and ask you
174
175
  to put them in the code. Read them:
175
176
 
176
177
  ```js
177
- window.devknobs.edits();
178
+ window.knobs.edits();
178
179
  ```
179
180
 
180
181
  Each edit is plain json: `kind` (`css-value`, `css-toggle`, `css-add` or
@@ -223,14 +224,14 @@ save the list and make it again:
223
224
 
224
225
  ```js
225
226
  // Read the list into your own context (the result of the evaluate call): a reload clears the page's variables.
226
- JSON.stringify(window.devknobs.edits());
227
+ JSON.stringify(window.knobs.edits());
227
228
  ```
228
229
 
229
230
  It comes back as a JSON string. Reload the page, then parse it and pass it back in:
230
231
 
231
232
  ```js
232
- const { applied, skipped } = await window.devknobs.setEdits(JSON.parse(JSON_YOU_KEPT));
233
- window.devknobs.undoEdit(); // undoes the last edit in force, returns it or null
233
+ const { applied, skipped } = await window.knobs.setEdits(JSON.parse(JSON_YOU_KEPT));
234
+ window.knobs.undoEdit(); // undoes the last edit in force, returns it or null
234
235
  ```
235
236
 
236
237
  `setEdits` makes each edit only where its element is found by its selector
@@ -251,9 +252,9 @@ wait for the user's click on `apply` in the panel.
251
252
  To see or screenshot a state the pointer or the keyboard would give, force it:
252
253
 
253
254
  ```js
254
- window.devknobs.forceState(".cta", ["hover"]); // or "focus", "focus-visible", "active", "focus-within"
255
+ window.knobs.forceState(".cta", ["hover"]); // or "focus", "focus-visible", "active", "focus-within"
255
256
  // screenshot, then:
256
- window.devknobs.forceState(null);
257
+ window.knobs.forceState(null);
257
258
  ```
258
259
 
259
260
  It takes an element or a selector, returns the states forced, and is no edit.
@@ -279,8 +280,8 @@ const conditions = [
279
280
 
280
281
  For each condition:
281
282
 
282
- 1. `window.devknobs.reset()`.
283
- 2. `window.devknobs.setState(condition)`. The panel stays as you set it in
283
+ 1. `window.knobs.reset()`.
284
+ 2. `window.knobs.setState(condition)`. The panel stays as you set it in
284
285
  "Check the page".
285
286
  3. Wait as in "Set a condition".
286
287
  4. Screenshot or read the DOM. Note what breaks.
@@ -296,10 +297,10 @@ changes data values, such as numbers and names. That is not a bug.
296
297
  Put the knobs back, and the panel as you noted it at the start:
297
298
 
298
299
  ```js
299
- window.devknobs.forceState(null); // a state you forced; reset() leaves it
300
- window.devknobs.reset();
301
- window.devknobs.setState({ panel: NOTED_PANEL }); // the panel json you noted
302
- await window.devknobs.ready();
300
+ window.knobs.forceState(null); // a state you forced; reset() leaves it
301
+ window.knobs.reset();
302
+ window.knobs.setState({ panel: NOTED_PANEL }); // the panel json you noted
303
+ await window.knobs.ready();
303
304
  ```
304
305
 
305
306
  The knobs are kept in `sessionStorage` and stay set across reloads in the tab
@@ -1,23 +0,0 @@
1
- var __defProp = Object.defineProperty;
2
- var __returnValue = (v) => v;
3
- function __exportSetter(name, newValue) {
4
- this[name] = __returnValue.bind(null, newValue);
5
- }
6
- var __export = (target, all) => {
7
- for (var name in all)
8
- __defProp(target, name, {
9
- get: all[name],
10
- enumerable: true,
11
- configurable: true,
12
- set: __exportSetter.bind(all, name)
13
- });
14
- };
15
- var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
16
- get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
17
- }) : x)(function(x) {
18
- if (typeof require !== "undefined")
19
- return require.apply(this, arguments);
20
- throw Error('Dynamic require of "' + x + '" is not supported');
21
- });
22
-
23
- export { __export, __require };
@@ -1,24 +0,0 @@
1
- "use client";
2
- var __defProp = Object.defineProperty;
3
- var __returnValue = (v) => v;
4
- function __exportSetter(name, newValue) {
5
- this[name] = __returnValue.bind(null, newValue);
6
- }
7
- var __export = (target, all) => {
8
- for (var name in all)
9
- __defProp(target, name, {
10
- get: all[name],
11
- enumerable: true,
12
- configurable: true,
13
- set: __exportSetter.bind(all, name)
14
- });
15
- };
16
- var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
17
- get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
18
- }) : x)(function(x) {
19
- if (typeof require !== "undefined")
20
- return require.apply(this, arguments);
21
- throw Error('Dynamic require of "' + x + '" is not supported');
22
- });
23
-
24
- export { __export, __require };