@softure-ai/marketing-kit 0.1.11 → 0.2.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.
Files changed (46) hide show
  1. package/CHANGELOG.md +16 -0
  2. package/README.md +36 -6
  3. package/dist/cli/main.js +3 -4
  4. package/dist/cli/main.js.map +1 -1
  5. package/dist/config/config.d.ts +3 -3
  6. package/dist/config/config.d.ts.map +1 -1
  7. package/dist/config/config.js +2 -2
  8. package/dist/config/config.js.map +1 -1
  9. package/dist/config/schema.d.ts +712 -71
  10. package/dist/config/schema.d.ts.map +1 -1
  11. package/dist/config/schema.js +33 -7
  12. package/dist/config/schema.js.map +1 -1
  13. package/dist/config/shot-steps.d.ts +156 -0
  14. package/dist/config/shot-steps.d.ts.map +1 -1
  15. package/dist/config/shot-steps.js +9 -1
  16. package/dist/config/shot-steps.js.map +1 -1
  17. package/dist/index.d.ts +1 -1
  18. package/dist/index.d.ts.map +1 -1
  19. package/dist/index.js +1 -1
  20. package/dist/index.js.map +1 -1
  21. package/dist/messages/index.d.ts +10 -22
  22. package/dist/messages/index.d.ts.map +1 -1
  23. package/dist/messages/index.js +8 -6
  24. package/dist/messages/index.js.map +1 -1
  25. package/dist/screenshot/screenshot.d.ts.map +1 -1
  26. package/dist/screenshot/screenshot.js +39 -2
  27. package/dist/screenshot/screenshot.js.map +1 -1
  28. package/dist/screenshot/steps.d.ts +1 -1
  29. package/dist/screenshot/steps.d.ts.map +1 -1
  30. package/dist/screenshot/steps.js +15 -1
  31. package/dist/screenshot/steps.js.map +1 -1
  32. package/package.json +1 -1
  33. package/schema/marketing.schema.json +789 -208
  34. package/src/cli/main.ts +3 -4
  35. package/src/config/config.ts +4 -5
  36. package/src/config/schema.ts +35 -8
  37. package/src/config/shot-steps.ts +9 -1
  38. package/src/index.ts +1 -2
  39. package/src/messages/index.ts +16 -8
  40. package/src/screenshot/screenshot.ts +35 -2
  41. package/src/screenshot/steps.ts +15 -1
  42. package/dist/messages/pl.d.ts +0 -3
  43. package/dist/messages/pl.d.ts.map +0 -1
  44. package/dist/messages/pl.js +0 -21
  45. package/dist/messages/pl.js.map +0 -1
  46. package/src/messages/pl.ts +0 -22
package/src/cli/main.ts CHANGED
@@ -5,7 +5,6 @@ import { join, resolve } from "node:path";
5
5
  import { findMissingFiles, formatConfigIssues, loadMarketingConfig, type MarketingConfig } from "../config/config.js";
6
6
  import { getGeometry, getLayoutName } from "../compose/timeline.js";
7
7
  import { sceneBeats } from "../film.js";
8
- import { getMarketingMessages } from "../messages/index.js";
9
8
  import { postsMarkdown } from "../posts/posts.js";
10
9
  import { recordFilm, ScreenGuardError, type RecordingLog } from "../record/record.js";
11
10
  import { findMachineProblem } from "../render/preflight.js";
@@ -92,14 +91,14 @@ function writePosts(config: MarketingConfig, film: LoadedFilm): string | null {
92
91
  mkdirSync(getOutDir(config, film), { recursive: true });
93
92
  writeFileSync(
94
93
  path,
95
- postsMarkdown({ title: film.title, post: film.post, linkTemplate: config.social.linkTemplate, messages: getMarketingMessages(config.brand.language) }),
94
+ postsMarkdown({ title: film.title, post: film.post, linkTemplate: config.social.linkTemplate, messages: config.brand.messages }),
96
95
  );
97
96
  return path;
98
97
  }
99
98
 
100
99
  function describePosts(config: MarketingConfig, film: LoadedFilm, path: string | null): string {
101
100
  if (path === null) return `no post copy: social.posts has no entry for "${film.id}" in ${config.file}.`;
102
- const labels = (film.post?.channels ?? []).map((channel) => getMarketingMessages(config.brand.language).posts.platforms[channel.platform]);
101
+ const labels = (film.post?.channels ?? []).map((channel) => config.brand.messages.posts.platforms[channel.platform]);
103
102
  return `✓ ${path}: post copy for ${labels.join(", ")}`;
104
103
  }
105
104
 
@@ -136,7 +135,7 @@ function render(config: MarketingConfig, film: LoadedFilm, options: FilmOptions)
136
135
  colors: config.brand.colors,
137
136
  brandName: config.brand.name,
138
137
  locale: config.brand.locale,
139
- messages: getMarketingMessages(config.brand.language),
138
+ messages: config.brand.messages,
140
139
  quality: options.quality ?? config.output.quality,
141
140
  output,
142
141
  });
@@ -3,7 +3,7 @@ import { dirname, resolve } from "node:path";
3
3
 
4
4
  import { getLayoutName } from "../compose/timeline.js";
5
5
  import type { Device, FilmScript } from "../film.js";
6
- import type { MarketingLocale } from "../messages/index.js";
6
+ import { getMarketingMessages, type MarketingMessages } from "../messages/index.js";
7
7
  import { DEFAULT_LINK_IN_BIO, PLATFORMS, type Platform } from "../platforms.js";
8
8
  import type { PlaceholderPace } from "../voice/placeholder.js";
9
9
  import type { SceneAction } from "./actions-schema.js";
@@ -82,8 +82,8 @@ export interface MarketingConfig {
82
82
  name: string;
83
83
  /** BCP 47, e.g. `en-US`. */
84
84
  locale: string;
85
- /** The dictionary of the copy: the locale's language. */
86
- language: MarketingLocale;
85
+ /** The copy of the posts and the film: English with `brand.messages` applied. */
86
+ messages: MarketingMessages;
87
87
  timezone: string;
88
88
  logo: string | null;
89
89
  colors: BrandColors;
@@ -210,8 +210,7 @@ export function loadMarketingConfig(path: string): LoadConfigResult {
210
210
  brand: {
211
211
  name: data.brand.name,
212
212
  locale: data.brand.locale,
213
- // The schema refuses a locale whose language has no dictionary.
214
- language: data.brand.locale.split("-")[0] as MarketingLocale,
213
+ messages: getMarketingMessages(data.brand.messages),
215
214
  timezone: data.brand.timezone,
216
215
  logo: data.brand.logo === undefined ? null : at(data.brand.logo.svg),
217
216
  colors: colors.colors,
@@ -12,7 +12,6 @@ import {
12
12
  resolveLayout,
13
13
  type LayoutName,
14
14
  } from "../compose/timeline.js";
15
- import { MARKETING_LOCALES, type MarketingLocale } from "../messages/index.js";
16
15
  import { bigNumberDataSchema, carouselDataSchema, headlineChartDataSchema, headlineCtaDataSchema } from "../og/templates/schemas.js";
17
16
  import { CHANNEL_CODE_MAX_LENGTH, CHANNEL_CODE_PATTERN, DEFAULT_LINK_IN_BIO, PLATFORMS } from "../platforms.js";
18
17
  import { ELEVENLABS_DEFAULT_MODEL } from "../voice/voiceover.js";
@@ -77,11 +76,6 @@ function isKnownTimezone(zone: string): boolean {
77
76
  }
78
77
  }
79
78
 
80
- function hasMessages(locale: string): boolean {
81
- const language = locale.split("-")[0];
82
- return MARKETING_LOCALES.some((known: MarketingLocale) => known === language);
83
- }
84
-
85
79
  function getWords(sentence: string): string[] {
86
80
  return sentence.split(/\s+/).map((word) => word.replace(/[.,?!:;]/g, ""));
87
81
  }
@@ -145,13 +139,43 @@ const roleTokensShape = Object.fromEntries(
145
139
  z.ZodOptional<typeof tokenName>
146
140
  >;
147
141
 
142
+ const messageText = (key: string) => nonEmpty.optional().describe(`src/messages/en.ts ${key}; English when left out.`);
143
+
144
+ /** The built-in copy (`src/messages/en.ts`), every key optional: the app's own translation or changed English copy. */
145
+ const brandMessagesSchema = z
146
+ .strictObject({
147
+ posts: z
148
+ .strictObject({
149
+ title: messageText("posts.title: the heading of posts.md, {title} is the film's title"),
150
+ linkInBio: messageText("posts.linkInBio: the call to action where a caption link is not clickable"),
151
+ bioLink: messageText("posts.bioLink: the bio link line, {link}"),
152
+ postLink: messageText("posts.postLink: the post link line, {link}"),
153
+ platforms: z
154
+ .strictObject({
155
+ instagram: messageText("posts.platforms.instagram"),
156
+ facebook: messageText("posts.platforms.facebook"),
157
+ tiktok: messageText("posts.platforms.tiktok"),
158
+ youtube: messageText("posts.platforms.youtube"),
159
+ linkedin: messageText("posts.platforms.linkedin"),
160
+ x: messageText("posts.platforms.x"),
161
+ })
162
+ .optional()
163
+ .describe("The platform names in posts.md."),
164
+ })
165
+ .optional()
166
+ .describe("The copy of posts.md."),
167
+ film: z.strictObject({ persona: messageText("film.persona: the persona card's first line, {name} and {age}") }).optional().describe("The copy inside the film."),
168
+ })
169
+ .default({})
170
+ .describe("The copy of the posts and the film, every key optional (src/messages/en.ts): the product's own translation, or changed English copy. A key left out reads English.");
171
+
148
172
  const brandSchema = z.strictObject({
149
173
  name: nonEmpty.describe("The product's name, shown on the end card."),
150
174
  locale: z
151
175
  .string()
152
176
  .regex(LOCALE_PATTERN, "must be a BCP 47 locale such as en-US")
153
- .refine(hasMessages, `needs a language with message dictionaries: ${MARKETING_LOCALES.join(", ")}`)
154
- .describe(`BCP 47 locale (en-US): the recording browser's locale, <html lang> and the language of the copy. Its language needs a message dictionary: ${MARKETING_LOCALES.join(", ")}.`),
177
+ .describe("BCP 47 locale (en-US): the recording browser's locale and <html lang>. The copy is English unless brand.messages translates it."),
178
+ messages: brandMessagesSchema,
155
179
  timezone: z.string().refine(isKnownTimezone, "must be an IANA timezone such as Europe/London").describe("IANA zone of the recording browser, e.g. Europe/London."),
156
180
  logo: z
157
181
  .strictObject({ svg: relativePath.endsWith(".svg", "must be an .svg file").describe("The logo as an .svg file, relative to the folder of marketing.json.") })
@@ -512,6 +536,9 @@ export const screenshotSchema = z.strictObject({
512
536
  context.addIssue({ code: "custom", path: ["scrollTo"], message: "is one viewport frame at a scroll position; a full-page shot has none, so drop full or scrollTo" });
513
537
  }
514
538
  if (entry.crop !== undefined && entry.full) context.addIssue({ code: "custom", path: ["crop"], message: "frames one element; a full-page shot has no element to frame, so drop full or crop" });
539
+ if (entry.crop?.fill === true && entry.crop.top !== undefined) {
540
+ context.addIssue({ code: "custom", path: ["crop", "fill"], message: "centres the target's content in the frame; crop.top would start the frame inside it, so drop one of them" });
541
+ }
515
542
  if (entry.crop !== undefined && entry.scrollTo !== undefined) {
516
543
  context.addIssue({ code: "custom", path: ["crop"], message: "places the frame on its element; scrollTo would place it too, so drop one of them" });
517
544
  }
@@ -6,7 +6,7 @@ import { locatorSchema } from "./actions-schema.js";
6
6
  * What a screenshot does on the page before it is judged: the sign-in form (`signIn.steps`) and an entry's own
7
7
  * `steps` (open collapsed sections, hide what a still image should not show). Plain Playwright calls on a locator,
8
8
  * with no camera and no timing: a screenshot records nothing in between. `crop` frames one element at a fixed aspect
9
- * ratio instead of the viewport, optionally from the top edge of another one.
9
+ * ratio instead of the viewport, optionally from the top edge of another one, or stretched to the frame (`fill`).
10
10
  */
11
11
 
12
12
  /** A Playwright key name, modifiers joined with `+`; Playwright itself refuses a name it does not know. */
@@ -51,6 +51,10 @@ export const shotStepSchema = z.discriminatedUnion("do", [
51
51
  .default(0)
52
52
  .describe(`How many of the last matches stay shown (0-${MAX_KEEP_LAST}, default 0); the step fails when there are not more matches than this.`),
53
53
  }),
54
+ z.strictObject({
55
+ do: z.literal("flatten").describe("Removes the top border and top margin of every match, e.g. the line above the first row a print state still shows."),
56
+ target: locatorSchema.describe("The elements, as a locator descriptor with exactly one of role, text, label, testId, css; every match is flattened."),
57
+ }),
54
58
  ]);
55
59
 
56
60
  export type ShotStep = z.output<typeof shotStepSchema>;
@@ -74,6 +78,10 @@ export const cropSchema = z.strictObject({
74
78
  })
75
79
  .describe("The frame's width to height, e.g. 4:3: as wide as the element (plus padding), from its top edge down."),
76
80
  padding: z.number().int().min(0).max(200).default(0).describe("CSS pixels of the page around the element on the left, right and top (0-200, default 0)."),
81
+ fill: z
82
+ .boolean()
83
+ .default(false)
84
+ .describe("Stretches a target shorter than the frame down to the frame's bottom edge and centres its content vertically, so no page shows below it (default false). Not with top."),
77
85
  });
78
86
 
79
87
  export type Crop = z.output<typeof cropSchema>;
package/src/index.ts CHANGED
@@ -170,10 +170,9 @@ export { MIN_FAILING_STATUS, SCREENSHOT_GATES, findScrollFailure, findSizeFailur
170
170
  export { findStorageStateProblem } from "./screenshot/storage-state.js";
171
171
  export { getScreenshotNames, getScreenshotShots, type ScreenshotNaming, type ScreenshotShot } from "./config/screenshot-names.js";
172
172
  export {
173
- MARKETING_LOCALES,
174
173
  formatMessage,
175
174
  getMarketingMessages,
176
175
  marketingMessages,
177
- type MarketingLocale,
176
+ type MarketingMessageOverrides,
178
177
  type MarketingMessages,
179
178
  } from "./messages/index.js";
@@ -1,17 +1,25 @@
1
1
  import { en } from "./en.js";
2
- import { pl } from "./pl.js";
3
2
 
4
- /** Complete default dictionaries of the copy that ends up in a film or a post. */
5
- export const marketingMessages = { en, pl };
6
-
7
- export type MarketingLocale = keyof typeof marketingMessages;
3
+ /** The built-in copy that ends up in a film or a post: English, the only built-in language. */
4
+ export const marketingMessages = { en };
8
5
 
9
6
  export type MarketingMessages = typeof en;
10
7
 
11
- export const MARKETING_LOCALES = Object.keys(marketingMessages) as MarketingLocale[];
8
+ /** The same shape with every key optional: `brand.messages`, an app's own translation or changed English copy. */
9
+ export type MarketingMessageOverrides = {
10
+ readonly [Group in keyof MarketingMessages]?: {
11
+ readonly [Key in keyof MarketingMessages[Group]]?: MarketingMessages[Group][Key] extends string
12
+ ? string
13
+ : { readonly [Leaf in keyof MarketingMessages[Group][Key]]?: string };
14
+ };
15
+ };
12
16
 
13
- export function getMarketingMessages(locale: MarketingLocale): MarketingMessages {
14
- return marketingMessages[locale];
17
+ /** The English copy with the app's overrides applied; a key the overrides leave out reads English. */
18
+ export function getMarketingMessages(overrides: MarketingMessageOverrides = {}): MarketingMessages {
19
+ return {
20
+ posts: { ...en.posts, ...overrides.posts, platforms: { ...en.posts.platforms, ...overrides.posts?.platforms } },
21
+ film: { ...en.film, ...overrides.film },
22
+ };
15
23
  }
16
24
 
17
25
  /** Replaces every `{name}` in `template` with its value; an unknown placeholder is a bug, so it throws. */
@@ -126,10 +126,39 @@ async function measureElement(page: Page, descriptor: LocatorDescriptor, key: st
126
126
  return { ok: true, rect };
127
127
  }
128
128
 
129
+ /** Rounding of the stretched element's edge against the frame's, in CSS pixels. */
130
+ const FILL_TOLERANCE_PX = 1;
131
+
132
+ /**
133
+ * `crop.fill`: stretches a target shorter than its frame (minus the top padding) to the frame's height and centres its
134
+ * content vertically, with `!important` inline styles in this browser only.
135
+ */
136
+ async function stretchToFrame(page: Page, crop: Crop, element: Rect): Promise<void> {
137
+ const frameHeight = Math.round(((element.width + 2 * crop.padding) * crop.aspect.height) / crop.aspect.width);
138
+ const height = frameHeight - crop.padding;
139
+ if (element.height >= height) return;
140
+ await getLocator(page, crop.target).evaluate((node, minHeight) => {
141
+ if (!(node instanceof HTMLElement)) return;
142
+ const styles: [string, string][] = [
143
+ ["box-sizing", "border-box"],
144
+ ["min-height", `${minHeight}px`],
145
+ ["display", "flex"],
146
+ ["flex-direction", "column"],
147
+ ["justify-content", "center"],
148
+ ];
149
+ for (const [property, value] of styles) node.style.setProperty(property, value, "important");
150
+ }, height);
151
+ }
152
+
129
153
  /** The crop's frame from its element (and `crop.top`'s top edge) and the page's scrollable size. */
130
154
  async function measureCrop(page: Page, crop: Crop): Promise<CropMeasure> {
131
- const element = await measureElement(page, crop.target, "crop.target");
155
+ let element = await measureElement(page, crop.target, "crop.target");
132
156
  if (!element.ok) return element;
157
+ if (crop.fill) {
158
+ await stretchToFrame(page, crop, element.rect);
159
+ element = await measureElement(page, crop.target, "crop.target");
160
+ if (!element.ok) return element;
161
+ }
133
162
  let top: number | undefined;
134
163
  if (crop.top !== undefined) {
135
164
  const topElement = await measureElement(page, crop.top, "crop.top");
@@ -137,7 +166,11 @@ async function measureCrop(page: Page, crop: Crop): Promise<CropMeasure> {
137
166
  top = topElement.rect.y;
138
167
  }
139
168
  const size = await page.evaluate(() => ({ width: document.documentElement.scrollWidth, height: document.documentElement.scrollHeight }));
140
- return findCropFrame({ element: element.rect, ...(top === undefined ? {} : { top }), page: size, aspect: crop.aspect, padding: crop.padding });
169
+ const frame = findCropFrame({ element: element.rect, ...(top === undefined ? {} : { top }), page: size, aspect: crop.aspect, padding: crop.padding });
170
+ if (!frame.ok || !crop.fill) return frame;
171
+ const gap = Math.round(frame.frame.y + frame.frame.height - (element.rect.y + element.rect.height));
172
+ if (gap > FILL_TOLERANCE_PX) return { ok: false, message: `crop.fill left crop.target ${gap} px short of the frame's bottom edge (it is not an HTML element, or a script reset its style)` };
173
+ return frame;
141
174
  }
142
175
 
143
176
  /**
@@ -7,7 +7,7 @@ import { getLocator } from "../record/locator.js";
7
7
  * Steps of the sign-in and of a screenshot entry, done in order on the page. A step that cannot be done (its
8
8
  * element never appears, matches several, is not an input, is not a `<details>`) is the page's or the config's
9
9
  * fault, so it comes back as a message naming the step; the message never carries a `fill` value, which may be a
10
- * password. `open` and `hide` act on every match of their target; the others need exactly one.
10
+ * password. `open`, `hide` and `flatten` act on every match of their target; the others need exactly one.
11
11
  */
12
12
 
13
13
  /** Long enough for a client-side page to render the element, short enough that a typo does not hang the run. */
@@ -32,6 +32,8 @@ async function runStep(page: Page, step: ShotStep): Promise<void> {
32
32
  return openEvery(getLocator(page, step.target));
33
33
  case "hide":
34
34
  return hideAllButLast(getLocator(page, step.target), step.keepLast);
35
+ case "flatten":
36
+ return flattenEvery(getLocator(page, step.target));
35
37
  }
36
38
  }
37
39
 
@@ -71,6 +73,18 @@ async function hideAllButLast(locator: Locator, keepLast: number): Promise<void>
71
73
  if (total <= keepLast) throw new Error(`matches ${total} elements, not more than keepLast ${keepLast}, so nothing would be hidden`);
72
74
  }
73
75
 
76
+ /** Drops the top border and top margin of every match, with `!important` like `hide`. */
77
+ async function flattenEvery(locator: Locator): Promise<void> {
78
+ await waitForMatches(locator);
79
+ await locator.evaluateAll((nodes) => {
80
+ for (const node of nodes) {
81
+ if (!(node instanceof HTMLElement || node instanceof SVGElement)) continue;
82
+ node.style.setProperty("border-top", "none", "important");
83
+ node.style.setProperty("margin-top", "0", "important");
84
+ }
85
+ });
86
+ }
87
+
74
88
  /** Null when every step was done; otherwise which one failed (`<where>[<index>] (<do>)`) and why. */
75
89
  export async function runShotSteps(page: Page, steps: readonly ShotStep[], where: string): Promise<string | null> {
76
90
  for (const [index, step] of steps.entries()) {
@@ -1,3 +0,0 @@
1
- import type { en } from "./en.js";
2
- export declare const pl: typeof en;
3
- //# sourceMappingURL=pl.d.ts.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"pl.d.ts","sourceRoot":"","sources":["../../src/messages/pl.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,SAAS,CAAC;AAGlC,eAAO,MAAM,EAAE,EAAE,OAAO,EAkBvB,CAAC"}
@@ -1,21 +0,0 @@
1
- // Polish copy lives only in message dictionaries; the language gate exempts `messages/` folders.
2
- export const pl = {
3
- posts: {
4
- title: "{title} — opisy postów",
5
- linkInBio: "Link w bio.",
6
- bioLink: "Link do bio: {link}",
7
- postLink: "Link w poście: {link}",
8
- platforms: {
9
- instagram: "Instagram (Reels)",
10
- facebook: "Facebook (Reels / post)",
11
- tiktok: "TikTok",
12
- youtube: "YouTube (Shorts)",
13
- linkedin: "LinkedIn",
14
- x: "X",
15
- },
16
- },
17
- film: {
18
- persona: "{name}, {age} lat",
19
- },
20
- };
21
- //# sourceMappingURL=pl.js.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"pl.js","sourceRoot":"","sources":["../../src/messages/pl.ts"],"names":[],"mappings":"AAEA,iGAAiG;AACjG,MAAM,CAAC,MAAM,EAAE,GAAc;IAC3B,KAAK,EAAE;QACL,KAAK,EAAE,wBAAwB;QAC/B,SAAS,EAAE,aAAa;QACxB,OAAO,EAAE,qBAAqB;QAC9B,QAAQ,EAAE,uBAAuB;QACjC,SAAS,EAAE;YACT,SAAS,EAAE,mBAAmB;YAC9B,QAAQ,EAAE,yBAAyB;YACnC,MAAM,EAAE,QAAQ;YAChB,OAAO,EAAE,kBAAkB;YAC3B,QAAQ,EAAE,UAAU;YACpB,CAAC,EAAE,GAAG;SACP;KACF;IACD,IAAI,EAAE;QACJ,OAAO,EAAE,mBAAmB;KAC7B;CACF,CAAC"}
@@ -1,22 +0,0 @@
1
- import type { en } from "./en.js";
2
-
3
- // Polish copy lives only in message dictionaries; the language gate exempts `messages/` folders.
4
- export const pl: typeof en = {
5
- posts: {
6
- title: "{title} — opisy postów",
7
- linkInBio: "Link w bio.",
8
- bioLink: "Link do bio: {link}",
9
- postLink: "Link w poście: {link}",
10
- platforms: {
11
- instagram: "Instagram (Reels)",
12
- facebook: "Facebook (Reels / post)",
13
- tiktok: "TikTok",
14
- youtube: "YouTube (Shorts)",
15
- linkedin: "LinkedIn",
16
- x: "X",
17
- },
18
- },
19
- film: {
20
- persona: "{name}, {age} lat",
21
- },
22
- };