summaryrefslogtreecommitdiff
path: root/plugins/theme-examples/hooks
diff options
context:
space:
mode:
authorChaoshuai Lyu <chaoshuai@anthropic.com>2026-11-20 17:17:51 -0800
committerGitHub <noreply@github.com>2026-11-20 17:17:51 -0800
commit73c8cf3ea7e296057b467990f2f5d61b4c922260 (patch)
treeb96ff4fad7dc52de0b537c688828b79e4cf33d95 /plugins/theme-examples/hooks
parentd586c3f10a8c2366179bf46b097b4f652622ffc6 (diff)
feat(theme-examples): add sound to Koi Pond and Falling Sand (#7191)HEADmain
Squash merge of 1 commit
Diffstat (limited to 'plugins/theme-examples/hooks')
-rw-r--r--plugins/theme-examples/hooks/register.tsx124
-rw-r--r--plugins/theme-examples/hooks/sounds.ts144
-rw-r--r--plugins/theme-examples/hooks/themes.ts10
3 files changed, 260 insertions, 18 deletions
diff --git a/plugins/theme-examples/hooks/register.tsx b/plugins/theme-examples/hooks/register.tsx
index df3fc540..6d8e7efc 100644
--- a/plugins/theme-examples/hooks/register.tsx
+++ b/plugins/theme-examples/hooks/register.tsx
@@ -13,6 +13,7 @@ import {
import { overShader } from './interactive'
import { keyToWrite, keysToClear, keysToRead, projectKeyFor } from './project-key'
import type { KeptKey, KeyEngine } from './project-key'
+import type { Sound } from './sounds'
import { THEMES, sceneFault, sceneOf } from './themes'
import type { Theme } from './themes'
import type { ThemeChoice } from '../types'
@@ -35,7 +36,7 @@ const SESSION_PREFIX = 'session:'
const SESSIONS_KEPT = 200
// Said where a theme is set and the engine answers that nothing draws it. That answer is what the attached windows said of themselves at the moment of
// the set: one that attaches later still draws the theme, and one that draws themes under another name than this engine asks after draws it all the
-// same. An engine with none of the three calls is answered the same way (setBackdrop's last line), and there nothing draws it. So the words hold
+// same. An engine with none of the three calls is answered the same way (setWithoutSound's last line), and there nothing draws it. So the words hold
// whether or not the theme shows, and never say why.
const UNSHOWN = 'If no theme shows, this window may not draw themes yet'
const KEPT_UNSHOWN = `${UNSHOWN}. Your choice is saved.`
@@ -52,7 +53,7 @@ const choice = atom({ plugin: 'theme-examples', key: 'choice' } as const, {}, {
/** What a set comes to on any engine, as far as this mod reads it: drawn or not. */
type BackdropAnswer = { isDrawn: boolean }
-type BackdropChoice = { id: string; glass: Theme['glass']; colorScheme?: Theme['window'] }
+type BackdropChoice = { id: string; glass: Theme['glass']; colorScheme?: Theme['window']; sound?: Sound }
/**
* The engines this mod meets, for the type checker alone: the theme noun or the older call may be absent.
* A CALL ON A MEMBER THAT MAY BE ABSENT IS WRITTEN PLAINLY, as $.noun.method(...), under a line of "@ts-expect-error". A "!" or a
@@ -63,10 +64,18 @@ type BackdropChoice = { id: string; glass: Theme['glass']; colorScheme?: Theme['
type AnyEngine = {
theme?: { set(args: unknown): Promise<BackdropAnswer>; clear(): Promise<unknown> }
// `toast` is named only so that this type shares a member with every engine's ui noun: the checker refuses one that shares none.
- ui: { toast: EngineInterface['ui']['toast']; backdrop?(args: BackdropChoice | undefined): Promise<BackdropAnswer> }
+ ui: {
+ toast: EngineInterface['ui']['toast']
+ log: EngineInterface['ui']['log']
+ backdrop?(args: BackdropChoice | undefined): Promise<BackdropAnswer>
+ }
}
// The way of setting a backdrop this engine took, learnt at the first set that can tell; a reload learns it again.
let taken: 'beside' | 'nested' | 'older' | 'none' | undefined
+// True once an engine has refused a set as holding an attribute "sound" that it does not know: no theme's sound is then tried; a reload learns it again.
+let engineLacksSound = false
+// The last failed set with sound told to the debug log, as the theme's id and the reason: told again only when either changes.
+let toldSoundFailure: string | undefined
/**
* A try may be followed by the next one only where the engine lacks the call (reaching for it throws a TypeError) or
@@ -83,6 +92,23 @@ function isNotThisEnginesWay(error: unknown, member?: string): boolean {
)
}
+/** The arguments of a set in the newest shape, without a sound. */
+function newestShape(backdrop: BackdropChoice): Record<string, unknown> {
+ return {
+ backdrop: { scene: backdrop.id, id: backdrop.id, glass: backdrop.glass },
+ ...(backdrop.colorScheme !== undefined && { overrideColorScheme: backdrop.colorScheme }),
+ }
+}
+
+/** Notes that the engine took a set in the newest shape. */
+function learnNewest(backdrop: BackdropChoice): void {
+ // With no kind to hand over this shape is the next one's too: it tells nothing of the engine, so nothing is learnt.
+ // A belt: learnt wrongly here, the next set with a kind would be refused once and the ways walked anew.
+ if (backdrop.colorScheme !== undefined) {
+ taken = 'beside'
+ }
+}
+
/**
* Sets a backdrop by whichever call this engine has: the theme noun with the window's kind beside the backdrop, the
* theme noun with it inside the backdrop, or the older call on the ui noun. The calls are written out plainly, each in
@@ -96,17 +122,11 @@ function isNotThisEnginesWay(error: unknown, member?: string): boolean {
async function setByAWay($: AnyEngine, backdrop: BackdropChoice): Promise<BackdropAnswer | undefined> {
if (taken === undefined || taken === 'beside') {
try {
+ const shape = newestShape(backdrop)
// @ts-expect-error An engine may lack this call: see AnyEngine.
- const set = await $.theme.set({
- backdrop: { scene: backdrop.id, id: backdrop.id, glass: backdrop.glass },
- ...(backdrop.colorScheme !== undefined && { overrideColorScheme: backdrop.colorScheme }),
- })
+ const set = await $.theme.set(shape)
- // With no kind to hand over this shape is the next one's too: it tells nothing of the engine, so nothing is learnt.
- // A belt: learnt wrongly here, the next set with a kind would be refused once and the ways walked anew.
- if (backdrop.colorScheme !== undefined) {
- taken = 'beside'
- }
+ learnNewest(backdrop)
return set
} catch (error) {
@@ -153,7 +173,7 @@ async function setByAWay($: AnyEngine, backdrop: BackdropChoice): Promise<Backdr
* A way once learnt is the only one tried. Where the engine does not take it after all the ways are walked anew; an
* engine with none of them draws nothing, and the answer says so.
*/
-async function setBackdrop($: AnyEngine, backdrop: BackdropChoice): Promise<BackdropAnswer> {
+async function setWithoutSound($: AnyEngine, backdrop: BackdropChoice): Promise<BackdropAnswer> {
if (taken === 'none') {
return { isDrawn: false }
}
@@ -180,6 +200,74 @@ async function setBackdrop($: AnyEngine, backdrop: BackdropChoice): Promise<Back
return { isDrawn: false }
}
+/**
+ * Whether a refused set shows that the engine is from before sound: it says that it does not know the attribute
+ * "sound". Any other failure, a refused member inside a sound too, proves nothing about the engine, so the next
+ * theme's sound is still tried.
+ */
+function isEngineWithoutSound(error: unknown): boolean {
+ return error instanceof Error && error.message.includes('does not know the attribute "sound"')
+}
+
+/**
+ * Says which theme could not be set with its sound and why, so that whoever changes a sound can read what to change.
+ * The failure may not be the sound's own, so the words say only what happened.
+ * TO THE DEBUG LOG ALONE, as `tellKeyStep` is: the person sees the theme, without its sound.
+ */
+async function tellSoundFailure($: AnyEngine, id: string, reason: string): Promise<void> {
+ const told = `${id}: ${reason}`
+
+ if (told === toldSoundFailure) {
+ return
+ }
+
+ toldSoundFailure = told
+
+ try {
+ await $.ui.log(`The theme ${id} could not be set with its sound, so it was set without it: ${reason}`, { to: 'debug' })
+ } catch {
+ // An engine without that call, or one that refuses it: nothing more to tell.
+ }
+}
+
+/**
+ * Sets a backdrop, with its sound where the theme has one and the engine takes it.
+ * THE SET WITH SOUND IS A TRY OF ITS OWN, AHEAD OF THE WAYS: were it the first way, an engine from before sound would
+ * refuse it in words that way's catch reads as "try the next shape", then refuse the next shape, and the theme would
+ * not be applied. After any failure here the theme is set without the sound; where that fails too, its error is thrown.
+ */
+async function setBackdrop($: AnyEngine, backdrop: BackdropChoice): Promise<BackdropAnswer> {
+ // Only an engine that takes the newest shape can take sound, so no other is asked.
+ if (backdrop.sound === undefined || engineLacksSound || (taken !== undefined && taken !== 'beside')) {
+ return setWithoutSound($, backdrop)
+ }
+
+ let failure: unknown
+
+ try {
+ const shape = { ...newestShape(backdrop), sound: backdrop.sound }
+ // @ts-expect-error An engine may lack this call: see AnyEngine.
+ const set = await $.theme.set(shape)
+
+ learnNewest(backdrop)
+
+ return set
+ } catch (error) {
+ failure = error
+ }
+
+ const set = await setWithoutSound($, backdrop)
+
+ if (isEngineWithoutSound(failure)) {
+ engineLacksSound = true
+ } else if (taken === 'beside') {
+ // Told only where the newest way took the theme. A show bears its theme's sound under the show's own id: the theme is the one to name.
+ await tellSoundFailure($, themeIdOfShow(backdrop.id) ?? backdrop.id, reasonOf(failure))
+ }
+
+ return set
+}
+
/** Clears the backdrop by whichever call this engine has; an engine with neither is left alone. */
async function clearBackdrop($: AnyEngine): Promise<void> {
try {
@@ -297,6 +385,11 @@ function themeList(): string {
].join('\n')
}
+/** What a set of a theme's backdrop carries. `id`: the theme's own, or a show's over it. */
+function backdropOf(theme: Theme, id = theme.id): BackdropChoice {
+ return { id, glass: theme.glass, colorScheme: theme.window, sound: theme.sound }
+}
+
/**
* Shows a theme behind the chat, or with none clears the session's theme, and answers what a set came to.
* A clear takes away whatever theme stands, whichever mod set it, so `show` is given none only on a person's ask
@@ -311,7 +404,7 @@ async function show($: EngineInterface, id: string | undefined): Promise<Backdro
return undefined
}
- return setBackdrop($, { id: theme.id, glass: theme.glass, colorScheme: theme.window })
+ return setBackdrop($, backdropOf(theme))
}
const PROJECT_PREFIX = 'project:'
@@ -715,11 +808,12 @@ async function fireworks($: EngineInterface): Promise<string> {
afterShader = theme?.shader !== undefined
+ // The theme's sound goes with its show: a set names the whole theme, and an ambience that is set again unchanged plays on.
set = await setBackdrop(
$,
theme === undefined
? { id: NIGHT_ID, glass: NIGHT_GLASS }
- : { id: `${theme.id}${suffix}`, glass: theme.glass, colorScheme: theme.window },
+ : backdropOf(theme, `${theme.id}${suffix}`),
)
} catch (error) {
// A show that did not begin costs a reply nothing, and the next word may try again.
diff --git a/plugins/theme-examples/hooks/sounds.ts b/plugins/theme-examples/hooks/sounds.ts
new file mode 100644
index 00000000..d6af5266
--- /dev/null
+++ b/plugins/theme-examples/hooks/sounds.ts
@@ -0,0 +1,144 @@
+// Sound for Koi Pond and Falling Sand. A theme's sound is numbers, never a recording: the desktop app makes it from
+// these layers of tones and noise once the person turns theme sound on. ./themes gives each to its scene once, for
+// both of the scene's entries, so going from one entry to the other keeps the ambience playing.
+import type { ThemeSetArgs } from 'claude-code'
+
+/**
+ * The `sound` of a theme: `ThemeSound`, where this Claude Code's types have it. Read off `ThemeSetArgs`, and not
+ * imported by name, so that the mod still type-checks against the types of a Claude Code from before sound: there it
+ * is any object, and nothing checks the numbers below.
+ */
+export type Sound = ThemeSetArgs extends { sound?: infer Known } ? NonNullable<Known> : object
+
+// A press sounds one note of each list, by where it lands from the window's left edge to its right: the upper note
+// glides up and the lower, an octave under it, glides down. All are notes of one pentatonic scale, as the drips are.
+const POND_PLIPS = ['E5', 'F#5', 'A5', 'B5', 'D6']
+const POND_BODIES = ['E4', 'F#4', 'A4', 'B4', 'D5']
+
+/** Koi Pond: tonal, with reverb. Still water, a drip now and then, and a plop where a press drops food. */
+export const KOI_POND_SOUND: Sound = {
+ ambience: {
+ reverb: 0.3,
+ layers: [
+ // The water: a low wash whose filter opens and closes once in 16 seconds, with two slow swells on the way.
+ { wave: 'pink', drone: true, gain: 0.6, filter: { type: 'bandpass', hz: 380, to: 620 }, tremolo: { hz: 0.125, depth: 0.35 } },
+ // A thin, high hiss that rises and falls a little, three times in the same 16 seconds.
+ { wave: 'pink', drone: true, gain: 0.135, filter: { type: 'bandpass', hz: 2400, to: 3400 }, tremolo: { hz: 0.1875, depth: 0.4 } },
+ // A drip every eight seconds or so. Its note rises, as a drop's does.
+ { wave: 'sine', notes: ['A5', 'B5', 'D6', 'E6', 'F#6', 'A6'], scatter: 0.12, glide: 5, attack: 0.003, release: 0.11, gain: 0.26 },
+ // Rarer and lower: a koi turning at the surface.
+ { wave: 'sine', notes: ['D4', 'E4', 'A4'], scatter: 0.04, glide: -4, attack: 0.012, release: 0.3, gain: 0.19, filter: { type: 'lowpass', hz: 900 } },
+ ],
+ },
+ cues: {
+ // A press drops a pellet: a plop, pitched by where it lands.
+ click: {
+ reverb: 0.22,
+ layers: [
+ { wave: 'sine', notes: POND_PLIPS, glide: 9, attack: 0.003, release: 0.1, gain: 0.4 },
+ { wave: 'sine', notes: POND_BODIES, glide: -5, attack: 0.004, release: 0.16, gain: 0.26 },
+ { wave: 'pink', attack: 0.002, release: 0.035, gain: 0.18, filter: { type: 'highpass', hz: 2600 } },
+ ],
+ },
+ // A message goes out: two quick drops, the second higher.
+ send: {
+ reverb: 0.2,
+ layers: [{ wave: 'sine', notes: ['E5', 'A5'], step: 0.08, glide: 4, attack: 0.003, release: 0.1, gain: 0.38 }],
+ },
+ // The turn is over: one slow, low ring, with a drop on top.
+ done: {
+ reverb: 0.45,
+ layers: [
+ { wave: 'sine', notes: ['D4', 'A4'], attack: 0.06, release: 1.3, gain: 0.18, filter: { type: 'lowpass', hz: 1200 } },
+ { wave: 'sine', notes: ['F#5'], glide: 3, attack: 0.004, release: 0.22, gain: 0.14 },
+ ],
+ },
+ // Claude waits on the person: a koi turns, and two drops follow, the second higher. The drops are short and
+ // slide a long way up, to keep them from ringing like a chime.
+ ask: {
+ reverb: 0.15,
+ layers: [
+ { wave: 'sine', notes: ['D4'], glide: -4, attack: 0.008, release: 0.22, gain: 0.3, filter: { type: 'lowpass', hz: 900 } },
+ { wave: 'sine', notes: [0, 'F#5', 'B5'], step: 0.13, glide: 9, attack: 0.003, release: 0.08, gain: 0.4 },
+ { wave: 'pink', attack: 0.002, release: 0.04, gain: 0.12, filter: { type: 'highpass', hz: 2600 } },
+ ],
+ },
+ // The turn ended in an error: a low note that sinks, like a stone going down.
+ error: {
+ reverb: 0.25,
+ layers: [
+ { wave: 'sine', notes: ['A3'], glide: -7, attack: 0.006, release: 0.4, gain: 0.34 },
+ { wave: 'sine', notes: ['A4'], glide: -7, attack: 0.006, release: 0.22, gain: 0.1 },
+ { wave: 'brown', attack: 0.004, release: 0.22, gain: 0.2, filter: { type: 'lowpass', hz: 480 } },
+ ],
+ },
+ },
+}
+
+// A press pours sand at the pointer. The first grain ticks on the stone, lower at the left and higher at the right.
+const SAND_TICKS = [1400, 1650, 1900, 2200, 2500, 2850]
+
+/** Falling Sand: mostly noise, with no reverb. A faint pour, a slide of sand now and then, and a short pour at a press. */
+export const FALLING_SAND_SOUND: Sound = {
+ ambience: {
+ layers: [
+ // The nozzles' steady pour: a wide hiss in two layers. The lower one drifts a little up and back once in 16
+ // seconds, with two slow swells.
+ { wave: 'white', drone: true, gain: 0.18, filter: { type: 'bandpass', hz: 2400, to: 2700 }, tremolo: { hz: 0.125, depth: 0.25 } },
+ { wave: 'white', drone: true, gain: 0.14, filter: { type: 'bandpass', hz: 4200 } },
+ // Grains ticking in the pour.
+ { wave: 'crackle', drone: true, gain: 0.03, filter: { type: 'highpass', hz: 2800 } },
+ // A heap gives way: a short slide of sand every ten seconds or so, lower than the pour, to stand clear of it.
+ { wave: 'pink', scatter: 0.1, attack: 0.06, release: 0.55, gain: 0.5, filter: { type: 'bandpass', hz: 1500, to: 600 } },
+ // Now and then a grain lands on stone: a short tick, like the one a press starts with.
+ { wave: 'triangle', notes: [1400, 1900, 2500], scatter: 0.25, glide: -9, attack: 0.002, release: 0.03, gain: 0.2 },
+ ],
+ },
+ cues: {
+ // A press pours: a hiss that falls as it thins, grains in it, and the tick of the first grain on stone.
+ click: {
+ layers: [
+ { wave: 'white', attack: 0.015, release: 0.32, gain: 1, filter: { type: 'bandpass', hz: 5200, to: 2300 } },
+ { wave: 'crackle', attack: 0.004, release: 0.3, gain: 0.2, filter: { type: 'bandpass', hz: 4000, to: 2000 } },
+ { wave: 'triangle', notes: SAND_TICKS, glide: -9, attack: 0.002, release: 0.03, gain: 0.15 },
+ ],
+ },
+ // A message goes out: a pinch of sand thrown up.
+ send: {
+ layers: [
+ { wave: 'white', attack: 0.004, release: 0.16, gain: 1, filter: { type: 'bandpass', hz: 2600, to: 6200 } },
+ { wave: 'white', attack: 0.004, release: 0.12, gain: 0.75, filter: { type: 'highpass', hz: 3000 } },
+ ],
+ },
+ // A tool call: one grain. It comes often, so it is about as loud as the ambience's own ticks.
+ tool: {
+ layers: [{ wave: 'crackle', attack: 0.002, release: 0.025, gain: 0.12, filter: { type: 'highpass', hz: 4200 } }],
+ },
+ // The turn is over: the last of a pour settles, and two pebbles come to rest.
+ done: {
+ layers: [
+ { wave: 'white', attack: 0.02, release: 0.6, gain: 0.75, filter: { type: 'bandpass', hz: 4200, to: 1100 } },
+ { wave: 'crackle', attack: 0.02, release: 0.8, gain: 0.25, filter: { type: 'bandpass', hz: 4200, to: 1100 } },
+ { wave: 'triangle', notes: [1760, 1320], step: 0.1, glide: -5, attack: 0.002, release: 0.05, gain: 0.2 },
+ ],
+ },
+ // Claude waits on the person: a pebble knocks on stone, twice and then once more. Each knock is two notes that
+ // make no chord and drop fast, to keep it from ringing like a chime.
+ ask: {
+ layers: [
+ { wave: 'triangle', notes: [950, 950, 0, 1130], step: 0.09, glide: -14, attack: 0.002, release: 0.05, gain: 0.55 },
+ { wave: 'triangle', notes: [1340, 1340, 0, 1600], step: 0.09, glide: -14, attack: 0.002, release: 0.035, gain: 0.35 },
+ { wave: 'white', attack: 0.003, release: 0.05, gain: 0.1, filter: { type: 'highpass', hz: 5000 } },
+ ],
+ },
+ // The turn ended in an error: a shelf of sand slumps.
+ error: {
+ layers: [
+ { wave: 'pink', attack: 0.008, release: 0.45, gain: 1, filter: { type: 'bandpass', hz: 700, to: 240 } },
+ { wave: 'pink', attack: 0.008, release: 0.4, gain: 1, filter: { type: 'bandpass', hz: 1100, to: 450 } },
+ { wave: 'white', attack: 0.008, release: 0.35, gain: 1, filter: { type: 'bandpass', hz: 1800, to: 800 } },
+ { wave: 'crackle', attack: 0.01, release: 0.3, gain: 0.3, filter: { type: 'bandpass', hz: 1800 } },
+ ],
+ },
+ },
+}
diff --git a/plugins/theme-examples/hooks/themes.ts b/plugins/theme-examples/hooks/themes.ts
index e5a77e1c..6fb359a9 100644
--- a/plugins/theme-examples/hooks/themes.ts
+++ b/plugins/theme-examples/hooks/themes.ts
@@ -23,6 +23,8 @@ import { rippleTankSvg } from './scenes/ripple-tank/still'
import { seaSparkleSvg } from './scenes/sea-sparkle/still'
import { semicolonySvg } from './scenes/semicolony/still'
import { starChartSvg } from './scenes/star-chart/still'
+import { FALLING_SAND_SOUND, KOI_POND_SOUND } from './sounds'
+import type { Sound } from './sounds'
/** The scenes a shader plays over. Each name is a folder under ./scenes, which holds the shader and its still. */
export type ShaderScene =
@@ -53,16 +55,18 @@ export type Theme = {
shader?: ShaderScene
/** Set where the picture is dark, or pale, whatever the window: a show's bursts are then bright, or deep, in both. */
ground?: Theme['window']
+ /** The theme's sound, where it has one (see ./sounds). */
+ sound?: Sound
}
/** What a scene's two entries share: both of its rows below spread one of these, so they cannot differ. */
-type Picture = Required<Pick<Theme, 'scene' | 'shader'>> & Pick<Theme, 'ground'>
+type Picture = Required<Pick<Theme, 'scene' | 'shader'>> & Pick<Theme, 'ground' | 'sound'>
const DUCK_POND: Picture = { scene: duckPondSvg, shader: 'duck-pond' }
-const FALLING_SAND: Picture = { scene: fallingSandSvg, shader: 'falling-sand' }
+const FALLING_SAND: Picture = { scene: fallingSandSvg, shader: 'falling-sand', sound: FALLING_SAND_SOUND }
const FIELD_LINES: Picture = { scene: fieldLinesSvg, shader: 'field-lines' }
const GARDEN_BEETLES: Picture = { scene: gardenBeetlesSvg, shader: 'garden-beetles' }
-const KOI_POND: Picture = { scene: koiPondSvg, shader: 'koi-pond', ground: 'dark' }
+const KOI_POND: Picture = { scene: koiPondSvg, shader: 'koi-pond', ground: 'dark', sound: KOI_POND_SOUND }
const RIPPLE_TANK: Picture = { scene: rippleTankSvg, shader: 'ripple-tank' }
const SEA_SPARKLE: Picture = { scene: seaSparkleSvg, shader: 'sea-sparkle' }
const SEMICOLONY: Picture = { scene: semicolonySvg, shader: 'semicolony' }