eyeling 1.24.12 → 1.24.14

package/HANDBOOK.md

@@ -3682,7 +3682,7 @@ That is exactly the sort of explanation that N3, and Eyeling in particular, can
 
 ## Appendix I — The Eyeling Playground
 
-The **Eyeling Playground** is the browser-based front end for experimenting with Eyeling without a local install or command-line workflow. It is meant for teaching, quick debugging, live demos, and shareable reasoning examples. Rather than treating reasoning as an offline batch process, the playground makes it interactive: users can edit N3 directly in the browser, load remote N3 from a URL, run reasoning, inspect streamed output, and share the current state through a link.
+The **Eyeling Playground** is the browser-based front end for experimenting with Eyeling without a local install or command-line workflow. It is meant for teaching, quick debugging, live demos, and shareable reasoning examples. Rather than treating reasoning as an offline batch process, the playground makes it interactive: users can edit N3 directly in the browser, load remote N3 from a URL, run reasoning, inspect streamed or rendered output, autosave local state, and create a compact share link when needed.
 
 This appendix explains what the playground is for, how it is structured, and why it matters in practice.
 
@@ -3696,7 +3696,8 @@ The playground exists to lower that initial friction. It lets a user:
 - edit or paste a small N3 program,
 - run reasoning immediately,
 - inspect output and errors in place,
-- and share the exact setup with a URL.
+- autosave local work between reloads,
+- and copy a compact share link when the setup should be shared.
 
 That makes the playground useful not only for newcomers, but also for experienced users who want a fast feedback loop for small examples.
 
@@ -3714,6 +3715,8 @@ A key recent addition is **background knowledge mode**. When enabled, the N3 loa
 
 That separation is helpful both pedagogically and practically. It mirrors real reasoning work, where a user often reasons _over_ a fixed body of data rather than constantly rewriting it.
 
+For repository examples, the playground also follows the same sidecar-input convention as the example test runner. When a loaded URL looks like `.../examples/name.n3`, the playground probes for `.../examples/input/name.trig`. If that companion TriG file exists, it is loaded automatically as background evidence and the run uses RDF/TriG compatibility mode, matching the command-line `-r` behavior used by `npm run test:examples`.
+
 ### I.3 Execution behavior
 
 The playground is designed to feel responsive even when reasoning is not trivial. To do that, it uses a browser execution model that can run inference in a worker rather than blocking the main UI thread. Output is then surfaced back into the page.
@@ -3728,6 +3731,8 @@ This matters because the playground is not just a text box plus a submit button.
 
 The output behavior also adapts to the kind of N3 program being run. In some cases the natural result is a streamed list of derived triples. In others, such as programs using output-oriented constructs like `log:outputString`, a rendered text result is more appropriate. The playground supports both styles.
 
+For Markdown-oriented `log:outputString` examples, the output pane has two views: a rendered Markdown view and a Markdown source view. The rendered view is selected by default when the output is text intended for presentation, while the source view keeps the exact generated Markdown available for copying, inspection, or comparison.
+
 ### I.4 Error handling and explainability
 
 For an interactive reasoning environment, error behavior matters almost as much as successful output. The playground therefore gives particular attention to syntax and runtime feedback.
@@ -3741,21 +3746,21 @@ The playground also exposes two configuration toggles that are especially useful
 
 Together these choices make the playground better suited to live explanation, teaching, and debugging than a minimal browser wrapper would be.
 
-### I.5 Shareable state through URLs
+### I.5 Local state and compact share links
+
+The playground deliberately separates ordinary editing from link sharing.
 
-One of the most practical features of the playground is that its state can be encoded in the page URL.
+During normal use, the live browser URL is kept short. Editor content and UI state are autosaved in `localStorage`, so reloading the page can restore local work without continuously rewriting the address bar with a large encoded N3 program.
 
-The canonical query parameters are:
+When a user does want a portable link, the **Copy share link** button creates one on demand:
 
-- `edit` — sets the editor content,
-- `url` — fills the URL field,
-- `loadbg` — determines whether the URL should be loaded as background knowledge,
-- `proofcomments` — initializes the proof-comments checkbox,
-- `httpsderef` — initializes the HTTPS dereferencing checkbox.
+- unedited examples that were loaded from a URL can be shared as short `?url=...` links,
+- edited programs are shared with a compact compressed `?state=...` payload,
+- default option values are omitted from that payload to keep links small.
 
-This makes the playground particularly strong for tutorials and demos. A link can specify not just a program, but a whole configuration: an imported resource, whether it belongs in background knowledge, a small editable overlay, and the relevant runtime toggles.
+This keeps everyday use pleasant while preserving the important tutorial and issue-reporting workflow: a link can still capture the imported resource, the local editable overlay, background-knowledge mode, proof-comments mode, and HTTPS-dereferencing mode.
 
-Older hash-based links are still accepted as a fallback, but new state updates are written using query parameters because they scale better as the UI grows beyond a single editor field.
+For compatibility, older `?edit=`, `?program=`, `?url=`, compact `?state=`, and hash-based links are still accepted when opened. The old `/demo` entry point is also kept as a redirect to the canonical `/playground` page.
 
 ### I.6 What the playground is good for
 
@@ -3775,7 +3780,7 @@ For short reasoning tasks, the playground can be a faster debugging surface than
 
 #### I.6.4 Sharing examples
 
-A single link can capture enough context for another person to reproduce an example quickly. This is valuable in issue reports, discussions, teaching material, and public-facing demonstrations.
+A copied share link can capture enough context for another person to reproduce an example quickly, without forcing the live browser URL to carry the full editor content during normal use. This is valuable in issue reports, discussions, teaching material, and public-facing demonstrations.
 
 ### I.7 Limits of the playground
 
@@ -3787,7 +3792,7 @@ In short: the playground is best thought of as a compact interactive front end f
 
 ### I.8 Why it matters
 
-The Eyeling Playground shows that N3 reasoning can be made substantially more approachable without flattening the underlying logic into a toy interface. A relatively small set of features — an editor, a URL loader, background knowledge mode, responsive execution, proof toggles, and shareable query parameters — is enough to support serious educational and exploratory work.
+The Eyeling Playground shows that N3 reasoning can be made substantially more approachable without flattening the underlying logic into a toy interface. A relatively small set of features — an editor, a URL loader, background knowledge mode, responsive execution, proof toggles, rendered Markdown output, local autosave, and compact share links — is enough to support serious educational and exploratory work.
 
 That is the main value of the playground. It gives Eyeling a public-facing, browser-native environment where reasoning is not hidden behind setup overhead, and where examples can move easily between author, teacher, student, and reviewer.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eyeling",
-  "version": "1.24.12",
+  "version": "1.24.14",
   "description": "A minimal Notation3 (N3) reasoner in JavaScript.",
   "main": "./index.js",
   "keywords": [

package/test/playground.test.js

@@ -22,8 +22,18 @@ const TTY = process.stdout.isTTY;
 const C = TTY
   ? { g: '\x1b[32m', r: '\x1b[31m', y: '\x1b[33m', dim: '\x1b[2m', n: '\x1b[0m' }
   : { g: '', r: '', y: '', dim: '', n: '' };
+const msTag = (ms) => `${C.dim}(${ms} ms)${C.n}`;
+
+const TOTAL_TESTS = 11;
+const idxWidth = String(TOTAL_TESTS).length;
+let passed = 0;
+let failed = 0;
+let currentTest = null;
+let nonTestFailure = false;
+const suiteStart = Date.now();
+
 function ok(msg) {
-  console.log(`${C.g}OK ${C.n} ${msg}`);
+  console.log(`${C.g}OK${C.n}  ${msg}`);
 }
 function info(msg) {
   console.log(`${C.y}==${C.n} ${msg}`);
@@ -31,6 +41,36 @@ function info(msg) {
 function fail(msg) {
   console.error(`${C.r}FAIL${C.n} ${msg}`);
 }
+function beginTest(msg) {
+  currentTest = { msg, start: Date.now() };
+}
+function endTest() {
+  const tc = currentTest;
+  if (!tc) return;
+  const idx = String(passed + failed + 1).padStart(idxWidth, '0');
+  ok(`${idx} ${tc.msg} ${msTag(Date.now() - tc.start)}`);
+  passed += 1;
+  currentTest = null;
+}
+function recordCurrentFailure() {
+  const tc = currentTest;
+  if (!tc) return false;
+  const idx = String(passed + failed + 1).padStart(idxWidth, '0');
+  fail(`${idx} ${tc.msg} ${msTag(Date.now() - tc.start)}`);
+  failed += 1;
+  currentTest = null;
+  return true;
+}
+function printSummary() {
+  console.log('');
+  const suiteMs = Date.now() - suiteStart;
+  info(`Total elapsed: ${suiteMs} ms (${(suiteMs / 1000).toFixed(2)} s)`);
+  if (failed === 0 && !nonTestFailure) {
+    ok(`All playground tests passed (${passed}/${TOTAL_TESTS})`);
+  } else {
+    fail(`Some playground tests failed (${passed}/${TOTAL_TESTS})`);
+  }
+}
 
 function guessContentType(p) {
   const ext = path.extname(p).toLowerCase();
@@ -534,6 +574,10 @@ async function main() {
         'https://raw.githubusercontent.com/eyereasoner/eyeling/refs/heads/main/examples/builtin/sudoku.js',
         { ct: 'application/javascript', body: localSudokuBuiltin },
       ],
+      [
+        'https://raw.githubusercontent.com/eyereasoner/eyeling/refs/heads/main/examples/input/sudoku.trig',
+        { code: 404, ct: 'text/plain', body: 'not found' },
+      ],
     ]);
 
     async function getText(url) {
@@ -551,13 +595,17 @@ async function main() {
       });
     }
 
+    beginTest('clean /playground URL serves the playground');
     const cleanRes = await getText(cleanPlaygroundUrl);
     assert.equal(cleanRes.statusCode, 200, 'clean /playground URL should serve the playground');
     assert.match(cleanRes.body, /Eyeling N3 Playground/, 'clean /playground URL should load the playground');
+    endTest();
 
+    beginTest('legacy /demo URL serves the redirect page');
     const legacyRes = await getText(legacyDemoUrl);
     assert.equal(legacyRes.statusCode, 200, 'legacy /demo URL should serve redirect page');
     assert.match(legacyRes.body, /playground/, 'legacy /demo URL should point to the playground');
+    endTest();
 
     await cdp.send(
       'Fetch.enable',
@@ -582,7 +630,7 @@ async function main() {
             'Fetch.fulfillRequest',
             {
               requestId: p.requestId,
-              responseCode: 200,
+              responseCode: hit.code || 200,
               responseHeaders: [
                 { name: 'Content-Type', value: `${hit.ct}; charset=utf-8` },
                 { name: 'Cache-Control', value: 'no-store' },
@@ -647,6 +695,7 @@ async function main() {
             })
           : [];
         const renderedPanel = document.getElementById('output-rendered');
+        const outputTabs = document.querySelector('.output-tabs');
         const renderedTab = document.getElementById('output-rendered-tab');
         const sourceTab = document.getElementById('output-source-tab');
         const sourceWrapper = document.getElementById('output-source');
@@ -659,8 +708,12 @@ async function main() {
           renderedHtml: renderedPanel ? String(renderedPanel.innerHTML || '') : '',
           renderedHidden: renderedPanel ? !!renderedPanel.hidden : true,
           sourceHidden: sourceWrapper ? sourceWrapper.classList.contains('markdown-source-hidden') : true,
+          outputTabsHidden: outputTabs ? !!outputTabs.hidden : true,
           renderedTabSelected: renderedTab ? renderedTab.getAttribute('aria-selected') === 'true' : false,
           sourceTabSelected: sourceTab ? sourceTab.getAttribute('aria-selected') === 'true' : false,
+          shareStatus: document.getElementById('share-status') ? String(document.getElementById('share-status').textContent || '') : '',
+          backgroundStatus: document.getElementById('background-status') ? String(document.getElementById('background-status').textContent || '') : '',
+          href: String(window.location.href || ''),
           highlighted,
         };
       })()`)) || { status: '', output: '', highlighted: [] }
@@ -709,6 +762,10 @@ async function main() {
       })()`);
     }
 
+    async function makeShareUrlInPage() {
+      return await evalInPage(`window.__eyelingPlaygroundMakeShareUrl()`);
+    }
+
     async function loadUrlIntoEditor(url) {
       const payload = JSON.stringify(String(url));
       await evalInPage(`(() => {
@@ -752,6 +809,7 @@ ${JSON.stringify(last, null, 2)}`);
 `;
 
     // 1) Baseline smoke test: the default program runs to completion.
+    beginTest('playground runs the default Socrates program');
     await clickRun();
     const baseline = await waitForState(
       'default program completion',
@@ -763,9 +821,13 @@ ${JSON.stringify(last, null, 2)}`);
     );
     assert.ok(typeof baseline.output === 'string' && baseline.output.length > 0, 'Expected non-empty output');
     for (const [re, msg] of DEFAULT_PROGRAM_EXPECTS) assert.match(baseline.output, re, msg);
-    ok('playground runs the default Socrates program');
+    assert.equal(baseline.outputTabsHidden, true, 'Expected plain Turtle output to hide Markdown tabs');
+    assert.equal(baseline.renderedHidden, true, 'Expected plain Turtle output to skip rendered Markdown panel');
+    assert.equal(baseline.sourceHidden, false, 'Expected plain Turtle output to show source directly');
+    endTest();
 
     // 2) N3 syntax errors should be shown in Output and highlight the offending line.
+    beginTest('playground shows syntax errors in Output and highlights the offending line');
     await setProgram(syntaxErrorProgram);
     await clickRun();
     const syntaxErr = await waitForState(
@@ -777,9 +839,10 @@ ${JSON.stringify(last, null, 2)}`);
     assert.match(syntaxErr.output, /\n\^\s*$/m, 'Expected caret line in syntax error output');
     assert.equal(syntaxErr.highlighted[0].line, 3, 'Expected line 3 to be highlighted');
     assert.equal(syntaxErr.highlighted[0].text, '^', 'Expected highlighted line text to match the broken line');
-    ok('playground shows syntax errors in Output and highlights the offending line');
+    endTest();
 
     // 3) Inference fuse output should be visible in the Output pane.
+    beginTest('playground clearly shows inference fuse output');
     await setProgram(fuseProgram);
     await clickRun();
     const fuse = await waitForState(
@@ -793,9 +856,10 @@ ${JSON.stringify(last, null, 2)}`);
     assert.match(fuse.output, /Inference fuse triggered\./i, 'Expected fuse message in Output');
     assert.match(fuse.output, /Fired rule:/i, 'Expected fired rule explanation in Output');
     assert.match(fuse.output, /Matched instance:/i, 'Expected matched instance in Output');
-    ok('playground clearly shows inference fuse output');
+    endTest();
 
     // 4) log:outputString should render as clean text, not raw triples.
+    beginTest('playground renders log:outputString Markdown with Rendered/Markdown source tabs');
     await setProgram(outputStringProgram);
     await clickRun();
     const rendered = await waitForState(
@@ -812,6 +876,7 @@ ${JSON.stringify(last, null, 2)}`);
       /:report\s+log:outputString\s+"|# Derived triples/i,
       'Expected clean rendered output without raw triples',
     );
+    assert.equal(rendered.outputTabsHidden, false, 'Expected Markdown output tabs to be visible for log:outputString');
     assert.equal(rendered.renderedHidden, false, 'Expected rendered Markdown tab to be visible by default');
     assert.equal(rendered.sourceHidden, true, 'Expected Markdown source tab to be hidden by default');
     assert.equal(rendered.renderedTabSelected, true, 'Expected Rendered tab to be selected by default');
@@ -822,6 +887,7 @@ ${JSON.stringify(last, null, 2)}`);
 
     await clickOutputSourceTab();
     const sourceView = await getPlaygroundState();
+    assert.equal(sourceView.outputTabsHidden, false, 'Expected Markdown output tabs to stay visible in source view');
     assert.equal(sourceView.sourceTabSelected, true, 'Expected Markdown source tab to be selectable');
     assert.equal(sourceView.renderedHidden, true, 'Expected rendered Markdown panel to hide after selecting source');
     assert.equal(sourceView.sourceHidden, false, 'Expected source editor to show after selecting source');
@@ -830,15 +896,49 @@ ${JSON.stringify(last, null, 2)}`);
     await clickOutputRenderedTab();
     const renderedAgain = await getPlaygroundState();
     assert.equal(renderedAgain.renderedTabSelected, true, 'Expected Rendered tab to be selectable again');
-    ok('playground renders log:outputString Markdown with Rendered/Markdown source tabs');
+    endTest();
+
+    // 5) Normal editing should not keep rewriting the browser URL with raw N3 content.
+    beginTest('playground keeps the live URL short and creates compact share links on demand');
+    assert.doesNotMatch(renderedAgain.href, /[?&](?:edit|program)=/, 'Expected live URL to avoid raw editor content');
+    const compactShareUrl = await makeShareUrlInPage();
+    assert.match(compactShareUrl, /[?&]state=/, 'Expected an on-demand compact state parameter');
+    assert.doesNotMatch(compactShareUrl, /[?&](?:edit|program)=/, 'Expected share link to avoid raw edit/program params');
+    assert.ok(compactShareUrl.length < playgroundUrl.length + encodeURIComponent(outputStringProgram).length, 'Expected compact share URL to be shorter than raw editor URL');
+    endTest();
+
+    // 6) URL-loaded examples should auto-load matching examples/input/<stem>.trig and run in RDF/TriG mode.
+    beginTest('playground auto-loads companion TriG sidecars and uses RDF/TriG mode');
+    await loadUrlIntoEditor(`${started.baseUrl}/examples/smoke-arithmetic.n3`);
+    const smokeLoaded = await waitForState(
+      'smoke-arithmetic URL loaded with companion TriG input',
+      (st) => /companion RDF\/TriG input/i.test(String(st.status || '')) && /input\/smoke-arithmetic\.trig/i.test(String(st.backgroundStatus || '')),
+      20000,
+    );
+    assert.match(smokeLoaded.backgroundStatus, /smoke-arithmetic\.trig/i, 'Expected companion TriG sidecar in background status');
+    await clickRun();
+    const smoke = await waitForState(
+      'URL-loaded smoke-arithmetic example completion with sidecar input',
+      (st) =>
+        String(st.status || '')
+          .trim()
+          .startsWith('Done') && /product = 42/i.test(String(st.output || '')),
+      30000,
+    );
+    assert.match(smoke.output, /product = 42/i, 'Expected result derived from companion TriG evidence');
+    endTest();
 
-    // 5) URL-loaded repository examples should auto-load matching examples/builtin/<stem>.js.
+    // 7) URL-loaded repository examples should auto-load matching examples/builtin/<stem>.js.
+    beginTest('playground auto-loads a companion example builtin for URL-loaded Sudoku');
     await loadUrlIntoEditor('https://raw.githubusercontent.com/eyereasoner/eyeling/refs/heads/main/examples/sudoku.n3');
     await waitForState(
       'sudoku URL loaded with companion builtin',
       (st) => /loaded n3 into the editor and loaded its example builtin/i.test(String(st.status || '')),
       20000,
     );
+    const urlLoadedShareUrl = await makeShareUrlInPage();
+    assert.match(urlLoadedShareUrl, /[?&]url=/, 'Expected URL-loaded examples to share as a short url= link');
+    assert.doesNotMatch(urlLoadedShareUrl, /[?&]state=/, 'Expected unedited URL-loaded examples to avoid state payloads');
     await clickRun();
     const sudoku = await waitForState(
       'URL-loaded Sudoku example completion',
@@ -850,14 +950,18 @@ ${JSON.stringify(last, null, 2)}`);
     );
     assert.match(sudoku.output, /Completed grid/i, 'Expected Sudoku rendered output');
     assert.match(sudoku.output, /unique valid Sudoku solution/i, 'Expected Sudoku builtin-backed result');
-    ok('playground auto-loads a companion example builtin for URL-loaded Sudoku');
+    endTest();
 
     // Ensure no uncaught runtime exceptions.
+    beginTest('playground has no uncaught runtime exceptions');
     assert.equal(exceptions.length, 0, `Uncaught exceptions in playground.html: ${JSON.stringify(exceptions[0] || {})}`);
+    endTest();
 
     // Console errors are noisy and often indicate a broken UI.
     // (We suppress known noise like /favicon.ico on the server.)
+    beginTest('playground has no console errors');
     assert.equal(consoleErrors.length, 0, `Console errors in playground.html: ${JSON.stringify(consoleErrors[0] || {})}`);
+    endTest();
 
     // Cleanup.
     try {
@@ -866,9 +970,13 @@ ${JSON.stringify(last, null, 2)}`);
   } finally {
     await cleanup();
   }
+
+  printSummary();
 }
 
 main().catch((e) => {
+  if (!recordCurrentFailure()) nonTestFailure = true;
+  printSummary();
   fail(e && e.stack ? e.stack : String(e));
   process.exit(1);
 });