oikos/plans/done/2026-08-03-cyberspace-style-adoption.md

2026-08-03 — Adopt cyberspace.online terminal aesthetic + dithered images

Status: Implemented in v0.16.0 (757ef2f). Shipped as a full theme replacement (Terracotta/Carbon → cyberspace BBS/terminal style), not the opt-in addition originally drafted below — the operator chose full replacement during execution (see decision theme.replace_with_cyberspace). The <RasterImage> Atkinson-dithering component and the warm-cream/JetBrains-Mono look landed as drafted; only the "opt-in vs replace" scope changed.

Adopt the look of https://cyberspace.online/ (a BBS / "social media de-imagined" terminal aesthetic) as a new, opt-in theme family in oikos, with both light and dark variants, plus a reusable <RasterImage> component that renders images to a <canvas> with Atkinson dithering (the "kinda dithered" image style). The existing Terracotta/Carbon themes stay the default; this adds, it does not replace.

---

TL;DR

1. Add a third theme family — "Cyberspace Dark" and "Cyberspace Light" — wired through the same --background / --foreground / … token layer every component already uses, so nothing in the UI tree changes; only the tokens get new values. Square corners (--radius: 0), warm cream-on-black, mono everything.
2. Extend web/src/lib/stores/theme.svelte.ts from a 2-state 'light'|'dark' toggle to a named-theme model, keeping .dark class behavior for compatibility.
3. Self-host JetBrains Mono (body) + a pixel/terminal face (VT323 or Departure Mono) for the logo/headings accents, replacing the Google Fonts <link>.
4. Build web/src/lib/components/RasterImage.svelte: draws any image to a <canvas> reduced to a 2-color (theme fg/bg) palette via Atkinson dithering, with an <img> fallback and a skeleton placeholder — exactly the cyberspace pattern. Re-renders when the theme changes (palette flips).
5. Optional cosmetic idioms (terminal-box focus ring, braille spinner, <s> strike lists) as small additive utilities, not a redesign.

The whole thing is non-breaking and incremental: each step ships behind the existing theme picker, so Terracotta/Carbon users see nothing until they opt in.

---

1. Extracted style spec (source of truth from cyberspace.online)

Captured from the live site's SSR HTML + inline boot script. This is the reference the tokens below are derived from.

1.1 Color model

Cyberspace defines exactly three colors per theme — fg, bg, fgDim — applied to CSS custom properties. Everything else (borders, primary, cards) is derived from those three. There are 11 named themes total; the two we care about:

Theme	fg (text)	bg (canvas)	fgDim (muted)
Dark	#efe5c0	#000000	#a89984
Light	#000000	#efe5c0	#3a3a3a

Note the elegance: light and dark are exact inverses — they share the same warm cream (#efe5c0, a Gruvbox-ish paper tone) and just swap which side of it is ink vs. paper. The muted tone #a89984 is straight out of the Gruvbox palette. This is why both themes read as "the same site" despite opposite polarity.

Boot-time fallback (the site's original/GRiD theme) is amber #FF9810 on #120900 — useful as a third optional accent if we ever want a true-phosphor variant.

1.2 Type

• Body / mono: JetBrains Mono (self-hosted .woff2, Regular).
• Boot + logo accents: Departure Mono (self-hosted .woff2). A quirky monospace; VT323 (Google, free) is a close, easy substitute.
• Stylized wordmark (ᑕ¥βєяรקค¢є, class .font-vt): a terminal/pixel face. Rule lives in their external entry.*.css (not in the SSR dump); VT323 is the safe assumption.

cyberspace sets font-mono on the root wrapper — the entire UI is monospace. There is no proportional body face. Headings use the same mono family at larger size / normal weight.

1.3 Layout & component idioms

• Left rail nav: fixed, icon-only when minimized (~80px), expands on click. Square buttons, Phosphor icons, uppercase text-xs labels.
• .terminal-box: the universal card. Bordered (border border-border), square corners (rounded-none everywhere — --radius is effectively 0), and on focus/emphasis gets ring-2 ring-fg (a 2px ring in the foreground color).
• Emphasis by inversion: active/primary state is bg-fg text-bg — fill with foreground ink, text becomes the canvas color. No separate "accent" hue; the accent is fg.
• Strikethrough as a feature list: <s>Ads</s> <s>Videos</s> … — crossed-out <s> elements spell out what the product removes. Cheap, on-brand.
• Braille spinner: BrailleSpinner component animates braille block chars (⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏) for loading states instead of a circle.
• Max content width max-w-4xl, centered; generous vertical rhythm; thin 2px scrollbars colored --color-border.
• Borders are 1px solid in a border color derived from fg/fgDim at low alpha (their --color-border is not literally in the dump, but every bordered surface uses it, and it tracks fg).

1.4 The dithered image (RasterImage) — what we actually know

From the SSR HTML the component is unambiguous about its shape, silent on its algorithm (the dither JS is in an external /_nuxt/*.js bundle not present in the page dump):

• Renders a <canvas> as primary output, with an <img> fallback as a sibling. Parent selectors [&>canvas]:max-w-full [&>canvas]:h-auto and [&>img]:… size both responsively.
• Emits a .raster-image-skeleton placeholder (empty div, background: var(--color-bg)) during SSR/before hydration — no flash of the raw photo.
• Scoped styles (data-v-4d61df89): .raster-image { display:block }, .raster-image-skeleton { display:block; background:var(--color-bg) }.

Inferred technique (standard for this look): Canvas 2D → drawImage → getImageData → per-pixel luminance reduction to a 2-color palette (fg/bg) with an error-diffusion pass (Atkinson or Floyd–Steinberg) → putImageData. This produces the characteristic speckled 1-bit halftone. Target is almost certainly the theme's own fg/bg, which is why the dithered art recolors correctly when you flip themes.

We will implement Atkinson (see §4) — it's the classic Mac/BBS dither, slightly softer than Floyd–Steinberg, and matches "kinda dithered" precisely.

---

2. Recommended approach: opt-in theme family (not a rebrand)

oikos today = Art-Nouveau / terracotta / rounded / serif-heading (Inknut Antiqua), floating-window desktop shell. cyberspace = BBS / mono / square / cream-on-black. These are opposite poles; a flat rebrand would discard the existing art direction and rework every component's rounding/spacing.

Decision: add cyberspace as a new theme family, selectable in the existing theme picker. This is low-risk, reversible, and lets the dithered images + terminal idioms land incrementally. The full-rebrand alternative is documented in §7 for if you later decide to make it the default.

Because every oikos component consumes colors through the Tailwind v4 token layer (--background, --foreground, --card, --border, --primary, …) defined in web/src/app.css @theme inline, a new theme is just a new set of values for those same custom properties — zero component edits required for the recolor. That indirection is the whole reason this is cheap.

---

3. Theme token additions (web/src/app.css)

Add two new blocks alongside the existing :root (Terracotta) and .dark (Carbon). They set the same token names to cyberspace's values, plus pin --radius: 0 for square corners and remap fonts (see §5).

Driven by a data-theme attribute on <html> (set by the store, §6), so all four states — Terracotta, Carbon, Cyberspace Dark, Cyberspace Light — coexist:

/* ── Cyberspace Dark (cream on black) ── */
:root[data-theme='cyber-dark'] {
  --radius: 0px;
  --background: #000000;
  --foreground: #efe5c0;
  --card: #000000;                 /* cyberspace has no card tint; cards are just bordered bg */
  --card-foreground: #efe5c0;
  --popover: #000000;
  --popover-foreground: #efe5c0;
  --primary: #efe5c0;              /* emphasis = fg ink */
  --primary-foreground: #000000;   /* inverted */
  --secondary: #1a1a1a;
  --secondary-foreground: #efe5c0;
  --muted: #141414;
  --muted-foreground: #a89984;     /* fgDim */
  --accent: #efe5c0;
  --accent-foreground: #000000;
  --destructive: #cc241d;          /* Gruvbox red, sits in the same palette */
  --destructive-foreground: #efe5c0;
  --border: color-mix(in oklab, #efe5c0 22%, transparent); /* fg-derived hairline */
  --input: color-mix(in oklab, #efe5c0 28%, transparent);
  --ring: #efe5c0;                 /* the ring-2 ring-fg look */
  --sidebar: #000000;
  --sidebar-foreground: #efe5c0;
  --sidebar-primary: #efe5c0;
  --sidebar-primary-foreground: #000000;
  --sidebar-accent: #1a1a1a;
  --sidebar-accent-foreground: #efe5c0;
  --sidebar-border: color-mix(in oklab, #efe5c0 22%, transparent);
  --sidebar-ring: #efe5c0;
  --chart-1: #efe5c0; --chart-2: #a89984; --chart-3: #fabd2f;
  --chart-4: #b8bb26; --chart-5: #83a598;   /* Gruvbox for charts */
  --success: #b8bb26; --warning: #fabd2f;

  /* oikos semantic aliases (app.css :root block) */
  --bg: var(--background); --bg-surface: var(--card); --bg-deeper: #050505;
  --bg-hover: var(--secondary); --bg-active: var(--accent);
  --text: var(--foreground); --text-muted: var(--muted-foreground);
  --accent-blue: #83a598; --accent-green: var(--success);
  --accent-red: var(--destructive); --accent-orange: var(--warning);

  /* terminal face for this theme only (see §5) */
  --font-sans: 'JetBrains Mono', ui-monospace, Menlo, monospace;
  --font-mono: 'JetBrains Mono', ui-monospace, Menlo, monospace;
  --font-heading: 'VT323', 'JetBrains Mono', monospace; /* pixel wordmark feel */
}

/* ── Cyberspace Light (black on cream paper) — exact inverse ── */
:root[data-theme='cyber-light'] {
  --radius: 0px;
  --background: #efe5c0;
  --foreground: #000000;
  --card: #efe5c0;
  --card-foreground: #000000;
  --popover: #efe5c0;
  --popover-foreground: #000000;
  --primary: #000000;
  --primary-foreground: #efe5c0;
  --secondary: #e0d6b0;
  --secondary-foreground: #000000;
  --muted: #e6dcc0;
  --muted-foreground: #3a3a3a;     /* fgDim */
  --accent: #000000;
  --accent-foreground: #efe5c0;
  --destructive: #9d0006;
  --destructive-foreground: #efe5c0;
  --border: color-mix(in oklab, #000000 22%, transparent);
  --input: color-mix(in oklab, #000000 28%, transparent);
  --ring: #000000;
  --sidebar: #efe5c0;
  --sidebar-foreground: #000000;
  --sidebar-primary: #000000;
  --sidebar-primary-foreground: #efe5c0;
  --sidebar-accent: #e0d6b0;
  --sidebar-accent-foreground: #000000;
  --sidebar-border: color-mix(in oklab, #000000 22%, transparent);
  --sidebar-ring: #000000;
  --chart-1: #000000; --chart-2: #3a3a3a; --chart-3: #b57614;
  --chart-4: #79740e; --chart-5: #076678;
  --success: #79740e; --warning: #b57614;

  --bg: var(--background); --bg-surface: var(--card); --bg-deeper: #e6dcc0;
  --bg-hover: var(--secondary); --bg-active: var(--accent);
  --text: var(--foreground); --text-muted: var(--muted-foreground);
  --accent-blue: #076678; --accent-green: var(--success);
  --accent-red: var(--destructive); --accent-orange: var(--warning);

  --font-sans: 'JetBrains Mono', ui-monospace, Menlo, monospace;
  --font-mono: 'JetBrains Mono', ui-monospace, Menlo, monospace;
  --font-heading: 'VT323', 'JetBrains Mono', monospace;
}

Two notes:

• .dark vs data-theme. The current store flips .dark on <html>. To keep Carbon working unchanged, leave .dark logic alone and layer data-theme on top: when a cyberspace theme is active the store sets data-theme and removes .dark (cyberspace themes are self-contained — they set both polarities explicitly). See §6.
• Borders from fg. cyberspace's hairline tracks the foreground, not a fixed gray. color-mix(in oklab, <fg> 22%, transparent) reproduces that and auto-flips between the two themes. Tune the % after visual review.

---

4. The dithered image component (RasterImage.svelte)

File: web/src/lib/components/RasterImage.svelte (sibling of the existing Spinner.svelte).

4.1 API

<RasterImage src={entity.iconUrl} alt="host icon" width={320} />
<!-- optional: scale (downsample factor), threshold bias, mono palette override -->

• src, alt — as <img>.
• width — render width in CSS px; canvas is sized to this × natural aspect. Downscaling before dithering is what sells the "lo-fi" look (defaults ~256– 320). Expose scale (0–1) to control.
• Reads the active theme's --foreground / --background via getComputedStyle(document.documentElement) so the dither palette follows the theme (cream/black in cyber-dark, black/cream in cyber-light, and perfectly sensible in Terracotta/Carbon too).

4.2 Behavior

1. Show .raster-image-skeleton (empty, background: var(--background)) until the source image loads — matches cyberspace's no-flash placeholder.
2. On load: create an offscreen canvas at width × (h/w*width), drawImage (with imageSmoothingEnabled = true for the downscale), pull getImageData.
3. Run Atkinson dithering to 2 colors:
   • For each pixel: luminance Y = 0.299R + 0.587G + 0.114B.
   • Threshold at 128 (+ optional bias), snap to either fg or bg.
   • Push 1/8 of the quantization error to each of 6 neighbors (Atkinson's kernel): right, below-left, below, below-right, and two pixels down on the next-next row. (Atkinson diffuses less than Floyd–Steinberg → softer, more "screen-printed" — exactly the cyberspace feel.)
   • Write fg/bg (read from CSS vars at render time) into the buffer.
4. putImageData. Canvas is the visible output; the loaded <img> is kept as aria-hidden fallback for no-JS / copy-image / accessibility.
5. Re-dither on theme change: subscribe to the theme store; when it flips, re-read --foreground/--background and re-run steps 3–4 (cheap — the decoded ImageBitmap is cached, only the palette pass reruns). This is the detail that makes the art flip polarity with the theme toggle.
6. Respect prefers-reduced-data / reduced motion? Dithering is not motion, but offer a plain prop to skip the canvas and render the raw <img> for users who want crisp photos (e.g. entity detail screens where legibility beats aesthetic).

4.3 Reference dither kernel (Atkinson)

        *   →   1/8   1/8
1/8 1/8 1/8       (current pixel = *)
    1/8 1/8        (* is at top-left of this 4×? — see standard Atkinson spread)

Spread pattern (error e from pixel at (x,y) distributed):

              px        x+1 (1/8)   x+2 (1/8)
x-1 (1/8)   x (1/8)   x+1 (1/8)
              x+1 (1/8)   x+2 (1/8)   [next row offsets]

Concretely, 6 neighbors each get e/8: (x+1,y), (x+2,y), (x-1,y+1), (x,y+1), (x+1,y+1), (x,y+2). (Clamp at edges — drop, don't wrap.)

4.4 Where to use it

• Entity icons / host thumbnails in the KB and entity desktop (the obvious win).
• Mascot or login/Config background art (ConfigBackground.svelte already exists — a dithered backdrop there would be striking).
• Any user-uploaded image in chat/knowledge where we want the "de-imagined" tone. Keep it opt-in per call site via the plain prop — don't dither diagrams/screenshots that need to stay readable.

4.5 Cross-origin caveat

getImageData throws on tainted canvases. If src is cross-origin and the server doesn't send CORS headers, fall back to the plain <img> (log once). For self-hosted assets (the common case here) it's a non-issue.

---

5. Fonts: self-host JetBrains Mono + VT323

cyberspace self-hosts both faces as .woff2. oikos currently pulls DM Sans / DM Mono / Inknut Antiqua from Google Fonts via a <link> in web/index.html:10.

• Drop JetBrainsMono-Regular.woff2 and VT323-Regular.woff2 under web/static/fonts/ (or web/public/fonts/ — match where static assets are served from; check vite.config).
• Add @font-face blocks at the top of app.css with font-display: swap.
• For the cyberspace themes only, the --font-sans/--font-mono/--font-heading overrides in §3 remap the families — Terracotta/Carbon keep DM Sans/Inknut untouched. This is the key trick: font choice is part of the theme, not a global swap, so the two art directions don't fight.
• Leave the Google Fonts <link> in place for now (Terracotta/Carbon still need it); add a follow-up to self-host those too if we want to kill the external request entirely. Out of scope for this plan.

VT323 vs Departure Mono: VT323 is free on Google Fonts and trivial to self-host; Departure Mono is the authentic cyberspace face but needs a license check. Recommend VT323 to start; swap to Departure Mono later if you want exact fidelity.

---

6. Theme store changes (web/src/lib/stores/theme.svelte.ts)

Current: Theme = 'light' | 'dark', flips .dark class. Extend to a named set while preserving the existing API (callers of toggleTheme/getTheme keep working):

export type ThemeName = 'terracotta' | 'carbon' | 'cyber-dark' | 'cyber-light'
// Back-compat aliases used by existing callers:
//   'light' -> 'terracotta', 'dark' -> 'carbon'

• Store key stays oikos-theme; migrate old 'light'/'dark' values on read.
• applyClass becomes applyTheme: sets data-theme on <html> and toggles .dark only for carbon (so Terracotta and both cyberspace themes run with no .dark). This is important: the .dark block in app.css must not layer on top of the cyberspace token blocks — cyberspace sets its own polarities.
• Update THEME_LABELS to the four names; update whatever UI surfaces the picker (search for THEME_LABELS / toggleTheme usages — likely Settings.svelte or the desktop shell's chrome) to a 4-option control instead of a binary toggle.

Watch out: any code that assumes document.documentElement.classList.contains('dark') ≡ "dark colors" will be wrong for cyber-dark. Audit grep -rn "classList.*dark\|\.dark" web/src and prefer reading getTheme()/data-theme instead.

---

7. Optional cosmetic idioms (additive utilities)

Small, theme-aware utilities in app.css — usable in any theme but idiomatic for cyberspace:

• .terminal-box — { border:1px solid var(--border); border-radius:0 } plus a .terminal-box:focus-within { box-shadow: 0 0 0 2px var(--ring) } to mirror the ring-2 ring-fg focus. Lets cards opt into the terminal look without a component rewrite.
• .braille-spinner — keyframe cycling ⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏ as ::after content, colored var(--muted-foreground). Alternative to Spinner.svelte for loading states under cyberspace themes.
• .font-vt — { font-family: var(--font-heading) } so the wordmark class cyberspace uses maps to our heading var (VT323 under cyber themes, Inknut under Terracotta). Drop-in for any stylized title.
• .strike-list — li > s { color: var(--muted-foreground) } convenience for the crossed-out feature-list pattern in marketing/empty states.

None of these are required for the theme to work; they're palette for the "de-imagined" voice where we want it.

---

8. Implementation order (incremental, each step shippable)

1. Fonts (§5) — self-host JetBrains Mono + VT323, @font-face in app.css. No visual change yet (only cyberspace themes reference them).
2. Tokens (§3) — add the two :root[data-theme='cyber-*'] blocks.
3. Store (§6) — extend theme.svelte.ts to named themes + data-theme; update the picker UI. At this point both cyberspace themes are live and fully recolor the whole app — the cheapest milestone, biggest visible win.
4. RasterImage.svelte (§4) — build + wire into entity icons and ConfigBackground. This is the "dithered image" deliverable.
5. Idioms (§7) — terminal-box, braille spinner, etc., applied opportunistically.

Each step is independently mergeable. Step 3 alone satisfies "light + dark cyberspace themes"; step 4 satisfies "dithered images."

---

9. Verification

• cd web && npm run build (or the repo's build command — confirm in web/package.json) — Tailwind v4 must accept the new data-theme selectors and color-mix() (both standard; no config change expected).
• npm run check / svelte-check for the store + component TS.
• Manual: cycle all four themes in the picker; confirm no .dark bleed on cyber-light; confirm RasterImage re-dithers on theme flip; confirm prefers-reduced-data/plain prop shows crisp image; confirm cross-origin src degrades to <img> without console errors.
• Lighthouse / a11y: 1-bit dithered images still need a real alt (kept on the fallback <img>); contrast on #a89984-on-black passes WCAG AA for body text (ratio ≈ 7.4:1) — fine.

---

10. Alternatives considered

• Full rebrand (replace Terracotta/Carbon). Highest visual payoff, highest cost: every component's rounding/serif/spacing was authored for the Art ouveau direction; square + mono would need a component-level sweep, not just tokens. Defer unless you want cyberspace as the oikos look — then do it as a follow-up that deletes Terracotta/Carbon and makes cyber-dark the sole default.
• CSS-only image dither (filters / SVG turbulence). Cheaper, but can't do true 1-bit error diffusion or recolor to theme fg/bg. Rejected — the canvas pass is the whole point and is ~60 lines.
• Ordered (Bayer) dither instead of Atkinson. More regular/grid-like ("newspaper halftone"). Atkinson is softer and more terminal-like; keep Bayer as a algorithm='bayer' prop option later if wanted.
• Server-side dithering. Could pre-dither icons at ingest. Rejected for now — client canvas keeps one source of truth (the original image) and lets the palette follow the live theme, which a baked asset can't.

---

11. Non-goals / out of scope

• Replicating cyberspace's sidebar-rail layout (oikos uses a floating-window desktop shell; the rail is a different app model). We take the visual language, not the IA.
• Porting the 9 other novelty themes (C64, Matrix, VT320, …). Two (light/dark) satisfy the request; the token model makes adding more trivial later.
• Removing the Google Fonts dependency for Terracotta/Carbon (follow-up).
• Licensing/redistributing Departure Mono (use VT323 unless cleared).

---

12. Risks

• .dark coupling. Existing code may equate .dark with "dark UI". Mitigation: audit in step 3; the grep is small.
• Dither perf on large images. Atkinson is O(n) and runs on a downscaled canvas (≤~320px wide), so per-image cost is negligible; but batch-rendering many entity icons on first paint could jank. Mitigation: dither lazily (on intersection) and cache the result on the element.
• Tainted canvas on cross-origin images → silent fallback to <img> (already handled in the design).
• Token drift. If a component hardcodes a color instead of using a token, it won't recolor under cyberspace. This is the same risk Carbon already has; no new exposure, just more visible under a stronger theme.