Public JavaScript API

Ravel 0.2 favors small, function-oriented packages. The exports described here are public contracts; internal object properties not described here may change within the 0.2 line. Each library package ships a handwritten index.d.ts file alongside its JavaScript entry point. Live execution uses contract version 1 for provider analysis and outcomes; incompatible contract changes belong in a future major release.

@pieceful/ravel-map

Use this package at adapter, editor, and host boundaries.

  • validateRavelMap(map, { uri? }) returns diagnostics without throwing.
  • assertRavelMap(map, { uri? }) returns a valid map or throws RavelMapValidationError, whose diagnostics property is portable data.
  • RAVEL_MAP_VERSION, RAVEL_MAP_SCHEMA_ID, and RAVEL_MAP_SCHEMA identify the version-1 interchange contract.
  • @pieceful/ravel-map/schema is the JSON Schema module.

@pieceful/ravel-markdown

  • markdownToMap(text, options) converts the compatibility fence profile or explicitly selected modern profile to { map, diagnostics }.
  • modernMarkdownToMap(text, options) parses heading-owned and named-fence modern Markdown.

@pieceful/ravel-markdown-litpro

  • litproMarkdownToMap(text, options) parses the independent historical adapter and returns { map, diagnostics, surface }.
  • options.dialect selects litpro-2017, pieceful-2020, or litpro-plus.
  • options.headings selects or configures legacy, flat, or none heading semantics.
  • isLitproMarkdown(text) detects an explicit lp.adapter: markdown-litpro front-matter selection without making a host parse Markdown configuration.

@pieceful/ravel-noweb

  • nowebToMap(text, options) losslessly scans ordinary noweb or the extended noweb-plus dialect and returns { map, diagnostics, surface }.
  • options.references selects noweb, underscore-quote, or both.
  • options.language and options.languages supply languages that classic noweb declarations do not encode; recognizable filename extensions are inferred when neither is present.
  • options.run and options.provider retain live intent as metadata only.

@pieceful/ravel-org

  • orgToMap(text, options) scans named Babel source blocks and returns { map, diagnostics, surface }.
  • #+NAME and #+LP_NAME declare individual pieces; :noweb-ref contributes the same source body to a repeated aggregate piece.
  • options.references selects org-noweb, underscore-quote, or both; options.nowebPipes explicitly enables piped Org-noweb uses.
  • options.executionOwner selects org or ravel. Execution and tangling requests without one owner are diagnosed, and parsing performs neither.

@pieceful/ravel-asciidoc

  • asciidocToMap(text, options) scans section-owned pieces, attributed source blocks, multi-fragment containers, native cross references, and ravel:: graph-directive macros, returning { map, diagnostics, surface }.
  • Section-title and lp-pipe definition pipelines use the shared typed grammar and run once after fragment concatenation.
  • ravel-run and ravel-provider attributes retain live intent as inert metadata. Parsing invokes neither Asciidoctor nor a language runtime.
  • surface.includes records AsciiDoc include declarations without reading undeclared files.

@pieceful/ravel-html

  • htmlToMap(text, options) parses authored HTML with scripting disabled and returns { map, diagnostics, surface }.
  • Semantic section and figure elements use data-ravel-piece; visible headings or captions provide display names and descendant pre > code elements provide fragments.
  • data-ravel-pipe, language, live metadata, native anchor links, and visible read, derive, and write elements map to the shared contracts.
  • Character references are decoded while fragment precision preserves honest source-to-value provenance. Scripts, runtime mutations, and template contents cannot declare pieces.
  • The older data-lp-* and lp-document spellings remain accepted aliases.

@pieceful/ravel-quarto

  • prepareQuartoRender(text, options) parses .qmd through modern Markdown, validates and resolves the Ravel graph, and returns temporary decorated source without invoking Quarto or an execution engine.
  • Native #lst-lp-* labels, lst-cap, and lp-id map to one semantic piece, one visible Quarto listing caption, and one rendered anchor.
  • Generated Uses, Used by, and piece-index Markdown links target those native anchors. Invalid graphs remain undecorated.
  • sourceMap maps authored temporary-source regions exactly and marks inserted graph prose as generated. cacheKeyMaterial includes authored source, prepared source, adapter format, and bridge version.
  • decorateQuartoMarkdown(text, map, program, options) exposes the pure decoration stage for hosts that already own graph construction.
  • weaveQuartoExecutions(text, map, program) replaces Quarto-owned cell source with resolved code while preserving cell options and provenance. Ravel-owned cells receive an eval: false guard.
  • prepareQuartoProject(documents, options) resolves all supplied .qmd documents against one graph and emits format-aware cross-document links.
  • stampQuartoProjectCache(project, stamp) adds a generated trailing cache token to temporary sources without shifting authored mappings.
  • remapQuartoDiagnostic(diagnostic, project) translates a temporary renderer position through authored, woven, and generated source-map segments.
  • @pieceful/ravel-quarto/node exports prepareQuartoProjectDirectory(), renderPreparedQuartoProject(), and renderQuartoProject() for isolated project-tree preparation and explicit Quarto invocation. Returned temporary trees remain caller-owned until cleanup().

@pieceful/ravel-myst

  • mystToMap(text, options) scans canonical {ravel:piece} directives, their {piece} alias, {ravel} graph directives, and labeled native {code}, {code-block}, and {code-cell} fallbacks, returning { map, diagnostics, surface }.
  • Piece arguments use the shared name-and-pipeline grammar. :label: supplies a rendered anchor and semantic ID, while :caption: remains the visible display name.
  • surface.references contains code-composition uses; surface.navigation separately contains MyST links, reference roles, and @label shorthand.
  • options.executionOwner selects myst or ravel for notebook cells. Cell metadata and effect plans are inert during parsing.

@pieceful/ravel-myst-plugin

  • The default export is a native MyST JavaScript plugin; pieceDirective is also exported for direct registration or testing.
  • {ravel:piece} and its {piece} alias render as standard MyST code/container nodes with syntax highlighting, visible captions, labels, and displayed pipelines.
  • :cell: emits MyST’s native executable code-cell structure by default. :execution-owner: ravel keeps the rendered block static so two runtimes cannot own the same cell.
  • {ravel} renders graph-directive bodies as visible static code; the adapter parses those bodies through the shared Ravel directive grammar.
  • The plugin does not parse a Ravel graph, weave artifacts, or execute live code. Use @pieceful/ravel-myst for those semantics.

@pieceful/ravel-core

  • parseChunkId and formatChunkId convert canonical chunk identities.
  • parseChunk parses an individual chunk body into portable syntax data. Adapters may opt into lossless noweb delimiters and provide authored-name to semantic-ID aliases without rewriting the body.
  • parseDefinitionPipeline gives source adapters the shared definition-time transform grammar without evaluating a pipeline.
  • parseRavelDirectiveBlock(text, { document, sourceAt }) gives Markdown, MyST, and future adapters one source-mapped grammar for in, create, alias, and out blocks.
  • combineMaps(maps) constructs the pre-transform graph.
  • transformGraph(graph, { transforms?, deferLiveResults?, liveResults? }) evaluates that graph and returns the program, deliverables, diagnostics, dependencies, and trace. Hosts use deferLiveResults before execution and pass the completed execution result as liveResults for ordinary text materialization.
  • planLiveExecutions(program, { providers }) performs the language-neutral analysis and dependency-planning stage for chunks marked executable.
  • executeLiveProgram(program, { providers, resources?, limits?, signal? }) executes that plan asynchronously and returns portable values, canonical serialization, statuses, and diagnostics.
  • ravelValueIssue, serializeRavelValue, and cloneRavelValue implement the recursive data boundary shared by execution providers.
  • createDeliverableProvenanceMap(deliverable) and createBuildProvenanceMap(program) construct version-1 sidecar and aggregate generated-output maps.
  • sourceAtGeneratedOffset(map, offset) and generatedRangesForSource(map, uri, offset) provide forward and reverse provenance lookup. Exact results include a corresponding offset; coarse results retain the best attributable range without claiming character identity.
  • generatedRangesForSourceRange(map, uri, range) maps a half-open source range, while explainGeneratedOffset(program, deliverable, offset) adds the definition, references, and dependency path.
  • provenanceMapVersion identifies the generated provenance contract.

The @pieceful/ravel-core/directives entry point exposes constructors for the portable directive IR. Custom transforms are functions that receive a string value and return a string; a failed or non-string result becomes a diagnostic.

@pieceful/ravel-js-live (0.2)

  • javascriptLiveProvider is the shared QuickJS/WebAssembly provider for js and javascript.
  • createJavaScriptLiveProvider(options?) creates a provider with configured memory, stack, execution-time, output, worker, and approved-module limits. options.modules maps exact import specifiers to immutable ESM source; options.workerFactory integrates a host’s emitted browser worker.
  • A provider keeps its Wasm module warm behind a terminable worker, creates a fresh QuickJS runtime for each execution, and exposes dispose().

The provider parses modules before execution, accepts one final export default, exposes literal ch("...") and load("...") lookups over immutable copied data, and resolves static imports only from the approved registry. See Live execution for the profile and current security boundary.

The Node-only @pieceful/ravel-js-live/node subpath exports prepareJavaScriptModules. It bundles installed package exports explicitly allowlisted by a host into the immutable ESM-source registry.

@pieceful/ravel-host-node

This Node-only package performs scoped filesystem input and artifact work.

  • loadBuildInput and loadTomlBuild load direct files or version-1 TOML runs.
  • planDeliverables, writeBuildArtifacts, and createBuildManifest support managed artifact production. A managed build writes a .ravelmap sidecar for every deliverable and an aggregate .ravelmap bundle.
  • cleanManagedArtifacts, refreshStaleArtifacts, planOutputBackup, and createOutputBackup implement the safe managed-output lifecycle.

Expected input/configuration failures throw RavelInputError with portable diagnostics. Filesystem failures remain ordinary host errors.

@pieceful/ravel

This package is the installed ravel executable. Its programmatic import is side-effect free for package tooling, but it intentionally exposes no parallel JavaScript command API; use the CLI contract instead.