eyeling 1.24.23 → 1.24.25

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
 

package/dist/browser/eyeling.browser.js

@@ -1691,15 +1691,85 @@ function __listElemsForBuiltin(listLike, facts) {
   return null;
 }
 
-function evalListFirstLikeBuiltin(sTerm, oTerm, subst) {
-  if (!(sTerm instanceof ListTerm)) return [];
-  if (!sTerm.elems.length) return [];
-  const first = sTerm.elems[0];
-  const s2 = unifyTerm(oTerm, first, subst);
-  return s2 !== null ? [s2] : [];
+function __pushBuiltinDeltaLimited(out, delta, maxResults) {
+  if (delta === null) return false;
+  out.push(delta);
+  return typeof maxResults === 'number' && maxResults > 0 && out.length >= maxResults;
 }
 
-function evalListRestLikeBuiltin(sTerm, oTerm, subst) {
+function __collectListLikeTermsFromTerm(t, out, seen) {
+  if (t instanceof ListTerm || t instanceof OpenListTerm) {
+    const k = termFastKey ? termFastKey(t) : null;
+    if (k === null || !seen.has(k)) {
+      if (k !== null) seen.add(k);
+      out.push(t);
+    }
+    if (t instanceof ListTerm) {
+      for (const e of t.elems) __collectListLikeTermsFromTerm(e, out, seen);
+    } else {
+      for (const e of t.prefix) __collectListLikeTermsFromTerm(e, out, seen);
+    }
+    return;
+  }
+  if (t instanceof GraphTerm) {
+    for (const tr of t.triples) {
+      __collectListLikeTermsFromTerm(tr.s, out, seen);
+      __collectListLikeTermsFromTerm(tr.p, out, seen);
+      __collectListLikeTermsFromTerm(tr.o, out, seen);
+    }
+  }
+}
+
+function __collectListLikeTermsFromFacts(facts) {
+  const out = [];
+  const seen = new Set();
+  for (const tr of facts) {
+    __collectListLikeTermsFromTerm(tr.s, out, seen);
+    __collectListLikeTermsFromTerm(tr.o, out, seen);
+  }
+  return out;
+}
+
+function evalListFirstLikeBuiltin(sTerm, oTerm, subst, facts, maxResults) {
+  if (sTerm instanceof ListTerm) {
+    if (!sTerm.elems.length) return [];
+    const first = sTerm.elems[0];
+    const s2 = unifyTerm(oTerm, first, subst);
+    return s2 !== null ? [s2] : [];
+  }
+
+  // For a variable subject, enumerate already-existing collection terms.
+  // This lets a rule body such as `_:x rdf:first 1; rdf:rest rdf:nil`
+  // bind `_:x` to an N3 collection literal `(1)` used elsewhere as a term.
+  // Also include ordinary rdf:first facts so the builtin path does not hide
+  // RDF-serialized lists when the subject starts unbound.
+  if (sTerm instanceof Var) {
+    const out = [];
+
+    for (const listTerm of __collectListLikeTermsFromFacts(facts)) {
+      if (!(listTerm instanceof ListTerm) || !listTerm.elems.length) continue;
+      let s2 = unifyTerm(sTerm, listTerm, subst);
+      if (s2 === null) continue;
+      s2 = unifyTerm(oTerm, listTerm.elems[0], s2);
+      if (__pushBuiltinDeltaLimited(out, s2, maxResults)) return out;
+    }
+
+    const RDF_FIRST = RDF_NS + 'first';
+    for (const tr of facts) {
+      if (!(tr.p instanceof Iri) || tr.p.value !== RDF_FIRST) continue;
+      let s2 = unifyTerm(sTerm, tr.s, subst);
+      if (s2 === null) continue;
+      s2 = unifyTerm(oTerm, tr.o, s2);
+      if (__pushBuiltinDeltaLimited(out, s2, maxResults)) return out;
+    }
+
+    return out;
+  }
+
+  return [];
+}
+
+function evalListRestLikeBuiltin(sTerm, oTerm, subst, facts, maxResults) {
   // Closed list: (a b c) -> (b c)
   if (sTerm instanceof ListTerm) {
     if (!sTerm.elems.length) return [];
@@ -1720,6 +1790,32 @@ function evalListRestLikeBuiltin(sTerm, oTerm, subst) {
     return s2 !== null ? [s2] : [];
   }
 
+  // See evalListFirstLikeBuiltin(): if the collection subject is still a
+  // variable, enumerate known list literals and ordinary rdf:rest facts.
+  if (sTerm instanceof Var) {
+    const out = [];
+
+    for (const listTerm of __collectListLikeTermsFromFacts(facts)) {
+      if (!(listTerm instanceof ListTerm) || !listTerm.elems.length) continue;
+      let s2 = unifyTerm(sTerm, listTerm, subst);
+      if (s2 === null) continue;
+      const rest = new ListTerm(listTerm.elems.slice(1));
+      s2 = unifyTerm(oTerm, rest, s2);
+      if (__pushBuiltinDeltaLimited(out, s2, maxResults)) return out;
+    }
+
+    const RDF_REST = RDF_NS + 'rest';
+    for (const tr of facts) {
+      if (!(tr.p instanceof Iri) || tr.p.value !== RDF_REST) continue;
+      let s2 = unifyTerm(sTerm, tr.s, subst);
+      if (s2 === null) continue;
+      s2 = unifyTerm(oTerm, tr.o, s2);
+      if (__pushBuiltinDeltaLimited(out, s2, maxResults)) return out;
+    }
+
+    return out;
+  }
+
   return [];
 }
 
@@ -2859,14 +2955,14 @@ function evalBuiltin(goal, subst, facts, backRules, depth, varGen, maxResults) {
     return s2 !== null ? [s2] : [];
   }
   if (pv === RDF_NS + 'first') {
-    return evalListFirstLikeBuiltin(g.s, g.o, subst);
+    return evalListFirstLikeBuiltin(g.s, g.o, subst, facts, maxResults);
   }
 
   // list:rest and rdf:rest
   // true iff $s is a (non-empty) list and $o is the rest (tail) of that list.
   // Schema: $s+ list:rest $o-
   if (pv === LIST_NS + 'rest') {
-    if (g.s instanceof ListTerm || g.s instanceof OpenListTerm) return evalListRestLikeBuiltin(g.s, g.o, subst);
+    if (g.s instanceof ListTerm || g.s instanceof OpenListTerm) return evalListRestLikeBuiltin(g.s, g.o, subst, facts, maxResults);
     const xs = __listElemsForBuiltin(g.s, facts);
     if (!xs || !xs.length) return [];
     const rest = new ListTerm(xs.slice(1));
@@ -2874,7 +2970,7 @@ function evalBuiltin(goal, subst, facts, backRules, depth, varGen, maxResults) {
     return s2 !== null ? [s2] : [];
   }
   if (pv === RDF_NS + 'rest') {
-    return evalListRestLikeBuiltin(g.s, g.o, subst);
+    return evalListRestLikeBuiltin(g.s, g.o, subst, facts, maxResults);
   }
 
   // list:iterate
@@ -7918,7 +8014,10 @@ function proveGoals(goals, subst, facts, backRules, depth, visited, varGen, maxR
     const isRdfFirstOrRest = goalPredicateIri === RDF_NS + 'first' || goalPredicateIri === RDF_NS + 'rest';
     const shouldTreatAsBuiltin =
       isBuiltinPred(goal0.p) &&
-      !(isRdfFirstOrRest && !(goal0.s instanceof ListTerm || goal0.s instanceof OpenListTerm));
+      !(
+        isRdfFirstOrRest &&
+        !(goal0.s instanceof ListTerm || goal0.s instanceof OpenListTerm || goal0.s instanceof Var)
+      );
 
     if (shouldTreatAsBuiltin) {
       const remaining = max - results.length;
@@ -11703,14 +11802,142 @@ const STRING_NS = 'http://www.w3.org/2000/10/swap/string#';
 const SKOLEM_NS = 'https://eyereasoner.github.io/.well-known/genid/';
 const RDF_JSON_DT = RDF_NS + 'JSON';
 
+function parseUriReferenceForResolution(uri) {
+  // RFC 3986 Appendix B-style component parser, with the scheme tightened to
+  // the RFC scheme grammar. Capturing delimiter presence matters: `?` with an
+  // empty query is defined, while no `?` means undefined.
+  const m = /^(([A-Za-z][A-Za-z0-9+.-]*):)?(\/\/([^/?#]*))?([^?#]*)(\?([^#]*))?(#(.*))?$/u.exec(String(uri));
+  if (!m) return null;
+  return {
+    scheme: m[2] !== undefined ? m[2] : undefined,
+    authority: m[4] !== undefined ? m[4] : undefined,
+    path: m[5] || '',
+    query: m[6] !== undefined ? (m[7] || '') : undefined,
+    fragment: m[8] !== undefined ? (m[9] || '') : undefined,
+  };
+}
+
+function recomposeUriReference(parts) {
+  let out = '';
+  if (parts.scheme !== undefined) out += `${parts.scheme}:`;
+  if (parts.authority !== undefined) out += `//${parts.authority}`;
+  out += parts.path || '';
+  if (parts.query !== undefined) out += `?${parts.query}`;
+  if (parts.fragment !== undefined) out += `#${parts.fragment}`;
+  return out;
+}
+
+function removeLastPathSegment(path) {
+  if (!path) return '';
+  const i = path.lastIndexOf('/');
+  if (i < 0) return '';
+  if (i === 0) return '';
+  return path.slice(0, i);
+}
+
+function removeDotSegments(path) {
+  // RFC 3986 section 5.2.4.  This deliberately avoids WHATWG URL parsing so
+  // Eyeling preserves IRI spelling (for example, it does not add a trailing
+  // slash to `http://example.org`) while still normalizing `.` and `..` path
+  // segments as required by section 5.2.2.
+  let input = String(path || '');
+  let output = '';
+
+  while (input.length > 0) {
+    if (input.startsWith('../')) {
+      input = input.slice(3);
+    } else if (input.startsWith('./')) {
+      input = input.slice(2);
+    } else if (input.startsWith('/./')) {
+      input = `/${input.slice(3)}`;
+    } else if (input === '/.') {
+      input = '/';
+    } else if (input.startsWith('/../')) {
+      input = `/${input.slice(4)}`;
+      output = removeLastPathSegment(output);
+    } else if (input === '/..') {
+      input = '/';
+      output = removeLastPathSegment(output);
+    } else if (input === '.' || input === '..') {
+      input = '';
+    } else {
+      let segmentEnd;
+      if (input[0] === '/') {
+        segmentEnd = input.indexOf('/', 1);
+      } else {
+        segmentEnd = input.indexOf('/');
+      }
+
+      if (segmentEnd < 0) {
+        output += input;
+        input = '';
+      } else {
+        output += input.slice(0, segmentEnd);
+        input = input.slice(segmentEnd);
+      }
+    }
+  }
+
+  return output;
+}
+
+function mergePaths(base, refPath) {
+  if (base.authority !== undefined && base.path === '') {
+    return `/${refPath}`;
+  }
+  const i = base.path.lastIndexOf('/');
+  if (i < 0) return refPath;
+  return `${base.path.slice(0, i + 1)}${refPath}`;
+}
+
 function resolveIriRef(ref, base) {
-  if (!base) return ref;
-  if (/^[A-Za-z][A-Za-z0-9+.-]*:/.test(ref)) return ref; // already absolute
-  try {
-    return new URL(ref, base).toString();
-  } catch {
-    return ref;
+  const r = parseUriReferenceForResolution(ref);
+  if (!r) return ref;
+
+  const baseParts = base ? parseUriReferenceForResolution(base) : null;
+
+  // Absolute references do not need a base, but RFC 3986 section 5.2.2 still
+  // applies remove_dot_segments(R.path) when R.scheme is defined.
+  if (r.scheme !== undefined) {
+    return recomposeUriReference({
+      scheme: r.scheme,
+      authority: r.authority,
+      path: removeDotSegments(r.path),
+      query: r.query,
+      fragment: r.fragment,
+    });
   }
+
+  // Without a usable base, preserve relative references as written.
+  if (!baseParts || baseParts.scheme === undefined) return ref;
+
+  const t = {
+    scheme: baseParts.scheme,
+    authority: undefined,
+    path: '',
+    query: undefined,
+    fragment: r.fragment,
+  };
+
+  if (r.authority !== undefined) {
+    t.authority = r.authority;
+    t.path = removeDotSegments(r.path);
+    t.query = r.query;
+  } else if (r.path === '') {
+    t.authority = baseParts.authority;
+    t.path = baseParts.path;
+    t.query = r.query !== undefined ? r.query : baseParts.query;
+  } else {
+    t.authority = baseParts.authority;
+    if (r.path.startsWith('/')) {
+      t.path = removeDotSegments(r.path);
+    } else {
+      t.path = removeDotSegments(mergePaths(baseParts, r.path));
+    }
+    t.query = r.query;
+  }
+
+  return recomposeUriReference(t);
 }
 
 // -----------------------------------------------------------------------------

package/eyeling.js

@@ -1691,15 +1691,85 @@ function __listElemsForBuiltin(listLike, facts) {
   return null;
 }
 
-function evalListFirstLikeBuiltin(sTerm, oTerm, subst) {
-  if (!(sTerm instanceof ListTerm)) return [];
-  if (!sTerm.elems.length) return [];
-  const first = sTerm.elems[0];
-  const s2 = unifyTerm(oTerm, first, subst);
-  return s2 !== null ? [s2] : [];
+function __pushBuiltinDeltaLimited(out, delta, maxResults) {
+  if (delta === null) return false;
+  out.push(delta);
+  return typeof maxResults === 'number' && maxResults > 0 && out.length >= maxResults;
 }
 
-function evalListRestLikeBuiltin(sTerm, oTerm, subst) {
+function __collectListLikeTermsFromTerm(t, out, seen) {
+  if (t instanceof ListTerm || t instanceof OpenListTerm) {
+    const k = termFastKey ? termFastKey(t) : null;
+    if (k === null || !seen.has(k)) {
+      if (k !== null) seen.add(k);
+      out.push(t);
+    }
+    if (t instanceof ListTerm) {
+      for (const e of t.elems) __collectListLikeTermsFromTerm(e, out, seen);
+    } else {
+      for (const e of t.prefix) __collectListLikeTermsFromTerm(e, out, seen);
+    }
+    return;
+  }
+  if (t instanceof GraphTerm) {
+    for (const tr of t.triples) {
+      __collectListLikeTermsFromTerm(tr.s, out, seen);
+      __collectListLikeTermsFromTerm(tr.p, out, seen);
+      __collectListLikeTermsFromTerm(tr.o, out, seen);
+    }
+  }
+}
+
+function __collectListLikeTermsFromFacts(facts) {
+  const out = [];
+  const seen = new Set();
+  for (const tr of facts) {
+    __collectListLikeTermsFromTerm(tr.s, out, seen);
+    __collectListLikeTermsFromTerm(tr.o, out, seen);
+  }
+  return out;
+}
+
+function evalListFirstLikeBuiltin(sTerm, oTerm, subst, facts, maxResults) {
+  if (sTerm instanceof ListTerm) {
+    if (!sTerm.elems.length) return [];
+    const first = sTerm.elems[0];
+    const s2 = unifyTerm(oTerm, first, subst);
+    return s2 !== null ? [s2] : [];
+  }
+
+  // For a variable subject, enumerate already-existing collection terms.
+  // This lets a rule body such as `_:x rdf:first 1; rdf:rest rdf:nil`
+  // bind `_:x` to an N3 collection literal `(1)` used elsewhere as a term.
+  // Also include ordinary rdf:first facts so the builtin path does not hide
+  // RDF-serialized lists when the subject starts unbound.
+  if (sTerm instanceof Var) {
+    const out = [];
+
+    for (const listTerm of __collectListLikeTermsFromFacts(facts)) {
+      if (!(listTerm instanceof ListTerm) || !listTerm.elems.length) continue;
+      let s2 = unifyTerm(sTerm, listTerm, subst);
+      if (s2 === null) continue;
+      s2 = unifyTerm(oTerm, listTerm.elems[0], s2);
+      if (__pushBuiltinDeltaLimited(out, s2, maxResults)) return out;
+    }
+
+    const RDF_FIRST = RDF_NS + 'first';
+    for (const tr of facts) {
+      if (!(tr.p instanceof Iri) || tr.p.value !== RDF_FIRST) continue;
+      let s2 = unifyTerm(sTerm, tr.s, subst);
+      if (s2 === null) continue;
+      s2 = unifyTerm(oTerm, tr.o, s2);
+      if (__pushBuiltinDeltaLimited(out, s2, maxResults)) return out;
+    }
+
+    return out;
+  }
+
+  return [];
+}
+
+function evalListRestLikeBuiltin(sTerm, oTerm, subst, facts, maxResults) {
   // Closed list: (a b c) -> (b c)
   if (sTerm instanceof ListTerm) {
     if (!sTerm.elems.length) return [];
@@ -1720,6 +1790,32 @@ function evalListRestLikeBuiltin(sTerm, oTerm, subst) {
     return s2 !== null ? [s2] : [];
   }
 
+  // See evalListFirstLikeBuiltin(): if the collection subject is still a
+  // variable, enumerate known list literals and ordinary rdf:rest facts.
+  if (sTerm instanceof Var) {
+    const out = [];
+
+    for (const listTerm of __collectListLikeTermsFromFacts(facts)) {
+      if (!(listTerm instanceof ListTerm) || !listTerm.elems.length) continue;
+      let s2 = unifyTerm(sTerm, listTerm, subst);
+      if (s2 === null) continue;
+      const rest = new ListTerm(listTerm.elems.slice(1));
+      s2 = unifyTerm(oTerm, rest, s2);
+      if (__pushBuiltinDeltaLimited(out, s2, maxResults)) return out;
+    }
+
+    const RDF_REST = RDF_NS + 'rest';
+    for (const tr of facts) {
+      if (!(tr.p instanceof Iri) || tr.p.value !== RDF_REST) continue;
+      let s2 = unifyTerm(sTerm, tr.s, subst);
+      if (s2 === null) continue;
+      s2 = unifyTerm(oTerm, tr.o, s2);
+      if (__pushBuiltinDeltaLimited(out, s2, maxResults)) return out;
+    }
+
+    return out;
+  }
+
   return [];
 }
 
@@ -2859,14 +2955,14 @@ function evalBuiltin(goal, subst, facts, backRules, depth, varGen, maxResults) {
     return s2 !== null ? [s2] : [];
   }
   if (pv === RDF_NS + 'first') {
-    return evalListFirstLikeBuiltin(g.s, g.o, subst);
+    return evalListFirstLikeBuiltin(g.s, g.o, subst, facts, maxResults);
   }
 
   // list:rest and rdf:rest
   // true iff $s is a (non-empty) list and $o is the rest (tail) of that list.
   // Schema: $s+ list:rest $o-
   if (pv === LIST_NS + 'rest') {
-    if (g.s instanceof ListTerm || g.s instanceof OpenListTerm) return evalListRestLikeBuiltin(g.s, g.o, subst);
+    if (g.s instanceof ListTerm || g.s instanceof OpenListTerm) return evalListRestLikeBuiltin(g.s, g.o, subst, facts, maxResults);
     const xs = __listElemsForBuiltin(g.s, facts);
     if (!xs || !xs.length) return [];
     const rest = new ListTerm(xs.slice(1));
@@ -2874,7 +2970,7 @@ function evalBuiltin(goal, subst, facts, backRules, depth, varGen, maxResults) {
     return s2 !== null ? [s2] : [];
   }
   if (pv === RDF_NS + 'rest') {
-    return evalListRestLikeBuiltin(g.s, g.o, subst);
+    return evalListRestLikeBuiltin(g.s, g.o, subst, facts, maxResults);
   }
 
   // list:iterate
@@ -7918,7 +8014,10 @@ function proveGoals(goals, subst, facts, backRules, depth, visited, varGen, maxR
     const isRdfFirstOrRest = goalPredicateIri === RDF_NS + 'first' || goalPredicateIri === RDF_NS + 'rest';
     const shouldTreatAsBuiltin =
       isBuiltinPred(goal0.p) &&
-      !(isRdfFirstOrRest && !(goal0.s instanceof ListTerm || goal0.s instanceof OpenListTerm));
+      !(
+        isRdfFirstOrRest &&
+        !(goal0.s instanceof ListTerm || goal0.s instanceof OpenListTerm || goal0.s instanceof Var)
+      );
 
     if (shouldTreatAsBuiltin) {
       const remaining = max - results.length;
@@ -11703,14 +11802,142 @@ const STRING_NS = 'http://www.w3.org/2000/10/swap/string#';
 const SKOLEM_NS = 'https://eyereasoner.github.io/.well-known/genid/';
 const RDF_JSON_DT = RDF_NS + 'JSON';
 
+function parseUriReferenceForResolution(uri) {
+  // RFC 3986 Appendix B-style component parser, with the scheme tightened to
+  // the RFC scheme grammar. Capturing delimiter presence matters: `?` with an
+  // empty query is defined, while no `?` means undefined.
+  const m = /^(([A-Za-z][A-Za-z0-9+.-]*):)?(\/\/([^/?#]*))?([^?#]*)(\?([^#]*))?(#(.*))?$/u.exec(String(uri));
+  if (!m) return null;
+  return {
+    scheme: m[2] !== undefined ? m[2] : undefined,
+    authority: m[4] !== undefined ? m[4] : undefined,
+    path: m[5] || '',
+    query: m[6] !== undefined ? (m[7] || '') : undefined,
+    fragment: m[8] !== undefined ? (m[9] || '') : undefined,
+  };
+}
+
+function recomposeUriReference(parts) {
+  let out = '';
+  if (parts.scheme !== undefined) out += `${parts.scheme}:`;
+  if (parts.authority !== undefined) out += `//${parts.authority}`;
+  out += parts.path || '';
+  if (parts.query !== undefined) out += `?${parts.query}`;
+  if (parts.fragment !== undefined) out += `#${parts.fragment}`;
+  return out;
+}
+
+function removeLastPathSegment(path) {
+  if (!path) return '';
+  const i = path.lastIndexOf('/');
+  if (i < 0) return '';
+  if (i === 0) return '';
+  return path.slice(0, i);
+}
+
+function removeDotSegments(path) {
+  // RFC 3986 section 5.2.4.  This deliberately avoids WHATWG URL parsing so
+  // Eyeling preserves IRI spelling (for example, it does not add a trailing
+  // slash to `http://example.org`) while still normalizing `.` and `..` path
+  // segments as required by section 5.2.2.
+  let input = String(path || '');
+  let output = '';
+
+  while (input.length > 0) {
+    if (input.startsWith('../')) {
+      input = input.slice(3);
+    } else if (input.startsWith('./')) {
+      input = input.slice(2);
+    } else if (input.startsWith('/./')) {
+      input = `/${input.slice(3)}`;
+    } else if (input === '/.') {
+      input = '/';
+    } else if (input.startsWith('/../')) {
+      input = `/${input.slice(4)}`;
+      output = removeLastPathSegment(output);
+    } else if (input === '/..') {
+      input = '/';
+      output = removeLastPathSegment(output);
+    } else if (input === '.' || input === '..') {
+      input = '';
+    } else {
+      let segmentEnd;
+      if (input[0] === '/') {
+        segmentEnd = input.indexOf('/', 1);
+      } else {
+        segmentEnd = input.indexOf('/');
+      }
+
+      if (segmentEnd < 0) {
+        output += input;
+        input = '';
+      } else {
+        output += input.slice(0, segmentEnd);
+        input = input.slice(segmentEnd);
+      }
+    }
+  }
+
+  return output;
+}
+
+function mergePaths(base, refPath) {
+  if (base.authority !== undefined && base.path === '') {
+    return `/${refPath}`;
+  }
+  const i = base.path.lastIndexOf('/');
+  if (i < 0) return refPath;
+  return `${base.path.slice(0, i + 1)}${refPath}`;
+}
+
 function resolveIriRef(ref, base) {
-  if (!base) return ref;
-  if (/^[A-Za-z][A-Za-z0-9+.-]*:/.test(ref)) return ref; // already absolute
-  try {
-    return new URL(ref, base).toString();
-  } catch {
-    return ref;
+  const r = parseUriReferenceForResolution(ref);
+  if (!r) return ref;
+
+  const baseParts = base ? parseUriReferenceForResolution(base) : null;
+
+  // Absolute references do not need a base, but RFC 3986 section 5.2.2 still
+  // applies remove_dot_segments(R.path) when R.scheme is defined.
+  if (r.scheme !== undefined) {
+    return recomposeUriReference({
+      scheme: r.scheme,
+      authority: r.authority,
+      path: removeDotSegments(r.path),
+      query: r.query,
+      fragment: r.fragment,
+    });
   }
+
+  // Without a usable base, preserve relative references as written.
+  if (!baseParts || baseParts.scheme === undefined) return ref;
+
+  const t = {
+    scheme: baseParts.scheme,
+    authority: undefined,
+    path: '',
+    query: undefined,
+    fragment: r.fragment,
+  };
+
+  if (r.authority !== undefined) {
+    t.authority = r.authority;
+    t.path = removeDotSegments(r.path);
+    t.query = r.query;
+  } else if (r.path === '') {
+    t.authority = baseParts.authority;
+    t.path = baseParts.path;
+    t.query = r.query !== undefined ? r.query : baseParts.query;
+  } else {
+    t.authority = baseParts.authority;
+    if (r.path.startsWith('/')) {
+      t.path = removeDotSegments(r.path);
+    } else {
+      t.path = removeDotSegments(mergePaths(baseParts, r.path));
+    }
+    t.query = r.query;
+  }
+
+  return recomposeUriReference(t);
 }
 
 // -----------------------------------------------------------------------------

package/lib/builtins.js

@@ -1680,15 +1680,85 @@ function __listElemsForBuiltin(listLike, facts) {
   return null;
 }
 
-function evalListFirstLikeBuiltin(sTerm, oTerm, subst) {
-  if (!(sTerm instanceof ListTerm)) return [];
-  if (!sTerm.elems.length) return [];
-  const first = sTerm.elems[0];
-  const s2 = unifyTerm(oTerm, first, subst);
-  return s2 !== null ? [s2] : [];
+function __pushBuiltinDeltaLimited(out, delta, maxResults) {
+  if (delta === null) return false;
+  out.push(delta);
+  return typeof maxResults === 'number' && maxResults > 0 && out.length >= maxResults;
+}
+
+function __collectListLikeTermsFromTerm(t, out, seen) {
+  if (t instanceof ListTerm || t instanceof OpenListTerm) {
+    const k = termFastKey ? termFastKey(t) : null;
+    if (k === null || !seen.has(k)) {
+      if (k !== null) seen.add(k);
+      out.push(t);
+    }
+    if (t instanceof ListTerm) {
+      for (const e of t.elems) __collectListLikeTermsFromTerm(e, out, seen);
+    } else {
+      for (const e of t.prefix) __collectListLikeTermsFromTerm(e, out, seen);
+    }
+    return;
+  }
+  if (t instanceof GraphTerm) {
+    for (const tr of t.triples) {
+      __collectListLikeTermsFromTerm(tr.s, out, seen);
+      __collectListLikeTermsFromTerm(tr.p, out, seen);
+      __collectListLikeTermsFromTerm(tr.o, out, seen);
+    }
+  }
+}
+
+function __collectListLikeTermsFromFacts(facts) {
+  const out = [];
+  const seen = new Set();
+  for (const tr of facts) {
+    __collectListLikeTermsFromTerm(tr.s, out, seen);
+    __collectListLikeTermsFromTerm(tr.o, out, seen);
+  }
+  return out;
+}
+
+function evalListFirstLikeBuiltin(sTerm, oTerm, subst, facts, maxResults) {
+  if (sTerm instanceof ListTerm) {
+    if (!sTerm.elems.length) return [];
+    const first = sTerm.elems[0];
+    const s2 = unifyTerm(oTerm, first, subst);
+    return s2 !== null ? [s2] : [];
+  }
+
+  // For a variable subject, enumerate already-existing collection terms.
+  // This lets a rule body such as `_:x rdf:first 1; rdf:rest rdf:nil`
+  // bind `_:x` to an N3 collection literal `(1)` used elsewhere as a term.
+  // Also include ordinary rdf:first facts so the builtin path does not hide
+  // RDF-serialized lists when the subject starts unbound.
+  if (sTerm instanceof Var) {
+    const out = [];
+
+    for (const listTerm of __collectListLikeTermsFromFacts(facts)) {
+      if (!(listTerm instanceof ListTerm) || !listTerm.elems.length) continue;
+      let s2 = unifyTerm(sTerm, listTerm, subst);
+      if (s2 === null) continue;
+      s2 = unifyTerm(oTerm, listTerm.elems[0], s2);
+      if (__pushBuiltinDeltaLimited(out, s2, maxResults)) return out;
+    }
+
+    const RDF_FIRST = RDF_NS + 'first';
+    for (const tr of facts) {
+      if (!(tr.p instanceof Iri) || tr.p.value !== RDF_FIRST) continue;
+      let s2 = unifyTerm(sTerm, tr.s, subst);
+      if (s2 === null) continue;
+      s2 = unifyTerm(oTerm, tr.o, s2);
+      if (__pushBuiltinDeltaLimited(out, s2, maxResults)) return out;
+    }
+
+    return out;
+  }
+
+  return [];
 }
 
-function evalListRestLikeBuiltin(sTerm, oTerm, subst) {
+function evalListRestLikeBuiltin(sTerm, oTerm, subst, facts, maxResults) {
   // Closed list: (a b c) -> (b c)
   if (sTerm instanceof ListTerm) {
     if (!sTerm.elems.length) return [];
@@ -1709,6 +1779,32 @@ function evalListRestLikeBuiltin(sTerm, oTerm, subst) {
     return s2 !== null ? [s2] : [];
   }
 
+  // See evalListFirstLikeBuiltin(): if the collection subject is still a
+  // variable, enumerate known list literals and ordinary rdf:rest facts.
+  if (sTerm instanceof Var) {
+    const out = [];
+
+    for (const listTerm of __collectListLikeTermsFromFacts(facts)) {
+      if (!(listTerm instanceof ListTerm) || !listTerm.elems.length) continue;
+      let s2 = unifyTerm(sTerm, listTerm, subst);
+      if (s2 === null) continue;
+      const rest = new ListTerm(listTerm.elems.slice(1));
+      s2 = unifyTerm(oTerm, rest, s2);
+      if (__pushBuiltinDeltaLimited(out, s2, maxResults)) return out;
+    }
+
+    const RDF_REST = RDF_NS + 'rest';
+    for (const tr of facts) {
+      if (!(tr.p instanceof Iri) || tr.p.value !== RDF_REST) continue;
+      let s2 = unifyTerm(sTerm, tr.s, subst);
+      if (s2 === null) continue;
+      s2 = unifyTerm(oTerm, tr.o, s2);
+      if (__pushBuiltinDeltaLimited(out, s2, maxResults)) return out;
+    }
+
+    return out;
+  }
+
   return [];
 }
 
@@ -2848,14 +2944,14 @@ function evalBuiltin(goal, subst, facts, backRules, depth, varGen, maxResults) {
     return s2 !== null ? [s2] : [];
   }
   if (pv === RDF_NS + 'first') {
-    return evalListFirstLikeBuiltin(g.s, g.o, subst);
+    return evalListFirstLikeBuiltin(g.s, g.o, subst, facts, maxResults);
   }
 
   // list:rest and rdf:rest
   // true iff $s is a (non-empty) list and $o is the rest (tail) of that list.
   // Schema: $s+ list:rest $o-
   if (pv === LIST_NS + 'rest') {
-    if (g.s instanceof ListTerm || g.s instanceof OpenListTerm) return evalListRestLikeBuiltin(g.s, g.o, subst);
+    if (g.s instanceof ListTerm || g.s instanceof OpenListTerm) return evalListRestLikeBuiltin(g.s, g.o, subst, facts, maxResults);
     const xs = __listElemsForBuiltin(g.s, facts);
     if (!xs || !xs.length) return [];
     const rest = new ListTerm(xs.slice(1));
@@ -2863,7 +2959,7 @@ function evalBuiltin(goal, subst, facts, backRules, depth, varGen, maxResults) {
     return s2 !== null ? [s2] : [];
   }
   if (pv === RDF_NS + 'rest') {
-    return evalListRestLikeBuiltin(g.s, g.o, subst);
+    return evalListRestLikeBuiltin(g.s, g.o, subst, facts, maxResults);
   }
 
   // list:iterate

package/lib/engine.js

@@ -2600,7 +2600,10 @@ function proveGoals(goals, subst, facts, backRules, depth, visited, varGen, maxR
     const isRdfFirstOrRest = goalPredicateIri === RDF_NS + 'first' || goalPredicateIri === RDF_NS + 'rest';
     const shouldTreatAsBuiltin =
       isBuiltinPred(goal0.p) &&
-      !(isRdfFirstOrRest && !(goal0.s instanceof ListTerm || goal0.s instanceof OpenListTerm));
+      !(
+        isRdfFirstOrRest &&
+        !(goal0.s instanceof ListTerm || goal0.s instanceof OpenListTerm || goal0.s instanceof Var)
+      );
 
     if (shouldTreatAsBuiltin) {
       const remaining = max - results.length;

package/lib/prelude.js

@@ -24,14 +24,142 @@ const STRING_NS = 'http://www.w3.org/2000/10/swap/string#';
 const SKOLEM_NS = 'https://eyereasoner.github.io/.well-known/genid/';
 const RDF_JSON_DT = RDF_NS + 'JSON';
 
+function parseUriReferenceForResolution(uri) {
+  // RFC 3986 Appendix B-style component parser, with the scheme tightened to
+  // the RFC scheme grammar. Capturing delimiter presence matters: `?` with an
+  // empty query is defined, while no `?` means undefined.
+  const m = /^(([A-Za-z][A-Za-z0-9+.-]*):)?(\/\/([^/?#]*))?([^?#]*)(\?([^#]*))?(#(.*))?$/u.exec(String(uri));
+  if (!m) return null;
+  return {
+    scheme: m[2] !== undefined ? m[2] : undefined,
+    authority: m[4] !== undefined ? m[4] : undefined,
+    path: m[5] || '',
+    query: m[6] !== undefined ? (m[7] || '') : undefined,
+    fragment: m[8] !== undefined ? (m[9] || '') : undefined,
+  };
+}
+
+function recomposeUriReference(parts) {
+  let out = '';
+  if (parts.scheme !== undefined) out += `${parts.scheme}:`;
+  if (parts.authority !== undefined) out += `//${parts.authority}`;
+  out += parts.path || '';
+  if (parts.query !== undefined) out += `?${parts.query}`;
+  if (parts.fragment !== undefined) out += `#${parts.fragment}`;
+  return out;
+}
+
+function removeLastPathSegment(path) {
+  if (!path) return '';
+  const i = path.lastIndexOf('/');
+  if (i < 0) return '';
+  if (i === 0) return '';
+  return path.slice(0, i);
+}
+
+function removeDotSegments(path) {
+  // RFC 3986 section 5.2.4.  This deliberately avoids WHATWG URL parsing so
+  // Eyeling preserves IRI spelling (for example, it does not add a trailing
+  // slash to `http://example.org`) while still normalizing `.` and `..` path
+  // segments as required by section 5.2.2.
+  let input = String(path || '');
+  let output = '';
+
+  while (input.length > 0) {
+    if (input.startsWith('../')) {
+      input = input.slice(3);
+    } else if (input.startsWith('./')) {
+      input = input.slice(2);
+    } else if (input.startsWith('/./')) {
+      input = `/${input.slice(3)}`;
+    } else if (input === '/.') {
+      input = '/';
+    } else if (input.startsWith('/../')) {
+      input = `/${input.slice(4)}`;
+      output = removeLastPathSegment(output);
+    } else if (input === '/..') {
+      input = '/';
+      output = removeLastPathSegment(output);
+    } else if (input === '.' || input === '..') {
+      input = '';
+    } else {
+      let segmentEnd;
+      if (input[0] === '/') {
+        segmentEnd = input.indexOf('/', 1);
+      } else {
+        segmentEnd = input.indexOf('/');
+      }
+
+      if (segmentEnd < 0) {
+        output += input;
+        input = '';
+      } else {
+        output += input.slice(0, segmentEnd);
+        input = input.slice(segmentEnd);
+      }
+    }
+  }
+
+  return output;
+}
+
+function mergePaths(base, refPath) {
+  if (base.authority !== undefined && base.path === '') {
+    return `/${refPath}`;
+  }
+  const i = base.path.lastIndexOf('/');
+  if (i < 0) return refPath;
+  return `${base.path.slice(0, i + 1)}${refPath}`;
+}
+
 function resolveIriRef(ref, base) {
-  if (!base) return ref;
-  if (/^[A-Za-z][A-Za-z0-9+.-]*:/.test(ref)) return ref; // already absolute
-  try {
-    return new URL(ref, base).toString();
-  } catch {
-    return ref;
+  const r = parseUriReferenceForResolution(ref);
+  if (!r) return ref;
+
+  const baseParts = base ? parseUriReferenceForResolution(base) : null;
+
+  // Absolute references do not need a base, but RFC 3986 section 5.2.2 still
+  // applies remove_dot_segments(R.path) when R.scheme is defined.
+  if (r.scheme !== undefined) {
+    return recomposeUriReference({
+      scheme: r.scheme,
+      authority: r.authority,
+      path: removeDotSegments(r.path),
+      query: r.query,
+      fragment: r.fragment,
+    });
   }
+
+  // Without a usable base, preserve relative references as written.
+  if (!baseParts || baseParts.scheme === undefined) return ref;
+
+  const t = {
+    scheme: baseParts.scheme,
+    authority: undefined,
+    path: '',
+    query: undefined,
+    fragment: r.fragment,
+  };
+
+  if (r.authority !== undefined) {
+    t.authority = r.authority;
+    t.path = removeDotSegments(r.path);
+    t.query = r.query;
+  } else if (r.path === '') {
+    t.authority = baseParts.authority;
+    t.path = baseParts.path;
+    t.query = r.query !== undefined ? r.query : baseParts.query;
+  } else {
+    t.authority = baseParts.authority;
+    if (r.path.startsWith('/')) {
+      t.path = removeDotSegments(r.path);
+    } else {
+      t.path = removeDotSegments(mergePaths(baseParts, r.path));
+    }
+    t.query = r.query;
+  }
+
+  return recomposeUriReference(t);
 }
 
 // -----------------------------------------------------------------------------

package/package.json

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

package/test/api.test.js

@@ -1245,6 +1245,35 @@ ${U('o1')} ${U('path')} (${U('c')} ${U('d')}).
     ],
   },
 
+  {
+    name: '49c rdf:first/rest bind an unbound rule blank to an N3 list literal',
+    opt: { proofComments: false },
+    input: `@prefix : <http://example.org/> .
+
+(1) <http://a.example/p> <http://a.example/o> .
+
+{
+  _:el1 rdf:first 1 .
+  _:el1 rdf:rest rdf:nil .
+  _:el1 <http://a.example/p> <http://a.example/o> .
+}
+=>
+{
+  :result :has :success-literal-25 .
+}.
+
+{ :result :has :success-literal-25 . }
+=>
+{
+  :test :is true .
+}.
+`,
+    expect: [
+      /:result\s+:has\s+:success-literal-25\s*\./,
+      /:test\s+:is\s+true\s*\./,
+    ],
+  },
+
   {
     name: '50 rdf collection materialization: rdf:first/rdf:rest triples become list terms',
     opt: { proofComments: false },

package/test/playground.test.js

@@ -873,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#> .
@@ -972,17 +977,45 @@ ${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.gistShareHidden, true, 'Expected ordinary compact share links to keep the Gist share 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 Gist-backed share option instead of only a huge link.
+    // 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');
@@ -1015,7 +1048,7 @@ ${JSON.stringify(last, null, 2)}`);
     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();
@@ -1035,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(
@@ -1082,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(