@softure-ai/marketing-kit 0.1.10 → 0.1.12

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/CHANGELOG.md CHANGED
@@ -4,6 +4,27 @@ Newest first. Each version lists what changed for an app that uses `@softure-ai/
4
4
  production, the version gets a line `verified in: <app>@<commit>` ([docs/05](../../docs/05-adoption-playbook.md),
5
5
  "Definition of done"). Versions before the first one below are described in their GitHub Releases (`marketing-kit@x.y.z`).
6
6
 
7
+ ## 0.1.12
8
+
9
+ - `shots` frames one row of a card that is shorter than its crop (#371):
10
+ - `crop.fill: true`: a target shorter than its frame is stretched to the frame's bottom edge for the capture and
11
+ its content centred vertically, so no page background or next card shows below it. Refused (gate `crop`) when
12
+ the target still ends above the frame's bottom edge; excludes `crop.top`.
13
+ - Step `flatten`: removes the top border and top margin of every match, e.g. the line above the first row a print
14
+ state still shows; fails when nothing matches.
15
+
16
+ ## 0.1.11
17
+
18
+ - `shots` entries take a print state (#333):
19
+ - `hide`: CSS selectors hidden in that entry's files only, on top of `app.hideSelectors`. New gate `hide`: the file
20
+ is refused when one of them still shows a rendered element inside the frame, or the browser cannot parse it.
21
+ - `crop.top`: a second locator whose top edge starts the frame (e.g. a row inside a card); the width stays
22
+ `crop.target`'s. Refused (gate `crop`) when it matches nothing or several, or lies outside the target.
23
+ - Step `open`: opens every matching `<details>`; fails on a match that is not a `<details>` or did not stay open.
24
+ - Step `hide` with `keepLast`: hides every match but the last N, e.g. the early columns of a sideways chart; fails
25
+ when that would hide nothing.
26
+ - `SCREENSHOT_GATES` gains `hide` (between `crop` and `size`).
27
+
7
28
  ## 0.1.10
8
29
 
9
30
  - Every command crashed on start-up when npm resolved satori to 0.35.2 or 0.36.0 (the case through `npx`, which has
package/README.md CHANGED
@@ -17,7 +17,7 @@ TTS providers (MK-7), screenshots (MK-4) and OG images (MK-5) build on it. Backg
17
17
  An app runs the kit through `npx` with a pinned version, not as a dependency:
18
18
 
19
19
  ```json
20
- { "scripts": { "marketing": "npx -y @softure-ai/marketing-kit@0.1.10" } }
20
+ { "scripts": { "marketing": "npx -y @softure-ai/marketing-kit@0.1.12" } }
21
21
  ```
22
22
 
23
23
  `npm run marketing -- all <video>` then runs the CLI. As a `devDependency` the kit would add more than 100 MB
@@ -75,7 +75,7 @@ recordings and compositions in `<output.buildDir>/<video>/`. None of it belongs
75
75
 
76
76
  `shots` captures every `screenshots[]` entry, or the one named, into `<output.dir>/screenshots/<id>.png`.
77
77
  Each entry gets a fresh browser at `width`×`height` CSS px with `app.colorScheme`, `brand.locale`,
78
- `brand.timezone`, `app.hideSelectors` hidden and its own `motion` preference (`reduce` by default).
78
+ `brand.timezone`, `app.hideSelectors` and its own `hide` hidden, and its own `motion` preference (`reduce` by default).
79
79
  `scale` sets the device pixels per CSS pixel (1-4, default 1): at `2` an 800×600 entry is a 1600×1200 PNG,
80
80
  sharp on a retina screen or a store listing. `colorSchemes` (e.g. `["light", "dark"]`) captures the entry
81
81
  once per scheme, in its own browser, into `<id>-light.png` and `<id>-dark.png`; without it, one `<id>.png`
@@ -90,18 +90,20 @@ folder of `marketing.json`, written by the app's own login script (`await contex
90
90
  `npx playwright codegen --save-storage=<file> <url>`. It holds a live session, so keep it out of git and regenerate
91
91
  it when the session expires; a missing or broken file stops `shots` before the browser starts. To have `shots` sign
92
92
  in itself, see [Signed-in screens](#signed-in-screens). `steps` run on the page after it loaded, before any gate
93
- reads it: `click` (open a collapsed section), `fill`, `check`, `press`, each with 10 s. `crop` frames one element
94
- at a fixed aspect ratio instead of the viewport, see [A frame around one element](#a-frame-around-one-element).
93
+ reads it: `click` (open a collapsed section), `fill`, `check`, `press`, `open`, `hide` and `flatten`, each with 10 s. `crop`
94
+ frames one element at a fixed aspect ratio instead of the viewport, see [A frame around one element](#a-frame-around-one-element);
95
+ `hide`, `crop.fill` and the `open`, `hide` and `flatten` steps give a frame its print state, see [A still image of an interactive card](#a-still-image-of-an-interactive-card).
95
96
  A screenshot is kept only when it passes every gate:
96
97
 
97
98
  | Gate | Refused when |
98
99
  | --- | --- |
99
100
  | `sign-in` | a `signedIn` entry, and the run's sign-in failed (the reason is printed with every such file) |
100
101
  | `status` | the page answers with HTTP 400 or above, or not at all (`load`: it did not load within 30 s) |
101
- | `steps` | a step could not be done (its element never appeared, matched several, is not an input) |
102
+ | `steps` | a step could not be done (its element never appeared, matched several, is not an input, is not a `<details>`, left nothing to hide, matched nothing to flatten) |
102
103
  | `scroll` | the page cannot scroll as far as `scrollTo` (the frame would show another place) |
103
104
  | `phrase` | the page does not show `expect` within 5 s of loading (hidden elements do not count) |
104
- | `crop` | the crop's target matches no element or several, its frame runs past the page, or the file is not the frame's size |
105
+ | `crop` | the crop's target (or `crop.top`) matches no element or several, `crop.top` lies outside the target, `crop.fill` could not stretch the target to the frame, its frame runs past the page, or the file is not the frame's size |
106
+ | `hide` | a selector of the entry's `hide` still shows an element inside the frame (an inline `!important` beat it), or the browser cannot parse it |
105
107
  | `size` | the file is smaller than `minBytes` (40 kB by default: a blank or broken page); the file is deleted |
106
108
  | `duplicate` | an earlier file of the same run has the same bytes (the page did not change between the two shots); deleted |
107
109
 
@@ -176,6 +178,61 @@ whose layout uses `100vh` may lay out taller for the capture. The file is the fr
176
178
  target that matches nothing or several elements. `crop` excludes `full` and `scrollTo`. An element is smaller than
177
179
  a page, so set `minBytes` for it (15000 is a fair floor for a filled card).
178
180
 
181
+ `crop.top` (a second locator, exactly one match) starts the frame at its element's top edge instead of the target's,
182
+ e.g. a row inside a card, while the width stays the target's. Its top edge must lie inside the target, or the crop
183
+ is refused: the frame would no longer show the target.
184
+
185
+ `crop.fill: true` stretches a target that is shorter than its frame down to the frame's bottom edge and centres its
186
+ content vertically (`min-height` and a centred flex column, inline with `!important`, in the capture browser only), so
187
+ no page background or next card shows below it. A target that is already as tall as the frame is left as it is. The
188
+ `crop` gate refuses the file when the target still ends above the frame's bottom edge (an SVG, or a script that resets
189
+ its style). `crop.fill` excludes `crop.top`: centring would move the row the frame starts at.
190
+
191
+ #### A still image of an interactive card
192
+
193
+ A frame of a signed-in card shows controls that mean nothing in a still image: hint `?` buttons, disclosure arrows,
194
+ closed sections, a chart that scrolls sideways and cuts its first amounts at the edge. An entry gives the frame its
195
+ print state:
196
+
197
+ ```jsonc
198
+ { "id": "breakdown", "path": "/dashboard", "width": 390, "height": 900, "scale": 2, "signedIn": true,
199
+ "expect": "{data:positionName}", "minBytes": 15000,
200
+ "hide": ["button.hint", "summary .arrow", ".chart-footnote"],
201
+ "steps": [
202
+ { "do": "open", "target": { "css": "details" } },
203
+ { "do": "hide", "target": { "css": ".chart .column" }, "keepLast": 3 }
204
+ ],
205
+ "crop": { "target": { "testId": "breakdown-card" }, "top": { "testId": "breakdown-total" }, "aspect": "6:5" } }
206
+ ```
207
+
208
+ - `hide`: CSS selectors hidden in this entry's files only, on top of `app.hideSelectors`, from the first paint. Before
209
+ the capture, the `hide` gate refuses the file when one of them still matches a rendered element inside the frame
210
+ (the crop's frame, the whole page with `full`, the viewport otherwise): an inline `!important` on the page beats the
211
+ kit's rule, and an element the frame keeps showing would look clickable. A selector that matches nothing passes.
212
+ - `{ "do": "open", "target": … }` opens every matching `<details>` (`nth` picks one). It fails when a match is not a
213
+ `<details>`, or does not stay open: details that share a `name` show one at a time.
214
+ - `{ "do": "hide", "target": …, "keepLast": N }` hides every match but the last `N` (default 0: all of them), e.g. all
215
+ but the last three columns of a chart that scrolls sideways, so no amount is cut at the frame's edge. It fails when
216
+ there are not more matches than `keepLast`, which hides nothing.
217
+ - `{ "do": "flatten", "target": … }` removes the top border and top margin of every match, e.g. the line a list's
218
+ `border-top` draws above the first row a print state still shows. It fails when nothing matches.
219
+
220
+ One row of a card, when the rest is hidden and the card is shorter than its frame: `crop.fill` stretches the card to
221
+ the frame and centres the row, and `flatten` drops the border the list kept above it.
222
+
223
+ ```jsonc
224
+ { "id": "frame-change", "path": "/dashboard", "width": 390, "height": 900, "scale": 2, "signedIn": true,
225
+ "expect": "Change since last month", "minBytes": 15000,
226
+ "steps": [
227
+ { "do": "open", "target": { "css": "details.change" } },
228
+ { "do": "hide", "target": { "css": "section.rail > header" } },
229
+ { "do": "hide", "target": { "css": "section.rail > div" } },
230
+ { "do": "hide", "target": { "css": "section.rail > dl > div" }, "keepLast": 1 },
231
+ { "do": "flatten", "target": { "css": "section.rail > dl" } }
232
+ ],
233
+ "crop": { "target": { "css": "section.rail" }, "aspect": "6:5", "fill": true } }
234
+ ```
235
+
179
236
  #### One page anywhere: `shots --page`
180
237
 
181
238
  ```bash
@@ -275,7 +332,7 @@ folder of `marketing.json`. A complete example: [examples/fixture/marketing.json
275
332
  | | `platforms` | `instagram`, `facebook`, `tiktok`, `youtube`, `linkedin`, `x`: `code`, `linkInBio` (true for Instagram, TikTok, YouTube) |
276
333
  | | `posts[]` | `video`, `caption`, `hashtags`, `codes` (this video's own codes), `disclosure` (`true`; `false` leaves the disclosure out); a video without one gets no `posts.md` |
277
334
  | | `disclosure` | a paragraph after every post's caption, before the link: that the persona is an example, that it is not advice, that the voice is AI-generated; `{persona}` becomes the video's persona name |
278
- | `screenshots[]` | `id`, `path`, `width`, `height`, `full` (`false`), `expect`, `motion` (`reduce`), `minBytes` (`40000`), `scale` (`1`), `colorSchemes`, `scrollTo`, `waitMs` (`0`), `storageState`, `signedIn` (`false`), `steps` (`[]`), `crop` | for `softure-marketing shots`, see [Screenshots](#screenshots) |
335
+ | `screenshots[]` | `id`, `path`, `width`, `height`, `full` (`false`), `expect`, `motion` (`reduce`), `minBytes` (`40000`), `scale` (`1`), `colorSchemes`, `scrollTo`, `waitMs` (`0`), `storageState`, `signedIn` (`false`), `steps` (`[]`), `crop`, `hide` (`[]`) | for `softure-marketing shots`, see [Screenshots](#screenshots) |
279
336
  | `signIn` | `prepare`, `path`, `steps`, `expect` | how `shots` signs in for `signedIn` entries, see [Signed-in screens](#signed-in-screens) |
280
337
  | `ogImages[]` | `id`, `template` (`headline-cta`, `headline-chart`, `big-number`, `carousel`), `size` (`"landscape"`, `"portrait"`, `"square"`, `"story"` or `[width, height]`; `landscape` for the headline cards, `portrait` for the others), `data` | for `softure-marketing og`, see [OG images](#og-images) |
281
338
  | `layout` | per layout (`9:16`, `1:1`, `16:9` for phone films; `desktop` for desktop films): `caption` (`top`, `left`, `right`, `fontSize`), `persona` (`top`, `left`, `right`), `endCard` (`top`, `left`, `right`, `headlineSize`, `phone.scale`, `phone.center`) | overrides of the layout's geometry table for every film of that layout, in frame px (`endCard.phone` is the browser window's pose in `desktop`); a missing key keeps the table's value. Values must fit the frame and each box's margins must leave at least 200 px for its text. The frame, the screen box and the camera target are fixed |
@@ -454,6 +511,19 @@ format, so its paid recordings are reused as they are, with no re-keying and no
454
511
  `from the cache`; an estimate line means the text, voice or model differs from FIRE's, and nothing
455
512
  was spent.
456
513
 
514
+ ### Upgrading to 0.1.12
515
+
516
+ - A 0.1.11 `marketing.json` works as it is. New: `crop.fill` and the step `flatten`. An app that frames one row of a
517
+ card with its own capture styles (a `min-height` on the card, a dropped `border-top`) can move that frame to
518
+ `marketing.json`.
519
+
520
+ ### Upgrading to 0.1.11
521
+
522
+ - A 0.1.10 `marketing.json` works as it is. New: `hide` on entries (with the `hide` gate), `crop.top`, and the steps
523
+ `open` and `hide`. An app that still captures its signed-in frames with its own browser test because it injects a
524
+ print stylesheet, opens every `<details>` or trims a sideways chart can move that file to `marketing.json` too.
525
+ - `SCREENSHOT_GATES` lists the new gate `hide`; code that switches over `ScreenshotGate` exhaustively needs its case.
526
+
457
527
  ### Upgrading to 0.1.10
458
528
 
459
529
  - A 0.1.9 `marketing.json` works as it is, with one new refusal: two files of one `shots` run with the same bytes