@nodaro/shared 3.37.0 → 3.38.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 (86) hide show
  1. package/dist/{chunk-4XI6B4RU.js → chunk-2BHOAYZW.js} +17 -4
  2. package/dist/chunk-2BHOAYZW.js.map +1 -0
  3. package/dist/{chunk-M6JHRWVY.cjs → chunk-7VDPBFER.cjs} +19 -3
  4. package/dist/chunk-7VDPBFER.cjs.map +1 -0
  5. package/dist/{chunk-6Y66YM4M.cjs → chunk-AQA6YXY5.cjs} +39 -10
  6. package/dist/chunk-AQA6YXY5.cjs.map +1 -0
  7. package/dist/{chunk-YVKUCBY2.js → chunk-BDSFMY4X.js} +5 -18
  8. package/dist/chunk-BDSFMY4X.js.map +1 -0
  9. package/dist/chunk-BLZBDPZJ.js +16 -0
  10. package/dist/chunk-BLZBDPZJ.js.map +1 -0
  11. package/dist/{chunk-NARVPCWW.cjs → chunk-D33YBZ3B.cjs} +170 -143
  12. package/dist/chunk-D33YBZ3B.cjs.map +1 -0
  13. package/dist/{chunk-7Q75OZBL.cjs → chunk-HZ46RDLD.cjs} +9 -24
  14. package/dist/chunk-HZ46RDLD.cjs.map +1 -0
  15. package/dist/{chunk-WXNQMJ67.js → chunk-LOWOJN65.js} +100 -6
  16. package/dist/chunk-LOWOJN65.js.map +1 -0
  17. package/dist/chunk-M7G66F6H.js +17 -0
  18. package/dist/chunk-M7G66F6H.js.map +1 -0
  19. package/dist/chunk-PSAWDKO3.cjs +19 -0
  20. package/dist/chunk-PSAWDKO3.cjs.map +1 -0
  21. package/dist/{chunk-L6HS52BV.js → chunk-QLCSS6DK.js} +165 -141
  22. package/dist/chunk-QLCSS6DK.js.map +1 -0
  23. package/dist/chunk-T3TOSWVH.cjs +20 -0
  24. package/dist/chunk-T3TOSWVH.cjs.map +1 -0
  25. package/dist/{chunk-J65CAOUV.cjs → chunk-TGZJXCLL.cjs} +105 -5
  26. package/dist/chunk-TGZJXCLL.cjs.map +1 -0
  27. package/dist/{chunk-WD6AJ533.js → chunk-THGNDVVH.js} +29 -4
  28. package/dist/chunk-THGNDVVH.js.map +1 -0
  29. package/dist/entries/credits.cjs +135 -134
  30. package/dist/entries/credits.js +3 -2
  31. package/dist/entries/llm-models.cjs +72 -52
  32. package/dist/entries/llm-models.d.cts +50 -13
  33. package/dist/entries/llm-models.d.ts +50 -13
  34. package/dist/entries/llm-models.js +2 -2
  35. package/dist/entries/media.cjs +66 -42
  36. package/dist/entries/media.d.cts +145 -4
  37. package/dist/entries/media.d.ts +145 -4
  38. package/dist/entries/media.js +1 -1
  39. package/dist/entries/models.cjs +43 -27
  40. package/dist/entries/models.d.cts +53 -3
  41. package/dist/entries/models.d.ts +53 -3
  42. package/dist/entries/models.js +2 -2
  43. package/dist/entries/pipeline.d.cts +2 -2
  44. package/dist/entries/pipeline.d.ts +2 -2
  45. package/dist/entries/social.cjs +187 -174
  46. package/dist/entries/social.d.cts +26 -1
  47. package/dist/entries/social.d.ts +26 -1
  48. package/dist/entries/social.js +3 -2
  49. package/dist/index.cjs +499 -426
  50. package/dist/index.d.cts +6 -5
  51. package/dist/index.d.ts +6 -5
  52. package/dist/index.js +7 -6
  53. package/dist/{scene-node-types-Cvbtf-0a.d.cts → model-constants-C43YS07I.d.cts} +1 -497
  54. package/dist/{scene-node-types-Cvbtf-0a.d.ts → model-constants-C43YS07I.d.ts} +1 -497
  55. package/dist/scene-node-types-BSrTKnV7.d.cts +499 -0
  56. package/dist/scene-node-types-BSrTKnV7.d.ts +499 -0
  57. package/package.json +1 -1
  58. package/src/__tests__/cast-swap-limits.test.ts +40 -0
  59. package/src/__tests__/fixtures/root-exports.baseline.json +6 -0
  60. package/src/__tests__/llm-models.test.ts +8 -8
  61. package/src/__tests__/llm-price-key.test.ts +55 -0
  62. package/src/__tests__/scrape-analysis-pricing.test.ts +41 -0
  63. package/src/__tests__/video-mask.test.ts +27 -0
  64. package/src/cast-swap-limits.ts +52 -0
  65. package/src/entries/llm-models.ts +4 -0
  66. package/src/entries/models.ts +7 -1
  67. package/src/entries/social.ts +1 -0
  68. package/src/llm-models.ts +61 -13
  69. package/src/mask-composite.ts +80 -3
  70. package/src/scrape-analysis-pricing.ts +73 -0
  71. package/src/script-model.ts +21 -0
  72. package/src/video-mask.ts +97 -0
  73. package/dist/chunk-4XI6B4RU.js.map +0 -1
  74. package/dist/chunk-6Y66YM4M.cjs.map +0 -1
  75. package/dist/chunk-7Q75OZBL.cjs.map +0 -1
  76. package/dist/chunk-FG4E7MTG.cjs +0 -4
  77. package/dist/chunk-FG4E7MTG.cjs.map +0 -1
  78. package/dist/chunk-J65CAOUV.cjs.map +0 -1
  79. package/dist/chunk-L6HS52BV.js.map +0 -1
  80. package/dist/chunk-M6JHRWVY.cjs.map +0 -1
  81. package/dist/chunk-NARVPCWW.cjs.map +0 -1
  82. package/dist/chunk-TZE673G6.js +0 -3
  83. package/dist/chunk-TZE673G6.js.map +0 -1
  84. package/dist/chunk-WD6AJ533.js.map +0 -1
  85. package/dist/chunk-WXNQMJ67.js.map +0 -1
  86. package/dist/chunk-YVKUCBY2.js.map +0 -1
@@ -0,0 +1,41 @@
1
+ import { describe, it, expect } from "vitest"
2
+ import { scrapeAnalysisPriceParts, scrapeAnalysisQuoteId, SCRAPE_ANALYSIS_FEATURE } from "../scrape-analysis-pricing.js"
3
+ import { buildMetaAdsScrapeCreditId, META_ADS_SCRAPE_MAX_COUNT } from "../meta-ads-scrape.js"
4
+ import { buildInstagramScrapeCreditId, INSTAGRAM_SCRAPE_MAX_COUNT } from "../instagram-scrape.js"
5
+ import { LLM_FEATURE_DEFAULTS } from "../llm-models.js"
6
+ import { resolveScriptModelId, SCRIPT_LEGACY_PROVIDER_MODELS } from "../script-model.js"
7
+
8
+ describe("scrapeAnalysisPriceParts — a scrape's analysis billed per call", () => {
9
+ it("no analysis, or another node: null", () => {
10
+ expect(scrapeAnalysisPriceParts({ type: "meta-ads-scrape", data: { count: 10 } })).toBeNull()
11
+ expect(scrapeAnalysisPriceParts({ type: "llm-chat", data: { analyze: true } })).toBeNull()
12
+ })
13
+ it("Meta Ads: its fixed scrape (no analysis suffix), the analysis model, count × sources items (clamped)", () => {
14
+ expect(scrapeAnalysisPriceParts({ type: "meta-ads-scrape", data: { count: 10, analyze: true } })).toEqual({
15
+ fixedId: buildMetaAdsScrapeCreditId({ count: 10, sources: 1 }),
16
+ analysisModel: LLM_FEATURE_DEFAULTS[SCRAPE_ANALYSIS_FEATURE],
17
+ items: 10,
18
+ })
19
+ expect(scrapeAnalysisPriceParts({ type: "meta-ads-scrape", data: { count: 9999, analyze: true, analysisModel: "claude-opus-5.5" } })).toMatchObject({ analysisModel: "claude-opus-5.5", items: META_ADS_SCRAPE_MAX_COUNT })
20
+ })
21
+ it("Instagram: the count the route accepts × the targets", () => {
22
+ const parts = scrapeAnalysisPriceParts({ type: "instagram-scrape", data: { count: 500, analyze: true, mode: "profile", targets: "a\nb" } })
23
+ expect(parts).toEqual({ fixedId: buildInstagramScrapeCreditId({ count: INSTAGRAM_SCRAPE_MAX_COUNT, sources: 2 }), analysisModel: LLM_FEATURE_DEFAULTS[SCRAPE_ANALYSIS_FEATURE], items: INSTAGRAM_SCRAPE_MAX_COUNT * 2 })
24
+ })
25
+ })
26
+
27
+ describe("scrapeAnalysisQuoteId — the whole analysis as one price id", () => {
28
+ it("is the analysis model's metered key as a `<key>:<items>u` quote", () => {
29
+ const parts = scrapeAnalysisPriceParts({ type: "meta-ads-scrape", data: { count: 10, analyze: true, analysisModel: "claude-opus-5.5" } })!
30
+ expect(scrapeAnalysisQuoteId(parts)).toBe(`${SCRAPE_ANALYSIS_FEATURE}:claude-opus-5.5:10u`)
31
+ })
32
+ })
33
+
34
+ describe("resolveScriptModelId — the model a Generate Script call runs on", () => {
35
+ it("an explicit model, else a legacy provider's, else the default", () => {
36
+ expect(resolveScriptModelId("claude", "gpt-5.2")).toBe("gpt-5.2")
37
+ expect(resolveScriptModelId("claude")).toBe(SCRIPT_LEGACY_PROVIDER_MODELS.claude)
38
+ expect(resolveScriptModelId()).toBe(LLM_FEATURE_DEFAULTS["generate-script"])
39
+ expect(resolveScriptModelId("toString")).toBe(LLM_FEATURE_DEFAULTS["generate-script"])
40
+ })
41
+ })
@@ -2,9 +2,11 @@ import { describe, it, expect } from "vitest"
2
2
  import { readFileSync } from "node:fs"
3
3
  import { resolve } from "node:path"
4
4
  import {
5
+ VIDEO_MASK_DEFAULTS,
5
6
  VIDEO_MASK_LIMITS,
6
7
  VIDEO_MASK_PROVIDERS,
7
8
  resolveVideoMaskProvider,
9
+ resolveVideoMaskZone,
8
10
  videoMaskBilledSeconds,
9
11
  videoMaskCreditId,
10
12
  videoMaskCreditIds,
@@ -65,6 +67,31 @@ describe("Video Mask pricing", () => {
65
67
  })
66
68
  })
67
69
 
70
+ describe("Video Mask zone", () => {
71
+ it("is off by default, and each margin is 0–49 % (the inner rectangle can never be empty)", () => {
72
+ expect(VIDEO_MASK_DEFAULTS.zone).toBeNull()
73
+ expect(VIDEO_MASK_LIMITS.ZONE_MARGIN_PCT_MIN).toBe(0)
74
+ expect(VIDEO_MASK_LIMITS.ZONE_MARGIN_PCT_MAX).toBe(49)
75
+ expect(VIDEO_MASK_LIMITS.ZONE_MARGIN_PCT_MAX * 2).toBeLessThan(100)
76
+ })
77
+
78
+ it("resolveVideoMaskZone reads a zone as the filter does: margins clamped to 0–49, anything else 0, all 0 = null", () => {
79
+ expect(resolveVideoMaskZone({ leftPct: 10, rightPct: 20, topPct: 5, bottomPct: 0 })).toEqual({ leftPct: 10, rightPct: 20, topPct: 5, bottomPct: 0 })
80
+ expect(resolveVideoMaskZone({ leftPct: 80, rightPct: -3 })).toEqual({ leftPct: 49, rightPct: 0, topPct: 0, bottomPct: 0 })
81
+ expect(resolveVideoMaskZone({ leftPct: "10", topPct: Number.NaN, bottomPct: Infinity })).toBeNull()
82
+ expect(resolveVideoMaskZone({ leftPct: 0, rightPct: 0, topPct: 0, bottomPct: 0 })).toBeNull()
83
+ expect(resolveVideoMaskZone(null)).toBeNull()
84
+ expect(resolveVideoMaskZone(undefined)).toBeNull()
85
+ expect(resolveVideoMaskZone("10,10,10,10")).toBeNull()
86
+ })
87
+ })
88
+
89
+ describe("Video Mask perShot", () => {
90
+ it("is off by default (one pass over the whole clip)", () => {
91
+ expect(VIDEO_MASK_DEFAULTS.perShot).toBe(false)
92
+ })
93
+ })
94
+
68
95
  describe("Mask Composite units", () => {
69
96
  // Repeated in docs/nodes/processing-video/mask-composite.md (at the 10-credit row).
70
97
  it.each([[3, 1], [5, 1], [10, 2], [10.0000001, 2], [61, 13], [300, 60]])("%s s → %s unit(s)", (sec, units) => {
@@ -0,0 +1,52 @@
1
+ /**
2
+ * Cast Swap's input limits, and what a trend built on it may put in its
3
+ * prompts. One definition read by the server (which enforces them) and by
4
+ * every screen that edits them (which holds Save before a refusal), so the two
5
+ * cannot drift apart.
6
+ */
7
+
8
+ /** The longest `postPrompt` Cast Swap takes. */
9
+ export const CAST_SWAP_POST_PROMPT_MAX = 4000
10
+
11
+ /**
12
+ * A trend's prompt limits.
13
+ *
14
+ * - `trendPromptMax` / `prePromptMax`: the longest prompt a trend version may
15
+ * store.
16
+ * - `detailsMax`: the longest details a user may add to a run. They follow the
17
+ * trend prompt in Cast Swap's `postPrompt`, after a blank line, so a new
18
+ * trend prompt is held to `CAST_SWAP_POST_PROMPT_MAX − 2 − detailsMax`.
19
+ * - `engineTextReserve`: the room kept for the text Cast Swap writes around a
20
+ * trend's prompts in the prompt it builds, at its longest (a block for each
21
+ * of the 13 roles a run allows with 200-character role names, five
22
+ * 500-character reference lines, the keep, mask and edit lines and the
23
+ * header: about 16,100 characters, rounded up so a small wording change does
24
+ * not need this moved). The pre prompt, the trend prompt and the details
25
+ * share what is left of Seedance 2.5's prompt cap.
26
+ */
27
+ export const TREND_PROMPT_LIMITS = {
28
+ trendPromptMax: 3000,
29
+ prePromptMax: 3000,
30
+ detailsMax: 1000,
31
+ engineTextReserve: 17_000,
32
+ } as const
33
+
34
+ /** Cast Swap's `faceMasking` bounds, each `[min, max]` inclusive. */
35
+ export const CAST_SWAP_FACE_MASKING_BOUNDS = {
36
+ /** `minFaceHeightPct` and `maxFaceHeightPct`, % of the frame's height (max 0 = no limit). */
37
+ faceHeightPct: [0, 100],
38
+ /** Each `zone` margin, % of the frame. */
39
+ zonePct: [0, 49],
40
+ /** % of the frame's width. */
41
+ blurStrengthPct: [0.1, 5],
42
+ threshold: [0.05, 0.95],
43
+ } as const satisfies Record<string, readonly [number, number]>
44
+
45
+ /** What Cast Swap uses for a `faceMasking` setting left out. */
46
+ export const CAST_SWAP_FACE_MASKING_DEFAULTS = {
47
+ minFaceHeightPct: 15,
48
+ maxFaceHeightPct: 0,
49
+ zonePct: 0,
50
+ blurStrengthPct: 2,
51
+ threshold: 0.5,
52
+ } as const
@@ -50,6 +50,9 @@ export {
50
50
  resolveLlmCreditId,
51
51
  supportsAdvancedMode,
52
52
  llmServesDirect,
53
+ llmPriceKey,
54
+ LLM_FEATURE_DEFAULTS_FROM,
55
+ llmDefaultsFeature,
53
56
  LLM_CREDIT_RUNGS,
54
57
  type LlmCreditRung,
55
58
  llmCreditIdForRung,
@@ -69,3 +72,4 @@ export {
69
72
  type LlmModelDef,
70
73
  type LlmReasoningEffort,
71
74
  } from "../llm-models.js"
75
+ export { SCRIPT_LEGACY_PROVIDER_MODELS, resolveScriptModelId } from "../script-model.js"
@@ -1,5 +1,5 @@
1
1
  /**
2
- * `@nodaro/shared/models` — Model constants: provider lists, prompt limits, per-model capability tables and defaults.
2
+ * `@nodaro/shared/models` — Model constants: provider lists, prompt limits, per-model capability tables and defaults, Cast Swap's input limits.
3
3
  *
4
4
  * One of the package's subpath entries (see `src/index.ts`). The root
5
5
  * re-exports every entry, so each name here is also importable from
@@ -197,6 +197,12 @@ export {
197
197
  maxVideoDurationSec,
198
198
  PRICING_DEFAULT_RESOLUTION,
199
199
  } from "../model-constants.js"
200
+ export {
201
+ CAST_SWAP_POST_PROMPT_MAX,
202
+ TREND_PROMPT_LIMITS,
203
+ CAST_SWAP_FACE_MASKING_BOUNDS,
204
+ CAST_SWAP_FACE_MASKING_DEFAULTS,
205
+ } from "../cast-swap-limits.js"
200
206
  export type {
201
207
  ImageAspectRatio,
202
208
  ImageResolution,
@@ -6,6 +6,7 @@
6
6
  * `@nodaro/shared`.
7
7
  */
8
8
  export { normalizePinterestUrl } from "../pinterest-url.js"
9
+ export { SCRAPE_ANALYSIS_FEATURE, scrapeAnalysisPriceParts, scrapeAnalysisQuoteId, type ScrapeAnalysisPriceParts } from "../scrape-analysis-pricing.js"
9
10
  export { SCRAPER_OUTPUT_FIELDS } from "../scraper-output-schemas.js"
10
11
  export {
11
12
  SOCIAL_POST_NODE_TYPES,
package/src/llm-models.ts CHANGED
@@ -1064,27 +1064,30 @@ export const STRUCTURED_VISION_MODELS = LLM_MODELS.filter(
1064
1064
 
1065
1065
  /**
1066
1066
  * Models {@link STRUCTURED_VISION_MODELS} carries that describe-to-picker does
1067
- * NOT offer. Its analyzer prompt is a rendered catalog legend — tens of
1068
- * thousands of input tokens per read — and on these models a single read
1069
- * costs far above what any of the node's credit rungs covers (production cost
1070
- * audit, 2026-10-20; the basis is in backend/src/ee/billing/credits.ts).
1071
- * Withheld from this feature only: the scrapers' per-post analysis reads a
1072
- * frame and a caption, not a legend, and keeps the whole list.
1067
+ * NOT offer — now none.
1068
+ *
1069
+ * Claude Fable 5 was withheld here (production cost audit, 2026-10-20): a
1070
+ * legend-sized read cost far above every tier rung. Metered pricing charges
1071
+ * each read what it really costs (tokens × the model's rate on the lane that
1072
+ * served it), so nothing needs withholding and the set is empty.
1073
+ *
1074
+ * @deprecated Always empty since metered LLM pricing. Kept exported so existing
1075
+ * importers keep compiling; it will be removed in a future major.
1073
1076
  */
1074
- export const DESCRIBE_TO_PICKER_WITHHELD_MODELS: ReadonlySet<string> = new Set(["claude-fable-5"])
1077
+ export const DESCRIBE_TO_PICKER_WITHHELD_MODELS: ReadonlySet<string> = new Set<string>()
1075
1078
 
1076
1079
  /**
1077
- * The same models, withheld from the other legend-sized structured reads for
1078
- * the same reason: `POST /v1/text-to-picker` (describe-to-picker's text twin,
1079
- * whose default run analyzes every picker's legend) and `POST /v1/llm/structured`
1080
- * (a caller's own legend-sized system prompt). One set, so a model withheld
1081
- * from one read of that size is withheld from all of them.
1080
+ * The same (empty) set for the other legend-sized structured reads:
1081
+ * `POST /v1/text-to-picker` and `POST /v1/llm/structured`.
1082
+ *
1083
+ * @deprecated Always empty since metered LLM pricing; see
1084
+ * {@link DESCRIBE_TO_PICKER_WITHHELD_MODELS}.
1082
1085
  */
1083
1086
  export const LLM_STRUCTURED_WITHHELD_MODELS: ReadonlySet<string> = DESCRIBE_TO_PICKER_WITHHELD_MODELS
1084
1087
 
1085
1088
  /**
1086
1089
  * The models describe-to-picker offers and accepts: the structured vision
1087
- * models minus {@link DESCRIBE_TO_PICKER_WITHHELD_MODELS}. The ONE list the
1090
+ * models minus {@link DESCRIBE_TO_PICKER_WITHHELD_MODELS} (empty — every one). The ONE list the
1088
1091
  * route gate, the config panel and the quick strip read, so a model the route
1089
1092
  * refuses is never offered and a saved node naming one is snapped to the
1090
1093
  * default (the route answers it with a `validation_error`).
@@ -1229,6 +1232,24 @@ export const LLM_FEATURE_DEFAULTS: Record<LlmFeature, string> = {
1229
1232
  "content-ideas": "gemini-3.6-flash",
1230
1233
  }
1231
1234
 
1235
+ /**
1236
+ * Billed features with no defaults of their own → the feature whose defaults
1237
+ * (model, {@link LLM_FEATURE_DEFAULT_EFFORTS} effort) their route borrows:
1238
+ * Generate Structured runs on Generate Text's, Text to Picker on Describe to
1239
+ * Picker's, the Choose Best judge on `pick-best-llm`'s. Read it through
1240
+ * {@link llmDefaultsFeature}. Structure only — no prices.
1241
+ */
1242
+ export const LLM_FEATURE_DEFAULTS_FROM: Readonly<Record<string, LlmFeature>> = {
1243
+ "llm-structured": "llm-chat",
1244
+ "text-to-picker": "describe-to-picker",
1245
+ "reduce:pick-best-llm": "pick-best-llm",
1246
+ }
1247
+
1248
+ /** The feature whose defaults a call of `feature` runs with: its {@link LLM_FEATURE_DEFAULTS_FROM} entry, else itself. */
1249
+ export function llmDefaultsFeature(feature: string): string {
1250
+ return Object.hasOwn(LLM_FEATURE_DEFAULTS_FROM, feature) ? LLM_FEATURE_DEFAULTS_FROM[feature]! : feature
1251
+ }
1252
+
1232
1253
  /**
1233
1254
  * The model describe-to-picker re-asks ONCE when a Claude analyzer could not
1234
1255
  * answer for a platform-side reason: its direct lane down or the platform's
@@ -1547,6 +1568,33 @@ export function llmServesDirect(
1547
1568
  )
1548
1569
  }
1549
1570
 
1571
+ /**
1572
+ * The price key of a metered LLM call — what a client asks
1573
+ * `POST /v1/credits/model-costs` (or `GET /v1/credits/model-cost?model=`) for
1574
+ * the call's estimated price: `<feature>:<modelId>`, plus `:direct` when the
1575
+ * call is served on the vendor's own API ({@link llmServesDirect}), which is
1576
+ * priced at the direct rate.
1577
+ *
1578
+ * With no `reasoningEffort` the default effort of the feature the call
1579
+ * borrows its defaults from applies ({@link llmDefaultsFeature},
1580
+ * {@link defaultReasoningEffort}) — the effort the call then runs at — so the
1581
+ * key names the lane the call is held and charged on.
1582
+ *
1583
+ * `modelId` must already be resolved: the model the call runs on, never empty
1584
+ * (a caller with no model passes the feature's default, `LLM_FEATURE_DEFAULTS`
1585
+ * of {@link llmDefaultsFeature}). An empty id throws a `TypeError`.
1586
+ */
1587
+ export function llmPriceKey(
1588
+ feature: string,
1589
+ modelId: string,
1590
+ reasoningEffort?: string,
1591
+ advancedMode?: boolean,
1592
+ ): string {
1593
+ if (!modelId) throw new TypeError(`llmPriceKey: modelId must be a resolved model id (feature "${feature}")`)
1594
+ const effort = reasoningEffort ?? defaultReasoningEffort(llmDefaultsFeature(feature), modelId)
1595
+ return llmServesDirect(modelId, effort, advancedMode) ? `${feature}:${modelId}:direct` : `${feature}:${modelId}`
1596
+ }
1597
+
1550
1598
  /**
1551
1599
  * The credit rungs an LLM feature bills on, cheapest first. `premium-direct` is
1552
1600
  * reached only by a premium model served direct (decided 2026-10-08): the bump
@@ -10,6 +10,15 @@
10
10
  * background is fitted to that frame (`backgroundFit`) and loops when shorter;
11
11
  * the mask is stretched to the frame and holds its last frame when shorter.
12
12
  *
13
+ * `fill` picks what fills the masked area. `"video"` (the default) is the
14
+ * foreground, as above. `"pixelate"` and `"blur"` fill it with the BACKGROUND
15
+ * itself, pixelated or blurred: there is no foreground then (a sent
16
+ * `foregroundUrl` is ignored), so the render follows the BACKGROUND (its size,
17
+ * frame rate and length; `backgroundFit` has nothing to fit), and the run is
18
+ * priced on the background's length. With no foreground the result always
19
+ * carries the background's sound — `audioSource` is ignored there
20
+ * ({@link maskCompositeEffectiveAudioSource}); the canvas hides the control.
21
+ *
13
22
  * Priced per started 5 seconds of the result (the foreground's length), like
14
23
  * Trim / Loop / Combine Videos: the node's own `model_pricing` row is ONE unit
15
24
  * (`maskCompositeUnits` counts them). Worked examples (repeated in
@@ -23,6 +32,10 @@
23
32
  export const MASK_COMPOSITE_BACKGROUND_FITS = ["cover", "contain", "stretch"] as const
24
33
  export type MaskCompositeBackgroundFit = (typeof MASK_COMPOSITE_BACKGROUND_FITS)[number]
25
34
 
35
+ /** What fills the masked area: the foreground video, or the background itself pixelated or blurred. */
36
+ export const MASK_COMPOSITE_FILLS = ["video", "pixelate", "blur"] as const
37
+ export type MaskCompositeFill = (typeof MASK_COMPOSITE_FILLS)[number]
38
+
26
39
  /** Which sound the result carries. `mix` blends both tracks at equal level. */
27
40
  export const MASK_COMPOSITE_AUDIO_SOURCES = ["foreground", "background", "mix", "none"] as const
28
41
  export type MaskCompositeAudioSource = (typeof MASK_COMPOSITE_AUDIO_SOURCES)[number]
@@ -34,7 +47,19 @@ export const MASK_COMPOSITE_BOUNDS = {
34
47
  /** Grow (+) or shrink (−) the white region, pixels. */
35
48
  GROW_MIN: -10,
36
49
  GROW_MAX: 10,
37
- /** The longest foreground a run accepts, seconds. */
50
+ /** How strongly the foreground covers the background inside the mask
51
+ * (1 = fully, today's output; 0 = not at all). */
52
+ OPACITY_MIN: 0,
53
+ OPACITY_MAX: 1,
54
+ /** Pixelate: the block size as a % of the frame's WIDTH (relative, so a
55
+ * setting looks the same at any resolution); the worker makes the blocks
56
+ * max(2, round(width × pct / 100)) px. 1.25 % = 16 px on a 1280-wide frame. */
57
+ PIXEL_SIZE_PCT_MIN: 0.2,
58
+ PIXEL_SIZE_PCT_MAX: 10,
59
+ /** Blur: the gaussian's sigma as a % of the frame's WIDTH (2 % ≈ sigma 25 px on a 1280-wide frame). */
60
+ BLUR_STRENGTH_PCT_MIN: 0.1,
61
+ BLUR_STRENGTH_PCT_MAX: 5,
62
+ /** The longest leading video (the foreground; the background when `fill` is not video) a run accepts, seconds. */
38
63
  MAX_DURATION_SEC: 300,
39
64
  } as const
40
65
 
@@ -60,6 +85,10 @@ export const MASK_COMPOSITE_DEFAULTS = {
60
85
  invertMask: false,
61
86
  feather: 2,
62
87
  grow: 0,
88
+ opacity: 1,
89
+ fill: "video" as MaskCompositeFill,
90
+ pixelSizePct: 1.25,
91
+ blurStrengthPct: 2,
63
92
  backgroundFit: "cover" as MaskCompositeBackgroundFit,
64
93
  audioSource: "foreground" as MaskCompositeAudioSource,
65
94
  } as const
@@ -68,6 +97,14 @@ export interface MaskCompositeSettings {
68
97
  readonly invertMask: boolean
69
98
  readonly feather: number
70
99
  readonly grow: number
100
+ /** Inside the mask: opacity × foreground + (1 − opacity) × background. */
101
+ readonly opacity: number
102
+ /** What fills the masked area (`video` = the foreground). */
103
+ readonly fill: MaskCompositeFill
104
+ /** Pixelate block size, % of the frame width (used when `fill` is `pixelate`). */
105
+ readonly pixelSizePct: number
106
+ /** Blur strength: the gaussian's sigma as a % of the frame width (used when `fill` is `blur`). */
107
+ readonly blurStrengthPct: number
71
108
  readonly backgroundFit: MaskCompositeBackgroundFit
72
109
  readonly audioSource: MaskCompositeAudioSource
73
110
  }
@@ -75,6 +112,9 @@ export interface MaskCompositeSettings {
75
112
  const clampInt = (v: unknown, min: number, max: number, fallback: number): number =>
76
113
  typeof v === "number" && Number.isFinite(v) ? Math.min(max, Math.max(min, Math.round(v))) : fallback
77
114
 
115
+ const clampNumber = (v: unknown, min: number, max: number, fallback: number): number =>
116
+ typeof v === "number" && Number.isFinite(v) ? Math.min(max, Math.max(min, v)) : fallback
117
+
78
118
  /**
79
119
  * Node data (or any loose object) → settings every engine renders with.
80
120
  * Unknown enum values fall back to the default and numbers are clamped, so a
@@ -88,6 +128,10 @@ export function resolveMaskCompositeSettings(data: Readonly<Record<string, unkno
88
128
  invertMask: typeof data.invertMask === "boolean" ? data.invertMask : d.invertMask,
89
129
  feather: clampInt(data.feather, b.FEATHER_MIN, b.FEATHER_MAX, d.feather),
90
130
  grow: clampInt(data.grow, b.GROW_MIN, b.GROW_MAX, d.grow),
131
+ opacity: clampNumber(data.opacity, b.OPACITY_MIN, b.OPACITY_MAX, d.opacity),
132
+ fill: maskCompositeFillOf(data),
133
+ pixelSizePct: clampNumber(data.pixelSizePct, b.PIXEL_SIZE_PCT_MIN, b.PIXEL_SIZE_PCT_MAX, d.pixelSizePct),
134
+ blurStrengthPct: clampNumber(data.blurStrengthPct, b.BLUR_STRENGTH_PCT_MIN, b.BLUR_STRENGTH_PCT_MAX, d.blurStrengthPct),
91
135
  backgroundFit: (MASK_COMPOSITE_BACKGROUND_FITS as readonly string[]).includes(data.backgroundFit as string)
92
136
  ? (data.backgroundFit as MaskCompositeBackgroundFit)
93
137
  : d.backgroundFit,
@@ -97,10 +141,43 @@ export function resolveMaskCompositeSettings(data: Readonly<Record<string, unkno
97
141
  }
98
142
  }
99
143
 
144
+ /** The fill a node, payload or request body asks for: an unknown value is `video` (the default). */
145
+ export function maskCompositeFillOf(data: Readonly<Record<string, unknown>> | null | undefined): MaskCompositeFill {
146
+ const f = data?.fill
147
+ return (MASK_COMPOSITE_FILLS as readonly string[]).includes(f as string) ? (f as MaskCompositeFill) : MASK_COMPOSITE_DEFAULTS.fill
148
+ }
149
+
150
+ /** Does this fill take a foreground video? Only `video` does; pixelate and blur fill from the background. */
151
+ export function maskCompositeUsesForeground(fill: MaskCompositeFill): boolean {
152
+ return fill === "video"
153
+ }
154
+
155
+ /**
156
+ * The input whose size, rate and length the result has (and so the one a run
157
+ * is measured and priced on): the canvas handle — `video` (the foreground) for
158
+ * the video fill, `background-video` for pixelate and blur. The one rule the
159
+ * route, the workflow run, the run estimates and the length walks read.
160
+ */
161
+ export function maskCompositeLeadHandle(data: Readonly<Record<string, unknown>> | null | undefined): "video" | "background-video" {
162
+ return maskCompositeUsesForeground(maskCompositeFillOf(data)) ? "video" : "background-video"
163
+ }
164
+
165
+ /**
166
+ * The sound a render actually carries. With no foreground (pixelate / blur) it
167
+ * is ALWAYS the background's — the only track there is — whatever
168
+ * `audioSource` says (the canvas hides that control for these fills, so a
169
+ * stored `none` from the Video fill can never silently mute the result).
170
+ */
171
+ export function maskCompositeEffectiveAudioSource(s: Pick<MaskCompositeSettings, "fill" | "audioSource">): MaskCompositeAudioSource {
172
+ if (maskCompositeUsesForeground(s.fill)) return s.audioSource
173
+ return "background"
174
+ }
175
+
100
176
  /** `POST /v1/mask-composite` request body. */
101
177
  export interface MaskCompositeRequest extends Partial<MaskCompositeSettings> {
102
- /** The video whose white-masked region is kept (its size, rate and length lead). */
103
- readonly foregroundUrl: string
178
+ /** The video whose white-masked region is kept (its size, rate and length lead).
179
+ * Required when `fill` is `video` (the default); not used by `pixelate` / `blur`. */
180
+ readonly foregroundUrl?: string
104
181
  /** The video shown where the mask is black. */
105
182
  readonly backgroundUrl: string
106
183
  /** The mask video — white = foreground (Video Mask's output). */
@@ -0,0 +1,73 @@
1
+ /**
2
+ * The two price parts of a Meta Ads or Instagram scrape with AI analysis while
3
+ * metered LLM pricing is on: the scrape's own fixed id (no analysis suffix), and
4
+ * the requested items, each analysed by one call of the analysis model — the
5
+ * item count and model both routes hold through `reserveFixedPlusLlmCalls`
6
+ * (the analysis feature `meta-ads-analysis`, both scrapes). ONE rule for the
7
+ * server's estimate and the editor's, so the two can never price a scrape
8
+ * apart. Pure; null for a scrape without analysis and for any other node.
9
+ */
10
+ import { LLM_FEATURE_DEFAULTS, llmPriceKey } from "./llm-models.js"
11
+ import { unitQuoteCreditId } from "./credit-estimators/unit-quote.js"
12
+ import {
13
+ META_ADS_SCRAPE_DEFAULT_COUNT,
14
+ META_ADS_SCRAPE_MAX_COUNT,
15
+ META_ADS_SCRAPE_MAX_SOURCES,
16
+ buildMetaAdsScrapeCreditId,
17
+ metaAdsAnalysisTierFrom,
18
+ metaAdsScrapeSources,
19
+ } from "./meta-ads-scrape.js"
20
+ import {
21
+ INSTAGRAM_SCRAPE_DEFAULT_COUNT,
22
+ INSTAGRAM_SCRAPE_MAX_COUNT,
23
+ buildInstagramScrapeCreditId,
24
+ instagramAnalysisTierFrom,
25
+ instagramRequestedCount,
26
+ instagramScrapeMode,
27
+ instagramScrapeSources,
28
+ } from "./instagram-scrape.js"
29
+
30
+ /** The analysis feature both scrapes bill their per-item analysis under. */
31
+ export const SCRAPE_ANALYSIS_FEATURE = "meta-ads-analysis"
32
+
33
+ export interface ScrapeAnalysisPriceParts {
34
+ /** The scrape's own fixed credit id (no analysis suffix). */
35
+ readonly fixedId: string
36
+ /** The model every item's analysis call runs on. */
37
+ readonly analysisModel: string
38
+ /** How many analysis calls the run holds: the items requested. */
39
+ readonly items: number
40
+ }
41
+
42
+ const clamp = (n: number, max: number) => Math.min(Math.max(Math.trunc(n) || 1, 1), max)
43
+
44
+ export function scrapeAnalysisPriceParts(node: { readonly type?: string; readonly data?: Record<string, unknown> }): ScrapeAnalysisPriceParts | null {
45
+ const data = node.data ?? {}
46
+ const analysisModel = typeof data.analysisModel === "string" && data.analysisModel ? data.analysisModel : LLM_FEATURE_DEFAULTS[SCRAPE_ANALYSIS_FEATURE]
47
+ if (node.type === "meta-ads-scrape" && metaAdsAnalysisTierFrom(data)) {
48
+ const count = typeof data.count === "number" ? data.count : META_ADS_SCRAPE_DEFAULT_COUNT
49
+ const sources = metaAdsScrapeSources(data)
50
+ return { fixedId: buildMetaAdsScrapeCreditId({ count, sources }), analysisModel, items: clamp(count, META_ADS_SCRAPE_MAX_COUNT) * clamp(sources, META_ADS_SCRAPE_MAX_SOURCES) }
51
+ }
52
+ if (node.type === "instagram-scrape" && instagramAnalysisTierFrom(data)) {
53
+ // The count the route accepts (its Zod: 1..INSTAGRAM_SCRAPE_MAX_COUNT), as the run sends it.
54
+ const stored = typeof data.count === "number" ? data.count : INSTAGRAM_SCRAPE_DEFAULT_COUNT
55
+ const count = instagramRequestedCount(instagramScrapeMode(data.mode as string | undefined), clamp(stored, INSTAGRAM_SCRAPE_MAX_COUNT))
56
+ const sources = instagramScrapeSources(data)
57
+ return { fixedId: buildInstagramScrapeCreditId({ count, sources }), analysisModel, items: Math.max(1, count * sources) }
58
+ }
59
+ return null
60
+ }
61
+
62
+ /**
63
+ * The whole analysis of a scrape as ONE price id: `<analysis key>:<items>u`
64
+ * (`unitQuoteCreditId` on the analysis model's metered price key). The server
65
+ * prices it as the run is held: the key's estimate × the items, rounded up
66
+ * once, marked up once at the call's charge id — so a client quotes the
67
+ * scrape's fixed id plus this, never the served one-call estimate × the items
68
+ * (rounded up per call, and marked up per call). Answered as an estimate while
69
+ * metered pricing is on; `missing` under the rollback.
70
+ */
71
+ export function scrapeAnalysisQuoteId(parts: ScrapeAnalysisPriceParts): string {
72
+ return unitQuoteCreditId(llmPriceKey(SCRAPE_ANALYSIS_FEATURE, parts.analysisModel), parts.items)
73
+ }
@@ -0,0 +1,21 @@
1
+ /**
2
+ * The model a Generate Script call runs on, in one place: an explicit
3
+ * `llmModel`, else a legacy script `provider` alias (nodes saved before the
4
+ * per-model picker), else the feature's default. The route validates against
5
+ * it, the worker runs it, and the server's estimate and the editor's price it —
6
+ * one rule, so none of them can name a different model.
7
+ */
8
+ import { LLM_FEATURE_DEFAULTS } from "./llm-models.js"
9
+ import type { ScriptProvider } from "./model-constants.js"
10
+
11
+ /** Legacy provider names → the LLM model ids they ran. */
12
+ export const SCRIPT_LEGACY_PROVIDER_MODELS: Readonly<Record<ScriptProvider, string>> = {
13
+ gemini: "gemini-3.6-flash",
14
+ claude: "claude-sonnet-4.6",
15
+ gpt: "gpt-5.2",
16
+ }
17
+
18
+ export function resolveScriptModelId(provider?: string, llmModel?: string): string {
19
+ const legacy = provider && Object.hasOwn(SCRIPT_LEGACY_PROVIDER_MODELS, provider) ? SCRIPT_LEGACY_PROVIDER_MODELS[provider as ScriptProvider] : undefined
20
+ return llmModel || legacy || LLM_FEATURE_DEFAULTS["generate-script"]
21
+ }
package/src/video-mask.ts CHANGED
@@ -23,10 +23,39 @@ export const VIDEO_MASK_PROVIDERS = ["sam-3.1", "sam-3"] as const
23
23
  export type VideoMaskProvider = (typeof VIDEO_MASK_PROVIDERS)[number]
24
24
  export const DEFAULT_VIDEO_MASK_PROVIDER: VideoMaskProvider = "sam-3.1"
25
25
 
26
+ /**
27
+ * `zone`: keep only the subjects whose bounding-box CENTRE lies inside an
28
+ * inner rectangle, given as margins in % of the frame (each
29
+ * `VIDEO_MASK_LIMITS.ZONE_MARGIN_PCT_MIN`–`ZONE_MARGIN_PCT_MAX`). All zero, or
30
+ * no zone, = off.
31
+ */
32
+ export interface VideoMaskZone {
33
+ readonly leftPct: number
34
+ readonly rightPct: number
35
+ readonly topPct: number
36
+ readonly bottomPct: number
37
+ }
38
+
26
39
  /** A new Video Mask node's settings — spread into its node definition. */
27
40
  export const VIDEO_MASK_DEFAULTS = {
28
41
  threshold: 0.5,
29
42
  provider: "sam-3.1" as VideoMaskProvider,
43
+ /** Off: the mask is the model's, frame for frame (see `HOLD_EMPTY_BELOW_FRACTION`). */
44
+ holdLastMask: false,
45
+ /** 0 = off: every region the model finds is kept (see `MIN_SUBJECT_HEIGHT_PCT_*`). */
46
+ minSubjectHeightPct: 0,
47
+ /** 0 = off: no ceiling on a region's height (see `MAX_SUBJECT_HEIGHT_PCT_*`). */
48
+ maxSubjectHeightPct: 0,
49
+ /** Off: subjects anywhere in the frame are kept (see `ZONE_MARGIN_PCT_*`). */
50
+ zone: null as VideoMaskZone | null,
51
+ /**
52
+ * Off: one pass over the whole clip. On: the clip's scene cuts are found
53
+ * first and each shot is segmented on its own — the model starts afresh
54
+ * after every cut (finding the new shot's subjects), and `holdLastMask`
55
+ * never carries a mask across a cut. A clip with no cut (a flash is not
56
+ * one) is one shot: the same mask, fitted to the clip's exact frame count.
57
+ */
58
+ perShot: false,
30
59
  } as const
31
60
 
32
61
  export const VIDEO_MASK_LIMITS = {
@@ -42,6 +71,41 @@ export const VIDEO_MASK_LIMITS = {
42
71
  THRESHOLD_STEP: 0.05,
43
72
  /** Default detection confidence. Lower finds more (and less precise) regions. */
44
73
  THRESHOLD_DEFAULT: VIDEO_MASK_DEFAULTS.threshold,
74
+ /**
75
+ * `holdLastMask`: a frame whose mask covers less than this fraction of the
76
+ * picture (0.002 % — about 41 px at 1080p: a stray speck, never a subject) counts as empty — the subject lost (hidden behind a
77
+ * hand, turned away) — and shows the most recent non-empty frame's mask
78
+ * instead. Frames before the first detection stay as they are.
79
+ */
80
+ HOLD_EMPTY_BELOW_FRACTION: 0.00002,
81
+ /**
82
+ * `minSubjectHeightPct`: drop every connected white region (8-connected)
83
+ * whose bounding box is shorter than this % of the frame height — extras'
84
+ * small faces behind the main subject. 0 = off. Applied before
85
+ * `holdLastMask`, so a frame left with only small regions counts as empty
86
+ * and is held from the last frame with a big subject.
87
+ */
88
+ MIN_SUBJECT_HEIGHT_PCT_MIN: 0,
89
+ MIN_SUBJECT_HEIGHT_PCT_MAX: 100,
90
+ /**
91
+ * `maxSubjectHeightPct`, the mirror: drop every region whose bounding box is
92
+ * TALLER than this % of the frame height (keep only the small subjects — a
93
+ * paste-back mask of the background faces). 0 = off. With both set, a
94
+ * region is kept when min ≤ height ≤ max (min > max is refused). Same pass,
95
+ * same order (before `holdLastMask`).
96
+ */
97
+ MAX_SUBJECT_HEIGHT_PCT_MIN: 0,
98
+ MAX_SUBJECT_HEIGHT_PCT_MAX: 100,
99
+ /**
100
+ * `zone` margins (left / right / top / bottom, % of the frame width or
101
+ * height): drop every connected region whose bounding-box centre lies
102
+ * outside `[w·left/100, w·(1−right/100)] × [h·top/100, h·(1−bottom/100)]`
103
+ * — the faces at the edges of the picture. At most 49 % a side, so the
104
+ * inner rectangle is never empty. Applied after the size cut and before
105
+ * `holdLastMask`, so a frame left with nothing inside counts as empty.
106
+ */
107
+ ZONE_MARGIN_PCT_MIN: 0,
108
+ ZONE_MARGIN_PCT_MAX: 49,
45
109
  } as const
46
110
 
47
111
  const VIDEO_MASK_BUCKETS_SEC = [5, 10, 15, 30, 60, 90, 120, 180, 240, 300] as const
@@ -84,6 +148,23 @@ export function resolveVideoMaskProvider(value: unknown): VideoMaskProvider {
84
148
  : DEFAULT_VIDEO_MASK_PROVIDER
85
149
  }
86
150
 
151
+ /**
152
+ * A zone as the region filter reads it: each margin a finite number clamped
153
+ * to `ZONE_MARGIN_PCT_MIN`–`ZONE_MARGIN_PCT_MAX` (anything else is 0), and
154
+ * null when there is no zone or every margin is 0 (off). The one reading
155
+ * shared by the worker, a workflow run's payload and the node's own run.
156
+ */
157
+ export function resolveVideoMaskZone(value: unknown): VideoMaskZone | null {
158
+ if (!value || typeof value !== "object") return null
159
+ const v = value as Record<string, unknown>
160
+ const margin = (x: unknown) =>
161
+ typeof x === "number" && Number.isFinite(x)
162
+ ? Math.min(VIDEO_MASK_LIMITS.ZONE_MARGIN_PCT_MAX, Math.max(VIDEO_MASK_LIMITS.ZONE_MARGIN_PCT_MIN, x))
163
+ : 0
164
+ const zone = { leftPct: margin(v.leftPct), rightPct: margin(v.rightPct), topPct: margin(v.topPct), bottomPct: margin(v.bottomPct) }
165
+ return zone.leftPct > 0 || zone.rightPct > 0 || zone.topPct > 0 || zone.bottomPct > 0 ? zone : null
166
+ }
167
+
87
168
  /** `POST /v1/video-mask` request body. */
88
169
  export interface VideoMaskRequest {
89
170
  /** The clip to segment. */
@@ -93,4 +174,20 @@ export interface VideoMaskRequest {
93
174
  /** Detection confidence, `VIDEO_MASK_LIMITS.THRESHOLD_MIN`–`THRESHOLD_MAX` (default 0.5). */
94
175
  readonly threshold?: number
95
176
  readonly provider?: VideoMaskProvider
177
+ /** Hold the last mask where the subject is lost (default false): an empty frame
178
+ * after the first detection repeats the most recent non-empty one. */
179
+ readonly holdLastMask?: boolean
180
+ /** Ignore subjects smaller than this % of the frame height, 0–100 (default 0 = off):
181
+ * connected regions whose bounding box is shorter are dropped from every frame. */
182
+ readonly minSubjectHeightPct?: number
183
+ /** Ignore subjects larger than this % of the frame height, 0–100 (default 0 = off):
184
+ * connected regions whose bounding box is taller are dropped from every frame. */
185
+ readonly maxSubjectHeightPct?: number
186
+ /** Keep only the subjects whose bounding-box centre is inside these margins, each
187
+ * 0–49 % of the frame (a margin left out is 0). null / omitted / all 0 = off. */
188
+ readonly zone?: Partial<VideoMaskZone> | null
189
+ /** Segment each shot on its own (default false): the clip's scene cuts are found
190
+ * first and the subjects are detected again in every shot; `holdLastMask` never
191
+ * carries a mask across a cut. The output then carries `shots`. */
192
+ readonly perShot?: boolean
96
193
  }