eyeling 1.19.6 → 1.21.0

package/HANDBOOK.md

@@ -54,7 +54,7 @@ That last point is the heart of Eyeling’s design: _forward rules are executed
 
 Eyeling deliberately keeps the implementation small and dependency-free:
 
-- the published package includes a single bundled file (`eyeling.js`)
+- the published package includes a Node-oriented bundle (`eyeling.js`) and a dedicated browser bundle (`dist/browser/eyeling.browser.js`)
 - the source is organized into `lib/*` modules that read like a miniature compiler + logic engine.
 
 This handbook is a tour of that miniature system.
@@ -1757,7 +1757,9 @@ The same API can now also emit RDF/JS output. When `rdfjs: true` is passed, ever
 - `triple` — Eyeling’s N3 string form
 - `quad` — the same fact as an RDF/JS default-graph quad
 
-For fully stream-oriented RDF/JS consumers there is also `reasonRdfJs(...)`, which exposes the derived facts as an async iterable of RDF/JS quads.
+If your closure may contain N3-only terms such as quoted formulas (`GraphTerm`), RDF/JS conversion can fail because those terms have no standard RDF/JS representation. In that case, pass `skipUnsupportedRdfJs: true` to keep the full N3 closure while silently omitting any derived triples that cannot be represented as RDF/JS quads. When this flag is enabled, `onDerived(...)` still fires for every derived fact, but `quad` is only present for the representable ones.
+
+For fully stream-oriented RDF/JS consumers there is also `reasonRdfJs(...)`, which exposes the derived facts as an async iterable of RDF/JS quads. The same `skipUnsupportedRdfJs: true` flag applies there as well.
 
 ---
 
@@ -1805,7 +1807,7 @@ Custom builtins can be loaded explicitly from the CLI:
 npx eyeling --builtin lib/builtin-sudoku.js examples/sudoku.n3
 ```
 
-### 14.2 The bundled CLI (`eyeling.js`)
+### 14.2 The bundled Node CLI/runtime (`eyeling.js`)
 
 The bundle contains the whole engine. The CLI path is the “canonical behavior”:
 
@@ -1831,6 +1833,42 @@ The current CLI supports a small set of flags (see `lib/cli.js`):
 - With no positional argument, Eyeling reads from stdin when input is piped.
 - Use `-` as the input path to read explicitly from stdin.
 
+### 14.3 Package entrypoint split for Node, browser, and CLI
+
+The repo now publishes three distinct surfaces instead of forcing browser tooling through the Node-first bundle entry:
+
+- `index.js` remains the **Node API** used by `require('eyeling')` and `import eyeling from 'eyeling'` in Node.
+- `bin/eyeling.cjs` is the **CLI shim** with the shebang. It loads the Node bundle and calls `main()`.
+- `dist/browser/eyeling.browser.js` is the **browser-safe bundle asset** with **no shebang**.
+- `dist/browser/index.mjs` is the **browser import surface** exported as `eyeling/browser`.
+
+That gives the intended mental model:
+
+```js
+import eyeling from 'eyeling'; // Node
+import eyelingBrowser from 'eyeling/browser'; // Browser / worker
+```
+
+```bash
+npx eyeling …                              # CLI
+```
+
+The `package.json` `exports` map points the `browser` condition at `dist/browser/index.mjs`, so browser-oriented bundlers stop resolving the package root to the Node wrapper in `index.js`.
+
+`dist/browser/index.mjs` intentionally re-exports only the browser-safe surface:
+
+- `reasonStream(...)`
+- `reasonRdfJs(...)`
+- `rdfjs`
+- `registerBuiltin(...)`
+- `unregisterBuiltin(...)`
+- `registerBuiltinModule(...)`
+- `listBuiltinIris()`
+
+It deliberately does **not** expose `loadBuiltinModule(...)`, because loading builtin files by module specifier is a Node-only pattern. In browsers, custom builtins should be registered directly in-process (for example with `registerBuiltin(...)` or `registerBuiltinModule(...)`).
+
+For browser apps, prefer running Eyeling in a **Web Worker** and importing `eyeling/browser` there.
+
 ### 14.3 `lib/entry.js`: bundler-friendly exports
 
 `lib/entry.js` exports:
@@ -1845,7 +1883,7 @@ The current CLI supports a small set of flags (see `lib/cli.js`):
 Eyeling exposes two JavaScript entry styles:
 
 - `reason(...)` from `index.js` when you want the same text output as the CLI
-- `reasonStream(...)` / `reasonRdfJs(...)` from the bundle entry when you want in-process reasoning and structured RDF/JS results
+- `reasonStream(...)` / `reasonRdfJs(...)` from the Node bundle or `eyeling/browser` when you want in-process reasoning and structured RDF/JS results
 
 #### 14.4.1 npm helper: `reason(...)`
 
@@ -1966,8 +2004,11 @@ import eyeling from './eyeling.js';
 
 const result = eyeling.reasonStream(input, {
   proof: false,
-  onDerived: ({ quad }) => {
+  rdfjs: true,
+  skipUnsupportedRdfJs: true,
+  onDerived: ({ triple, quad }) => {
     if (quad) console.log(quad);
+    else console.warn('Skipped non-RDF/JS derived triple:', triple);
   },
 });
 ```
@@ -1975,11 +2016,15 @@ const result = eyeling.reasonStream(input, {
 That same path also lets derived results be consumed as an async stream of RDF/JS quads:
 
 ```js
-for await (const quad of eyeling.reasonRdfJs(input)) {
+for await (const quad of eyeling.reasonRdfJs(input, {
+  skipUnsupportedRdfJs: true,
+})) {
   console.log(quad);
 }
 ```
 
+Use `skipUnsupportedRdfJs: true` when you want RDF/JS consumers to ignore derived triples that contain N3-only terms such as quoted formulas. This affects only RDF/JS export. The underlying Eyeling closure and `closureN3` output remain unchanged.
+
 Use these entry points when you need one or more of the following:
 
 - RDF/JS quads as fact input

package/bin/eyeling.cjs

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+'use strict';
+
+const bundle = require('../eyeling.js');
+
+if (!bundle || typeof bundle.main !== 'function') {
+  throw new Error('Eyeling CLI bundle did not expose main()');
+}
+
+bundle.main();