LearnNewsExamplesConnect
Frontmatter
assigneesneo-gpt-euclid
createdAtSep 9, 2026, 10:23 AM
updatedAtSep 12, 2026, 1:28 PM
githubUrlhttps://github.com/neomjs/neo/issues/18530
authorneo-opus-grace
commentsCount0
parentIssuenull
subIssues[]
subIssuesCompleted0
subIssuesTotal0
contentTrust
projected
quarantined0
signals[]
blockedBy[]
blocking[]
closedAtSep 12, 2026, 1:28 PM

The DockLayouts panes guide teaches component code with no live previews, unlike its own section

Closed v13.2.0/archive-v13-2-0-chunk-20 documentationenhancementaidashboard
neo-opus-grace
neo-opus-grace commented on Sep 9, 2026, 10:23 AM

Serves: #17540 — the DockLayouts guide arc. Follow-up to #18517 (approved and merging), which builds a complete runnable example and shows none of it running.

The Problem

Neo guides teach component code through live previews: the portal parses the fence, opens a Monaco editor, and renders the example. #18517 builds a five-module work queue — Model, Store, Controller, Container, Workspace — entirely in javascript readonly fences. The reader gets source they cannot run, for an example whose whole point is that the pane keeps working while the layout moves it.

A guide whose thesis is "complete a task, then move the queue, and watch the record survive" is the strongest possible candidate for a live preview, and it is the one guide in its arc that has none.

The Architectural Reality

Fence flavours across learn/guides:

160  ```javascript readonly
 93  ```javascript
 46  <div id="neo-pre-live-preview-1"></div>javascript
// live-preview, per ComponentsAndContainers.md
import Container from '../container/Base.mjs';        // guide-relative import root

class MainView extends Container {
    static config = {
        className: 'Guides.components1.MainView',      // Guides.* namespace, per-example slug
        ...
    }
}

MainView = Neo.setupClass(MainView);                   // assignment, not export default

#18517 uses ../../../src/data/Model.mjs, className: 'WorkQueue.model.Task', and export default Neo.setupClass(...). So each fence needs its import root, namespace and tail rewritten, and the five modules need composing into something a single preview can mount.

The Fix

Convert the guide's component examples to javascript live-preview so the reader can run the queue, complete a task, and see the record survive — the exact journey the prose describes.

The five modules are a genuine constraint: a live preview mounts one view. Options for the implementer to choose between, not a prescription:

  • one preview composing the whole workspace, with the Model/Store/Controller shown as readonly context above it
  • progressive previews that build up — grid bound to a Store, then the controller action, then the docked workspace
  • one preview at the payoff point only, keeping the teaching sequence readonly

Whichever shape is chosen, the movement journey is the part that must be runnable. Ownership survival is a claim the reader currently has to take on trust.

AC

  • AC-1 The guide's component examples render as live previews in the portal, verified by loading the page — not by the fence token alone.
  • AC-2 The example that demonstrates the pane surviving a move / collapse / reveal is runnable. If exactly one preview is affordable, it is that one.
  • AC-3 Converted examples follow the live-preview shape used by ComponentsAndContainers.md: guide-relative imports, a Guides.* className, and the assignment tail.
  • AC-4 DockLayoutsAdoption.md gets the same verdict — converted, or its exemption stated with a reason. It is the precedent #18517 followed, and leaving it unexamined reproduces this ticket later.
  • AC-5 Any example left readonly says why in one line, so the next guide in the arc inherits a decision rather than an accident.

Out of Scope

The guide's prose, structure and technical content — reviewed and approved on #18517. New dock features. The live-preview mechanism itself.

Avoided Traps

Do not convert by renaming the fence: the import root, className namespace and Neo.setupClass tail all differ, and a renamed fence that fails to mount is worse than an honest readonly. Do not assume five modules can become five previews — a preview mounts one view. Do not verify by grepping for the token; load the portal page and confirm the example actually renders.

Decision Record impact

none — a documentation convention, not an architectural contract.

Sweeps and ownership

Live latest-20 open sweep run before filing; nothing covers guide live previews. Fence counts measured at dev@335b2ca43a.

Raised by @tobiu. Filed by @neo-opus-grace, who reviewed #18517 against the full guide-authoring bar and did not check it against its sibling guides — the bar does not name live previews, and I graded the artifact without asking what the neighbouring guides in its own section do.

tobiu referenced in commit 259964a - "docs(dock): add runnable pane ownership preview (#18530) (#18597)" on Sep 12, 2026, 1:28 PM
tobiu closed this issue on Sep 12, 2026, 1:28 PM