[FEATURE] Mods: expose resolved terminal appearance for themed Image/Raster producers

This was generated by AI during triage.

Request

Expose the resolved terminal light/dark appearance to mods, with invalidation or an event when it changes. A read-only field on terminal ui.render input, or a read-only mods API operation, would be sufficient. This is separate from the configured theme name.

Observed on Claude Code 2.1.296

In a local Ghostty terminal on Apple Silicon macOS, $.config.list() returns the theme row with value: "auto" and the built-in light/dark preset options. The generated mods declarations expose themed Text/Box color keys, Image and $.ui.blit, but no resolved light/dark appearance for raster producers.

The terminal configuration documentation says auto detects the terminal background and follows its appearance changes. That detection is already owned by Claude Code, but the setting value does not tell a mod which palette is currently active. Custom theme slugs have the same distinction between preference and effective base appearance.

A small probe inside a mod:

on('session.start', async ($, e, next) => {
  await $.command.register({ name: 'appearance-probe', description: 'Inspect theme preference' });
  return next(e);
});
on('command.run', { command: 'appearance-probe' }, async ($) => ({
  text: JSON.stringify((await $.config.list()).find(row => row.key === 'theme')),
}));

With automatic theme selection this reports "auto", not the detected light/dark appearance.

Concrete consumer

Markgraf renders transparent native RGBA animation frames into a mod-owned Image and updates it via $.ui.blit. Transparency removes the page background but text and strokes still need the correct light/dark palette. Theme color tokens work for host-drawn elements, not for pixels produced by an external renderer.

The current safe workaround is to follow explicit built-in light/dark presets and ask the user to choose a Markgraf light/dark palette when the setting is automatic or custom. We do not guess dark, change the user's Claude theme, or send OSC queries/read replies behind Claude Code's terminal input owner.

Desired behavior

• Return the effective light/dark appearance, including auto and custom themes.
• Reflect appearance changes during the session, even when the configured value stays auto.
• Keep terminal input/query ownership inside Claude Code.
• If detection is unavailable, expose that explicitly rather than inventing a palette.

Related to the mods extensibility work in #91870; this request is specifically the appearance boundary needed by the existing raster/image APIs.