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.
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.
#18517builds a five-module work queue — Model, Store, Controller, Container, Workspace — entirely injavascript readonlyfences. 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', andexport 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-previewso 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:
readonlycontext above itWhichever 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
ComponentsAndContainers.md: guide-relative imports, aGuides.*className, and the assignment tail.DockLayoutsAdoption.mdgets 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.readonlysays 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.setupClasstail all differ, and a renamed fence that fails to mount is worse than an honestreadonly. 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-authoringbar 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.