Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Notebook Input Package

Status: Implemented for the current host-neutral boundary. The package owns the Observable-style viewof source transform, tracked input metadata, DOM input node binding helpers, callback-driven view runtime helpers, and the current local Inputs runtime built from @lapis-notes/ui primitives for the supported control set. Remaining parity work is tracked by task id TASK-NOTEBOOK-001.

Purpose

@lapis-notes/notebook-input separates notebook input source helpers and tracked DOM/input lifecycle behavior from the product plugin. The current extraction owns the constrained Observable-style viewof transform, tracked input metadata, DOM input node value/listener helpers, the callback-driven lapis.view binding workflow, and the local runtime surface whose supported controls render through shared @lapis-notes/ui primitives. The product plugin continues to own input DOM registration, notebook session writes, output id allocation, and rerun scheduling.

Current Scope

  • transformObservableViewof(source) rewrites supported top-level viewof name = expression declarations into const name = await lapis.view(name, expression) calls.
  • findObservableViewofDefinitions(source) returns unique viewof names for source-level analysis.
  • The transform uses the canonical lapis global name from @lapis-notes/notebook-stdlib.
  • loadNotebookDomRuntime() lazily assembles the DOM-backed notebook runtime surface for hosts that have already chosen in-process DOM execution. That runtime owns the Inputs namespace exposed to notebook cells, pairs it with html and svg helpers from notebook-stdlib, routes supported controls through @lapis-notes/ui primitives for app-level UI parity, and throws explicit errors for unsupported factories.
  • createTrackedNotebookInputs(inputs) wraps Observable input factories so reconstructable controls can attach host-neutral metadata to the returned DOM nodes without parsing source text.
  • styles.css gives notebook hosts a notebook-input-owned stylesheet entrypoint for the current UI-backed controls without importing upstream styles directly from the product plugin.
  • attachNotebookInputMetadata(value, metadata) and getNotebookInputMetadata(value) expose the private metadata attachment surface used to carry input type, current value, serializable config, reconstructable flag, and source details from tracked Observable inputs into a runtime host.
  • canReconstructNotebookInput(metadata) and reconstructNotebookInputNode(metadata) let runtime hosts decide whether persisted structured inputs are directly rebuildable and recreate supported controls from stored metadata without re-running the owning cell. Newly created metadata identifies the local runtime with source.library: "@lapis-notes/notebook-input".
  • isTemplateStringsArray(value) and exported htl template tag types support runtime hosts that bridge lapis.html/lapis.svg with htl tagged template calls.
  • bindNotebookInputNode(node, options) seeds an optional initial DOM input value, reports the current value, binds input and change listeners, and returns a disposer for the runtime host to attach to its DOM-output lifecycle.
  • getNotebookInputNodeValue(node) and setNotebookInputNodeValue(node, value) provide shared DOM input value access for hosts without owning persistence policy.
  • createNotebookViewRuntime(options) builds the async lapis.view(name, input) host function from callbacks. It resolves promised DOM nodes, validates that the result is a DOM node, reads any tracked input metadata, binds input listeners, writes the current value through host callbacks, registers the live DOM output, appends the host’s typed output, and emits input-change events through the host callback.
  • isNotebookDomNode(value) provides shared DOM-node detection for runtime hosts that need to classify cell return values.

Boundary Rules

This package must stay host-neutral at import time. It may lazily load DOM-only helper code, the Svelte runtime, and @lapis-notes/ui primitives only inside loadNotebookDomRuntime(), so workspace boot and non-DOM notebook runs stay startup-thin. It must not import @lapis-notes/api, product-plugin modules, notebook session managers, workers, or DuckDB at top level. Runtime hosts are responsible for deciding when DOM-backed execution is available, passing host callbacks into createNotebookViewRuntime, registering live DOM outputs, persisting scalar input values, turning tracked input metadata into product-level structured outputs, and emitting rerun requests.

Consumers

@lapis-notes/notebook consumes this package from notebook analysis, render DOM detection, and cell execution paths. The DOM helper surface still loads lazily only for DOM-backed notebooks, while notebook-input adds the tracked wrapper and the UI-backed control factories that let notebook inputs hand reconstructable metadata to the product runtime and rebuild supported controls from persisted structured outputs without changing the package’s host-neutral boundary.