@nodaro/shared 3.18.0 → 3.19.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@nodaro/shared",
3
- "version": "3.18.0",
3
+ "version": "3.19.0",
4
4
  "description": "Shared types, model catalog, wire contracts, and structural vocabularies for the Nodaro platform and SDK.",
5
5
  "type": "module",
6
6
  "license": "Apache-2.0",
@@ -0,0 +1,27 @@
1
+ // packages/shared/src/__tests__/caption-plan.test.ts
2
+ import { describe, it, expect, expectTypeOf } from "vitest"
3
+ import type { CaptionPlan, CaptionWordTiming } from "../index.js"
4
+
5
+ describe("CaptionPlan", () => {
6
+ it("is exported from the package barrel with the documented fields", () => {
7
+ const plan: CaptionPlan = {
8
+ v: 1,
9
+ hookText: "Saved 3 hours a week",
10
+ hookEndMs: 1600,
11
+ bodyEndMs: 4300,
12
+ captions: [{ text: "so", startMs: 1600, endMs: 1900 }],
13
+ videoDurationMs: 8000,
14
+ language: "en",
15
+ }
16
+ expect(plan.v).toBe(1)
17
+ expectTypeOf<CaptionWordTiming>().toEqualTypeOf<{ readonly text: string; readonly startMs: number; readonly endMs: number }>()
18
+ })
19
+
20
+ it("requires its version and carries no styling", () => {
21
+ // @ts-expect-error — `v` is required
22
+ const noVersion: CaptionPlan = { hookText: "", hookEndMs: 0, bodyEndMs: 0, captions: [] }
23
+ // @ts-expect-error — a plan carries times and words only
24
+ const styled: CaptionPlan = { v: 1, hookText: "", hookEndMs: 0, bodyEndMs: 0, captions: [], look: "clean" }
25
+ expect([noVersion, styled]).toHaveLength(2)
26
+ })
27
+ })
@@ -4,7 +4,9 @@ import {
4
4
  extractPresetData,
5
5
  PRESET_EXCLUDED_KEYS,
6
6
  PRESET_APPLY_CLEAR_KEYS,
7
+ PRESET_LEVER_GROUPS,
7
8
  presetApplyClearKeys,
9
+ presetLeverClearKeys,
8
10
  presetDataMatches,
9
11
  } from "../node-preset-extract.js"
10
12
 
@@ -234,3 +236,63 @@ describe("Scene3D presets", () => {
234
236
  expect(presetApplyClearKeys({ scenePrompt: "New scene" })).toContain("promptPrefix")
235
237
  })
236
238
  })
239
+
240
+ describe("caption lever group (applying a caption preset over another)", () => {
241
+ // The values of the Hook Plate, Body Captions and Clean Subtitles presets in @nodaro/prompts.
242
+ const HOOK_PLATE = { style: "subtitle", look: "clean", position: "top", positionY: 20, fontSize: 32, fontWeight: 800, maxWordsPerLine: 4, color: "#111111", backgroundColor: "#FFFFFF", autoTranscribe: false }
243
+ const BODY = { style: "word-highlight", look: "outline", position: "bottom", positionY: 72, fontSize: 32, maxWordsPerLine: 3, color: "#FFFFFF", autoTranscribe: true }
244
+ const CLEAN = { style: "subtitle", position: "bottom", fontSize: 32, color: "#FFFFFF", autoTranscribe: true }
245
+ const apply = (node: Record<string, unknown>, preset: Record<string, unknown>, nodeType?: string) => ({
246
+ ...node,
247
+ ...Object.fromEntries(presetApplyClearKeys(preset, nodeType).map((k) => [k, undefined])),
248
+ ...preset,
249
+ })
250
+
251
+ it("Body Captions over Hook Plate clears the plate's backgroundColor and fontWeight", () => {
252
+ const after = apply(HOOK_PLATE, BODY, "add-captions")
253
+ expect(after.backgroundColor).toBeUndefined()
254
+ expect(after.fontWeight).toBeUndefined()
255
+ expect(after.look).toBe("outline")
256
+ })
257
+
258
+ it("Clean Subtitles over Hook Plate clears backgroundColor, look, positionY, fontWeight and maxWordsPerLine", () => {
259
+ const after = apply(HOOK_PLATE, CLEAN, "add-captions")
260
+ for (const k of ["backgroundColor", "look", "positionY", "fontWeight", "maxWordsPerLine"]) expect(after[k], k).toBeUndefined()
261
+ expect(after.position).toBe("bottom")
262
+ })
263
+
264
+ it("an existing caption preset over a clean node leaves no lever set", () => {
265
+ const after = apply({ style: "subtitle" }, CLEAN, "add-captions")
266
+ for (const k of PRESET_LEVER_GROUPS["add-captions"]!) expect(after[k], k).toBeUndefined()
267
+ expect(after).toMatchObject(CLEAN)
268
+ })
269
+
270
+ it("never clears a lever the preset sets", () => {
271
+ for (const k of presetLeverClearKeys(HOOK_PLATE, "add-captions")) expect(HOOK_PLATE).not.toHaveProperty(k)
272
+ })
273
+
274
+ it("empty preset data clears no group member", () => {
275
+ expect(presetLeverClearKeys({}, "add-captions")).toEqual([])
276
+ expect(presetLeverClearKeys({ style: undefined }, "add-captions")).toEqual([])
277
+ })
278
+
279
+ it("a node type with no group, or no node type, behaves as today", () => {
280
+ expect(presetLeverClearKeys(CLEAN, "generate-image")).toEqual([])
281
+ expect(presetLeverClearKeys(CLEAN)).toEqual([])
282
+ expect([...presetApplyClearKeys(CLEAN, "generate-image")].sort()).toEqual([...PRESET_APPLY_CLEAR_KEYS].sort())
283
+ expect([...presetApplyClearKeys(CLEAN)].sort()).toEqual([...PRESET_APPLY_CLEAR_KEYS].sort())
284
+ })
285
+
286
+ it("a hand-set fontFamily is cleared by any caption preset that does not set it (the stated cost)", () => {
287
+ expect(apply({ ...BODY, fontFamily: "Anton" }, CLEAN, "add-captions").fontFamily).toBeUndefined()
288
+ })
289
+
290
+ it("an inherited key name is not a node type", () => {
291
+ expect(presetLeverClearKeys(CLEAN, "constructor")).toEqual([])
292
+ })
293
+
294
+ it("group members stay capture-included, and PRESET_EXCLUDED_KEYS still covers PRESET_APPLY_CLEAR_KEYS", () => {
295
+ for (const k of PRESET_LEVER_GROUPS["add-captions"]!) expect(PRESET_EXCLUDED_KEYS.has(k), k).toBe(false)
296
+ for (const k of PRESET_APPLY_CLEAR_KEYS) expect(PRESET_EXCLUDED_KEYS.has(k), k).toBe(true)
297
+ })
298
+ })
@@ -0,0 +1,27 @@
1
+ export interface CaptionWordTiming {
2
+ readonly text: string
3
+ readonly startMs: number
4
+ readonly endMs: number
5
+ }
6
+
7
+ /**
8
+ * A caption plan: the opening line, where it ends, and the timed words that
9
+ * follow it. Times and words only — no styling travels on a plan; whoever
10
+ * renders it applies the look. Times are milliseconds from the video's start.
11
+ */
12
+ /** The opening line and the body's words, timed. No styling. */
13
+ export interface CaptionPlan {
14
+ readonly v: 1
15
+ /** The opening line as written; sent as is, never trimmed. */
16
+ readonly hookText: string
17
+ /** Where the opening line ends; the body starts here. */
18
+ readonly hookEndMs: number
19
+ /** Where the body captions end, any tail included (the producer decides it). */
20
+ readonly bodyEndMs: number
21
+ /** The body's words, in milliseconds. */
22
+ readonly captions: readonly CaptionWordTiming[]
23
+ /** When known, the opening line and the body are clamped to it. */
24
+ readonly videoDurationMs?: number
25
+ /** Primary language tag: "en", "he", … */
26
+ readonly language?: string
27
+ }
package/src/index.ts CHANGED
@@ -1166,6 +1166,7 @@ export {
1166
1166
  resolveCaptionLevers,
1167
1167
  } from "./caption-styles.js"
1168
1168
  export type { StaticCaptionStyle, KineticCaptionStyle, CaptionStyle, CaptionLookId, CaptionLookLevers, KineticOnlyCaptionLeverKey } from "./caption-styles.js"
1169
+ export type { CaptionPlan, CaptionWordTiming } from "./caption-plan.js"
1169
1170
 
1170
1171
  export {
1171
1172
  transcribeWordTimestampsRefusal,
@@ -1409,7 +1410,7 @@ export {
1409
1410
  describeNodeAdjustments,
1410
1411
  } from "./normalize-node-params.js"
1411
1412
  export type { NodeParamAdjustment, NormalizedNodes } from "./normalize-node-params.js"
1412
- export { extractPresetData, PRESET_EXCLUDED_KEYS, PRESET_APPLY_CLEAR_KEYS, presetApplyClearKeys, presetDataMatches } from "./node-preset-extract.js"
1413
+ export { extractPresetData, PRESET_EXCLUDED_KEYS, PRESET_APPLY_CLEAR_KEYS, PRESET_LEVER_GROUPS, presetApplyClearKeys, presetLeverClearKeys, presetDataMatches } from "./node-preset-extract.js"
1413
1414
  export { PROMPT_PREFIX_KEY, PROMPT_SUFFIX_KEY, readPromptAffixes } from "./prompt-affixes.js"
1414
1415
  export type { PromptAffixFields, PromptAffixes } from "./prompt-affixes.js"
1415
1416
 
@@ -63,11 +63,43 @@ const PROMPT_CONTENT_KEYS: readonly string[] = ["prompt", "scenePrompt", "editPr
63
63
  */
64
64
  export function presetApplyClearKeys(
65
65
  presetData: Readonly<Record<string, unknown>>,
66
+ nodeType?: string,
66
67
  ): readonly string[] {
67
68
  const ownsPromptContent = PROMPT_CONTENT_KEYS.some((k) => presetData[k] !== undefined)
68
- return ownsPromptContent
69
+ const base = ownsPromptContent
69
70
  ? [...PRESET_APPLY_CLEAR_KEYS, PROMPT_PREFIX_KEY, PROMPT_SUFFIX_KEY]
70
71
  : PRESET_APPLY_CLEAR_KEYS
72
+ const levers = presetLeverClearKeys(presetData, nodeType)
73
+ return levers.length > 0 ? [...base, ...levers] : base
74
+ }
75
+
76
+ /**
77
+ * Per node type, the look levers a preset may leave unset. Applying any preset
78
+ * with data to a node of a listed type clears every member that preset does not
79
+ * set, so one preset's plate colour, weight or position never carries over into
80
+ * the next. Data-driven, so a new preset of a listed type is covered by
81
+ * construction. The members stay capture-included: a saved preset carries the
82
+ * levers its node had, so it clears only the ones that were unset when it was saved.
83
+ */
84
+ export const PRESET_LEVER_GROUPS: Readonly<Record<string, readonly string[]>> = {
85
+ "add-captions": [
86
+ "look", "fontFamily", "fontWeight", "strokeColor", "strokeWidth", "highlightColor",
87
+ "uppercase", "positionY", "animate", "maxWordsPerLine", "backgroundColor",
88
+ ],
89
+ }
90
+
91
+ /**
92
+ * The lever-group keys applying THIS preset clears on a node of `nodeType`: every
93
+ * member of the node type's group that the preset does not set. Nothing for a node
94
+ * type with no group, and nothing for empty preset data. Pure.
95
+ */
96
+ export function presetLeverClearKeys(
97
+ presetData: Readonly<Record<string, unknown>>,
98
+ nodeType?: string,
99
+ ): readonly string[] {
100
+ if (!nodeType || !Object.hasOwn(PRESET_LEVER_GROUPS, nodeType)) return []
101
+ if (!Object.values(presetData).some((v) => v !== undefined)) return []
102
+ return PRESET_LEVER_GROUPS[nodeType]!.filter((k) => presetData[k] === undefined)
71
103
  }
72
104
 
73
105
  /**