Files
orca/src/shared/plugins/artifacts/plugin-theme-background.ts
T
Neil b0dd73e7aa feat(plugins): play a looping video behind app themes (#39450)
App themes may set background.videoPath: a muted, looping MP4 or WebM (H.264
recommended, VP9 or AV1; one video track, no audio; <= 60 s, 8 MB, 2.3 MP)
played over the required static background.path. Main checks it from container
headers without decoding and serves it on the orca-plugin-image slot
theme-<i>-video; images stay static-only. The renderer reveals it on its first
frame, keeps the still on any failure or a decoded size past the limits, plays
it only while main reports the window focused, shown and not minimized and no
dialog is open, and omits it under prefers-reduced-motion.

Animated WebP was measured and declined: software-decoded every frame, it cost
11-23 points of CPU vs 3-10 for the same loop as video.

Implements #38363 proposed by @dohaidang.
2026-11-07 03:32:14 -08:00

103 lines
3.6 KiB
TypeScript

import { z } from 'zod'
import { pluginRelativePathSchema } from '../manifest/plugin-manifest-fields'
import {
PLUGIN_MANIFEST_V2_SINCE,
PLUGIN_THEME_VIDEO_BACKGROUND_SINCE,
pluginFieldDoc,
pluginPathFieldDoc
} from '../manifest/plugin-schema-field-docs'
import { PLUGIN_THEME_BACKGROUND_RULE_TEXT } from '../images/plugin-image-fields'
import { PLUGIN_THEME_VIDEO_RULE_TEXT } from '../media/plugin-theme-video-rules'
import { parsePluginImageUrl } from '../images/plugin-image-url'
const NEXT = PLUGIN_MANIFEST_V2_SINCE
const backgroundStyleFields = {
opacity: z
.number()
.min(0)
.max(1)
.optional()
.meta(
pluginFieldDoc(
'How strongly the image shows over the theme background, 0 to 1. Defaults to 1.',
NEXT,
[0.35]
)
),
size: z
.enum(['cover', 'contain', 'tile'])
.optional()
.meta(pluginFieldDoc('How the image fills the window. Defaults to `cover`.', NEXT)),
position: z
.enum(['center', 'top', 'bottom', 'left', 'right'])
.optional()
.meta(pluginFieldDoc('Which edge the image anchors to. Defaults to `center`.', NEXT))
}
const backgroundFields = {
path: pluginRelativePathSchema.meta(
pluginPathFieldDoc(`Image file in the plugin. ${PLUGIN_THEME_BACKGROUND_RULE_TEXT}`, NEXT, [
'images/dusk.webp'
])
),
videoPath: pluginRelativePathSchema
.optional()
.meta(
pluginPathFieldDoc(
`Looping video played over \`path\` while the window is focused and motion is not reduced; only \`path\` shows otherwise, when the video cannot play, and in releases before ${PLUGIN_THEME_VIDEO_BACKGROUND_SINCE}. ${PLUGIN_THEME_VIDEO_RULE_TEXT}`,
PLUGIN_THEME_VIDEO_BACKGROUND_SINCE,
['images/dusk.mp4']
)
),
...backgroundStyleFields
}
/** `validate:plugin` shape: unknown keys fail authoring. */
export const pluginThemeBackgroundSchema = z
.strictObject(backgroundFields)
.meta(
pluginFieldDoc(
'One image painted under translucent terminals and chats (Background Opacity below 1). Never blurred.',
NEXT
)
)
export type PluginThemeBackgroundArtifact = z.infer<typeof pluginThemeBackgroundSchema>
// Why per-field catch: a style value added later falls back to its default instead of dropping the image.
const tolerantBackgroundSchema = z.object({
path: backgroundFields.path,
videoPath: backgroundFields.videoPath.catch(undefined),
opacity: backgroundStyleFields.opacity.catch(undefined),
size: backgroundStyleFields.size.catch(undefined),
position: backgroundStyleFields.position.catch(undefined)
})
/** Runtime keeps a theme whose background is malformed or newer; at worst it paints no image. */
export function tolerantPluginThemeBackground(
value: unknown
): PluginThemeBackgroundArtifact | undefined {
const parsed = tolerantBackgroundSchema.safeParse(value)
return parsed.success ? parsed.data : undefined
}
const installedImageUrlSchema = z
.string()
.refine((url) => parsePluginImageUrl(url)?.kind === 'installed')
/** What main hands the renderer: `orca-plugin-image` URLs main serves only after checking the bytes.
* `videoUrl` is optional per field so a bad one leaves the static image. */
export const pluginThemeBackgroundRegistrationSchema = z.object({
url: installedImageUrlSchema,
videoUrl: installedImageUrlSchema.optional().catch(undefined),
...backgroundStyleFields
})
/** Registration field: an unreadable background drops the image, never the theme. */
export const tolerantPluginThemeBackgroundRegistration = pluginThemeBackgroundRegistrationSchema
.optional()
.catch(undefined)
export type PluginThemeBackground = z.infer<typeof pluginThemeBackgroundRegistrationSchema>