30:T428,## Instructions The ordering of the cells is synced to the insertion of the runtime variable set, so there is a **single global ordering of cells** that all visualizers share. While it might make more sense for each visualizer to have its own ordering, the advantage of using the runtime ordering is that this is preserved when [single file exporting](https://observablehq.com/@tomlarkworthy/exporter). Thus, the global ordering changes are be preserved after export. Usage ```js visualizer(runtime, { // get a runtime reference from @mootari/access-runtime invalidation, // the visualizer need a reference to the invalidation promise to tear down DOM state if being used dynamically module, // default main, filter: (cell_name, variables, cellIndex, status) => true, // filter what variables are displayed inspector: /* default */ Inspector.into, // factory for creating cells detachNodes: false, // detach DOM nodes from their current parent when evaluating, so new visualizer can steal them classList: "" // additional class string to add }) ```31:T721,### Differences to other works - The Observable's [export cell renderer](https://observablehq.com/documentation/embeds/advanced#rendering-cells) describes a pattern tofirst create a `div`, a CSS style tag, and then use Inspector.into when starting the runtime, - [@asg017/v0-6-0-of-the-unofficial-observablehq-compiler](https://observablehq.com/@asg017/v0-6-0-of-the-unofficial-observablehq-compiler#cell-214) follows a similar pattern of setting up the framing and rendering of the runtime before starting a notebook using Inspector.into This approach here is very different. The problem with the above approaches is only one Inspector can be used, _**and**_ it has to be decided before running the notebook in a privileged context, and you have to select a CSS stylesheet all in advance. In contrast, the [visualizer](https://observablehq.com/@tomlarkworthy/visualizer) allows multiple Inspectors to be attached dynamically after the runtime is started, and the can be added from inside the notebook environment like any other notebook logic. The workhorse of the methodology is being able to attached Observers to variables dynamically, which is implemented [here](https://observablehq.com/@tomlarkworthy/runtime-sdk#cell-159). So this means you no longer need to choose a stylesheet upfront, or add a div, or even instantiate an Inspector before starting a runtime, as these decisions can be done inside the loaded notebook, allowing you to start the runtime _headless_, then add multiple views of the notebook as needed. ```html ``` 32:T49c,visualizer = ( runtime, { invalidation, module = main, filter = () => true, inspector = Inspector.into, detachNodes = false, classList = "" } = {} ) => { console.log("creating visualizer"); backgroundJobs; const root = html`

`; const visualizer = html`

${root}

`; root.filter = filter; root.module = module; root.inspector = inspector; root.detachNodes = detachNodes; root.visualizer = visualizer; viewof visualizers.value.add(root); viewof visualizers.dispatchEvent(new Event("input")); invalidation.then(() => { console.log("removing visualizer", root); root.remove(); root.visualizer.remove(); root.dispatchEvent(new Event("input")); // We need to keep roots around so we know not to sync with them // But this is also a cause of a memory leak. // Probably we need a new set to record the disposed sync div nodes. viewof visualizersToDelete.value.add(root); viewof visualizersToDelete.dispatchEvent(new Event("input")); }); return visualizer; }33:T8bb,renderImportCell = (cell, { isKnown = () => true } = {}) => { const ii = cell?.importInfo ?? null; const span = document.createElement("span"); span.className = "observablehq--inspect observablehq--import"; if (!ii || ii.type !== "import") { span.appendChild(document.createTextNode("invalid importInfo")); return span; } if (typeof ii.source === "string" && ii.source.trim().startsWith("import")) { span.appendChild(document.createTextNode(ii.source.trim())); return span; } const moduleId = String(ii.notebook ?? ii.specifier ?? ii.from ?? "").trim(); const rawSpecs = Array.isArray(ii.specifiers) ? ii.specifiers : []; const specs = rawSpecs .map((s) => ({ imported: s?.imported ?? null, local: s?.local ?? null })) .filter((d) => d.imported != null || d.local != null) .map((d) => ({ imported: d.imported == null ? "" : String(d.imported), local: d.local == null ? "" : String(d.local) })) .filter((d) => d.imported || d.local); span.appendChild(document.createTextNode("import {")); if (specs.length) { let first = true; for (const s of specs) { if (!first) span.appendChild(document.createTextNode(", ")); first = false; const imported = s.imported || s.local; const local = s.local || s.imported || ""; const a = document.createElement("a"); a.textContent = imported; if (imported && isKnown(imported) && moduleId) { a.href = navHref({ open: moduleId, cell: imported }); } else { a.className = "observablehq--unknown"; } span.appendChild(a); if (imported && local && imported !== local) { span.appendChild(document.createTextNode(` as ${local}`)); } } } span.appendChild(document.createTextNode("}")); span.appendChild(document.createTextNode(" from ")); if (!moduleId) { span.appendChild( document.createTextNode(`"${String(ii.from ?? ii.specifier ?? "")}"`) ); return span; } const from = String(ii.from ?? ii.specifier ?? moduleId); const fromLink = span.appendChild(document.createElement("a")); fromLink.href = navHref({ open: moduleId }); fromLink.textContent = `"${from}"`; return span; }34:T12e1,syncers = { const syncers = this || new Map(); const isManagedCellNode = (node) => !!node?.classList?.contains("observablehq"); const nextManaged = (node) => { while (node && !isManagedCellNode(node)) node = node.nextSibling; return node; }; const disposeRoot = (root, entry) => { const { observers, headers } = entry || {}; headers?.forEach((node) => node?.remove?.()); headers?.clear?.(); observers?.forEach((obsEntry, v) => { obsEntry.remove(); if (v?._observer?.fulfilled && v._value) v._observer.fulfilled(v._value, v._name); }); observers?.clear?.(); }; const ensureObserver = (root, inspector, observers, v) => { const existing = observers.get(v); if (existing?.root === root) return existing; if (existing) existing.remove(); const observer = inspector(v); const unobserve = observe(v, observer, { detachNodes: root.detachNodes }); const entry = { observer, root, remove: () => { observers.delete(v); const node = observer?._node; if (node) { // Detach the variable's live element value const val = v?._value; if (val && val.nodeType && val.parentNode === node) node.removeChild(val); node.remove(); } unobserve?.(); } }; observers.set(v, entry); return entry; }; for (const [root, entry] of [...syncers.entries()]) { if (!inspectors.has(root)) { disposeRoot(root, entry); syncers.delete(root); } } inspectors.forEach((inspector, root) => { if (viewof visualizersToDelete.value.has(root)) return; if (!syncers.has(root)) syncers.set(root, { observers: new Map(), headers: new Map() }); const { observers, headers } = syncers.get(root); const cells = liveCellMap.get(root.module) || []; const seenVars = new Set(); const seenHeaderKeys = new Set(); const desired = []; let i = 0; const filterState = {}; for (const cell of cells) { const cell_name = cell?.name; if (!root.filter(cell_name, cell.variables, i++, filterState)) continue; if (cell?.type === "import") { const ii = cell?.importInfo ?? null; if (!ii || ii.type !== "import") continue; if (ii.specifier === "builtin") continue; const headerKey = `${String(ii.specifier ?? "")}#${String( cell?.name ?? i - 1 )}`; seenHeaderKeys.add(headerKey); let header = headers.get(headerKey); if (!header) { header = createImportCellHeader(cell); headers.set(headerKey, header); } else if (header.__viz) { header.__viz.cell = cell; } header.variable = cell.variables[0]; const isKnown = (imported) => { try { return !!root?.module?._scope?.has?.(imported); } catch { return true; } }; const node = renderImportCell(cell, { isKnown }); const statement = header.__viz.statement; while (statement.firstChild) statement.removeChild(statement.firstChild); statement.appendChild(node); desired.push(header); continue; } const renderedVars = variablesForCell(cell); for (const v of renderedVars) { if (!v) continue; if (visualizers.has(v._value) && v._value?.detachNodes) continue; seenVars.add(v); const entry = ensureObserver(root, inspector, observers, v); if (entry?.observer?._node) desired.push(entry.observer._node); } } for (const [k, node] of [...headers.entries()]) { if (!seenHeaderKeys.has(k)) { node.remove(); headers.delete(k); } } for (const [v, entry] of [...observers.entries()]) { if (!seenVars.has(v)) entry.remove(); } const desiredSet = new Set(desired); for (const child of [...root.childNodes]) { if (isManagedCellNode(child) && !desiredSet.has(child)) child.remove(); } let cursor = nextManaged(root.firstChild); for (const node of desired) { cursor = nextManaged(cursor); if (node === cursor) { cursor = cursor.nextSibling; continue; } root.insertBefore(node, cursor || null); } for (let n = nextManaged(cursor); n; ) { const next = n.nextSibling; if (isManagedCellNode(n) && !desiredSet.has(n)) n.remove(); n = nextManaged(next); } }); for (const root of [...viewof visualizersToDelete.value]) { const entry = syncers.get(root); if (entry) disposeRoot(root, entry); syncers.delete(root); inspectors.delete(root); viewof visualizersToDelete.value.delete(root); viewof visualizers.value.delete(root); } return syncers; }35:[] 2e:{"title":"Visualizer: Own Cell Renderer","cells":[{"id":0,"value":"# Visualizer: Own Cell Renderer\n\nInstead of cells being rendered into a `div` that is setup before the runtime is started, we invert, by rendering cells into a div hosted _inside_ the notebook. Through this inversion, it is possible to change radically change how notebook renders within userspace. For example, creating a minimap, grid or both at the same time. \n\n```js\nimport {visualizer, lopeviz_handle_css} from '@tomlarkworthy/visualizer'\n```\n\nOn its own this notebook is not very useful. It lays a foundation for total transformation of how notebooks can be rendered, but those new formats need to be developed.\n","pinned":false,"hidden":false,"mode":"md"},{"id":2049,"value":"","pinned":false,"hidden":false,"mode":"md"},{"id":1846,"value":"### Example - Rendering _this notebook_'s runtime-sdk-dependancy","pinned":false,"hidden":false,"mode":"md"},{"id":1510,"value":"{\n return visualizer(runtime, {\n invalidation,\n module: runtimSdkModule,\n classList: \"runtimeSdk\",\n detachNodes: true\n });\n}","pinned":false,"hidden":false,"mode":"ojs"},{"id":2305,"value":"","pinned":false,"hidden":false,"mode":"html"},{"id":1577,"value":"---","pinned":false,"hidden":false,"mode":"md"},{"id":1379,"value":"$30","pinned":false,"hidden":false,"mode":"md"},{"id":1714,"value":"## Customizing the visual representation\n\nThe `inspector` variable defines a factory of variable observers, matching the signature of Observable's [`Inspector.into`](https://github.com/observablehq/inspector#Inspector_into) method. The visualizer uses this factory to build listeners to the runtime's variables. By default it is the default observable inspector, which renders cells in the way you are familiar, however, you can change this to anything. In this notebook we also provide examples around the [minicell](https://observablehq.com/@tomlarkworthy/minicell), which renders just the variables's name, giving a minimap feel, but the possibilities are endless.","pinned":false,"hidden":false,"mode":"md"},{"id":1731,"value":"---\n\n---","pinned":false,"hidden":false,"mode":"md"},{"id":1743,"value":"## Runtime Tooling Compatible\n\nVisualizer uses the underlying runtime as the authoritative state, so it composes with the [single file exporter](https://observablehq.com/@tomlarkworthy/exporter) and [editor](https://observablehq.com/@tomlarkworthy/editor) (not shown), enabling editable, reordering and offline-first notebooks that (re)serialise to single files. Try clicking \"tab\".","pinned":false,"hidden":false,"mode":"md"},{"id":1883,"value":"$31","pinned":false,"hidden":false,"mode":"md"},{"id":1757,"value":"---\n\n## Implementation","pinned":false,"hidden":false,"mode":"md"},{"id":186,"value":"viewof allVariables = variables(runtime)","pinned":false,"hidden":false,"mode":"ojs"},{"id":266,"value":"mainVariables = [...allVariables].filter((v) => v._module == main)","pinned":false,"hidden":false,"mode":"ojs"},{"id":177,"value":"$32","pinned":true,"hidden":false,"mode":"ojs"},{"id":1244,"value":"viewof visualizers = Inputs.input(new Set())","pinned":false,"hidden":false,"mode":"ojs"},{"id":1689,"value":"viewof visualizersToDelete = Inputs.input(new Set())","pinned":false,"hidden":false,"mode":"ojs"},{"id":226,"value":"inspectors = {\n const inspectors = this || new Map(); // preserve state across invalidations\n visualizers.forEach((root) => {\n if (inspectors.has(root)) return;\n const factory = root.inspector(root);\n const inspector = (variable, ...args) => {\n const inspector = factory(variable, ...args);\n inspector._node.variable = variable;\n if (variable._name) inspector._node.setAttribute(\"cell\", variable._name);\n return inspector;\n };\n inspectors.set(root, inspector);\n });\n inspectors.forEach((fn, root) => {\n if (!visualizers.has(root)) {\n console.log(\"tidy up inspector for \", root);\n inspectors.delete(root);\n }\n });\n return inspectors;\n}","pinned":true,"hidden":false,"mode":"ojs"},{"id":2232,"value":"TRACE_CELL = trace_variable","pinned":false,"hidden":false,"mode":"ojs"},{"id":2320,"value":"","pinned":false,"hidden":false,"mode":"html"},{"id":2416,"value":"createImportCellHeader = (cell) => {\n const header = document.createElement(\"div\");\n header.className = \"observablehq lope-viz-import\";\n header.setAttribute(\"data-cell-type\", \"import\");\n header.setAttribute(\"data-cell-name\", String(cell?.name ?? \"\"));\n if (cell?.module_name)\n header.setAttribute(\"data-module-name\", String(cell.module_name));\n header.setAttribute(\"cell\", String(cell?.name ?? \"import\"));\n const line = document.createElement(\"div\");\n line.className = \"lope-viz-import-line\";\n const statement = document.createElement(\"div\");\n statement.className = \"lope-viz-import-statement\";\n line.appendChild(statement);\n header.appendChild(line);\n header.__viz = { statement, cell };\n return header;\n}","pinned":false,"hidden":false,"mode":"ojs"},{"id":2415,"value":"variablesForCell = {\n return cell => {\n if (!cell)\n return [];\n if (cell.type === 'import')\n return [];\n // mutable: variables = [initial X, mutable X, X]; render X (live), not initial (seed). #159\n const i = cell.type === 'mutable' ? 2 : 0;\n return [cell.variables?.[i]].filter(Boolean);\n };\n}","pinned":false,"hidden":false,"mode":"ojs"},{"id":2414,"value":"$33","pinned":false,"hidden":false,"mode":"ojs"},{"id":2349,"value":"$34","pinned":true,"hidden":false,"mode":"ojs"},{"id":1832,"value":"### background jobs and keep alive","pinned":false,"hidden":false,"mode":"md"},{"id":1446,"value":"backgroundJobs = {\n console.log(\"background job\");\n keepalive(visualizerModule, \"syncers\");\n}","pinned":false,"hidden":false,"mode":"ojs"},{"id":1440,"value":"viewof visualizerModule = thisModule()","pinned":false,"hidden":false,"mode":"ojs"},{"id":1835,"value":"### imports","pinned":false,"hidden":false,"mode":"md"},{"id":223,"value":"import { Inspector, isnode } from \"@tomlarkworthy/inspector\"","pinned":false,"hidden":false,"mode":"ojs"},{"id":183,"value":"import {\n myModule as runtimSdkModule,\n unorderedSync, // needed by consumers\n repositionSetElement,\n runtime,\n main,\n variables,\n descendants,\n lookupVariable,\n toObject,\n observe,\n keepalive,\n thisModule,\n trace_variable\n} from \"@tomlarkworthy/runtime-sdk\"","pinned":false,"hidden":false,"mode":"ojs"},{"id":2237,"value":"import { liveCellMap } from \"@tomlarkworthy/cell-map\"","pinned":false,"hidden":false,"mode":"ojs"},{"id":2419,"value":"import { navHref } from \"@tomlarkworthy/lopepage-urls\"","pinned":true,"hidden":false,"mode":"ojs"}],"files":"$W35","stdlib":"1","titling":"auto"}