Skip to content

Latest commit

 

History

History
460 lines (410 loc) · 29.8 KB

themes.md

File metadata and controls

460 lines (410 loc) · 29.8 KB

Themes Module

Overview

The dashboard is fully skinnable. A theme ranges from a bare color palette up to a full "experience pack" (fonts, sandboxed overlays, audio, persona). A color theme is the degenerate case of a pack — the whole spectrum lives behind one Theme dropdown in Settings → Display: install many, select one.

Themes are a standalone subsystem built on useTheme, not Kiro Crew apps. This document is the source of truth for the end-to-end subsystem. The frontend pack-author contract (the CSS-var surface and the overrides.css selector allowlist) lives in website/docs/theming-contract.md; where the two overlap, this spec governs.

Capability Tiers

theme.json MUST declare "formatVersion": 1 (required integer major, mirroring the platform layer's pinned-CONTRACT_VERSION precedent). Validation rejects a missing/non-integer value, and rejects an unknown major with an explicit "this pack requires a newer version of Kiro Crew" message — never the opaque generic-validation errors — so an older Kiro Crew degrades honestly when handed a newer pack. Semantics changes within a major stay backward-tolerant; breaking manifest changes bump the major.

A pack's JSON files (theme.json, variables.json, a saved custom theme record, and an appearance pack's manifest.json) are read with user_json.loads_user_json, which accepts one leading UTF-8 byte-order mark: an editor that writes one (Windows Notepad does) must not turn a valid hand-edited file into "not valid JSON" or drop the pack from the list.

theme.json also declares a level (0/1/2) that gates which asset categories a pack may ship. Validation is tier-scaled to payload trust.

Tier level Surface unlocked
L0 Color 0 the 60 theme CSS variables (dark + light) only
L1 Branded 1 + branding/ (logo, favicon, wordmark, welcome), styles/fonts/, scoped overrides.css, loader/*.png|webp|gif|svg
L2 Experience 2 + overlays/ + topbar/ sandboxed HTML, audio/, persona.md

Level-1 and Level-2 manifests may also declare loaderIcons: 4–8 distinct names from the bundled stock-symbol allowlist (cloud, flower, heart, moon, sparkles, star, sun, zap). The backend validates and surfaces the names in the theme asset descriptor; the frontend maps them to bundled Lucide components and reuses the existing carousel. No component code, SVG, or asset path crosses the manifest boundary. Missing declarations preserve the Kiro ghost poses, and trusted compiled themes retain the broader registerThemeBranding() component seam.

Installed packs may also supply the loader art, not just select symbols: loader/*.png .webp .gif .svg (1–8 images, Level 1) are the pack's own loader art: one image renders on its own, 2–8 are cycled by the stock carousel. Animated WebP/APNG/GIF and animated SVG self-animate inside the <img>, so a pack can ship a single fully-authored loop. Under prefers-reduced-motion: reduce each loader image is instead painted once, at its first frame, onto a <canvas> (PackLoaderImage, website/src/pages/chat/PackLoaderImage.tsx): nothing on the page can pause an image's own animation, and theme overlays already stand down under reduced motion. Each is served through the ordinary asset route with a strict Content-Type + nosniff under _THEME_ASSET_CSP (default-src 'none'; sandbox) and referenced only as an <img> — SVG is safe the same way logo.svg is (an <img>-loaded SVG runs in the browser's secure static/animated mode: no scripts, no external loads, animation still plays), so it needs no HTML-serving route of its own. The frontend resolveLoader precedence is: compiled loader → pack images (one on its own, 2–8 cycled) → loaderIcons (manifest, then compiled) → the default poses.

The empty chat's welcome screen (WelcomeView) has one brand-mark slot, and a Level-1 pack fills it with branding/welcome.svg|png|webp|gif (256 KB, served and rendered like the loader art, so an animated image plays in place). Precedence: compiled registerThemeBranding() logo → pack welcome image → pack logo → the stock ghost. So a pack that ships only a logo shows it there too, matching the left rail.

Constants (dashboard/theme_validate.py): _THEME_MAX_LEVEL=2, _THEME_MAX_FONTS=6, _THEME_MAX_OVERLAYS=5, _THEME_PERSONA_MAX_CHARS=2000, plus per-file byte caps (_THEME_FILE_CAPS) and per-level entry-count + total uncompressed byte ceilings.

Fonts are role-tagged

Each entry in theme.json's fonts list carries a role of sans or mono (absent ⇒ sans, so pre-role packs keep their meaning). A role fills a CSS token — --theme-font-sans / --theme-font-mono — that the Font Family preference reads through, which is what routes a pack's proportional face to the Sans option and its monospace face to Mono while System stays on the OS face. --mono reads the mono token as well, so code surfaces follow a pack's monospace face.

The indirection is load-bearing: the preference applies --font-body as an inline style on <html>, and an inline declaration outranks every selector, so a pack declaring --font-body on its own [data-theme=…] block would never win. _THEME_MAX_FONTS covers both roles at once, so shipping a mono face does not cost a sans weight. Declaring any font token — or font / font-family on a whole-UI surface — in overrides.css is rejected at install (_overrides_font_violation, which decodes CSS escapes and matches the font shorthand as well as the longhand) and dropped by the runtime scoper, keeping the manifest the single route and the preference honest for every pack.

The font layer is gated behind _validate_theme_dir(..., installing=True) rather than applied on every call, because that function also runs when the theme-detail route re-reads an installed pack — and that route answers 500 on a validation failure, which the dashboard fetches for every theme at boot. Enforcing it there would drop a pre-rule pack out of the theme map entirely, colours included. The runtime scoper still removes the pin, so the preference is protected either way.

File-drop artwork contrast

ChatDropOverlay renders its transparent file-chomper image with the stable class chat-drop-art and paints no inline colour. website/src/styles/chat-transcript.css (next to the loader-ghost block) gives that class a 1px black silhouette shadow (drop-shadow) under [data-mode="light"], the resolved mode useTheme writes on <html>, so it applies to installed light palettes too. The white ghost and paper stay visible against light backgrounds without recoloring the artwork or changing drag behavior. Dark palettes are excluded by the selector, not by an assumption about their --bg, and render the art as they did before. Only a compiled edition theme's own CSS can override the rule. An installed pack cannot: chat-drop-art is not an overrides.css class hook, so scopeOverridesCss drops any rule that targets it, and palette tokens cannot reach the hardcoded shadow value.

Install Pipeline

  1. Source — a local directory (read in place, then copied into staging), an uploaded .zip, or an https github.com repo shallow-cloned server-side (_clone_github, --depth 1, 30s timeout, host allowlist). The clone spawns through the sandbox chokepoint, which fails closed where no OS sandbox backend exists: that refusal answers 503 with code: "theme_install_sandbox_unavailable", never an unsandboxed retry — the URL is user-influenced and git clone executes remote content. A local source spawns nothing, so it stays available on such a host. A .zip upload (POST /api/themes/install-zip, the archive as the body) is how a browser that is not on the gateway host installs a pack: a folder path names the gateway's filesystem, which a phone cannot reach. dashboard/theme_zip.py unpacks it into a private temporary directory and refuses what only an archive can express — a name that leaves the directory (absolute, : in any component, .., backslash, or a target that does not resolve under the directory), a symlink or other non-regular entry, a file and a folder sharing one name, a path over six parts (even metadata), an unreadable member, a member compressed with anything but stored or deflate (zipfile decompresses a whole BZIP2 or LZMA buffer at once, before any byte count sees it), more entries than the largest tier allows (vetted by zip_vet.vet_zip_inventory_bytes before zipfile parses the directory), or more unpacked bytes than it allows (counted on the bytes written, not only the headers). Refusals answer 400 with code: "theme_zip_invalid"; an empty body is 400 theme_zip_empty, an oversized one 413 theme_zip_too_large. macOS metadata (__MACOSX/, ._*, .DS_Store) is skipped, and a pack wrapped in one top-level folder is found inside it. The unpacked directory then goes through the same local-source steps below; the governance gate is the same one.
  2. Stage — the source is copied into a private staging snapshot (.install-staging-<token>) via a per-file, symlink-rejecting, byte-bounded loop (_copy_installed_theme). The source dir remains attacker-writable throughout, so nothing read from it is trusted twice: the copy enforces a hard cumulative byte ceiling, and everything after this step operates on the snapshot only.
  3. Validate — _validate_theme_dir(stage, installing=True) runs on the immutable staging snapshot and returns (record | None, error): tier-gated category allowlist, filename allowlist, per-file/total size caps, symlink rejection, path-traversal rejection (_safe_theme_slug), CSS/HTML denylists, audio magic-byte sniff, and persona bounds. Validating the snapshot (not the source) closes the validate/copy TOCTOU class.
  4. Promote — the validated snapshot is atomically renamed into ~/.kiro/crew/themes/<slug>/. Concurrent installs of the same slug are serialized so staging never clobbers a live pack. Re-install overwrites (the update path); a 409 is returned only when a slug collides with an editor-created custom record.

HTTP Routes

Registered by dashboard/routes/themes.py (register), except GET /api/theme/boot, which dashboard/routes/realtime.py registers. The validation/parsing core lives in dashboard/theme_validate.py (constants, CSS tokenizer, _validate_*, _theme_asset_descriptor, path/slug helpers); the HTTP handlers below live in dashboard/handlers/themes.py:

Method Route Purpose
POST /api/themes/install Install from local dir or GitHub (overwrite on re-install)
POST /api/themes/install-zip Install from an uploaded .zip body (overwrite on re-install)
DELETE /api/themes/{slug} Remove an installed theme
GET /api/themes List custom + installed themes (the frontend adds built-ins)
GET /api/themes/{slug} Theme detail + resolved level
GET /api/theme/{slug}/assets/{path} Serve a pack asset (nosniff + content-type allowlist, validator + 304)
GET /api/theme/{slug}/overlay/{id} Serve overlay HTML (locked CSP, validator + 304)
GET /api/theme/{slug}/topbar/{mode} Serve topbar HTML for dark/light (locked CSP, validator + 304)

(GET /api/theme/boot and the editor CRUD POST/PUT /api/themes[/{slug}] predate this subsystem and remain the color-theme surface.)

Asset, overlay and topbar responses revalidate, never expire

All three serving routes answer through one helper (_theme_asset_response), which itself calls the dashboard-wide kiro_crew.dashboard.conditional_get (the same compare the appearance-media, app-art and crew-avatar routes use). A 200 carries ETag: W/"<hex>" — the 8-byte blake2b digest of the body bytes just read — and Cache-Control: private, max-age=0, must-revalidate. A request whose If-None-Match matches (RFC 9110 weak comparison via aiohttp's parsed request.if_none_match, so a list, the strong form of the same value and * all match) answers 304 with no body. The 304 repeats the 200's ETag, Cache-Control, X-Content-Type-Options: nosniff and Content-Security-Policy (_THEME_ASSET_CSP for assets, _THEME_OVERLAY_CSP for overlay/topbar HTML), so a revalidation never relaxes what the full response promised.

There is deliberately no long max-age: a re-install replaces the pack directory in place under the same slug and the same asset URLs, so a freshness lifetime would keep serving the old pack's bytes from the browser cache. Hashing the body keeps the validator honest across that swap while still turning the fonts, overrides.css and branding images fetched on every dashboard load into header-only round trips.

Security Model

  • Sandboxed rendering — overlays and topbars render in sandbox="allow-scripts" iframes without allow-same-origin, so they get no cookies, storage, or same-origin fetch. This is the real runtime boundary; install-time denylists are defense-in-depth.

  • Overlay layers — each overlay declaration may set layer. above (default) paints in the shell's decor slot, over the chat but under the top bar. behind paints in a second slot at z-index -1 inside the shell, over the shell background but under the nav, content and panels, so message bubbles and cards cover it. A behind overlay must be click-through: install rejects layer: "behind" with pointerEvents: true, and the client forces pointer-events: none on it. Routes without the shell (/popout/, /embed/) have no behind slot and skip behind overlays, since nothing there would cover them.

  • Locked CSP — overlay/topbar responses carry a fixed Content-Security-Policy including a sandbox directive; asset responses carry X-Content-Type-Options: nosniff and a content-type allowlist.

  • Descriptor-pinned containment — pack install and serving resolve the opened file descriptor before trusting bytes: /proc/self/fd on Linux, fcntl.F_GETPATH on macOS, and GetFinalPathNameByHandleW on Windows. The resolved path must remain inside the pack root; an unavailable or failed resolution rejects the read rather than falling back to a pathname-only check. On macOS, a case-only spelling mismatch is accepted by the shared reader only after a no-follow walk proves identity with the held descriptor; containment compares kernel spellings of the file and pinned root, never a globally case-folded prefix. This lets legitimate APFS aliases reach the install destination guard, which still refuses a source inside its own destination before promotion and preserves source and sibling contents.

  • postMessage allowlist — the parent (ThemeExperienceLayer.tsx) accepts only theme:resize, theme:sound, and theme:visibility messages from a pack iframe; all others are dropped. theme:state travels in the opposite direction, from the parent to each live theme iframe.

  • CSS containment — install-time denylist (no @import, external url(), dangerous functions/bindings, forbidden selectors, z-index > _THEME_OVERLAY_MAX_ZINDEX) via a string-aware top-level rule tokenizer, plus a runtime positive-selector scoper (scopeOverridesCss, website/src/hooks/themeCss.ts) that keeps only allowlisted selector forms and drops every non-@media at-rule. The scoper is the load-bearing runtime boundary for attacker-authored overrides.css injected into the main document; both hand-rolled parsers are slated for consolidation onto CSSOM rule-walking as a pre-1.0 blocker, tracked in kirodotdev#316 (milestone-bound to the first L1-pack release). Until then, drift between the two parsers — and between the scoper and real browser CSS parsing (escapes, comments, exotic at-rules) — is pinned by the shared adversarial corpus test/fixtures/theme_css_corpus.json, asserted against both parsers (pytest + vitest); new evasion classes MUST land as corpus cases. Same-pack-relative url()s are rewritten to absolute asset-route URLs (rewriteOverridesUrls); fonts are declared via theme.json fonts (served as font/ttf) and injected by injectThemeFonts, since an @font-face in overrides.css would be scoped away.

  • HTML containment — overlay/topbar HTML is rejected at install if it references external scripts, fetch/XMLHttpRequest, document.cookie, or localStorage/sessionStorage.

  • Persona — persona.md capped at 2000 chars (_THEME_PERSONA_MAX_CHARS, the enforced control). _validate_persona additionally runs an advisory keyword check for boundary phrases (e.g. a "drop persona" / security-override clause): this is a hygiene nudge on the pack author, not a security control — it is a substring scan that carries no runtime authority and is trivially satisfiable. The enforced server-side controls are (1) the hard 2000-char length bound and (2) content-binding (the injected text must hash-match the value the request supplies). The consent flow itself is a client-side UX affordance, not server-enforced authorization — see below.

    Parts and the consent dialog. An installed Level-2 pack has up to three parts, each on or off on its own: Sounds (audio and the mute button), Overlays (overlays and the topbar strip) and Persona. The palette, branding and overrides.css always apply while the pack is selected. A pack that ships sounds or a persona shows a dialog on first activation with one checkbox per part it ships, all checked, and the persona text verbatim under the Persona checkbox. Save applies the checked parts; Keep colors only (also Escape) turns every part off on this first answer. A pack that ships only overlays shows them without asking. The answer is one record per slug in the browser's localStorage, mc-theme-experience-<slug> = {sounds, overlays, persona} (website/src/utils/themeConsent.ts); while it exists the dialog does not return. A part the record does not list is off, so a part a re-install adds stays off until the user turns it on. The record is stored before the grant, so no grant is ever left without a record. When localStorage refuses the record (full or disabled), the answer is kept for that tab only with the persona off and no grant; when it refuses the grant, the persona is saved as off, since chat sends only a stored grant.

    Consent gate (what it actually guarantees — and what it does not). The persona grant is a separate key, mc-theme-consent-<slug>, holding sha256(persona_text) of the text the user saw and checked. It is written only while the Persona part is on and revoked whenever it is off; Sounds and Overlays never read or write it, so a pack without a persona never holds one. On every first-turn chat the frontend threads the stored grant as theme_consent_sha; _maybe_inject_persona (chat_utils_slots.py) injects the pack's persona only when theme_consent_sha equals sha256 of the persona text it reads from disk at that moment (constant-time compare). A missing hash, or a stale one after a reinstall rewrote persona.md, fails closed: the new, never-consented text is not injected. The layer revokes the stale grant before the user answers and asks again about the persona only; Sounds and Overlays keep their answer. This is surprise-prevention: what is injected is exactly the persona text the user saw and checked. It is not server-enforced consent: the server never records a grant, GET /api/themes/{slug} returns personaInfo.sha256 (and the text) to any authenticated caller, so an authenticated API client can synthesize a valid theme_consent_sha without a human ever seeing the modal. Consent also lives in one browser's localStorage, so headless/multi-browser clients have no consent story. Anyone extending persona scope (longer bound, per-turn injection, richer tiers) MUST NOT build on a server-side-consent invariant — it does not exist. The legacy boolean theme_consent request field is still parsed for backward-compatible bodies/logging but grants no injection on its own.

    "Keep colors only" and changing the answer later. On a first answer, Keep colors only stores every part off and revokes any grant, so nothing reaches theme_consent_sha, and no sounds, overlays, topbar or mute button run. No change to the pack clears it. The parts of the active pack are changed in Settings > Display > Theme > Experience (ThemeExperienceSettings.tsx), which lists only the parts the pack ships. Sounds and Overlays apply when toggled. Turning Persona on stores the persona as wanted without a grant, which opens the consent dialog asking about the persona only, with its text; the grant is written when Save is pressed there. That dialog's decline button reads Keep persona off; it (or Escape) turns only the persona off and leaves Sounds and Overlays as they were. Turning Persona off revokes the grant at once. When Save in the dialog cannot store the choice, the dialog closes and the choice applies for that tab. When it cannot store the persona grant, the dialog stays open on the persona alone and shows an error without the agent hand-off, since the persona pick is not saved yet. When a toggle in the Experience section cannot be stored, the choice still applies for that tab and an error with the agent hand-off shows under the section until the next toggle is stored. The layer and the section re-read on the mc-theme-experience-changed event and the storage event. Picking a theme in the picker or restoring it at boot changes no record, so a pack with a record never asks again and one without a record asks. A grant from an older build that matches the pack migrates once to an all-on record.

    All personas come from installed packs and are content-bound consent-gated by the mechanism above — there is no built-in / unconditional persona path. A theme injects a persona only via a validated persona.md in an installed pack (custom-<slug>), and only when the caller's theme_consent_sha matches the on-disk text. There is no trusted first-party registry that injects without consent.

    Scope of a persona. A persona is tone/voice only. It cannot change the agent's available tools, its refusals, or any guardrail — it is appended as ordinary text appended to the first user message of a session (not the system prompt) with no runtime authority over policy.

    Governance. Persona injection is gated by the capabilities.theme_persona governance capability (SCOPE_CATALOG, capability_default=True): standalone it defaults to allow, but an enterprise POLICY can force-disable installed-pack persona injection wholesale (consulted at the injection site in _turn_build_prompt, chat_turn/prompt_assembly.py; a denying policy skips injection silently). See governance.md.

Frontend Integration Points

Surface File Role
Loader website/src/hooks/useTheme.tsx Applies CSS vars; applyThemeOverrides → scopeOverridesCss + rewriteOverridesUrls (themeCss.ts); injectThemeFonts; pre-apply self-repair; themeSwitching state
Render cache website/src/hooks/themeRenderCache.ts Persists the active pack's detail under localStorage["mc-theme-data"] and reads it back synchronously at ThemeProvider mount so the first paint is themed
Experience layer website/src/components/ThemeExperienceLayer.tsx Mounts sandboxed overlay/topbar iframes + audio; enforces the postMessage allowlist
Settings UI website/src/pages/settings/DisplayPanel.tsx Single Theme dropdown + install-from-GitHub/local folder/uploaded .zip + remove + "Applying…" status indicator; the Experience section listing the active Level-2 pack's parts (Sounds, Overlays, Persona) as toggles (ThemeExperienceSettings.tsx); the catalog-failure and unstyled-theme notices with Retry (see Catalog failure below)
Utility bridge website/src/tailwind-theme.css Tailwind v4 @theme mapping each utility (bg-accent, text-muted/40, rounded-md, shadow-sm, font-mono) onto the runtime CSS variable of the same stem, plus the dark: variant keyed on [data-theme="dark"]. A pack changes what a utility renders by writing the variable; it never touches this file.

Boot sequence: themed first paint

Fetching /api/themes, then each pack's detail, then overrides.css, then the fonts, each round trip behind the last, would paint an installed theme seconds late. The boot path therefore has two parts.

  1. Render cache (zero requests). localStorage["mc-theme-data"] holds ONE entry: the active pack's CustomThemeData JSON (the GET /api/themes/{slug} detail), written when that pack is applied. ThemeProvider reads it synchronously at mount and seeds variables, fonts and branding before the first paint. The cache holds only the Level-1 projection (colors, fonts, branding, overrides flag and loader art); Level-2 experience content (overlays, topbar, audio and persona) is applied only from the current server detail because consent is bound to its content hash. The server stays the source of truth: customThemesLoaded is never set from the cache, so self-repair and the picker still wait for the real catalog. The entry is removed when the selection moves to a built-in theme, when the pack is deleted, or when the catalog no longer lists the slug (the pack was removed elsewhere). It is never written when the serialized detail exceeds roughly 200 KB (MAX_ENTRY_CHARS), so the cache cannot grow past one small pack.
  2. Parallel active fetch. fetchCatalog, run by the ["custom-themes-catalog"] React Query (staleTime: Infinity), requests the active pack's detail alongside /api/themes instead of after it, applies it on arrival (refreshing the cache entry), and skips that slug in the catalog pass. loadCustomThemes is the one-shot refresh for post-mutation callers (the theme editor and the Display panel): it cancels the in-flight catalog fetch, refetches, is serialized so back-to-back mutations cannot race, and resolves true or false without ever rejecting.

The asset routes' validators (above) cover the third leg: once the detail is applied, the fonts and overrides.css it references revalidate as 304s rather than re-downloading.

Catalog failure

  • Auth denial. A /api/themes 403 with a lapsed access cookie waits for the silent refresh checkSessionExpired starts and replays exactly once; an auth denial is never retried by the query, and the re-auth banner owns that recovery.
  • Anything else. While no catalog has loaded, the query retries indefinitely (the gateway may still be booting, or a tunnel answered 502/503); once one has loaded, a failed refetch follows the app-wide retry policy. Delays use the shared curve, 1 s doubling to a 30 s cap.
  • Notices. customThemesLoadError reports a catalog that will not load (a gateway auth denial excluded; a proxy challenge included), and installedThemeLoadFailed reports a selected pack that is listed but whose detail failed. The Display panel renders both, with a Retry for the catalog.
  • Listed but unstyled. While installedThemeLoadFailed holds, the default built-in theme's attribute is painted and the user's selection is kept, so the picker still shows it and the notice explains the state.
  • Self-repair keys on the listing. A pack the catalog lists is not reset to the default because its detail failed; only a slug the catalog no longer lists is.

One theme, one picker row (registered vs installed)

allThemes is [...builtinThemes(), ...REGISTERED_THEMES, ...customThemes]. A downstream edition contributes a built-in theme through the registerTheme() seam (see extension-seams), and that registrar de-duplicates against THEMES and REGISTERED_THEMES — but not against installed packs, which arrive asynchronously from GET /api/themes long after registration. Their values differ too (lcars vs custom-lcars), so an edition that ships a theme BOTH ways gets two picker rows for one theme with nothing flagging it.

The pack row is the broken one, which is why registration wins: a registered theme's CSS is keyed to [data-theme="<slug>-dark"] and lives in the edition's compiled stylesheet, while a pack renders under [data-theme="custom-<slug>-dark"] — a selector that stylesheet does not define. The pack copy therefore shows only the flat variables in its variables.json and loses every structural rule (nav shapes, body::before overlays, message bubbles), which variables.json cannot express at all. allThemes drops an installed pack whose slug matches a registered theme; matching is on the whole slug, so kr-extended is not evicted by a registered kr. Pinned by website/src/test/themeRegisteredPackDedupe.test.tsx.

Contribute a theme ONE way. A pack is the right vehicle when it needs a persona (_maybe_inject_persona gates on the custom- prefix, so a registered theme cannot carry one); registration is the right vehicle when the theme needs structural CSS beyond the variable set.

Sample / Test Packs

No theme-bearing packs ship in the code package (wheel/sdist/frozen). Sample and test packs live outside the repo; the full-L2 install/validate/persona regression is exercised entirely from fixtures built in a temp directory (see test/test_theme_install.py::TestFullL2Fixture), so nothing shippable carries a persona or third-party-derived branding.

This covers art assets too, not just personas and manifests. When retiring a theme, delete its art in the same change: MANIFEST.in's recursive-include src/kiro_crew/static * ships every file under src/kiro_crew/static/ in the sdist, wheel and DMG, so an orphan there is a shipped orphan, not dead weight in a dev tree.