@pieceful/ravel-host-browser 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 James Taylor
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,55 @@
+# `@pieceful/ravel-host-browser`
+
+An in-memory, browser-safe [Ravel](https://github.com/jostylr/ravel) host for rendering one Markdown document into
+a Ravel Map, completed program, generated deliverables, diagnostics, and
+provenance maps.
+
+```sh
+npm install @pieceful/ravel-host-browser
+```
+
+```js
+import { renderMarkdownDocument } from "@pieceful/ravel-host-browser";
+
+const result = renderMarkdownDocument(
+  `
+---
+ravel:
+  document: greeting
+---
+
+\`\`\`javascript {.ravel #main type=js}
+console.log("Hello from Ravel");
+\`\`\`
+
+\`\`\`ravel
+out("dist/greeting.js", _"main.js")
+\`\`\`
+`,
+  { uri: "greeting.md" },
+);
+
+if (!result.ok) {
+  console.error(result.diagnostics);
+} else {
+  console.log(result.deliverables[0].value);
+  console.log(result.deliverables[0].provenanceMap);
+}
+```
+
+`BrowserRenderResult` always returns structured diagnostics instead of throwing
+for authored source errors. On success it contains the parsed map, completed
+`RavelProgram`, and every declared deliverable with a provenance map. Use the
+program with `@pieceful/ravel-explorer` when you want a bounded dependency
+graph in a browser UI.
+
+## Boundary
+
+This host has no filesystem, network, project loading, artifact writing, or
+live `.run` execution capability. It evaluates one caller-supplied Markdown
+string using the explicit opt-in Markdown profile by default. Its optional
+`transforms` are trusted synchronous functions supplied by the embedding
+application; a document cannot register or discover them.
+
+The [Ravel playground](https://ravel.jostylr.com/playground/) is a complete
+browser example built with this package.

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@pieceful/ravel-host-browser",
+  "version": "0.2.0",
+  "type": "module",
+  "sideEffects": false,
+  "description": "Portable in-memory Markdown host for the Ravel graph engine.",
+  "license": "MIT",
+  "author": "James Taylor",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jostylr/ravel.git",
+    "directory": "packages/host-browser"
+  },
+  "bugs": {
+    "url": "https://github.com/jostylr/ravel/issues"
+  },
+  "homepage": "https://ravel.jostylr.com/",
+  "engines": {
+    "node": ">=22"
+  },
+  "keywords": [
+    "ravel",
+    "literate-programming",
+    "browser",
+    "markdown",
+    "provenance"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "types": "./src/index.d.ts",
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@pieceful/ravel-core": "0.2.0",
+    "@pieceful/ravel-map": "0.2.0",
+    "@pieceful/ravel-markdown": "0.2.0"
+  }
+}

package/src/index.d.ts

@@ -0,0 +1,42 @@
+import type {
+  Deliverable,
+  DeliverableProvenanceMap,
+  Diagnostic,
+  RavelProgram,
+  RavelMap
+} from "@pieceful/ravel-core";
+
+export interface BrowserDeliverable extends Deliverable {
+  provenanceMap: DeliverableProvenanceMap;
+}
+
+export type BrowserTransform = (value: string, context: unknown) => string;
+
+export interface BrowserRenderOptions {
+  /** Source URI used in diagnostics and provenance. Defaults to `playground.md`. */
+  uri?: string;
+  /** Optional stable document identity. */
+  document?: string;
+  /** Markdown profile. Defaults to the explicit opt-in Ravel profile. */
+  mode?: "opt-in" | "primary";
+  /**
+   * Trusted application-supplied synchronous transforms. Document source cannot
+   * register transforms, and this host never provides filesystem or network access.
+   */
+  transforms?: Record<string, BrowserTransform> | Map<string, BrowserTransform>;
+}
+
+export interface BrowserRenderResult {
+  version: 1;
+  source: { uri: string; document: string | null };
+  map: RavelMap | null;
+  program: RavelProgram | null;
+  deliverables: BrowserDeliverable[];
+  diagnostics: Diagnostic[];
+  ok: boolean;
+}
+
+export function renderMarkdownDocument(
+  source: string,
+  options?: BrowserRenderOptions
+): BrowserRenderResult;

package/src/index.js

@@ -0,0 +1,71 @@
+import {
+  combineMaps,
+  createDeliverableProvenanceMap,
+  transformGraph
+} from "@pieceful/ravel-core";
+import { validateRavelMap } from "@pieceful/ravel-map";
+import { markdownToMap } from "@pieceful/ravel-markdown";
+
+const point = () => ({ line: 0, column: 0, offset: 0 });
+
+const hostDiagnostic = (error, uri) => ({
+  code: "RB100",
+  severity: "error",
+  message: error?.message ?? String(error),
+  source: {
+    uri,
+    range: { start: point(), end: point() }
+  }
+});
+
+/**
+ * Render one in-memory Markdown document through the portable Ravel pipeline.
+ *
+ * This host intentionally has no filesystem, process, network, load, or export
+ * surface. The caller owns the source string and any copy/paste interaction.
+ */
+export const renderMarkdownDocument = (source, options = {}) => {
+  const uri = options.uri ?? "playground.md";
+  const mode = options.mode ?? "opt-in";
+
+  try {
+    const adapted = markdownToMap(source, {
+      uri,
+      mode,
+      ...(options.document ? { document: options.document } : {})
+    });
+    const validationDiagnostics = validateRavelMap(adapted.map, { uri });
+    const program = transformGraph(combineMaps([adapted.map]), {
+      transforms: options.transforms
+    });
+    const diagnostics = [
+      ...adapted.diagnostics,
+      ...validationDiagnostics,
+      ...program.diagnostics
+    ];
+    const deliverables = Object.values(program.deliverables).map((deliverable) => ({
+      ...deliverable,
+      provenanceMap: createDeliverableProvenanceMap(deliverable)
+    }));
+
+    return {
+      version: 1,
+      source: { uri, document: adapted.map.document.id },
+      map: adapted.map,
+      program,
+      deliverables,
+      diagnostics,
+      ok: diagnostics.every((entry) => entry.severity !== "error")
+    };
+  } catch (error) {
+    return {
+      version: 1,
+      source: { uri, document: options.document ?? null },
+      map: null,
+      program: null,
+      deliverables: [],
+      diagnostics: [hostDiagnostic(error, uri)],
+      ok: false
+    };
+  }
+};