@graphlearning/shell 0.2.0 → 0.4.0

package/dist/styles.css

@@ -13,6 +13,21 @@
 :root {
   --bg: #1a1d23; /* Zed-slate (matches graphl-studio/aws) */
   --fg: #eceef2;
+  /* The foreground's RGB CHANNELS, so every `rgba(var(--ink-rgb), a)` in this file flips with the
+     theme. There were ~20 literal rgba(255,255,255,a) values here — all of them "ink at some alpha"
+     — and one token converts every one by substitution rather than needing eleven alpha tokens.
+     Dark keeps the exact values it always had. */
+  --ink-rgb: 255, 255, 255;
+  /* Surfaces lifted OFF --bg: the slide panel, and a catalog card's hover. Literals before 0.4.0. */
+  --surface-lift: #2f333d;
+  --surface-lift-2: #22262e;
+  --slide-ink: #c8cdd6; /* the slide body's text colour */
+  --foot-dim: #5b616f; /* the capture footer's section counter */
+  --foot-dimmer: #4b515e; /* the catalog chevron at rest */
+  /* A SCRIM, not ink: the page colour at 90%, sat behind the floating controls so they stay legible
+     over whatever the scene puts under them. It has to follow --bg, so it cannot be alpha over
+     --ink-rgb like the rest — on light, ink-at-90% would be a near-black button. */
+  --scrim: rgba(26, 29, 35, 0.9);
   /* --- the three tokens a CONTENT REPO owns -------------------------------------------------
      These are NEUTRAL DEFAULTS. Each repo overrides them in its own theme.css, imported AFTER
      this stylesheet so the cascade lets the repo win. They are the entire per-repo design
@@ -26,6 +41,65 @@
   --brand-hover: #a8adb8;
   --accent-2: #c8cdd6;
   --font-sans: 'IBM Plex Sans', ui-sans-serif, system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif;
+
+  /* --- site-chrome tokens (SiteHeader) ------------------------------------------------------
+     The same names and the same values ui-graphl declares, so the bar is identical on the catalog
+     and inside every app. Do NOT rename them: when light mode arrives it is purely additive here
+     — a light :root plus prefers-color-scheme and [data-theme] blocks, same names — and the
+     header's own CSS never has to change again. --text aliases the shell's existing --fg (same
+     value) rather than duplicating the colour. These are PLATFORM tokens: the bar stays
+     platform-blue on every site, deliberately NOT --brand, because looking the same everywhere is
+     the whole reason it exists. */
+  --text: var(--fg);
+  --muted: #8b909c;
+  --accent: #5b8cff;
+  --accent-soft: rgba(91, 140, 255, 0.14); /* the current nav item */
+  --line: rgba(var(--ink-rgb), 0.09);
+  --header-bg: rgba(var(--ink-rgb), 0.014);
+  --hover: rgba(var(--ink-rgb), 0.05);
+  --site-h: 60px; /* the bar's row height (its 1px rule is extra) — .idx subtracts it from 100vh */
+}
+
+/* LIGHT — same token NAMES, different values, exactly as the note above anticipated. Set by
+   ConceptApp on <html> from its `theme` prop; nothing selects on it but this block.
+ *
+ * WHY AN EXPLICIT ATTRIBUTE AND NOT prefers-color-scheme: a deck is a VIDEO. The recorded frame
+ * cannot depend on the machine that renders it, or the same slug captures differently on two
+ * laptops. The repo chooses the theme at build time and the recorder inherits it.
+ *
+ * --line / --header-bg / --hover / --idx-line are NOT redeclared: they are alpha over --ink-rgb,
+ * so flipping the channels flips them too. That is the whole reason --ink-rgb exists.
+ *
+ * NOT TOUCHED HERE: --brand, --brand-hover and --accent-2. Those belong to the content repo
+ * (theme.css, loaded after this file), and a brand tuned for glow on slate can be unreadable on
+ * off-white — python's is a mid-blue that drops to ~2.5:1 on #f7f8fa. A repo going light must
+ * re-pick its three tokens; the shell cannot do it for them without taking ownership of the one
+ * surface it deliberately leaves alone. */
+:root[data-theme='light'] {
+  --bg: #f7f8fa; /* identical to ui-flow's light surface, so the scene pane and the page agree */
+  --fg: #1a1d23;
+  --ink-rgb: 26, 29, 35;
+  /* On dark the slide panel is LIFTED off the canvas; on light the same relationship means going
+     brighter than the page, not darker — so white, not a grey. */
+  --surface-lift: #ffffff;
+  --surface-lift-2: #eef1f5;
+  --slide-ink: #333a45;
+  --foot-dim: #7a8493;
+  --foot-dimmer: #98a2b1;
+  --muted: #5a6675;
+  /* Platform blue darkened until it carries text contrast on off-white; #5b8cff is tuned to glow
+     on slate and reads washed out here. Still platform blue, still not --brand. */
+  --accent: #2f6fe0;
+  --accent-soft: rgba(47, 111, 224, 0.12);
+  --scrim: rgba(247, 248, 250, 0.9);
+}
+
+/* Set for the single frame a theme swap lands in, so the whole page changes at once instead of the
+   ground flipping while everything with a hover transition cross-fades after it. Ported from
+   ui-graphl's styles.css — the site bar exists three times and they only stay one design if every
+   change lands in all of them. */
+.theme-swap * {
+  transition: none !important;
 }
 
 html,
@@ -84,8 +158,8 @@ body {
   justify-content: center;
   overflow: auto;
   box-sizing: border-box;
-  background: #2f333d; /* lifted slide surface, off the #1a1d23 scene canvas */
-  border-left: 1px solid rgba(255, 255, 255, 0.09);
+  background: var(--surface-lift); /* lifted slide surface, off the #1a1d23 scene canvas */
+  border-left: 1px solid rgba(var(--ink-rgb), 0.09);
   transform: translateX(100%);
   transition: transform 0.32s cubic-bezier(0.4, 0, 0.2, 1);
   z-index: 10;
@@ -101,9 +175,9 @@ body {
   width: 36px;
   height: 36px;
   border-radius: 10px;
-  border: 1px solid rgba(255, 255, 255, 0.12);
-  background: rgba(26, 29, 35, 0.9);
-  color: rgba(255, 255, 255, 0.82);
+  border: 1px solid rgba(var(--ink-rgb), 0.12);
+  background: var(--scrim);
+  color: rgba(var(--ink-rgb), 0.82);
   font-size: 19px;
   line-height: 1;
   cursor: pointer;
@@ -145,9 +219,9 @@ body {
   width: 36px;
   height: 36px;
   border-radius: 10px;
-  border: 1px solid rgba(255, 255, 255, 0.12);
-  background: rgba(26, 29, 35, 0.9);
-  color: rgba(255, 255, 255, 0.82);
+  border: 1px solid rgba(var(--ink-rgb), 0.12);
+  background: var(--scrim);
+  color: rgba(var(--ink-rgb), 0.82);
   cursor: pointer;
   pointer-events: auto; /* the footer container is pointer-events:none; re-enable the buttons */
   transition: color 0.15s, border-color 0.15s;
@@ -186,7 +260,7 @@ body {
   padding: 4px 6px;
   border: none;
   background: transparent;
-  color: rgba(255, 255, 255, 0.82);
+  color: rgba(var(--ink-rgb), 0.82);
   font-family: var(--font-sans);
   font-size: 17px;
   font-weight: 700;
@@ -258,11 +332,11 @@ body {
   font-size: 1.55vh;
   font-weight: 700;
   letter-spacing: -0.01em;
-  color: rgba(255, 255, 255, 0.9);
+  color: rgba(var(--ink-rgb), 0.9);
 }
 .reel-foot__count {
   font-size: 1.4vh;
-  color: rgba(255, 255, 255, 0.5);
+  color: rgba(var(--ink-rgb), 0.5);
   font-variant-numeric: tabular-nums;
   letter-spacing: 0.04em;
 }
@@ -338,7 +412,7 @@ body {
 .slide-panel__scaler {
   box-sizing: border-box;
   padding: 0 40px; /* portrait: trimmed side padding to fill the phone width (landscape restores 60) */
-  color: #c8cdd6;
+  color: var(--slide-ink);
   --fs-body: 31px; /* portrait/reels: larger so the slide fills the phone (landscape restores 26) */
   --fs-title: calc(var(--fs-body) * 1.73);
   --fs-heading: calc(var(--fs-body) * 1.2);
@@ -391,56 +465,185 @@ body {
   content: '—';
   position: absolute;
   left: 0;
-  color: rgba(255, 255, 255, 0.28);
+  color: rgba(var(--ink-rgb), 0.28);
 }
 .slide-panel__scaler strong {
-  color: rgba(255, 255, 255, 0.95);
+  color: rgba(var(--ink-rgb), 0.95);
   font-weight: 700;
 }
 .slide-panel__scaler em {
   font-style: italic;
-  color: rgba(255, 255, 255, 0.85);
+  color: rgba(var(--ink-rgb), 0.85);
 }
 .slide-panel__scaler code {
   font-family: 'IBM Plex Mono', ui-monospace, monospace;
   font-size: var(--fs-code);
   padding: 2px 7px;
   border-radius: 5px;
-  background: rgba(255, 255, 255, 0.08);
-  color: rgba(255, 255, 255, 0.9);
+  background: rgba(var(--ink-rgb), 0.08);
+  color: rgba(var(--ink-rgb), 0.9);
 }
 
 /* --- Course catalog / landing page (CourseIndex) ---------------------------- */
 /* The index is a scrollable page (unlike the fixed stage): the catalog of courses, each course a
    card listing its ordered sections. Python-blue (--idx-accent) is the one accent. */
-.idx {
-  --idx-accent: var(--brand);
-  --idx-muted: #8b909c;
-  --idx-line: rgba(255, 255, 255, 0.09);
-  min-height: 100vh;
+/* ── Site chrome (SiteHeader) ──────────────────────────────────────────────────────────────────
+   Ported from ui-graphl/styles.css, class for class. ui-graphl is buildless vanilla and this is a
+   React package, so one shared component is impossible — but one shared DESIGN is not, and it only
+   survives if neither copy drifts. Change this, change that. The single deliberate deviation is
+   --site-h: over there the 60px row height is a literal, here .idx has to subtract it.
+
+   Traditional chrome: brand on the left, section nav on the right, full-bleed rule underneath. The
+   inner row matches the catalog's own max-width so the brand lines up with the cards below it. */
+.site {
+  border-bottom: 1px solid var(--line);
+  background: var(--header-bg);
+}
+.site__inner {
   max-width: 940px;
   margin: 0 auto;
-  padding: 40px 32px 64px;
+  /* Explicit, and NOT optional: ui-graphl has a global `* { box-sizing: border-box }` and this
+     stylesheet deliberately does not (a global reset here would move the section view, which is
+     burned into video). Without it the bar's column is 940 + 64 of padding while .idx is 940
+     inclusive, and the brand sits 32px left of the cards it is supposed to line up with. */
   box-sizing: border-box;
+  padding: 0 32px;
+  min-height: var(--site-h);
+  display: flex;
+  align-items: center;
+  gap: 20px;
 }
-.idx__head {
-  margin-bottom: 36px;
+.site__brand {
+  margin-right: auto; /* holds the brand left; nav + actions collect on the right */
+  display: inline-flex;
+  align-items: center;
+  gap: 10px;
+  text-decoration: none;
+  color: inherit;
 }
-/* Catalog header: GraphL platform eyebrow over the AWS subject title (no marketing subtitle). */
-.idx__brand {
-  display: inline-block;
-  font-size: 13px;
+.site__logo {
+  display: block;
+  border-radius: 6px;
+}
+.site__name {
+  font-size: 17px;
   font-weight: 700;
-  letter-spacing: 0.16em;
-  text-transform: uppercase;
-  color: var(--idx-accent);
-  margin-bottom: 10px;
+  letter-spacing: -0.01em;
+}
+.site__nav {
+  display: flex;
+  gap: 4px;
+}
+.site__link {
+  flex: none;
+  white-space: nowrap;
+  padding: 8px 12px;
+  border-radius: 8px;
+  font-size: 15px;
+  font-weight: 600;
+  color: var(--muted);
   text-decoration: none;
-  transition: opacity 0.15s ease;
+  transition: color 0.15s ease, background 0.15s ease;
 }
-.idx__brand:hover {
-  opacity: 0.72;
+.site__link:hover {
+  color: var(--text);
+  background: var(--hover);
 }
+.site__link[aria-current='page'] {
+  color: var(--text);
+  background: var(--accent-soft);
+}
+.site__link:focus-visible {
+  outline: 2px solid var(--accent);
+  outline-offset: 2px;
+}
+/* The icon buttons — the theme toggle and the account control when they exist. Kept separate from
+   the nav so that on a phone the nav can drop to its own row while these stay up on the brand row.
+   Empty until something is passed to SiteHeader's `actions` slot. */
+.site__actions {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+}
+/* Square icon button, styled here so the slot's occupant does not have to carry its own CSS. Sized
+   36px so it is a comfortable target without towering over the 60px header row. */
+.site__icon {
+  flex: none;
+  width: 36px;
+  height: 36px;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  font-size: 16px;
+  line-height: 1;
+  font-family: inherit;
+  color: var(--muted);
+  background: transparent;
+  border: 1px solid transparent;
+  border-radius: 9px;
+  cursor: pointer;
+  transition: color 0.15s ease, background 0.15s ease, border-color 0.15s ease;
+}
+.site__icon:hover {
+  color: var(--text);
+  background: var(--hover);
+}
+.site__icon:focus-visible {
+  outline: 2px solid var(--accent);
+  outline-offset: 2px;
+}
+
+/* Phone: the nav row scrolls horizontally rather than collapsing into a hamburger. There are three
+   sections today and there will be more, but they are the primary navigation and the whole point of
+   the current one is being visible; a menu would hide "you are here" behind a tap. */
+@media (max-width: 560px) {
+  .site__inner {
+    padding: 8px 20px;
+    flex-wrap: wrap;
+    gap: 0 12px;
+  }
+  .site__nav {
+    order: 3; /* after brand and actions ⇒ its own row */
+    flex: 1 0 100%;
+    margin: 2px -20px 0; /* bleed to the screen edges so the row can scroll fully */
+    padding: 0 20px 4px;
+    overflow-x: auto;
+    scrollbar-width: none;
+  }
+  .site__nav::-webkit-scrollbar {
+    display: none;
+  }
+  .site__link {
+    display: flex;
+    align-items: center;
+    min-height: 40px; /* comfortable touch target */
+    padding: 8px 10px;
+    font-size: 14px;
+  }
+  .site__icon {
+    width: 40px;
+    height: 40px;
+  }
+}
+
+.idx {
+  --idx-accent: var(--brand);
+  --idx-muted: var(--muted); /* was the literal #8b909c — the same value --muted already holds, so
+                               aliasing is byte-identical on dark and picks up the light block */
+  --idx-line: rgba(var(--ink-rgb), 0.09);
+  /* The bar is a sibling above this column, so the viewport it can fill is what the bar leaves.
+     On a phone the bar wraps to two rows and this under-subtracts — harmless, it is a min. */
+  min-height: calc(100vh - var(--site-h) - 1px); /* the bar's row, plus its 1px rule */
+  max-width: 940px;
+  margin: 0 auto;
+  padding: 28px 32px 64px;
+  box-sizing: border-box;
+}
+.idx__head {
+  margin-bottom: 36px;
+}
+/* Catalog header: just the subject title now — the GraphL wordmark it used to sit under is in
+   the site bar above (SiteHeader), which is the same bar graphl.in carries. */
 .idx__subject {
   margin: 0;
   font-size: 40px;
@@ -470,7 +673,7 @@ body {
 .idx-card {
   border: 1px solid var(--idx-line);
   border-radius: 14px;
-  background: rgba(255, 255, 255, 0.018);
+  background: rgba(var(--ink-rgb), 0.018);
   overflow: hidden;
 }
 .idx-card__head {
@@ -489,7 +692,7 @@ body {
   transition: background 0.15s ease;
 }
 .idx-card__head:hover {
-  background: #22262e;
+  background: var(--surface-lift-2);
 }
 /* Divider only when open — a collapsed row is a clean single bar. */
 .idx-card--open .idx-card__head {
@@ -556,7 +759,7 @@ body {
   font-size: 13px;
   font-weight: 600;
   font-variant-numeric: tabular-nums;
-  color: #5b616f;
+  color: var(--foot-dim);
 }
 .idx-sec__row a:hover .idx-sec__num {
   color: var(--idx-accent);
@@ -569,7 +772,7 @@ body {
 .idx-sec__chev {
   flex: none;
   font-size: 19px;
-  color: #4b515e;
+  color: var(--foot-dimmer);
   transition: color 0.12s ease, transform 0.12s ease;
 }
 .idx-sec__row a:hover .idx-sec__chev {
@@ -587,7 +790,16 @@ body {
   font-size: 12px;
   padding: 2px 7px;
   border-radius: 5px;
-  background: rgba(255, 255, 255, 0.08);
-  color: rgba(255, 255, 255, 0.9);
+  background: rgba(var(--ink-rgb), 0.08);
+  color: rgba(var(--ink-rgb), 0.9);
 }
 
+/* The bar's phone gutter is 20px, so the catalog column's has to be too — otherwise the brand and
+   the subject title below it sit on two different left edges. Matches ui-graphl's own phone rule.
+   It lives down HERE, not up with the rest of the .site phone rules, because .idx's own padding is
+   declared after them and would otherwise win at equal specificity. */
+@media (max-width: 560px) {
+  .idx {
+    padding: 20px 20px 48px;
+  }
+}

package/dist/useTheme.d.ts

@@ -0,0 +1,17 @@
+import type { ThemeKey } from '@graphlearning/flow';
+export declare function readStored(): ThemeKey | null;
+/**
+ * The theme actually painted. CAPTURE PINS IT TO THE DECK, ignoring the stored choice and the reader
+ * entirely — and that is not a nicety. A recorder runs a fresh headless profile with empty storage,
+ * so without this pin what a capture painted would depend on the machine that rendered it. The
+ * declared prop is the only thing burned into a video.
+ */
+export declare const resolveTheme: (deck: ThemeKey, stored: ThemeKey | null, capture: boolean) => ThemeKey;
+/**
+ * Owns the reader's choice and keeps <html data-theme> in step with it. Returns the theme to hand
+ * SceneView, plus a two-state flip for the toggle.
+ */
+export declare function useTheme(deck: ThemeKey, capture: boolean): {
+    theme: ThemeKey;
+    toggle: () => void;
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@graphlearning/shell",
-  "version": "0.2.0",
-  "description": "The GraphL concept-app shell \u2014 hash router, section view (scene left / slide right), slide panel, course catalog and narration channel, plus the capture/record/publish toolchain that drives them. A content repo supplies courses + scenes.",
+  "version": "0.4.0",
+  "description": "The GraphL concept-app shell — hash router, section view (scene left / slide right), slide panel, course catalog and narration channel, plus the capture/record/publish toolchain that drives them. A content repo supplies courses + scenes.",
   "license": "UNLICENSED",
   "repository": {
     "type": "git",
@@ -28,17 +28,17 @@
     "watch": "vite build --watch"
   },
   "peerDependencies": {
-    "@graphlearning/flow": ">=0.5.0 <1.0.0",
+    "@graphlearning/flow": ">=0.8.0 <1.0.0",
+    "esbuild": ">=0.20",
     "lucide-react": "^1.28.0",
+    "puppeteer": ">=24",
     "react": "^19.2.0",
     "react-dom": "^19.2.0",
     "react-markdown": "^10.1.0",
-    "remark-gfm": "^4.0.1",
-    "puppeteer": ">=24",
-    "esbuild": ">=0.20"
+    "remark-gfm": "^4.0.1"
   },
   "devDependencies": {
-    "@graphlearning/flow": "^0.5.0",
+    "@graphlearning/flow": "^0.8.0",
     "@types/react": "^19.2.0",
     "@types/react-dom": "^19.2.0",
     "@vitejs/plugin-react": "^4.3.4",