@contractspec/example.video-api-showcase 2.1.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.
@@ -0,0 +1,42 @@
1
+ // @bun
2
+ // src/build-api-video.ts
3
+ import { VIDEO_FORMATS } from "@contractspec/lib.video-gen/design/layouts";
4
+ import { resolveRenderConfig } from "@contractspec/lib.video-gen/renderers/config";
5
+ var DEFAULT_FPS = 30;
6
+ var DEFAULT_DURATION_FRAMES = 450;
7
+ function buildApiVideo(spec, options) {
8
+ const fps = options?.fps ?? DEFAULT_FPS;
9
+ const durationInFrames = options?.durationInFrames ?? DEFAULT_DURATION_FRAMES;
10
+ return {
11
+ id: `api-video-${spec.specName.toLowerCase()}-${Date.now().toString(36)}`,
12
+ scenes: [
13
+ {
14
+ id: "scene-api-overview",
15
+ compositionId: "ApiOverview",
16
+ props: {
17
+ specName: spec.specName,
18
+ method: spec.method,
19
+ endpoint: spec.endpoint,
20
+ specCode: spec.specCode,
21
+ generatedOutputs: spec.generatedOutputs,
22
+ tagline: options?.tagline ?? "One spec. Every surface."
23
+ },
24
+ durationInFrames
25
+ }
26
+ ],
27
+ totalDurationInFrames: durationInFrames,
28
+ fps,
29
+ format: VIDEO_FORMATS.landscape
30
+ };
31
+ }
32
+ function buildRenderConfig(outputPath, preset = "standard") {
33
+ return resolveRenderConfig({ outputPath }, preset);
34
+ }
35
+ function buildApiVideoSuite(specs, options) {
36
+ return specs.map((spec) => buildApiVideo(spec, options));
37
+ }
38
+ export {
39
+ buildRenderConfig,
40
+ buildApiVideoSuite,
41
+ buildApiVideo
42
+ };
@@ -0,0 +1 @@
1
+ import './video-api-showcase.docblock';
@@ -0,0 +1,67 @@
1
+ // @bun
2
+ // src/docs/video-api-showcase.docblock.ts
3
+ import { registerDocBlocks } from "@contractspec/lib.contracts-spec/docs";
4
+ var blocks = [
5
+ {
6
+ id: "docs.examples.video-api-showcase",
7
+ title: "Video API Showcase (example)",
8
+ summary: "Spec-driven example: build API overview videos directly from contract spec metadata using manual VideoProject construction.",
9
+ kind: "reference",
10
+ visibility: "public",
11
+ route: "/docs/examples/video-api-showcase",
12
+ tags: ["video", "api", "spec-driven", "example"],
13
+ body: `## What this example shows
14
+
15
+ - Manually constructing a \`VideoProject\` from contract spec metadata (name, method, endpoint, code, outputs).
16
+ - Using the \`ApiOverview\` composition to visualize how a spec generates multiple API surfaces.
17
+ - Configuring render settings with quality presets (\`draft\`, \`standard\`, \`high\`).
18
+ - Building video scenes with explicit composition IDs and props.
19
+
20
+ ## Key concepts
21
+
22
+ - **Spec-to-Video**: Contract spec metadata (name, method, endpoint, code snippet) becomes the input props for the \`ApiOverview\` composition.
23
+ - **Manual project construction**: Instead of using \`VideoGenerator\`, this example builds the \`VideoProject\` directly -- useful when you know exactly which composition and props to use.
24
+ - **Render configuration**: Shows how to use \`resolveRenderConfig()\` with quality presets for different output needs.
25
+
26
+ ## Notes
27
+
28
+ - This approach is ideal when the video structure is known ahead of time (e.g., always an API overview).
29
+ - For dynamic scene planning from content briefs, use \`VideoGenerator\` instead (see the video-marketing-clip example).
30
+ `
31
+ },
32
+ {
33
+ id: "docs.examples.video-api-showcase.usage",
34
+ title: "Video API Showcase -- Usage",
35
+ summary: "How to generate API overview videos from contract spec definitions.",
36
+ kind: "usage",
37
+ visibility: "public",
38
+ route: "/docs/examples/video-api-showcase/usage",
39
+ tags: ["video", "api", "usage"],
40
+ body: `## Usage
41
+
42
+ \`\`\`ts
43
+ import { buildApiVideo } from "@contractspec/example.video-api-showcase/build-api-video";
44
+ import { createUserSpec, listTransactionsSpec } from "@contractspec/example.video-api-showcase/sample-specs";
45
+
46
+ // Build a video project for a single API spec
47
+ const project = buildApiVideo(createUserSpec);
48
+
49
+ console.log(project.scenes[0].compositionId); // "ApiOverview"
50
+ console.log(project.format); // { type: "landscape", width: 1920, height: 1080 }
51
+
52
+ // Build with custom duration and tagline
53
+ const custom = buildApiVideo(listTransactionsSpec, {
54
+ durationInFrames: 600,
55
+ tagline: "From spec to production in seconds.",
56
+ });
57
+ \`\`\`
58
+
59
+ ## Guardrails
60
+
61
+ - The \`specCode\` field should be a concise snippet (10-20 lines) for readability in the video.
62
+ - Generated outputs list should contain 3-8 items for optimal visual layout.
63
+ - Tagline should be short (under 40 characters) to fit within the composition frame.
64
+ `
65
+ }
66
+ ];
67
+ registerDocBlocks(blocks);
@@ -0,0 +1 @@
1
+ export {};
@@ -0,0 +1,67 @@
1
+ // @bun
2
+ // src/docs/video-api-showcase.docblock.ts
3
+ import { registerDocBlocks } from "@contractspec/lib.contracts-spec/docs";
4
+ var blocks = [
5
+ {
6
+ id: "docs.examples.video-api-showcase",
7
+ title: "Video API Showcase (example)",
8
+ summary: "Spec-driven example: build API overview videos directly from contract spec metadata using manual VideoProject construction.",
9
+ kind: "reference",
10
+ visibility: "public",
11
+ route: "/docs/examples/video-api-showcase",
12
+ tags: ["video", "api", "spec-driven", "example"],
13
+ body: `## What this example shows
14
+
15
+ - Manually constructing a \`VideoProject\` from contract spec metadata (name, method, endpoint, code, outputs).
16
+ - Using the \`ApiOverview\` composition to visualize how a spec generates multiple API surfaces.
17
+ - Configuring render settings with quality presets (\`draft\`, \`standard\`, \`high\`).
18
+ - Building video scenes with explicit composition IDs and props.
19
+
20
+ ## Key concepts
21
+
22
+ - **Spec-to-Video**: Contract spec metadata (name, method, endpoint, code snippet) becomes the input props for the \`ApiOverview\` composition.
23
+ - **Manual project construction**: Instead of using \`VideoGenerator\`, this example builds the \`VideoProject\` directly -- useful when you know exactly which composition and props to use.
24
+ - **Render configuration**: Shows how to use \`resolveRenderConfig()\` with quality presets for different output needs.
25
+
26
+ ## Notes
27
+
28
+ - This approach is ideal when the video structure is known ahead of time (e.g., always an API overview).
29
+ - For dynamic scene planning from content briefs, use \`VideoGenerator\` instead (see the video-marketing-clip example).
30
+ `
31
+ },
32
+ {
33
+ id: "docs.examples.video-api-showcase.usage",
34
+ title: "Video API Showcase -- Usage",
35
+ summary: "How to generate API overview videos from contract spec definitions.",
36
+ kind: "usage",
37
+ visibility: "public",
38
+ route: "/docs/examples/video-api-showcase/usage",
39
+ tags: ["video", "api", "usage"],
40
+ body: `## Usage
41
+
42
+ \`\`\`ts
43
+ import { buildApiVideo } from "@contractspec/example.video-api-showcase/build-api-video";
44
+ import { createUserSpec, listTransactionsSpec } from "@contractspec/example.video-api-showcase/sample-specs";
45
+
46
+ // Build a video project for a single API spec
47
+ const project = buildApiVideo(createUserSpec);
48
+
49
+ console.log(project.scenes[0].compositionId); // "ApiOverview"
50
+ console.log(project.format); // { type: "landscape", width: 1920, height: 1080 }
51
+
52
+ // Build with custom duration and tagline
53
+ const custom = buildApiVideo(listTransactionsSpec, {
54
+ durationInFrames: 600,
55
+ tagline: "From spec to production in seconds.",
56
+ });
57
+ \`\`\`
58
+
59
+ ## Guardrails
60
+
61
+ - The \`specCode\` field should be a concise snippet (10-20 lines) for readability in the video.
62
+ - Generated outputs list should contain 3-8 items for optimal visual layout.
63
+ - Tagline should be short (under 40 characters) to fit within the composition frame.
64
+ `
65
+ }
66
+ ];
67
+ registerDocBlocks(blocks);
@@ -0,0 +1,2 @@
1
+ declare const example: import("@contractspec/lib.contracts-spec").ExampleSpec;
2
+ export default example;
@@ -0,0 +1,34 @@
1
+ // @bun
2
+ // src/example.ts
3
+ import { defineExample } from "@contractspec/lib.contracts-spec";
4
+ var example = defineExample({
5
+ meta: {
6
+ key: "video-api-showcase",
7
+ version: "1.0.0",
8
+ title: "Video API Showcase",
9
+ description: "Generate API documentation videos from contract spec definitions using the ApiOverview composition.",
10
+ kind: "script",
11
+ visibility: "public",
12
+ stability: "experimental",
13
+ owners: ["@platform.core"],
14
+ tags: ["video", "api", "documentation", "spec-driven"]
15
+ },
16
+ docs: {
17
+ rootDocId: "docs.examples.video-api-showcase",
18
+ usageDocId: "docs.examples.video-api-showcase.usage"
19
+ },
20
+ entrypoints: {
21
+ packageName: "@contractspec/example.video-api-showcase",
22
+ docs: "./docs"
23
+ },
24
+ surfaces: {
25
+ templates: true,
26
+ sandbox: { enabled: true, modes: ["markdown"] },
27
+ studio: { enabled: true, installable: true },
28
+ mcp: { enabled: true }
29
+ }
30
+ });
31
+ var example_default = example;
32
+ export {
33
+ example_default as default
34
+ };
@@ -0,0 +1,4 @@
1
+ export * from './sample-specs';
2
+ export * from './build-api-video';
3
+ export { default as example } from './example';
4
+ import './docs';
package/dist/index.js ADDED
@@ -0,0 +1,242 @@
1
+ // @bun
2
+ // src/build-api-video.ts
3
+ import { VIDEO_FORMATS } from "@contractspec/lib.video-gen/design/layouts";
4
+ import { resolveRenderConfig } from "@contractspec/lib.video-gen/renderers/config";
5
+ var DEFAULT_FPS = 30;
6
+ var DEFAULT_DURATION_FRAMES = 450;
7
+ function buildApiVideo(spec, options) {
8
+ const fps = options?.fps ?? DEFAULT_FPS;
9
+ const durationInFrames = options?.durationInFrames ?? DEFAULT_DURATION_FRAMES;
10
+ return {
11
+ id: `api-video-${spec.specName.toLowerCase()}-${Date.now().toString(36)}`,
12
+ scenes: [
13
+ {
14
+ id: "scene-api-overview",
15
+ compositionId: "ApiOverview",
16
+ props: {
17
+ specName: spec.specName,
18
+ method: spec.method,
19
+ endpoint: spec.endpoint,
20
+ specCode: spec.specCode,
21
+ generatedOutputs: spec.generatedOutputs,
22
+ tagline: options?.tagline ?? "One spec. Every surface."
23
+ },
24
+ durationInFrames
25
+ }
26
+ ],
27
+ totalDurationInFrames: durationInFrames,
28
+ fps,
29
+ format: VIDEO_FORMATS.landscape
30
+ };
31
+ }
32
+ function buildRenderConfig(outputPath, preset = "standard") {
33
+ return resolveRenderConfig({ outputPath }, preset);
34
+ }
35
+ function buildApiVideoSuite(specs, options) {
36
+ return specs.map((spec) => buildApiVideo(spec, options));
37
+ }
38
+
39
+ // src/docs/video-api-showcase.docblock.ts
40
+ import { registerDocBlocks } from "@contractspec/lib.contracts-spec/docs";
41
+ var blocks = [
42
+ {
43
+ id: "docs.examples.video-api-showcase",
44
+ title: "Video API Showcase (example)",
45
+ summary: "Spec-driven example: build API overview videos directly from contract spec metadata using manual VideoProject construction.",
46
+ kind: "reference",
47
+ visibility: "public",
48
+ route: "/docs/examples/video-api-showcase",
49
+ tags: ["video", "api", "spec-driven", "example"],
50
+ body: `## What this example shows
51
+
52
+ - Manually constructing a \`VideoProject\` from contract spec metadata (name, method, endpoint, code, outputs).
53
+ - Using the \`ApiOverview\` composition to visualize how a spec generates multiple API surfaces.
54
+ - Configuring render settings with quality presets (\`draft\`, \`standard\`, \`high\`).
55
+ - Building video scenes with explicit composition IDs and props.
56
+
57
+ ## Key concepts
58
+
59
+ - **Spec-to-Video**: Contract spec metadata (name, method, endpoint, code snippet) becomes the input props for the \`ApiOverview\` composition.
60
+ - **Manual project construction**: Instead of using \`VideoGenerator\`, this example builds the \`VideoProject\` directly -- useful when you know exactly which composition and props to use.
61
+ - **Render configuration**: Shows how to use \`resolveRenderConfig()\` with quality presets for different output needs.
62
+
63
+ ## Notes
64
+
65
+ - This approach is ideal when the video structure is known ahead of time (e.g., always an API overview).
66
+ - For dynamic scene planning from content briefs, use \`VideoGenerator\` instead (see the video-marketing-clip example).
67
+ `
68
+ },
69
+ {
70
+ id: "docs.examples.video-api-showcase.usage",
71
+ title: "Video API Showcase -- Usage",
72
+ summary: "How to generate API overview videos from contract spec definitions.",
73
+ kind: "usage",
74
+ visibility: "public",
75
+ route: "/docs/examples/video-api-showcase/usage",
76
+ tags: ["video", "api", "usage"],
77
+ body: `## Usage
78
+
79
+ \`\`\`ts
80
+ import { buildApiVideo } from "@contractspec/example.video-api-showcase/build-api-video";
81
+ import { createUserSpec, listTransactionsSpec } from "@contractspec/example.video-api-showcase/sample-specs";
82
+
83
+ // Build a video project for a single API spec
84
+ const project = buildApiVideo(createUserSpec);
85
+
86
+ console.log(project.scenes[0].compositionId); // "ApiOverview"
87
+ console.log(project.format); // { type: "landscape", width: 1920, height: 1080 }
88
+
89
+ // Build with custom duration and tagline
90
+ const custom = buildApiVideo(listTransactionsSpec, {
91
+ durationInFrames: 600,
92
+ tagline: "From spec to production in seconds.",
93
+ });
94
+ \`\`\`
95
+
96
+ ## Guardrails
97
+
98
+ - The \`specCode\` field should be a concise snippet (10-20 lines) for readability in the video.
99
+ - Generated outputs list should contain 3-8 items for optimal visual layout.
100
+ - Tagline should be short (under 40 characters) to fit within the composition frame.
101
+ `
102
+ }
103
+ ];
104
+ registerDocBlocks(blocks);
105
+ // src/example.ts
106
+ import { defineExample } from "@contractspec/lib.contracts-spec";
107
+ var example = defineExample({
108
+ meta: {
109
+ key: "video-api-showcase",
110
+ version: "1.0.0",
111
+ title: "Video API Showcase",
112
+ description: "Generate API documentation videos from contract spec definitions using the ApiOverview composition.",
113
+ kind: "script",
114
+ visibility: "public",
115
+ stability: "experimental",
116
+ owners: ["@platform.core"],
117
+ tags: ["video", "api", "documentation", "spec-driven"]
118
+ },
119
+ docs: {
120
+ rootDocId: "docs.examples.video-api-showcase",
121
+ usageDocId: "docs.examples.video-api-showcase.usage"
122
+ },
123
+ entrypoints: {
124
+ packageName: "@contractspec/example.video-api-showcase",
125
+ docs: "./docs"
126
+ },
127
+ surfaces: {
128
+ templates: true,
129
+ sandbox: { enabled: true, modes: ["markdown"] },
130
+ studio: { enabled: true, installable: true },
131
+ mcp: { enabled: true }
132
+ }
133
+ });
134
+ var example_default = example;
135
+
136
+ // src/sample-specs.ts
137
+ var createUserSpec = {
138
+ specName: "CreateUser",
139
+ method: "POST",
140
+ endpoint: "/api/users",
141
+ specCode: `export const createUser = defineCommand({
142
+ meta: {
143
+ name: "CreateUser",
144
+ version: "1.0.0",
145
+ stability: "Stable",
146
+ },
147
+ io: {
148
+ input: z.object({
149
+ email: z.string().email(),
150
+ name: z.string(),
151
+ role: z.enum(["admin", "user"]),
152
+ }),
153
+ output: z.object({
154
+ id: z.string().uuid(),
155
+ email: z.string(),
156
+ createdAt: z.date(),
157
+ }),
158
+ },
159
+ });`,
160
+ generatedOutputs: [
161
+ "REST Endpoint",
162
+ "GraphQL Mutation",
163
+ "Prisma Model",
164
+ "TypeScript SDK",
165
+ "MCP Tool",
166
+ "OpenAPI Spec"
167
+ ]
168
+ };
169
+ var listTransactionsSpec = {
170
+ specName: "ListTransactions",
171
+ method: "GET",
172
+ endpoint: "/api/transactions",
173
+ specCode: `export const listTransactions = defineQuery({
174
+ meta: {
175
+ name: "ListTransactions",
176
+ version: "1.0.0",
177
+ stability: "Stable",
178
+ },
179
+ io: {
180
+ input: z.object({
181
+ accountId: z.string().uuid(),
182
+ from: z.date().optional(),
183
+ to: z.date().optional(),
184
+ limit: z.number().default(50),
185
+ }),
186
+ output: z.object({
187
+ transactions: z.array(transactionSchema),
188
+ total: z.number(),
189
+ hasMore: z.boolean(),
190
+ }),
191
+ },
192
+ });`,
193
+ generatedOutputs: [
194
+ "REST Endpoint",
195
+ "GraphQL Query",
196
+ "Prisma Query",
197
+ "TypeScript SDK",
198
+ "OpenAPI Spec"
199
+ ]
200
+ };
201
+ var sendNotificationSpec = {
202
+ specName: "SendNotification",
203
+ method: "POST",
204
+ endpoint: "/api/notifications",
205
+ specCode: `export const sendNotification = defineCommand({
206
+ meta: {
207
+ name: "SendNotification",
208
+ version: "1.0.0",
209
+ stability: "Beta",
210
+ },
211
+ io: {
212
+ input: z.object({
213
+ userId: z.string().uuid(),
214
+ channel: z.enum(["push", "email", "sms"]),
215
+ title: z.string(),
216
+ body: z.string(),
217
+ }),
218
+ output: z.object({
219
+ notificationId: z.string().uuid(),
220
+ deliveredAt: z.date().nullable(),
221
+ status: z.enum(["sent", "failed", "queued"]),
222
+ }),
223
+ },
224
+ });`,
225
+ generatedOutputs: [
226
+ "REST Endpoint",
227
+ "GraphQL Mutation",
228
+ "TypeScript SDK",
229
+ "MCP Tool",
230
+ "OpenAPI Spec",
231
+ "Event Schema"
232
+ ]
233
+ };
234
+ export {
235
+ sendNotificationSpec,
236
+ listTransactionsSpec,
237
+ example_default as example,
238
+ createUserSpec,
239
+ buildRenderConfig,
240
+ buildApiVideoSuite,
241
+ buildApiVideo
242
+ };
@@ -0,0 +1,41 @@
1
+ // src/build-api-video.ts
2
+ import { VIDEO_FORMATS } from "@contractspec/lib.video-gen/design/layouts";
3
+ import { resolveRenderConfig } from "@contractspec/lib.video-gen/renderers/config";
4
+ var DEFAULT_FPS = 30;
5
+ var DEFAULT_DURATION_FRAMES = 450;
6
+ function buildApiVideo(spec, options) {
7
+ const fps = options?.fps ?? DEFAULT_FPS;
8
+ const durationInFrames = options?.durationInFrames ?? DEFAULT_DURATION_FRAMES;
9
+ return {
10
+ id: `api-video-${spec.specName.toLowerCase()}-${Date.now().toString(36)}`,
11
+ scenes: [
12
+ {
13
+ id: "scene-api-overview",
14
+ compositionId: "ApiOverview",
15
+ props: {
16
+ specName: spec.specName,
17
+ method: spec.method,
18
+ endpoint: spec.endpoint,
19
+ specCode: spec.specCode,
20
+ generatedOutputs: spec.generatedOutputs,
21
+ tagline: options?.tagline ?? "One spec. Every surface."
22
+ },
23
+ durationInFrames
24
+ }
25
+ ],
26
+ totalDurationInFrames: durationInFrames,
27
+ fps,
28
+ format: VIDEO_FORMATS.landscape
29
+ };
30
+ }
31
+ function buildRenderConfig(outputPath, preset = "standard") {
32
+ return resolveRenderConfig({ outputPath }, preset);
33
+ }
34
+ function buildApiVideoSuite(specs, options) {
35
+ return specs.map((spec) => buildApiVideo(spec, options));
36
+ }
37
+ export {
38
+ buildRenderConfig,
39
+ buildApiVideoSuite,
40
+ buildApiVideo
41
+ };
@@ -0,0 +1,66 @@
1
+ // src/docs/video-api-showcase.docblock.ts
2
+ import { registerDocBlocks } from "@contractspec/lib.contracts-spec/docs";
3
+ var blocks = [
4
+ {
5
+ id: "docs.examples.video-api-showcase",
6
+ title: "Video API Showcase (example)",
7
+ summary: "Spec-driven example: build API overview videos directly from contract spec metadata using manual VideoProject construction.",
8
+ kind: "reference",
9
+ visibility: "public",
10
+ route: "/docs/examples/video-api-showcase",
11
+ tags: ["video", "api", "spec-driven", "example"],
12
+ body: `## What this example shows
13
+
14
+ - Manually constructing a \`VideoProject\` from contract spec metadata (name, method, endpoint, code, outputs).
15
+ - Using the \`ApiOverview\` composition to visualize how a spec generates multiple API surfaces.
16
+ - Configuring render settings with quality presets (\`draft\`, \`standard\`, \`high\`).
17
+ - Building video scenes with explicit composition IDs and props.
18
+
19
+ ## Key concepts
20
+
21
+ - **Spec-to-Video**: Contract spec metadata (name, method, endpoint, code snippet) becomes the input props for the \`ApiOverview\` composition.
22
+ - **Manual project construction**: Instead of using \`VideoGenerator\`, this example builds the \`VideoProject\` directly -- useful when you know exactly which composition and props to use.
23
+ - **Render configuration**: Shows how to use \`resolveRenderConfig()\` with quality presets for different output needs.
24
+
25
+ ## Notes
26
+
27
+ - This approach is ideal when the video structure is known ahead of time (e.g., always an API overview).
28
+ - For dynamic scene planning from content briefs, use \`VideoGenerator\` instead (see the video-marketing-clip example).
29
+ `
30
+ },
31
+ {
32
+ id: "docs.examples.video-api-showcase.usage",
33
+ title: "Video API Showcase -- Usage",
34
+ summary: "How to generate API overview videos from contract spec definitions.",
35
+ kind: "usage",
36
+ visibility: "public",
37
+ route: "/docs/examples/video-api-showcase/usage",
38
+ tags: ["video", "api", "usage"],
39
+ body: `## Usage
40
+
41
+ \`\`\`ts
42
+ import { buildApiVideo } from "@contractspec/example.video-api-showcase/build-api-video";
43
+ import { createUserSpec, listTransactionsSpec } from "@contractspec/example.video-api-showcase/sample-specs";
44
+
45
+ // Build a video project for a single API spec
46
+ const project = buildApiVideo(createUserSpec);
47
+
48
+ console.log(project.scenes[0].compositionId); // "ApiOverview"
49
+ console.log(project.format); // { type: "landscape", width: 1920, height: 1080 }
50
+
51
+ // Build with custom duration and tagline
52
+ const custom = buildApiVideo(listTransactionsSpec, {
53
+ durationInFrames: 600,
54
+ tagline: "From spec to production in seconds.",
55
+ });
56
+ \`\`\`
57
+
58
+ ## Guardrails
59
+
60
+ - The \`specCode\` field should be a concise snippet (10-20 lines) for readability in the video.
61
+ - Generated outputs list should contain 3-8 items for optimal visual layout.
62
+ - Tagline should be short (under 40 characters) to fit within the composition frame.
63
+ `
64
+ }
65
+ ];
66
+ registerDocBlocks(blocks);
@@ -0,0 +1,66 @@
1
+ // src/docs/video-api-showcase.docblock.ts
2
+ import { registerDocBlocks } from "@contractspec/lib.contracts-spec/docs";
3
+ var blocks = [
4
+ {
5
+ id: "docs.examples.video-api-showcase",
6
+ title: "Video API Showcase (example)",
7
+ summary: "Spec-driven example: build API overview videos directly from contract spec metadata using manual VideoProject construction.",
8
+ kind: "reference",
9
+ visibility: "public",
10
+ route: "/docs/examples/video-api-showcase",
11
+ tags: ["video", "api", "spec-driven", "example"],
12
+ body: `## What this example shows
13
+
14
+ - Manually constructing a \`VideoProject\` from contract spec metadata (name, method, endpoint, code, outputs).
15
+ - Using the \`ApiOverview\` composition to visualize how a spec generates multiple API surfaces.
16
+ - Configuring render settings with quality presets (\`draft\`, \`standard\`, \`high\`).
17
+ - Building video scenes with explicit composition IDs and props.
18
+
19
+ ## Key concepts
20
+
21
+ - **Spec-to-Video**: Contract spec metadata (name, method, endpoint, code snippet) becomes the input props for the \`ApiOverview\` composition.
22
+ - **Manual project construction**: Instead of using \`VideoGenerator\`, this example builds the \`VideoProject\` directly -- useful when you know exactly which composition and props to use.
23
+ - **Render configuration**: Shows how to use \`resolveRenderConfig()\` with quality presets for different output needs.
24
+
25
+ ## Notes
26
+
27
+ - This approach is ideal when the video structure is known ahead of time (e.g., always an API overview).
28
+ - For dynamic scene planning from content briefs, use \`VideoGenerator\` instead (see the video-marketing-clip example).
29
+ `
30
+ },
31
+ {
32
+ id: "docs.examples.video-api-showcase.usage",
33
+ title: "Video API Showcase -- Usage",
34
+ summary: "How to generate API overview videos from contract spec definitions.",
35
+ kind: "usage",
36
+ visibility: "public",
37
+ route: "/docs/examples/video-api-showcase/usage",
38
+ tags: ["video", "api", "usage"],
39
+ body: `## Usage
40
+
41
+ \`\`\`ts
42
+ import { buildApiVideo } from "@contractspec/example.video-api-showcase/build-api-video";
43
+ import { createUserSpec, listTransactionsSpec } from "@contractspec/example.video-api-showcase/sample-specs";
44
+
45
+ // Build a video project for a single API spec
46
+ const project = buildApiVideo(createUserSpec);
47
+
48
+ console.log(project.scenes[0].compositionId); // "ApiOverview"
49
+ console.log(project.format); // { type: "landscape", width: 1920, height: 1080 }
50
+
51
+ // Build with custom duration and tagline
52
+ const custom = buildApiVideo(listTransactionsSpec, {
53
+ durationInFrames: 600,
54
+ tagline: "From spec to production in seconds.",
55
+ });
56
+ \`\`\`
57
+
58
+ ## Guardrails
59
+
60
+ - The \`specCode\` field should be a concise snippet (10-20 lines) for readability in the video.
61
+ - Generated outputs list should contain 3-8 items for optimal visual layout.
62
+ - Tagline should be short (under 40 characters) to fit within the composition frame.
63
+ `
64
+ }
65
+ ];
66
+ registerDocBlocks(blocks);
@@ -0,0 +1,33 @@
1
+ // src/example.ts
2
+ import { defineExample } from "@contractspec/lib.contracts-spec";
3
+ var example = defineExample({
4
+ meta: {
5
+ key: "video-api-showcase",
6
+ version: "1.0.0",
7
+ title: "Video API Showcase",
8
+ description: "Generate API documentation videos from contract spec definitions using the ApiOverview composition.",
9
+ kind: "script",
10
+ visibility: "public",
11
+ stability: "experimental",
12
+ owners: ["@platform.core"],
13
+ tags: ["video", "api", "documentation", "spec-driven"]
14
+ },
15
+ docs: {
16
+ rootDocId: "docs.examples.video-api-showcase",
17
+ usageDocId: "docs.examples.video-api-showcase.usage"
18
+ },
19
+ entrypoints: {
20
+ packageName: "@contractspec/example.video-api-showcase",
21
+ docs: "./docs"
22
+ },
23
+ surfaces: {
24
+ templates: true,
25
+ sandbox: { enabled: true, modes: ["markdown"] },
26
+ studio: { enabled: true, installable: true },
27
+ mcp: { enabled: true }
28
+ }
29
+ });
30
+ var example_default = example;
31
+ export {
32
+ example_default as default
33
+ };