octocode-cli 1.3.1 → 1.5.1

package/skills/octocode-slides/references/animation.md

@@ -0,0 +1,281 @@
+# animation.md — In-Slide Step Animation
+
+> Reference for `scripts/animation.js` — the step engine for Octocode Slides.
+
+---
+
+## What it does
+
+`animation.js` lets a single slide reveal its content **one component at a time**, controlled by the same `→` / `←` keys the presenter already uses to navigate between slides.
+
+| Key | Behaviour when steps remain | Behaviour when no steps remain |
+|-----|-----------------------------|-------------------------------|
+| `→` / `Space` / `↓` | Reveal the next step | Advance to the next slide |
+| `←` / `↑` | Hide the last visible step | Retreat to the previous slide |
+
+The slide never advances until all steps have been shown. The slide never retreats until all shown steps have been hidden. Slide authors only opt in per slide; the deck-level controller already knows how to route step-aware keys through the active iframe.
+
+---
+
+## How it works (technical summary)
+
+`animation.js` adds a `keydown` listener in **capture phase** on the slide's `document`. Because it is loaded **before** `navbridge.js`, its handler fires first. When a step is consumed, it calls `e.stopImmediatePropagation()` — `navbridge.js` never sees the event, so the parent (`index.html`) is never told to change slides.
+
+When all steps are exhausted in the current direction, the key passes through normally to navbridge, which forwards it to the parent, and normal slide navigation resumes.
+
+### Full event flow (parent-window focus)
+
+When the parent `index.html` has keyboard focus — initial load, browser chrome refocus, overview close, or other parent-level interaction — raw nav keys would otherwise bypass `animation.js` and jump straight to `go()`. `base.html` avoids that by routing step-aware nav keys through the active iframe first:
+
+```
+User presses → / ← (parent window has focus)
+  │
+  ▼
+index.html handleKey()  — no passthrough flag
+  └── postMessage {type:'octocode-slides:key', key} to active iframe
+          │
+          ▼
+      navbridge.js message listener  — dispatches synthetic keydown
+              │
+              ▼
+          animation.js (capture, runs first)
+              ├── step available in that direction?
+              │       └── showNext() / hideLast() + stopImmediatePropagation
+              │               └── navbridge keydown listener NEVER fires
+              │                       └── no postMessage back → parent stays on slide ✓
+              │
+              └── no step left in that direction? → falls through
+                      │
+                      ▼
+                  navbridge.js keydown listener
+                      └── postMessage {type:'octocode-slides:nav', key} to parent
+                              │
+                              ▼
+                          index.html message handler
+                              └── handleKey({passthrough:true}) → go(next/previous) ✓
+```
+
+### When the iframe already has focus (user clicked inside the slide)
+
+The same intercept still applies, but the first keydown is real instead of synthetic: `animation.js` intercepts in capture phase, and navbridge forwards only unconsumed keys to the parent.
+
+```
+User presses → / ← (iframe has focus)
+  │
+  ▼
+animation.js (capture, runs first)
+  ├── step available in that direction? → consume + stopImmediatePropagation → parent stays on slide
+  └── no step left in that direction? → fall through
+          │
+          ▼
+      navbridge.js (capture, runs second)
+          └── postMessage → parent handleKey({passthrough:true}) → go(next/previous)
+```
+
+
+---
+
+## Required loading order
+
+`animation.js` **must be loaded before `navbridge.js`** so its event listener registers first and intercepts keys before navbridge forwards them.
+
+```html
+<!-- In every slide that uses steps — before </body> -->
+<script src="../js/animation.js"></script>   <!-- ← FIRST -->
+<script src="../js/navbridge.js"></script>   <!-- ← always last -->
+```
+
+Slides that do not use steps can omit `animation.js` entirely — navbridge behaviour is unaffected.
+
+---
+
+## Marking steps
+
+Add `data-step="N"` to any element. `N` is a 1-based integer that controls reveal order. Elements without `data-step` are always visible.
+
+```html
+<!-- Ordered by data-step value -->
+<li data-step="1">First point — revealed on first →</li>
+<li data-step="2">Second point — revealed on second →</li>
+<li data-step="3">Third point — revealed on third →</li>
+```
+
+### DOM-order fallback
+
+If `data-step` has no value (or a non-numeric value), DOM order is used as the fallback. You can mix explicit and implicit ordering — explicit numbers always sort before implicit ones.
+
+```html
+<!-- All three reveal in DOM order because no numeric value is given -->
+<div data-step>Alpha</div>
+<div data-step>Beta</div>
+<div data-step>Gamma</div>
+```
+
+---
+
+## Default animation
+
+The script injects these defaults via a `<style>` block:
+
+```css
+/* Hidden state (before reveal) */
+[data-step] {
+  opacity: 0;
+  transform: translateY(14px);
+  transition: opacity 320ms cubic-bezier(.4,0,.2,1),
+              transform 320ms cubic-bezier(.4,0,.2,1);
+}
+
+/* Visible state (after reveal) */
+[data-step].step-visible {
+  opacity: 1;
+  transform: translateY(0);
+}
+```
+
+The transition reverses automatically when a step is hidden (on `←`).
+
+---
+
+## Customising the animation
+
+Override the default animation in the slide's local `<style>` block. Define both states — the hidden default AND the visible override:
+
+```html
+<style>
+  /* Example: slide in from the left */
+  [data-step] {
+    opacity: 0;
+    transform: translateX(-24px);
+    transition: opacity 280ms ease, transform 280ms ease;
+  }
+  [data-step].step-visible {
+    opacity: 1;
+    transform: translateX(0);
+  }
+</style>
+```
+
+### Staggered delays
+
+Use `transition-delay` on individual elements or CSS nth selectors:
+
+```html
+<style>
+  [data-step]:nth-of-type(2) { transition-delay: 60ms; }
+  [data-step]:nth-of-type(3) { transition-delay: 120ms; }
+</style>
+```
+
+Or set inline:
+
+```html
+<li data-step="1">Fast</li>
+<li data-step="2" style="transition-delay:80ms">Delayed</li>
+```
+
+---
+
+## Optional step indicator
+
+Add `data-step-indicator` to the slide root element to enable a small dot bar that tracks how many steps have been revealed:
+
+```html
+<div class="slide slide--content" data-step-indicator>
+  <!-- … slide content … -->
+</div>
+```
+
+The dot bar appears fixed at the bottom-centre of the slide. Active dots fill white; pending dots are dim. Customise via CSS:
+
+```css
+.step-indicator { bottom: 28px; gap: 8px; }       /* reposition / spacing */
+.step-dot       { width: 8px; height: 8px; }       /* dot size */
+.step-dot.is-done { background: var(--accent); }   /* use theme accent */
+```
+
+---
+
+## Full example — content slide with steps
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <title>Three Wins</title>
+  <link rel="stylesheet" href="../css/base.css">
+  <link rel="stylesheet" href="../css/theme.css">
+</head>
+<body>
+<div class="slide slide--content" data-step-indicator>
+  <header class="slide-header">
+    <h1>Three things that changed everything</h1>
+  </header>
+
+  <main class="slide-content">
+    <ul class="content-list">
+      <li data-step="1">Deploy time dropped from 45 min to 4 min</li>
+      <li data-step="2">Error rate fell 60 % after adding type safety</li>
+      <li data-step="3">Team onboarding time cut in half</li>
+    </ul>
+  </main>
+</div>
+
+<!-- Steps load first, navbridge second — order is required -->
+<script src="../js/animation.js"></script>
+<script src="../js/navbridge.js"></script>
+</body>
+</html>
+```
+
+**Navigation flow for this slide:**
+1. Slide loads — all three `<li>` elements are invisible
+2. First `→` → "Deploy time…" fades up
+3. Second `→` → "Error rate…" fades up
+4. Third `→` → "Team onboarding…" fades up
+5. Fourth `→` → slide advances to the next slide
+6. First `←` (from later slide): retreat to this slide (all steps visible)
+7. Next `←` → "Team onboarding…" fades out
+8. Next `←` → "Error rate…" fades out
+9. Next `←` → "Deploy time…" fades out
+10. Next `←` → retreat to the previous slide
+
+---
+
+## Step state on return
+
+When a slide is revisited (e.g. you advanced past it and pressed `←` to come back), its step state is preserved — all previously revealed steps remain visible. This is intentional: returning to a slide you already walked through does not force you to step through it again.
+
+To reset steps, reload the page or navigate away and back across a full reload boundary.
+
+---
+
+## Slides without steps
+
+If a slide has no `[data-step]` elements, `animation.js` is a complete no-op — it adds no visible CSS, registers no effective handler, and does not affect navbridge or slide-change timing. You can safely include `animation.js` in a slide template even if that slide has no steps.
+
+---
+
+## Checklist for slide authors
+
+- [ ] `animation.js` loaded **before** `navbridge.js` in the slide HTML
+- [ ] Every step element has `data-step="N"` with a unique integer value
+- [ ] Step values are 1-based and sequential (1, 2, 3 …); gaps are allowed (1, 3, 5 …)
+- [ ] Content that should always be visible does **not** have `data-step`
+- [ ] Slide title / header does **not** have `data-step` (it must be visible on entry)
+- [ ] Tested: all steps reveal correctly on `→`, hide correctly on `←`
+- [ ] Tested: after last step, next `→` advances to the next slide
+- [ ] Tested: before first step, `←` retreats to the previous slide
+
+---
+
+## Integration with the Phase 5 implementation checklist
+
+When building a slide with steps, add this row to the Phase 5 template alignment check:
+
+| Check | Pass condition |
+|-------|---------------|
+| animation.js loaded before navbridge | `<script src="../js/animation.js">` appears before `<script src="../js/navbridge.js">` in the same slide file |
+
+Do not add `animation.js` to `index.html` or `js/navbridge.js` — it is a per-slide script, not a deck-level script.

package/skills/octocode-slides/references/design-system.md

@@ -0,0 +1,316 @@
+# Design System Reference — Octocode Slides
+
+Read at Phase 4 start (before any design decisions).
+
+---
+
+## CSS Variable Contract
+
+`scripts/base.css` (copied verbatim to `css/base.css`) defines these variables. `theme.css` overrides them. Slide HTML uses them via `var(...)`. No slide ever sets a raw color, font-family, or font-size.
+
+```
+--bg          slide background
+--surface     card / panel backgrounds
+--border      dividers, code block edges
+--accent      one focal element per slide
+--text        body text
+--muted       captions, metadata, labels
+--code-bg     code block background
+--code-text   code block text
+--font-head   heading font stack
+--font-body   body font stack
+--font-mono   monospace font stack
+```
+
+Typography scale (defined in base.css using `clamp()` only):
+`--t-display  --t-title  --t-sub  --t-body  --t-small  --t-code`
+
+Calibration bands:
+
+| Token | Target range | Use |
+|-------|-------------|-----|
+| `--t-display` | 48–64pt | Title slide headline |
+| `--t-title` | 28–44pt | Slide heading |
+| `--t-sub` | 22–28pt | Sub-heading, key number |
+| `--t-body` | 18–24pt | Bullets, paragraphs |
+| `--t-small` | 14–18pt | Captions, source lines |
+| `--t-code` | 14–18pt | Code blocks |
+
+---
+
+## Slide Title Contract
+
+Claim-sentence vs topic-label rule lives in `slide-rules.md §1.2` (master rule set) and is summarised in `SKILL.md → Operating principles`. This file does not restate it — but every CSS decision below assumes titles carry meaning, not labels.
+
+---
+
+## Design Reasoning
+
+The reasoning chain that drives every aesthetic decision lives in `references/04-design.md → Design Reasoning Chain`. Walk that chain *before* opening this document — the answers there determine which sections of the design system you actually need.
+
+This file is the visual *contract*: tokens, palettes, typography presets, font pairings. It is not the *process*.
+
+---
+
+## Theme Authoring — rules of thumb
+
+The Phase 4 process is in `04-design.md`; this section captures the rules that process applies. Use these alongside the Design Reasoning Chain — not as a replacement.
+
+**Audience signals → visual posture (a starting frame, not a verdict):**
+
+| Audience | What it suggests |
+|----------|-----------------|
+| Developers / technical | High contrast, code-native fonts, readable from distance |
+| Executives / investors | Premium restraint, serif or distinctive sans, limited palette |
+| Creative / product | More expressive color and layout, personality over safety |
+| Academic / research | Clean, readable, data-forward — legibility over style |
+| Mixed / public | Light background, clear hierarchy, no niche aesthetics |
+
+**Font pairing rules:**
+- Two fonts maximum (one heading, one body). Monospace adds a third for code.
+- Heading font should have *character* — chosen, not defaulted (Inter / Roboto alone fail Visual Slop).
+- Body font legible at 18–22pt on screen.
+- The pair should feel related: both geometric, both humanist, or contrast intentionally (serif heading + sans body).
+
+**Color order — pick in this sequence so contrast and hierarchy fall out naturally:**
+1. `--bg` (the base — sets the entire mood)
+2. `--text` (contrast ≥ 4.5:1 against `--bg` — non-negotiable)
+3. `--accent` (one focused punch; used on ≤3 elements per slide)
+4. `--surface`, `--border`, `--muted` (usually derived from `--bg`)
+5. `--code-bg`, `--code-text` (readable mono colors that feel cohesive with the theme)
+
+Use OKLCH for dark/muted themes to get perceptually uniform lightness steps.
+Validate every `--text` / `--bg` pair at `https://webaim.org/resources/contrastchecker`.
+
+---
+
+## Theme Selection Matrix
+
+When a user gives a strong context signal, use this as a starting-point compass — not a final answer:
+
+| Audience | Explore these aesthetics first |
+|----------|-----------------------------|
+| Developers / engineers | Dark + monospace or geometric sans, cool accent |
+| Business / executives | Dark premium or editorial light, warm or neutral |
+| Designers / creatives | Warm editorial, expressive type, strong accent |
+| Academics / researchers | Light, serif heading, data-forward, restrained accent |
+| Marketing / product | High-energy color, bold display font, modern sans |
+| Mixed / general | Light background, legible sans, subtle accent |
+
+---
+
+## Font Pairing Presets
+
+Validated pairings across common contexts. All on Google Fonts or Fontshare (free).
+
+| Context | Heading | Body | Note |
+|---------|---------|------|------|
+| Modern corporate | Outfit | Source Sans 3 | Clean, not generic |
+| Startup pitch | Poppins Bold | DM Sans | Friendly confidence |
+| Creative / editorial | Fraunces | Plus Jakarta Sans | Striking contrast |
+| Technical / data | IBM Plex Mono | IBM Plex Sans | Cohesive family |
+| Warm editorial | Instrument Serif | Sora | Uncommon serif presence |
+| Dark keynote | Cabinet Grotesk ExtraBold | General Sans | Display weight impact |
+| Research / academic | Lora | Inter | Authoritative + readable |
+| Dev talk | JetBrains Mono | Space Grotesk | Code-native personality |
+
+Treat these as starting points for research, not the only options.
+
+---
+
+## Curated Palette Library
+
+Five battle-tested palettes with validated WCAG AA contrast ratios. Use these as a starting point for Phase 4 or as direct overrides when the brief gives a strong context signal. Validate modified values at `https://webaim.org/resources/contrastchecker` before shipping when contrast is uncertain.
+
+---
+
+### Graphite — dark cool · developers / tech stage
+High contrast, code-native. Works on dark projectors. Cool-blue accent reads clearly at distance.
+
+| Token | Value | Role |
+|-------|-------|------|
+| `--bg` | `#0F1117` | Slide background |
+| `--surface` | `#161B25` | Card / panel |
+| `--border` | `#24293A` | Dividers |
+| `--accent` | `#5A9EFF` | Focal element — contrast **5.2:1** on `--bg` ✓ |
+| `--text` | `#E4E9F2` | Body text — contrast **14.1:1** on `--bg` ✓ |
+| `--muted` | `#6B7694` | Captions |
+| `--code-bg` | `#0A0E16` | Code blocks |
+| `--code-text` | `#79C0FF` | Code text |
+
+Recommended pair: **Space Grotesk ExtraBold** / IBM Plex Sans
+
+---
+
+### Cream — light warm · business / editorial / product
+Premium, print-friendly. Terracotta accent feels chosen, not defaulted. Passes easily in bright rooms.
+
+| Token | Value | Role |
+|-------|-------|------|
+| `--bg` | `#FAF9F6` | Slide background |
+| `--surface` | `#F0EDE6` | Card / panel |
+| `--border` | `#E0DDD4` | Dividers |
+| `--accent` | `#A84427` | Focal element — contrast **5.8:1** on `--bg` ✓ |
+| `--text` | `#1C1916` | Body text — contrast **17.4:1** on `--bg` ✓ |
+| `--muted` | `#8A867E` | Captions |
+| `--code-bg` | `#EDE9E0` | Code blocks |
+| `--code-text` | `#7A3218` | Code text |
+
+Recommended pair: **Fraunces** / Plus Jakarta Sans
+
+---
+
+### Midnight — dark warm · keynote / executive / premium pitch
+Warm purple-black base with gold accent. Feels deliberate and high-end. Differentiates from standard dark themes.
+
+| Token | Value | Role |
+|-------|-------|------|
+| `--bg` | `#100E17` | Slide background |
+| `--surface` | `#1A1726` | Card / panel |
+| `--border` | `#2C2840` | Dividers |
+| `--accent` | `#C9A86C` | Focal element — contrast **7.3:1** on `--bg` ✓ |
+| `--text` | `#EDE8F5` | Body text — contrast **15.4:1** on `--bg` ✓ |
+| `--muted` | `#7A7090` | Captions |
+| `--code-bg` | `#0C0A12` | Code blocks |
+| `--code-text` | `#E8D5A3` | Code text |
+
+Recommended pair: **Cabinet Grotesk ExtraBold** / General Sans
+
+---
+
+### Blueprint — dark technical · data / architecture / engineering
+Deep navy with muted teal. Signals technical credibility without the neon-dashboard cliché. Good for diagram-heavy decks.
+
+| Token | Value | Role |
+|-------|-------|------|
+| `--bg` | `#0B1220` | Slide background |
+| `--surface` | `#101A30` | Card / panel |
+| `--border` | `#1E2E4A` | Dividers |
+| `--accent` | `#4EC9E0` | Focal element — contrast **5.7:1** on `--bg` ✓ |
+| `--text` | `#D8E3F0` | Body text — contrast **13.5:1** on `--bg` ✓ |
+| `--muted` | `#6080A8` | Captions |
+| `--code-bg` | `#071020` | Code blocks |
+| `--code-text` | `#85C9E8` | Code text |
+
+Recommended pair: **IBM Plex Mono** / IBM Plex Sans
+
+---
+
+### Nordic — light cool · academic / research / mixed audience
+Soft off-white base with deep navy accent. Universally readable, projects well, passes AAA on text.
+
+| Token | Value | Role |
+|-------|-------|------|
+| `--bg` | `#F5F6FA` | Slide background |
+| `--surface` | `#EAECF4` | Card / panel |
+| `--border` | `#D4D8E8` | Dividers |
+| `--accent` | `#2F4FA8` | Focal element — contrast **8.1:1** on `--bg` ✓ WCAG AAA |
+| `--text` | `#1A1D2E` | Body text — contrast **16.3:1** on `--bg` ✓ |
+| `--muted` | `#7880A0` | Captions |
+| `--code-bg` | `#E0E4F0` | Code blocks |
+| `--code-text` | `#1A3A80` | Code text |
+
+Recommended pair: **Lora** / Source Sans 3
+
+---
+
+## Design Rules
+
+### Typography
+- Heading size: `--t-display` on title/section slides only; `--t-title` everywhere else.
+- Body text below `--t-body` (≈18pt): split the slide instead of shrinking the font.
+- Line height: `1.12` for display, `1.25` for headings, `1.6` for body.
+- Letter spacing: `-0.02em` on display/title, `0` on body.
+- All-caps: title and section slides only; avoid all-caps body text.
+- `calc(-1 * clamp(...))` for negated lengths instead of `-clamp(...)`.
+
+### Color
+- Accent: **one focal element per slide** — main heading OR one highlighted figure, not both.
+- Max 3 distinct colors visible per slide: bg, text, accent. Muted is a bg derivative.
+- Dark themes: WCAG AA (4.5:1) minimum. Validate new accents before shipping.
+- Gold/yellow accents only on dark backgrounds — they fail contrast on light.
+
+### Layout
+- Slide padding: `var(--pad)` on all sides; usually not tighter than `var(--sp-6)`.
+- **Canonical regions (a slide uses up to four):**
+  - `.slide-logo` — optional, top-right brand mark
+  - `.slide-header` — optional, holds `.title` + `.description`
+  - `.slide-content` — required, smart flex body
+  - `.slide-footer` — optional, source / page / link
+  Only `.slide-content` is required. Logo and footer are usually deck-wide for visual rhythm, but can be skipped on hero / section slides — pick a posture and stick to it. The skeleton is a contract for *where* things sit when present, not a prescription that every slide must show every region.
+- Centered slide types (`title`, `section`, `quote`, `closing`) center their stack vertically; `title` and `closing` also center horizontally.
+- Per-slide flex / grid wireframes and the content-signal → layout decision table live in `references/wireframes.md`.
+
+### Slide Density (hard limits)
+
+| Type | What it delivers | Max content |
+|------|-----------------|-------------|
+| `title` | First impression, tone | Title + subtitle + meta (3 lines) |
+| `agenda` | Roadmap — what's coming and why | 4–6 items, short labels |
+| `section` | Topic transition, mental reset | Label + 1-line teaser |
+| `content` | Claim + supporting evidence | Heading + max 4 bullets (12 words each) |
+| `two-col` | Comparison, before/after, two views | Heading + 2 cols × 2–3 bullets |
+| `stats` | A single number that IS the point | 1–2 large numbers + label + 1-line context |
+| `quote` | External credibility, emotional punch | 1 quote ≤ 30 words + attribution |
+| `code` | Working proof, concrete example | 1 code block ≤ 20 lines + title claim |
+| `chart` | Data-driven proof, trend, distribution | 3–5 data points; title states the finding |
+| `image` | Visual proof, atmosphere, diagram | 1 image + title + optional 1-line caption |
+| `timeline` | Sequence, journey, roadmap | 3–5 steps with short labels |
+| `comparison` | Decision matrix, option analysis | 2 cols × 3 rows max |
+| `closing` | Land the conclusion, drive action | Headline + CTA + next step |
+
+---
+
+## Anti-Slop Guide
+
+Full anti-pattern list → `references/slide-rules.md` §9. The swap test is in `references/slide-rules.md` §6.4.
+
+---
+
+## Resources
+
+**Fonts and color/accessibility tools** → `references/resources.md` → Fonts and Color Tools sections (CDN imports, pairings, contrast checkers).
+
+### Design Inspiration
+
+**Dribbble** — `https://dribbble.com`
+Filter by "presentation" for headline treatment, data visualization, and section divider patterns.
+
+**Behance** — `https://behance.net`
+Filter "presentation" by Most Appreciated for real end-to-end deck compositions.
+
+**Slideworks** — `https://slideworks.io/resources/47-real-mckinsey-presentations`
+Real consulting firm decks. Best reference for information-dense layouts and the takeaway-title approach.
+
+---
+
+### HTML Presentation Frameworks (for research and inspiration)
+
+**Reveal.js** — `https://revealjs.com` · `https://github.com/hakimel/reveal.js` (68k ⭐)
+Layered CSS theming, `data-auto-animate`, speaker notes. Inspect their themes for layout/spacing ideas.
+
+**Slidev** — `https://sli.dev` · `https://github.com/slidevjs/slidev` (34k ⭐)
+Markdown + Vue 3. Strong two-column layouts and code annotation patterns.
+
+---
+
+### Design Methodology
+
+**Extended Frames — Visual Hierarchy** — `https://extendedframes.com/visual-hierarchy-in-design-and-presentation`
+F/Z eye-path patterns, per-slide-type layout archetypes, 10-point pre-delivery checklist.
+
+**Chronicle — Visual Presentation Principles** — `https://chroniclehq.com/blog/visual-presentations-tips-types-design-principles`
+Layout, hierarchy levers, consistency, and the most common failure modes.
+
+---
+
+## PDF Export (Optional)
+
+The `@media print` rule in `base.css` outputs 1280×720 pages. To export with headless Chrome:
+
+```bash
+# After: npx serve .octocode/slides/{{slideName}}
+chromium-browser --headless --print-to-pdf=output.pdf \
+  --no-pdf-header-footer --window-size=1280,720 \
+  http://localhost:3000
+```