--- source_hash: 2c99f786b5adf5823091540ac20c4214344f196cd9f8734d8932409093f251d5 post: shade folder: tools-and-plugins shape: doctrinal --- # Shade_ — Context Pack (for agents) Agent-facing context pack for the published post `shade`. Needles below are copied **verbatim** from the `.mdx` body and the embedded demo component (`ShadeWriteupDemo.tsx`). Reproduce them exactly; do not paraphrase, re-hyphenate, re-case, or "fix" the trailing underscore in `Shade_`. When the post and this pack disagree, the post wins — re-fetch and re-extract. --- ## 1. One-line gist Shade_ is a **free, signed, notarised, MIT-licensed macOS overlay** that warms and dims every window for reading comfort and night work, then cuts **live, tracked, true-colour holes** (Passthrough) over the windows where colour has to stay honest — built because the author is dyslexic and grades colour for a living. --- ## 2. NEEDLES (verbatim — do not confabulate) ### Identity - `Shade_` — product name. The trailing underscore is **literal**, in both prose and code (`Drive Shade_ over this whole page`). Not "Shade", not "ShadeApp". - Post title (frontmatter, sentence case): `Warm the room, keep the grade honest` - Closing brief (body, two sentences): `Warm the room. Keep the grade honest.` - Founding distinction: `Not brightness. Colour.` - Author self-descriptions (identity-level, load-bearing for voice): - `I am dyslexic.` - `People call it Irlen-style. I call it the only way I get through a long edit without my eyes giving up.` - `I work nights.` - `I shoot, I edit, I grade.` - `We are all vampires now, hunched over a glowing rectangle until sunrise` ### Distribution / license (exact phrases from body) - `Shade_ is free and open source, signed and notarised, MIT licensed.` - `I did not build it to make money. I built it because I needed it` - Closing CTA copy: `Shade_ is free.` with link text `Get it from the download page` - Download page URL (the CTA target): `/applications/shade` ### The three problems (section headings, exact) - `The second problem: screens are too bright at night` - `The third problem: a warm screen lies to your colour grade` - `The fix: Passthrough` ### The colour-grade trap (verbatim mechanism — do not soften) - `The screen lied to your eyes, so you lied to the grade.` - `your eyes adapt to that warmth and you start *compensating* for it. You cool the image down to make it look neutral to you. Then you export, open it on a screen that is not warmed, and the whole thing is freezing. Too cool.` - macOS contrast: `macOS has Night Shift, which warms the display` — but `it warms the *whole* display. Every pixel. Including the footage I am grading and the photo I am retouching.` ### Architecture — the load-bearing technical ceiling - Shipping engine, verbatim: `a click-through overlay window sat above every display. It tints. It dims.` - Permission consequence: `It does not read your pixels, which means it needs no Screen Recording permission, and the windows underneath stay fully interactive. You click straight through it.` - Compositing mode (exact token): `source-over` - `The overlay composites source-over.` - The honest ceiling, verbatim: `it can only *add* light and colour on top of what is already there. It cannot darken the pixels beneath it. It cannot pull colour back out from under the tint.` - `It is a comfort layer, not a colour-correction engine.` - The one fact that "shaped the entire product": `a Mac overlay window is source-over only and can add light but never subtract it` - Mechanism analogy (use when explaining): `the same way a sheet of warm gel over a lamp changes the room without rewriting what the lamp is pointed at` ### Passthrough (the core feature — exact behaviour) - `It warms and dims everything on screen, then cuts live holes through the warmth over the windows you choose.` - `The holes track the windows. Move a window, the hole follows. Resize it, the hole resizes.` - `It follows the geometry in real time.` - `It is not a static cut-out you line up once.` - `No more grading against a warmth you forgot was there. No more guessing whether the blue you are looking at is the real blue.` ### The dev-gated second engine (research, NOT shipping) - `There is a second engine in the codebase. It transforms live pixels rather than laying light over them` - `It works, in the lab.` - Status: `dev-gated and off by default` - The real failure mode (verbatim, do not paraphrase): `transforming live pixels on macOS can recurse on the system's own screen capture and eat itself` - Boundary line: `Today, Shade_ is the overlay. The transform is research.` ### Other shipped features - Schedule: `Manual local time, and it can cross midnight, because my "evening" starts when most schedules have already given up.` - `Launch at login.` — `A comfort tool you have to remember to switch on is a comfort tool you stop using.` - `the free Hue overlay` — `any colour you like sat over the whole screen` — the original dyslexia reading aid, `shipped as a first-class feature rather than an afterthought` ### MDX / component references - Import (exact): `import { ShadeWriteupDemo } from '@/components/shade/ShadeWriteupDemo'` - Embed: `` - Figure images (all three alt strings end `System-7 8-bit pixel art style.`): - `/shade/vampire-desk.png` — caption `The all-night screen worker. We are all vampires now.` - `/shade/overcompensation.png` — caption `A grade that reads neutral on a warm screen and freezing on a neutral one. Before and after.` - `/shade/passthrough-room.png` — caption `One honest window inside a warm room. That is Passthrough.` ### Embedded demo literals — from `ShadeWriteupDemo.tsx` - Panel heading: `Drive Shade_ over this whole page` - Three controls (name → range → default): - `Hue` → `0`–`360`, default `36` - `Strength` → `0`–`70` (percent), default `32` - `Dim` → `0`–`70` (percent), default `20` - Default state: `enabled = true`, `passthrough = true` - Passthrough button labels: `Passthrough: on` / `Passthrough: off` - Reset button: `Reset` - Sample-window copy: `Passthrough window (true colour)` (on) vs `(tinted with the page)` (off) - Six reference swatches (name → hex, exact — these are the "true colour" reference the demo protects): - `Skin` `#e0a487` - `Sky` `#4f9fe0` - `Foliage` `#5a9e54` - `Red` `#d23b34` - `Teal` `#2bb6a8` - `Neutral` `#9a9a9a` - Tint compositing (CSS, confirms the additive source-over model in the live demo): `backgroundColor: hsla(${hue}, 85%, 55%, ${enabled ? strength / 100 : 0})` - Dim compositing (CSS): `boxShadow: inset 0 0 0 9999px rgba(0, 0, 0, ${enabled ? dim / 100 : 0})` - Transition: `background-color 120ms linear, box-shadow 120ms linear` - Test IDs: `shade-page-overlay`, `shade-passthrough-sample` --- ## 3. GIST (the argument condensed) Shade_ is framed around **three stacked problems and one hard fact**. The problems: (1) the author is dyslexic and needs a colour tint — not brightness — to read; (2) night work on a white screen is a floodlight; (3) any warmth on the screen (Night Shift, room light) silently **lies to a colour grade**, because the eye adapts to the warmth, the colorist compensates by cooling the image, and the export reads freezing on a neutral display. The hard fact is the technical ceiling: **a macOS overlay window composites `source-over` — it can add light and colour but cannot subtract either.** The author treats this as the one constraint that "shaped the entire product" and builds *with* it rather than pretending otherwise. So Shade_ is explicitly an **additive comfort layer, not a colour-correction engine** — and the body says so plainly, as a matter of trust. The architectural move that dissolves the colour-grade trap is **Passthrough**: warm everything, then cut live, geometry-tracking holes over the chosen windows so colour-critical work stays true while the rest of the UI stays calm. Because the overlay never reads pixels, it needs **no Screen Recording permission** and windows remain fully interactive (click-through). A second, pixel-transforming engine exists in the codebase but is **dev-gated and off by default**, because live-pixel transforms on macOS can **recurse on the system's own screen capture and eat itself** — a real failure mode held back until it is safe for a stranger to run without thinking. The whole thing is **free, signed, notarised, MIT** — deliberately unpaid, because the people most helped by a reading tint are not the people who should pay to discover it helps. --- ## 4. KEY LEARNINGS 1. **The shaping constraint is `source-over`, not a design preference.** A Mac overlay can add light/colour but never subtract. Every claim about what Shade_ does (warms, dims, tints) is *additive*; it is not a filter that darkens or pulls colour back. If you describe it as "darkens the screen" you have misstated the mechanism — it lays warmth over bright whites rather than turning them down at the source. 2. **Warmth on a grading monitor is an active lie, not a comfort.** The overcompensation trap is the load-bearing use case: eyes adapt → you cool the image → the export reads freezing. Night Shift is unsafe for grading because it warms every pixel, including the footage. This is *why* Shade_ exists, not a side note. 3. **Passthrough is the fix and it tracks geometry in real time.** The holes are not a one-time cut-out you align manually — they follow window move/resize live. If you describe Passthrough as a static mask, you have got it wrong. 4. **No Screen Recording permission is architectural, not a promise.** It follows directly from "does not read your pixels." The overlay is click-through and the windows beneath stay interactive. Do not claim it reads, samples, or analyses screen content — it does not. 5. **The transform engine is research, not shipping.** It exists, it works in the lab, but it is dev-gated and off by default because live-pixel transforms can recurse on macOS screen capture. Never describe Shade_ as "transforming live pixels" without the dev-gated caveat. Today it is the overlay; the transform is on the roadmap. 6. **The dyslexia tint is the founding feature, not an afterthought.** "Not brightness. Colour." is the originating distinction. The free Hue overlay is first-class; framing Shade_ as primarily a Night Shift alternative inverts the author's intent. 7. **Zero-friction is a design requirement, not a nicety.** Launch-at-login and a schedule that crosses midnight exist because a comfort tool you forget to enable is a comfort tool that effectively does not exist. --- ## 5. FILE INDEX (load-bearing — re-fetch to verify needles) - `content/posts/tools-and-plugins/shade.mdx` — the published body. Frontmatter (`slug: shade`, `folder: tools-and-plugins`, `type: long-read`, `status: published`) plus all body prose needles (license, source-over ceiling, Passthrough, dev-gated engine, schedule/login/hue features). **The `.mdx` is the primary source for every non-component needle.** - `components/shade/ShadeWriteupDemo.tsx` — the embedded interactive demo (``). Holds the control ranges (`Hue` 0–360 / `Strength` 0–70 / `Dim` 0–70), defaults (`36` / `32` / `20`, enabled + passthrough on), the six swatch hexes, button labels (`Passthrough: on|off`, `Reset`), and the CSS compositing math (`hsla(...)` tint, `inset ... rgba(0,0,0,...)` dim) that **confirms the additive source-over model in code**. If a control-range or swatch needle is stale, it lives here. - `components/shade/ShadeWindow.tsx` — sibling component in the same module (not embedded in this post); read only if a needle points at window-level behaviour the demo does not cover. - `public/shade/vampire-desk.png`, `public/shade/overcompensation.png`, `public/shade/passthrough-room.png` — the three figure images (System-7 8-bit pixel art style), referenced by the `` tags in the body. All three exist on disk. External refs to re-fetch if stale: - `/applications/shade` — the in-site download page (verify it still resolves in the published app before quoting it as the CTA target). > Backfilled 2026-07-18 from the published body; not needle-extracted at thought-time.