matthummel-pa · matthummel-pa · Oct 2, 2026
@@ -41,7 +41,7 @@ Block Directory (those cannot have wp-admin UI).
 - Front-end JS is `src/view.js` via `block.json` `viewScript`.
 - **Typography:** bold sans-serif only (Outfit / system UI). Never serif.
   See `.cursor/rules/brand-typography.mdc`. The front-end TOC block
-  inherits the theme; do not inject a branded (or serif) font there.
+  inherits the theme. Focus paper uses `"Segoe UI", system-ui, sans-serif`.
 
 ## How it works
 1. `TOCguide_Headings::get_all()` parses the post with `parse_blocks()` and builds
@@ -51,10 +51,22 @@ Block Directory (those cannot have wp-admin UI).
 3. A `render_block` filter injects matching `id` attributes with
    `WP_HTML_Tag_Processor`. Both sides use the same map.
 4. Settings (`tocguide_settings`) control smooth-scroll offset, auto-generate
-   of the Gutenberg block, schema, and uninstall cleanup.
+   (top, after the first heading, or Fixed left), the Design tab, schema,
+   and uninstall cleanup. The Design preview updates as you edit.
 5. Auto-generate calls `WP_Block::render()` with settings as block attributes.
    `[tocguide]` still maps to the same `render_nav()` output for classic content.
+   Shortcode attributes include `close`, `focus`, `fixed`, `theme`
+   (`inherit` / `exclude` / `include`), and `export`.
    View assets enqueue when the block, shortcode, or auto-generate is in use.
+6. Fixed left (`is-fixed-left`) docks on a singular view at `min-width: 1100px`
+   into an 18rem column of `main` (or `article`). Archives and narrower
+   screens leave the outline inline. The header stays put.
+7. Focus sets `html.tocguide-is-focusing`, hides surrounding chrome, and
+   styles the post as a paper card. `#tocguide-focus-exit` (**Show page** /
+   **Bring the rest back** / Escape) restores the page.
+8. Resume stores `tocguide-bm-{postId}` in `localStorage` via
+   IntersectionObserver and shows the button only when that heading is in
+   the current outline.
 
 ## File map
 - `tocguide.php` — headers, constants, boot.
@@ -68,8 +80,9 @@ Block Directory (those cannot have wp-admin UI).
 - `.wordpress-org/` — directory banner/icon assets (PNG + SVG).
 
 ## Roadmap
-**Free (this repo, v1.0):** block + shortcode + auto-insert, presets, collapse,
-sticky, scroll-spy, offset, schema opt-in, admin support pages.
+**Free (this repo):** block, shortcode, auto-insert (including Fixed left on a
+wide single post or page), presets, collapse, close, Focus, sticky, scroll-spy,
+Design settings with a live preview, offset, schema opt-in, admin support pages.
 
 **Later / Pro ideas:** extra numbering styles, per-heading include/exclude UI,
 site-editor pattern library, premium presets. Do not cripple the free plugin

@@ -52,8 +52,9 @@ Most Table of Contents plugins stop at a list of links. TOCguide starts there an
 | **Anchors match the list** | IDs are injected from the same heading map. Custom HTML anchors win. |
 | **Reading Guide (opt-in)** | Previews, density bars, `~N min` badges, progress fade — computed from your content, not an API. |
 | **Study tools (opt-in)** | Progress bar, resume bookmark, private note pads, citations, export — all `localStorage` or clipboard. |
+| **A place to read** | Fixed left on a wide single post or page. Optional Focus clears the page to a paper sheet; **Show page** or Escape brings it back. |
 | **Works where you write** | Gutenberg block, `[tocguide]` shortcode, auto-insert, Elementor / Divi / Bricks and the other builders we document. |
-| **Theme-native** | The published TOC inherits the theme. No branded font on the front end. |
+| **Theme-native** | The published outline inherits the theme. Focus paper uses `"Segoe UI", system-ui, sans-serif`. |
 
 Zero config for the default path: insert the block, get an accessible `<nav>`.
 
@@ -64,6 +65,9 @@ Zero config for the default path: insert the block, get an accessible `<nav>`.
 ```mermaid
 timeline
     title TOCguide
+    1.6 : Fixed left on a wide single post or page
+        : Focus — Show page or Escape
+        : Design tab with a live preview
     1.5.0 : One identity — tocguide everywhere
          : Breaking prefix rename
          : Docs + support URLs
@@ -77,7 +81,8 @@ timeline
 
 | Version | Ship | What people notice |
 | :---: | :---: | --- |
-| **1.5.0** | **Now** | One slug everywhere: PHP, CSS, block `tocguide/table-of-contents`, `[tocguide]`, settings key. **Re-insert the block** if you used an earlier zip. |
+| **1.6.15** | **Now** | Fixed left stays with the post on archives. On a wide single post or page it sits in a left column of the main content. Focus, close, resume, and the Design tab are in this line. |
+| 1.5.0 | Sep 2026 | One slug everywhere: PHP, CSS, block `tocguide/table-of-contents`, `[tocguide]`, settings key. **Re-insert the block** if you used an earlier zip. |
 | 1.4.0 | Sep 2026 | Public name TOCguide for WordPress.org guideline 17. |
 | 1.3.x | Sep 2026 | Sitewide colors/fonts, focus rings, and the color-picker escape fix. |
 | 1.2.x | Sep 2026 | Progress bar, bookmark, reader notes, Section Planner. |
@@ -86,6 +91,20 @@ timeline
 
 Full prose: [`CHANGELOG.md`](CHANGELOG.md) · directory copy: [`readme.txt`](readme.txt).
 
+### v1.6 — Fixed left, Focus, and Design
+
+**Fixed left.** On a single post, page, or attachment, screens at least 1100px wide keep the outline in an 18rem column inside `main` (or `article` when the theme has no `main`). WordPress marks those views with `wp-singular`, `single`, `page`, or `attachment` on the body. The header and the rest of the page stay put. Archives, the blog index, and narrower screens leave the outline with the content.
+
+Turn it on in the block sidebar (**Behavior → Fixed left**), with **Settings → TOCguide → Auto-insert → Position → Fixed left**, or with `fixed="1"`. Settings copy says the same thing: it applies when reading a single post or page. Auto-insert still skips a post that already has the block or `[tocguide]`.
+
+**Close.** The close button is on by default. It hides the outline for that visit. **Show outline** brings it back. `close="0"` removes the button.
+
+**Focused reading.** **Behavior → Focused reading** (shortcode `focus="1"`, off by default) adds a Focus control. Turning it on adds `tocguide-is-focusing` on the `<html>` element, hides the surrounding page chrome, and sets the post copy on a paper card. That card uses `"Segoe UI", system-ui, sans-serif`. A floating button, `#tocguide-focus-exit`, stays on screen with **Show page**, **Bring the rest back**, and an Esc keycap. Escape or that button restores the page.
+
+**Resume.** With the resume bookmark on, an IntersectionObserver stores the last heading in `localStorage` under `tocguide-bm-{postId}`. The Resume button stays hidden until that key holds a heading that is in the current post’s outline.
+
+**Design.** **Settings → TOCguide → Design** sets the style, colours, type size, and spacing. The preview updates as you edit. A whole number such as `15` is saved as `15px`. A small decimal such as `0.95` is saved as `0.95rem`. Font choices are sans-serif or monospace already on the device.
+
 ### v1.5.0 — one identity
 
 | Surface | Value |
@@ -122,7 +141,7 @@ Full prose: [`CHANGELOG.md`](CHANGELOG.md) · directory copy: [`readme.txt`](rea
 | Feature | Enable | State |
 | --- | --- | --- |
 | Reading progress bar | Study Tools or `rprogress="1"` | `IntersectionObserver` |
-| Resume bookmark | `bookmark="1"` | `localStorage` `tocguide-bm-{post}` |
+| Resume bookmark | `bookmark="1"` | `localStorage` `tocguide-bm-{postId}`; the button stays hidden until that heading is in this post |
 | Reader note pads | `rnotes="1"` | `localStorage` `tocguide-rn-…` |
 | Section Planner | Block sidebar | `sectionStatus` attribute (editor only) |
 
@@ -166,12 +185,14 @@ Written for Plugin Directory review (FAQ + 18 guidelines). This is a **Plugin Di
 - Live editor preview as you add or edit headings
 - H1–H6 (H1 off by default), numbered or bulleted, five Block Styles
 - Smooth scroll + offset (`prefers-reduced-motion` respected)
-- Collapse/expand, sticky outline, scroll-spy
-- Auto-insert (top of content or after the first heading)
+- Collapse/expand, close for the visit, sticky outline, scroll-spy
+- Fixed left: an 18rem column of the main content on a wide single post or page
+- Optional Focus: paper sheet of the post, with **Show page** or Escape to restore the page
+- Auto-insert: top of content, after the first heading, or Fixed left
 - `[tocguide]` shortcode for classic content and page builders
 - Skip a heading with `no-toc` or `tocguide-skip`
 - Optional ItemList JSON-LD (off by default)
-- Settings + Docs & Support in wp-admin
+- Settings → TOCguide, including a Design tab whose preview updates as you edit
 
 <p align="center">
   <img src="docs/assets/tocguide-settings-panel.svg" alt="TOCguide settings mockup" width="560">
@@ -211,15 +232,46 @@ Or clone this repo into `wp-content/plugins/tocguide`, run `npm install && npm r
 
 1. Edit a post that has **Heading** blocks.
 2. Insert **Table of Contents** (usually right after the intro).
-3. In the sidebar: title, heading levels, list style, preset, collapse, sticky, Reading Guide.
+3. In the sidebar: title, heading levels, list style, preset, collapse, sticky, Fixed left, Focused reading, Reading Guide.
 
 ### Shortcode
 
 ```
 [tocguide]
 [tocguide title="On this page" ordered="1" style="boxed"]
+[tocguide fixed="1" focus="1" bookmark="1"]
 ```
 
+On/off attributes accept `1`, `true`, `yes`, or `on`.
+
+| Attribute | Accepted values | Default |
+| --- | --- | --- |
+| `title` | Text | Table of Contents |
+| `showtitle` | on/off | on |
+| `titletag` | `p`, `h2`, `h3`, `h4` | `p` |
+| `h1`–`h6` | on/off | `h2` and `h3` on |
+| `ordered` | on/off | off |
+| `numbering` | `default`, `nested` | `default` |
+| `markers` | on/off (`1` shows them) | on |
+| `collapsible`, `collapsed` | on/off | off |
+| `close` | on/off | on |
+| `focus` | on/off | off |
+| `sticky` | on/off | off |
+| `fixed` | on/off. `fixed="1"` keeps the outline in a left column on a wide single post or page | off |
+| `compact` | on/off | off |
+| `columns` | `1` or `2` | `1` |
+| `underline` | on/off | off |
+| `highlight` | on/off, or omit to use the site setting | site setting |
+| `maxheight` | pixels (`0` is unlimited) | `0` |
+| `min` | integer (`-1` uses the site minimum) | `-1` |
+| `smooth` | `inherit`, `on`, `off` | `inherit` |
+| `style` | `default`, `minimal`, `boxed`, `underline`, `card` | `default` |
+| `theme` | `inherit`, `exclude`, `include` | `inherit` |
+| `preview`, `guide`, `previews`, `density`, `readtime`, `progress`, `reactions`, `citations` | on/off | off |
+| `citation` | `apa`, `mla`, `chicago`, `harvard`, `plain` | `apa` |
+| `export` | on/off. `export="1"` adds Copy, .md, .doc, and Print | off |
+| `rprogress`, `bookmark`, `rnotes` | on/off | off |
+
 ---
 
 ## Develop

@@ -83,7 +83,9 @@ Match [Gutenberg block coding](https://developer.wordpress.org/block-editor/gett
 - [ ] Block inserts, live-previews headings, saves
 - [ ] Front-end links hit the right `id` (including custom anchors)
 - [ ] Level toggles, presets, collapse, sticky
-- [ ] `[tocguide]` and auto-insert (and *not* duplicating when the block is present)
+- [ ] `[tocguide]` and auto-insert (including Fixed left: wide singular dock, inline on archives and small screens)
+- [ ] Focus: Show page and Escape restore the page
+- [ ] A post that already has the block or shortcode is left alone by auto-insert
 - [ ] Duplicate heading text → unique slugs
 - [ ] `WP_DEBUG` is quiet
 

@@ -47,6 +47,9 @@ With the block selected, use the sidebar:
 | **Max height** | Scroll the list when it is taller than this (0 = unlimited). |
 | **Style** | Block Styles panel: Default, Minimal, Boxed, Underline, Card. |
 | **Sticky / collapsible / highlight** | Reading behavior. Smooth scroll can inherit the site setting or override it. |
+| **Fixed left** | On a single post or page, wide screens (1100px and up) keep the outline in an 18rem column of the main content. The header and the rest of the page stay put. Archives, the blog index, and smaller screens leave the outline with the content. |
+| **Close button** | On by default. Hides the outline for that visit. **Show outline** brings it back. |
+| **Focused reading** | Off by default. Adds Focus. Turning it on sets the post copy on a paper card (`"Segoe UI", system-ui, sans-serif`) and hides the surrounding page. **Show page**, **Bring the rest back**, or Escape restores the page. |
 | **Minimum headings / scroll offset** | `-1` inherits **Settings → TOCguide**. |
 
 Color, spacing, typography, and border are the normal block controls.
@@ -57,11 +60,12 @@ Color, spacing, typography, and border are the normal block controls.
 
 **Settings → TOCguide → Auto-generate the block**
 
-This prints the same **Table of Contents** Gutenberg block on the front end. It is not a shortcode.
+This prints the same **Table of Contents** Gutenberg block on the front end from the auto-insert settings.
 
 - Off (default) — add the block yourself, or use `[tocguide]` in classic content
 - Top of content
 - After the first heading
+- Fixed left — on a wide single post or page, an 18rem column of the main content. On a small screen the outline stays with the content. Auto-insert itself runs on singular views.
 
 Choose post types (Posts, Pages, …). Set title, heading levels, style, columns, collapse, and the rest of the layout on that same screen.
 
@@ -74,19 +78,32 @@ If a post already has the block or `[tocguide]`, auto-generate is skipped so you
 ```
 [tocguide]
 [tocguide title="On this page" ordered="1" numbering="nested" style="boxed" collapsible="1"]
+[tocguide fixed="1" focus="1" bookmark="1" export="1"]
 ```
 
-Attributes: `title`, `showtitle`, `titletag`, `h1`–`h6`, `ordered`, `numbering`, `markers`, `collapsible`, `collapsed`, `sticky`, `compact`, `columns`, `underline`, `highlight`, `maxheight`, `min`, `smooth`, `style`.
+On/off attributes accept `1`, `true`, `yes`, or `on`.
+
+Layout and behavior: `title`, `showtitle`, `titletag`, `h1`–`h6`, `ordered`, `numbering`, `markers`, `collapsible`, `collapsed`, `close` (default on), `focus` (default off), `sticky`, `fixed` (default off; `fixed="1"` docks on a wide single post or page), `compact`, `columns`, `underline`, `highlight`, `maxheight`, `min` (`-1` uses the site minimum), `smooth` (`inherit`, `on`, or `off`), `style`, `theme` (`inherit`, `exclude`, or `include`).
+
+Reading Guide: `preview`, `guide`, `previews`, `density`, `readtime`, `progress`, `reactions`, `citations`, `citation` (`apa`, `mla`, `chicago`, `harvard`, or `plain`).
+
+Study tools: `export="1"` (Copy, .md, .doc, Print), `rprogress="1"`, `bookmark="1"` (resume; the button stays hidden until `tocguide-bm-{postId}` holds a heading in this post), `rnotes="1"`.
+
+---
+
+## 6. Design settings
+
+**Settings → TOCguide → Design** sets the style, colours, type size, and spacing. The preview updates as you edit. A whole number such as `15` is saved as `15px`. A small decimal such as `0.95` is saved as `0.95rem`. Font choices are sans-serif or monospace already on the device. Save publishes that look on every outline.
 
 ---
 
-## 6. Skip a heading
+## 7. Skip a heading
 
 On the Heading block: **Advanced → Additional CSS class(es)** → `no-toc` (or `tocguide-skip`).
 
 ---
 
-## 7. Troubleshooting
+## 8. Troubleshooting
 
 **Empty TOC**
 - Use real Heading blocks, not bold paragraphs.
@@ -102,10 +119,14 @@ On the Heading block: **Advanced → Additional CSS class(es)** → `no-toc` (or
 
 **Styles clash with the theme**
 - Try another preset, or CSS on `.tocguide`, `.tocguide__link`, `.tocguide__link.is-active`.
+- **Settings → TOCguide → Design** can exclude theme list styles. The preview updates as you edit.
+
+**Fixed left stays in the post**
+- The left column applies on a single post or page at 1100px and wider. Archives, the blog index, and smaller screens keep the outline with the content.
 
 ---
 
-## 8. FAQ
+## 9. FAQ
 
 **Classic Editor?** Use `[tocguide]`.
 
@@ -117,6 +138,6 @@ On the Heading block: **Advanced → Additional CSS class(es)** → `no-toc` (or
 
 ---
 
-## 9. Getting help
+## 10. Getting help
 
 [GitHub Issues](https://github.com/matthummel-pa/tocguide/issues) — include WordPress version, theme, and a screenshot. Policy: [SUPPORT.md](../SUPPORT.md).