eyeling 1.24.20 → 1.24.24

package/HANDBOOK.md

@@ -3733,7 +3733,7 @@ The output behavior also adapts to the kind of N3 program being run. In some cas
 
 For Markdown-oriented `log:outputString` examples, the output pane has two views: a rendered Markdown view and a Markdown source view. Those tabs appear only when the actual output looks like Markdown; Turtle or other plain output stays in the source editor without the Markdown toggle. The rendered view is selected by default for Markdown output, while the source view keeps the exact generated Markdown available for copying, inspection, or comparison.
 
-Repository example reports often contain relative source links that are written for the checked-in files under `examples/output/*.md`. When such an example is loaded into the playground from a raw URL, the rendered Markdown view resolves those relative links against the corresponding static output page rather than against `/playground`, so links like `../name.n3` and `../input/name.trig` continue to point to the intended example files.
+Repository example reports often contain relative source links that are written for the checked-in files under `examples/output/*.md`. When such an example is loaded into the playground from a raw URL, or restored later from compact/Gist-backed state, the rendered Markdown view resolves those relative links against the corresponding static output page rather than against `/playground`, so links like `../name.n3` and `../input/name.trig` continue to point to the intended example files. The playground preserves this base in shared state when possible and can also recover it from the injected `@base <.../examples/name.n3>` line.
 
 ### I.4 Error handling and explainability
 
@@ -3760,11 +3760,11 @@ When a user does want a portable link, the **Copy share link** button creates on
 - edited programs are shared with a compact compressed `?state=...` payload,
 - default option values are omitted from that payload to keep links small.
 
-If a generated compact share link is still very long, the playground reveals a **Create TinyURL** option. The threshold is intentionally conservative, and the shortener handoff is explicit rather than automatic: after the user chooses that option, the browser uses a TinyURL API token stored locally in that browser to create the short link and copy it to the clipboard. The API request is sent as a POST with `referrerPolicy: "no-referrer"`, so an already-long playground URL is not leaked again as a large `Referer` header. If no token is provided, or if the API request fails, the playground falls back to opening TinyURL without putting the long URL in TinyURL's address bar, and it copies the compact share link so it can be pasted manually. This avoids silently sending encoded editor content to a third-party service while still making the account-backed TinyURL workflow one click after setup.
+If a generated embedded-state link is still very long, the playground reveals **Create Gist share**. That option asks for a GitHub token with gist permission, stores the compact playground state as a secret Gist JSON file, and copies a small `?stateurl=...` playground link that fetches the state file client-side. The token is stored only in that browser's `localStorage`, the Gist is created by a POST request with `referrerPolicy: "no-referrer"`, and the shared playground URL no longer contains the large encoded program.
 
 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.
 
-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.
+For compatibility, older `?edit=`, `?program=`, `?url=`, compact `?state=`, `?stateurl=`, and hash-based links are 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
 

package/package.json

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

package/test/playground.test.js

@@ -722,7 +722,8 @@ async function main() {
           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 || '') : '',
-          shortenerHidden: document.getElementById('open-shortener-btn') ? !!document.getElementById('open-shortener-btn').hidden : true,
+          gistShareHidden: document.getElementById('create-gist-share-btn') ? !!document.getElementById('create-gist-share-btn').hidden : true,
+          gistShareText: document.getElementById('create-gist-share-btn') ? String(document.getElementById('create-gist-share-btn').textContent || '').trim() : '',
           backgroundStatus: document.getElementById('background-status') ? String(document.getElementById('background-status').textContent || '') : '',
           href: String(window.location.href || ''),
           highlighted,
@@ -783,15 +784,16 @@ async function main() {
         return {
           url,
           length: url.length,
-          threshold: window.__eyelingPlaygroundShareUrlShortenerThreshold,
-          needsShortener: window.__eyelingPlaygroundShouldOfferShortener(url),
-          shortenerUrl: window.__eyelingPlaygroundMakeShareUrlShortenerUrl(url),
+          threshold: window.__eyelingPlaygroundGistShareThreshold,
+          needsGistShare: window.__eyelingPlaygroundShouldOfferGistShare(url),
+          hasEmbeddedState: window.__eyelingPlaygroundShareUrlHasEmbeddedState(url),
+          stateUrlShare: window.__eyelingPlaygroundMakeShareUrlFromStateUrl('https://gist.githubusercontent.com/user/id/raw/eyeling-playground-state.json'),
         };
       })()`);
     }
 
-    async function createTinyUrlWithStubInPage(longUrl, token, response) {
-      const payload = JSON.stringify({ longUrl: String(longUrl), token: String(token), response });
+    async function createGistBackedShareUrlWithStubInPage(token, response) {
+      const payload = JSON.stringify({ token: String(token), response });
       return await evalInPage(`(async () => {
         const args = ${payload};
         const originalFetch = window.fetch;
@@ -816,8 +818,15 @@ async function main() {
           };
         };
         try {
-          const tinyUrl = await window.__eyelingPlaygroundCreateTinyUrl(args.longUrl, args.token);
-          return { tinyUrl, seen };
+          const state = {
+            edit: (window.__cmStubsById && window.__cmStubsById['n3-editor']) ? window.__cmStubsById['n3-editor'].getValue() : '',
+            url: '',
+            loadbg: false,
+            proofcomments: false,
+            httpsderef: true,
+          };
+          const shareUrl = await window.__eyelingPlaygroundCreateGistBackedShareUrl(state, args.token);
+          return { shareUrl, seen };
         } finally {
           window.fetch = originalFetch;
         }
@@ -864,6 +873,11 @@ ${JSON.stringify(last, null, 2)}`);
     const outputStringProgram = `@prefix : <#> .
 @prefix log: <http://www.w3.org/2000/10/swap/log#> .
 :report log:outputString "## Hello from output string\n\nLine 2 with **bold** and [Eyeling](https://example.org/eyeling)\n" .
+`;
+    const baseOnlyMarkdownProgram = `@base <https://raw.githubusercontent.com/eyereasoner/eyeling/refs/heads/main/examples/smoke-arithmetic.n3> .
+@prefix : <#> .
+@prefix log: <http://www.w3.org/2000/10/swap/log#> .
+:report log:outputString "# stateurl link base\n\n[N3 rules](../smoke-arithmetic.n3)\n[Input TriG](../input/smoke-arithmetic.trig)\n" .
 `;
     const logQueryTurtleProgram = `@prefix : <#> .
 @prefix log: <http://www.w3.org/2000/10/swap/log#> .
@@ -963,18 +977,46 @@ ${JSON.stringify(last, null, 2)}`);
     assert.equal(renderedAgain.renderedTabSelected, true, 'Expected Rendered tab to be selectable again');
     endTest();
 
-    // 5) Normal editing should not keep rewriting the browser URL with raw N3 content.
+    // 5) Shared state files may only restore editor text. If that text came from a repository
+    // example, the injected @base line should still give Markdown links the static output-page base.
+    beginTest('playground resolves Markdown links from restored example base directives');
+    await setProgram(baseOnlyMarkdownProgram);
+    await clickRun();
+    const baseOnlyMarkdown = await waitForState(
+      'base-only Markdown output completion',
+      (st) =>
+        String(st.status || '')
+          .trim()
+          .startsWith('Done') && /stateurl link base/i.test(String(st.output || '')),
+      20000,
+    );
+    assert.match(
+      baseOnlyMarkdown.renderedHtml,
+      new RegExp('href="' + started.baseUrl.replace(/[.*+?^${}()|[\]\\]/g, '\\$&') + '/examples/smoke-arithmetic\\.n3"'),
+      'Expected restored-state Markdown source links to resolve against the static output page',
+    );
+    assert.match(
+      baseOnlyMarkdown.renderedHtml,
+      new RegExp('href="' + started.baseUrl.replace(/[.*+?^${}()|[\]\\]/g, '\\$&') + '/examples/input/smoke-arithmetic\\.trig"'),
+      'Expected restored-state Markdown TriG links to resolve against the static output page',
+    );
+    endTest();
+
+    // 6) 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');
+    await setProgram(outputStringProgram);
+    const compactShareState = await getPlaygroundState();
+    assert.doesNotMatch(compactShareState.href, /[?&](?:edit|program)=/, 'Expected live URL to avoid raw editor content');
     const compactShareUrl = await makeShareUrlInPage();
+    const rawEditorUrlLength = playgroundUrl.length + '?edit='.length + encodeURIComponent(outputStringProgram).length;
     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');
-    assert.equal(renderedAgain.shortenerHidden, true, 'Expected ordinary compact share links to keep the shortener option hidden');
+    assert.ok(compactShareUrl.length < rawEditorUrlLength, 'Expected compact share URL to be shorter than raw editor URL');
+    assert.equal(compactShareState.gistShareHidden, true, 'Expected ordinary compact share links to keep the Gist share option hidden');
     endTest();
 
-    // 6) Very large edited programs should offer a URL shortener handoff instead of only a huge link.
-    beginTest('playground offers a URL shortener option for oversized share links');
+    // 7) Very large edited programs should offer a Gist-backed share option instead of only a huge link.
+    beginTest('playground offers a Gist-backed option for oversized state links');
     const longShareProgram = Array.from({ length: 1400 }, (_, i) => {
       const n = String(i).padStart(4, '0');
       const token = ((i * 2654435761) >>> 0).toString(36).padStart(7, '0');
@@ -983,21 +1025,30 @@ ${JSON.stringify(last, null, 2)}`);
     await setProgram(longShareProgram);
     const longShare = await makeShareUrlDiagnosticsInPage();
     assert.ok(longShare.length > longShare.threshold, `Expected test share URL to exceed threshold (${longShare.length} <= ${longShare.threshold})`);
-    assert.equal(longShare.needsShortener, true, 'Expected oversized share URL to request a shortener option');
-    assert.equal(longShare.shortenerUrl, 'https://tinyurl.com/app', 'Expected TinyURL app fallback handoff to avoid embedding the huge URL');
-    assert.equal(longShare.shortenerUrl.includes(encodeURIComponent(longShare.url).slice(0, 40)), false, 'Expected shortener fallback URL not to carry the generated share URL');
-    const tinyUrlCreated = await createTinyUrlWithStubInPage(longShare.url, 'test-token-123', {
-      data: { tiny_url: 'https://tinyurl.com/eyeling-test' },
+    assert.equal(longShare.needsGistShare, true, 'Expected oversized embedded state to request a Gist-backed sharing option');
+    assert.equal(longShare.hasEmbeddedState, true, 'Expected oversized edited program to be an embedded state link');
+    assert.match(longShare.stateUrlShare, /[?&]stateurl=/, 'Expected stateurl= links to be supported for externally stored state');
+    assert.doesNotMatch(longShare.stateUrlShare, /[?&]state=/, 'Expected externally stored state links to avoid embedded state payloads');
+    const gistShare = await createGistBackedShareUrlWithStubInPage('github-gist-token-123', {
+      files: {
+        'eyeling-playground-state.json': {
+          raw_url: 'https://gist.githubusercontent.com/user/id/raw/eyeling-playground-state.json',
+        },
+      },
     });
-    assert.equal(tinyUrlCreated.tinyUrl, 'https://tinyurl.com/eyeling-test', 'Expected TinyURL API response to produce a short URL');
-    assert.equal(tinyUrlCreated.seen.url, 'https://api.tinyurl.com/create', 'Expected TinyURL API create endpoint');
-    assert.equal(tinyUrlCreated.seen.options.method, 'POST', 'Expected TinyURL API POST request');
-    assert.equal(tinyUrlCreated.seen.options.headers.Authorization, 'Bearer test-token-123', 'Expected bearer token authorization');
-    assert.equal(tinyUrlCreated.seen.options.referrerPolicy, 'no-referrer', 'Expected TinyURL API request not to send a long Referer');
-    assert.match(String(tinyUrlCreated.seen.options.body || ''), /"url":/, 'Expected TinyURL API body to include the long URL');
+    assert.match(gistShare.shareUrl, /[?&]stateurl=/, 'Expected Gist-backed share URL to use a compact stateurl parameter');
+    assert.doesNotMatch(gistShare.shareUrl, /[?&]state=/, 'Expected Gist-backed share URL not to embed the compressed state');
+    assert.ok(gistShare.shareUrl.length < 300, 'Expected Gist-backed share URL to stay small');
+    assert.equal(gistShare.seen.url, 'https://api.github.com/gists', 'Expected GitHub Gist create endpoint');
+    assert.equal(gistShare.seen.options.method, 'POST', 'Expected GitHub Gist API POST request');
+    assert.equal(gistShare.seen.options.headers.Authorization, 'Bearer github-gist-token-123', 'Expected bearer token authorization');
+    assert.equal(gistShare.seen.options.referrerPolicy, 'no-referrer', 'Expected GitHub Gist API request not to send a long Referer');
+    assert.match(String(gistShare.seen.options.body || ''), /"public":false/, 'Expected a secret Gist, not a public Gist');
+    assert.match(String(gistShare.seen.options.body || ''), /eyeling-playground-state\.json/, 'Expected shared state to be saved as JSON');
+    assert.match(String(gistShare.seen.options.body || ''), /\\"e\\":/, 'Expected compact editor state in the Gist payload');
     endTest();
 
-    // 7) log:query can produce Turtle; that should stay in plain source output without Markdown tabs.
+    // 8) log:query can produce Turtle; that should stay in plain source output without Markdown tabs.
     beginTest('playground hides markdown tabs for Turtle log:query output');
     await setProgram(logQueryTurtleProgram);
     await clickRun();
@@ -1017,7 +1068,7 @@ ${JSON.stringify(last, null, 2)}`);
     assert.equal(logQueryTurtle.sourceHidden, false, 'Expected Turtle log:query output to show source directly');
     endTest();
 
-    // 8) URL-loaded examples should auto-load matching examples/input/<stem>.trig and run in RDF/TriG mode.
+    // 9) 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('https://raw.githubusercontent.com/eyereasoner/eyeling/refs/heads/main/examples/smoke-arithmetic.n3');
     const smokeLoaded = await waitForState(
@@ -1064,7 +1115,7 @@ ${JSON.stringify(last, null, 2)}`);
     assert.equal(smokeRenderedAgain.sourceHidden, true, 'Expected smoke-arithmetic source editor to hide again');
     endTest();
 
-    // 9) URL-loaded repository examples should auto-load matching examples/builtin/<stem>.js.
+    // 10) 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(