wiki-plugin-hitchhiker 0.2.0

package/README.md

@@ -0,0 +1,84 @@
+# wiki-plugin-hitchhiker
+
+The house **UX layer** for the hitchhiker Federated Wiki farms. It rewilds several
+built-in client behaviours *without forking or rebuilding `client.js`*, and ships some
+farm-wide default pages. Piloted on the **private farm (:4243)**.
+
+It has three parts:
+
+## 1. Default pages (`pages/`)
+Files in `pages/` are served on **every** site of the farm (wiki-server's plugin-pages
+fallback), unless a site has authored its own page of that slug. Currently:
+`tools`, `changes-to-this-site` (copied from hitchhikers.earth, journals stripped),
+and `about-hitchhiker-plugin`.
+
+This plugin defines **no authorable item type** (no `factory.json`) — its value is the
+pages and the served client script below.
+
+## 2. Client UX override (`client/wiki-ux.js`)
+Served at `/plugins/hitchhiker/wiki-ux.js` and loaded globally on every page by the
+**`wiki-security-hitchhiker`** bootstrap (a fork of `wiki-security-friends` whose
+`client/security.js` injects `<script src=/plugins/hitchhiker/wiki-ux.js>`; that security
+module is the only client hook that auto-runs on every page). The private farm's
+`config.json` sets `security_type: hitchhiker`.
+
+`wiki-ux.js` reaches the client only through the public `window.wiki` / `window.plugins`
+surface. It installs:
+- **Factory chooser** — replaces `window.plugins.factory.emit` with a searchable, curated,
+  described plugin picker (keeps the original `bind`, so all `drop.js` drag-drops survive);
+  wraps `bind` for extra media-URL drops.
+- **Page-flag click** → an in-lineup page, **inserted** to the right of the clicked page
+  (never wiping the lineup):
+  - logged in → a **Tools** page: **Fork** (only for remote/blue or unsaved/yellow pages),
+    **🔍 Similarity search** (only if `wiki-plugin-similarity` is installed — opens a ghost
+    report of similar pages), **Trash** (→ recycler, recoverable), **Clean the journal**
+    (ghost with a stripped journal), **Simplify** (collapse the lineup to Welcome Visitors +
+    the page).
+  - logged out → a **Navigate** page: Simplify + this site's recent Changes.
+  - **Shift-click** the flag = Simplify directly (skip the page).
+- **Page-flag drop target** — drop a URL / link / page-flag onto a flag: the favicon shows
+  a loud pulsing highlight; on drop it opens a ghost **preview card** (see the server below).
+
+## 3. Server component (`server/server.js`, ESM)
+`GET /system/unfurl.json?url=…` → a normalized **static** link-preview card
+`{ url, title, description, provider, author, type, image, favicon, source }`.
+- oEmbed metadata first (`@extractus/oembed-extractor`), OpenGraph/Twitter/JSON-LD fallback
+  (`open-graph-scraper`). Metadata only — never the oEmbed HTML embed (no live third-party
+  iframes/scripts).
+- The thumbnail is fetched **server-side and inlined as a `data:` URI**, so the card makes
+  zero client→provider requests.
+- **SSRF-guarded**: public `http`/`https` only; private/loopback/link-local ranges and
+  `*.localhost`/`.local`/`.internal` refused before any fetch. 30-min in-memory cache.
+  Never throws — returns a minimal fallback card offline/on error.
+
+> ⚠️ **Private-farm only for now.** Before any public-farm deployment, harden the SSRF guard
+> against redirect-following (the extractor libs do their own fetch and may follow redirects
+> to internal hosts) and tighten image caps.
+
+## Install / build
+```sh
+# Use the farm's Node (v24) — npm under an older node in PATH will fail.
+export PATH="$HOME/.nvm/versions/node/v24.18.0/bin:$PATH"
+cd ~/Code/wiki-plugins/wiki-plugin-hitchhiker
+npm install            # installs open-graph-scraper + @extractus/oembed-extractor
+```
+There is **no build step** — `client/wiki-ux.js` is plain hand-written JS served as-is.
+
+**Operational notes**
+- The `server/` component and its deps must be present or the v24 pages scan can crash on a
+  symlinked dev plugin — **always `npm install` (Node v24) after a fresh clone or after
+  `update-wiki`**.
+- `server.js` is **ESM** (matches `wiki-plugin-similarity`; loads via `import()` on the v24
+  farm). An ESM server silently 404s on older wiki-server that uses `require()` + Node < 22.12
+  — revisit for portability before publishing to an older/public farm.
+- Wired into the farm via `~/bin/wiki-start` (`LOCAL_PLUGINS` symlink + wiki-deps entry).
+  `server.js` registers at startup, so **restart the farm** after changing it.
+- Dev caching: the local wiki-server `staticPathOptions` is patched to `maxAge:0`, and the
+  security bootstrap appends `?v=<ts>` to `wiki-ux.js` on `*.localhost`, so edits appear on a
+  normal reload. `update-wiki` reverts the `maxAge` patch.
+
+## Related
+- `wiki-security-hitchhiker` — the friends-fork that bootstraps `wiki-ux.js` (to be replaced
+  by an own-identity / trust-graph security module).
+- `wiki-plugin-similarity` — sibling plugin whose ESM server pattern this mirrors; also powers
+  the Similarity tool.

package/api/openapi.json

@@ -0,0 +1,125 @@
+{
+  "openapi": "3.1.0",
+  "info": {
+    "title": "Hitchhiker",
+    "version": "0.1.0",
+    "description": "The house UX layer. Two farm-wide services its client needs and nothing else provides: a list of every wiki on this machine, and a link unfurler. Served by this plugin\u2019s own server and described here, not mounted by the farm."
+  },
+  "paths": {
+    "/system/farm-domains.json": {
+      "get": {
+        "x-fedwiki-served-by": "plugin",
+        "x-fedwiki-read-only": true,
+        "operationId": "farmDomains",
+        "summary": "Every wiki on this machine",
+        "description": "Both farms \u2014 the private one this server runs, and the mirrored public tree if there is one \u2014 as two lists of hostnames. Used by the client to offer sites you can reach.",
+        "responses": {
+          "200": {
+            "description": "Local and public domains.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/FarmDomains"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/system/unfurl.json": {
+      "get": {
+        "x-fedwiki-served-by": "plugin",
+        "x-fedwiki-read-only": true,
+        "operationId": "unfurl",
+        "summary": "What is at the other end of a link",
+        "description": "Fetches a URL and returns a card for it \u2014 title, description, provider, thumbnail. Tries oEmbed first, then OpenGraph. Results are cached in memory, and the fetch is guarded against being pointed at private addresses. That guard and that cache are why this stays on the plugin\u2019s own server: a farm handler holds no state between calls and has no policy about what it may fetch.",
+        "parameters": [
+          {
+            "name": "url",
+            "in": "query",
+            "required": true,
+            "description": "The link to unfurl.",
+            "schema": {
+              "type": "string"
+            },
+            "x-fedwiki-example": "https://example.com"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "A card describing the link.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Card"
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "components": {
+    "schemas": {
+      "FarmDomains": {
+        "type": "object",
+        "properties": {
+          "local": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Sites of the farm this server runs."
+          },
+          "public": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Sites of the mirrored public tree, if present."
+          }
+        }
+      },
+      "Card": {
+        "type": "object",
+        "properties": {
+          "url": {
+            "type": "string"
+          },
+          "title": {
+            "type": "string"
+          },
+          "description": {
+            "type": "string"
+          },
+          "provider": {
+            "type": "string"
+          },
+          "author": {
+            "type": "string"
+          },
+          "type": {
+            "type": "string"
+          },
+          "image": {
+            "type": "string",
+            "description": "Inlined as a data URI where small enough."
+          },
+          "favicon": {
+            "type": "string"
+          },
+          "source": {
+            "type": "string",
+            "enum": [
+              "oembed",
+              "opengraph"
+            ],
+            "description": "Which of the two answered."
+          }
+        }
+      }
+    }
+  }
+}

package/client/fish.js

@@ -0,0 +1,101 @@
+// fish.js — parametric Mice & Fish flag generator (Fish Picker v0.2)
+// Pure SVG strings, zero deps. viewBox 0 0 100 100, faces right.
+//   colour/school = topic · species/shape = person
+//   companion = human/AI (hidden < 24px) · markings = individual (variant)
+
+function hashSeed(str){let h=2166136261>>>0;for(const c of String(str)){h^=c.charCodeAt(0);h=Math.imul(h,16777619);}return h>>>0;}
+function rng(seed){let s=(seed>>>0)||1;return()=>{s=(Math.imul(s,1664525)+1013904223)>>>0;return s/4294967296;};}
+
+const SCHOOLS={fab:28,academy:212,environment:130,garden:130,myth:150,democracy:278,liquid:262,secret:194,vision:330,ide:250,fish:200,earth:96};
+function schoolHue(topic){if(!topic)return 208;const k=Object.keys(SCHOOLS).find(k=>String(topic).includes(k));return SCHOOLS[k]??208;}
+
+function baseId(id){return String(id).replace(/-agent$/,'');}
+function speciesFor(id){const b=baseId(id);if(b.startsWith('david'))return 'koi';if(b.startsWith('max'))return 'pufferfish';if(b.startsWith('mitch'))return 'pike';return 'koi';}
+const poly=pts=>pts.map(p=>p.map(n=>n.toFixed(1)).join(',')).join(' ');
+
+// --- companion: human = mouse, agent = robo-mouse. cx,cy = its centre ---
+function companionSVG(isAgent,mx,my,hue){
+  if(isAgent){const t=`hsl(${hue} 30% 55%)`;return `<g stroke="#333" stroke-width="0.7">
+    <rect x="${mx-5}" y="${my-2}" width="3" height="4" fill="${t}"/><rect x="${mx+2}" y="${my-2}" width="3" height="4" fill="${t}"/>
+    <rect x="${mx-5}" y="${my}" width="10" height="7" rx="1.5" fill="${t}"/>
+    <line x1="${mx}" y1="${my-2}" x2="${mx}" y2="${my-6}"/><circle cx="${mx}" cy="${my-6.5}" r="1.1" fill="#e33"/>
+    <circle cx="${mx-1.5}" cy="${my+3}" r="0.9" fill="#111" stroke="none"/><circle cx="${mx+2.5}" cy="${my+3}" r="0.9" fill="#111" stroke="none"/></g>`;}
+  return `<g stroke="#555" stroke-width="0.6">
+    <circle cx="${mx-4}" cy="${my}" r="3" fill="#bfb8b0"/><circle cx="${mx+4}" cy="${my}" r="3" fill="#bfb8b0"/>
+    <ellipse cx="${mx}" cy="${my+3}" rx="6" ry="4.5" fill="#cfc8c0"/>
+    <path d="M ${mx+5} ${my+5} q 6 2 7 -2" fill="none"/>
+    <circle cx="${mx-1.5}" cy="${my+2.5}" r="0.8" fill="#111" stroke="none"/><circle cx="${mx+2.5}" cy="${my+2.5}" r="0.8" fill="#111" stroke="none"/>
+    <circle cx="${mx+0.5}" cy="${my+4.5}" r="0.7" fill="#e88" stroke="none"/></g>`;
+}
+const eye=(x,y,line)=>`<circle cx="${x}" cy="${y}" r="4" fill="#fff" stroke="${line}" stroke-width="0.8"/><circle cx="${x+1}" cy="${y}" r="1.8" fill="#111"/>`;
+
+// --- species renderers: return {behind, body, clip, front, crest:[x,y]} ---
+function koi(cx,cy,c,rand){
+  const rx=29,ry=13.5, tx=cx-rx+2;
+  const tail=`<path d="M ${tx} ${cy} C ${tx-16} ${cy-16} ${tx-22} ${cy-8} ${tx-15} ${cy-1}
+     C ${tx-22} ${cy+8} ${tx-16} ${cy+16} ${tx} ${cy} Z" fill="${c.fin}" stroke="${c.line}" stroke-width="0.8"/>`;
+  const dorsal=`<path d="M ${cx-15} ${cy-ry+2} Q ${cx-1} ${cy-ry-10} ${cx+13} ${cy-ry+3} Z" fill="${c.fin}" stroke="${c.line}" stroke-width="0.8"/>`;
+  const barbels=`<path d="M ${cx+rx-1} ${cy+2} q 4 3 3 6 M ${cx+rx-1} ${cy+3} q 5 1 6 5" fill="none" stroke="${c.line}" stroke-width="0.9" stroke-linecap="round"/>`;
+  const body=`<ellipse cx="${cx}" cy="${cy}" rx="${rx}" ry="${ry}" fill="${c.body}" stroke="${c.line}" stroke-width="1"/>`;
+  return {behind:tail+dorsal, body, clip:`<ellipse cx="${cx}" cy="${cy}" rx="${rx}" ry="${ry}"/>`,
+    front:barbels+`<path d="M ${cx+rx-1} ${cy+3.5} q 4 1 5 -1" fill="none" stroke="${c.line}" stroke-width="1"/>`,
+    eyeAt:[cx+rx*0.55,cy-2], crest:[cx-1,cy-ry-11], koiPatch:true};
+}
+function pufferfish(cx,cy,c,rand){
+  const r=18.5, tx=cx-r+2;
+  let spikes='';const N=15;
+  for(let i=0;i<N;i++){const a=i/N*Math.PI*2,d=0.12;
+    const b1=[cx+Math.cos(a-d)*r,cy+Math.sin(a-d)*r],b2=[cx+Math.cos(a+d)*r,cy+Math.sin(a+d)*r],ap=[cx+Math.cos(a)*(r+5),cy+Math.sin(a)*(r+5)];
+    spikes+=`<polygon points="${poly([b1,ap,b2])}" fill="${c.fin}" stroke="${c.line}" stroke-width="0.4"/>`;}
+  const tail=`<path d="M ${tx} ${cy} q -10 -8 -12 0 q 2 8 12 0 Z" fill="${c.fin}" stroke="${c.line}" stroke-width="0.8"/>`;
+  const body=`<circle cx="${cx}" cy="${cy}" r="${r}" fill="${c.body}" stroke="${c.line}" stroke-width="1"/>`;
+  return {behind:tail+spikes, body, clip:`<circle cx="${cx}" cy="${cy}" r="${r}"/>`,
+    front:`<path d="M ${cx+r-1} ${cy+4} q 3 2 5 0" fill="none" stroke="${c.line}" stroke-width="1"/>`,
+    eyeAt:[cx+r*0.5,cy-3], crest:[cx,cy-r-7]};
+}
+function pike(cx,cy,c,rand){
+  const rx=35,ry=9, snout=cx+rx+3;
+  const body=`<path d="M ${snout} ${cy} C ${cx+rx-4} ${cy-ry} ${cx-rx+8} ${cy-ry} ${cx-rx} ${cy}
+     C ${cx-rx+8} ${cy+ry} ${cx+rx-4} ${cy+ry} ${snout} ${cy} Z" fill="${c.body}" stroke="${c.line}" stroke-width="1"/>`;
+  const tx=cx-rx+2;
+  const tail=`<polygon points="${poly([[tx,cy],[tx-16,cy-13],[tx-8,cy],[tx-16,cy+13]])}" fill="${c.fin}" stroke="${c.line}" stroke-width="0.8"/>`;
+  const dorsal=`<path d="M ${cx-18} ${cy-ry+2} Q ${cx-11} ${cy-ry-7} ${cx-3} ${cy-ry+3} Z" fill="${c.fin}" stroke="${c.line}" stroke-width="0.8"/>`;
+  const anal=`<polygon points="${poly([[cx-16,cy+ry-1],[cx-6,cy+ry-1],[cx-11,cy+ry+7]])}" fill="${c.fin}" stroke="${c.line}" stroke-width="0.7"/>`;
+  return {behind:tail+dorsal+anal, body, clip:`<path d="M ${snout} ${cy} C ${cx+rx-4} ${cy-ry} ${cx-rx+8} ${cy-ry} ${cx-rx} ${cy} C ${cx-rx+8} ${cy+ry} ${cx+rx-4} ${cy+ry} ${snout} ${cy} Z"/>`,
+    front:`<path d="M ${cx+rx-2} ${cy+2.5} q 6 1 9 -1" fill="none" stroke="${c.line}" stroke-width="1"/>`,
+    eyeAt:[cx+rx*0.62,cy-2.5], crest:[cx-4,cy-ry-9]};
+}
+const RENDER={koi,pufferfish,pike};
+
+function fishSVG(id,size=64){
+  const hue=schoolHue(id.topic);
+  const species=id.species||speciesFor(id.id);
+  const rand=rng(hashSeed(`${id.id}|${id.topic}|${id.variant??0}`));
+  const c={body:`hsl(${hue} 62% 56%)`,belly:`hsl(${hue} 58% 74%)`,fin:`hsl(${hue} 66% 44%)`,mark:`hsl(${hue} 60% 37%)`,line:`hsl(${hue} 45% 26%)`};
+  const cx=52,cy=50;
+  const p=(RENDER[species]||koi)(cx,cy,c,rand);
+  const clipId=`b${hashSeed(id.id+id.topic).toString(36)}`;
+
+  // markings — koi big soft patches, others stripes/spots by variant
+  let marks='';
+  if(p.koiPatch){const n=2+Math.floor(rand()*2);for(let i=0;i<n;i++){const x=cx-14+rand()*30,y=cy-9+rand()*14,rr=4+rand()*4;marks+=`<ellipse cx="${x.toFixed(1)}" cy="${y.toFixed(1)}" rx="${rr.toFixed(1)}" ry="${(rr*0.75).toFixed(1)}" fill="${c.mark}" opacity="0.8"/>`;}}
+  else if(rand()<0.5){const n=2+Math.floor(rand()*3);for(let i=0;i<n;i++){const x=cx-20+ (i+0.7)*(40/n);marks+=`<rect x="${x.toFixed(1)}" y="0" width="${(1.5+rand()*1.6).toFixed(1)}" height="100" fill="${c.mark}" opacity="0.8"/>`;}}
+  else{const n=3+Math.floor(rand()*5);for(let i=0;i<n;i++){marks+=`<circle cx="${(cx-18+rand()*36).toFixed(1)}" cy="${(cy-8+rand()*16).toFixed(1)}" r="${(1.1+rand()*1.6).toFixed(1)}" fill="${c.mark}" opacity="0.8"/>`;}}
+
+  const companion=size>=24?companionSVG(id.type==='agent',p.crest[0],p.crest[1],hue):'';
+
+  return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100" width="${size}" height="${size}" shape-rendering="geometricPrecision">
+ <defs><clipPath id="${clipId}">${p.clip}</clipPath></defs>
+ ${p.behind}
+ ${p.body}
+ <ellipse cx="${cx}" cy="${cy+5}" rx="24" ry="6" fill="${c.belly}" opacity="0.85" clip-path="url(#${clipId})"/>
+ <g clip-path="url(#${clipId})">${marks}</g>
+ ${p.front}
+ ${eye(p.eyeAt[0],p.eyeAt[1],c.line)}
+ ${companion}
+</svg>`;
+}
+
+const API = { fishSVG, schoolHue, speciesFor, SCHOOLS };
+if (typeof module !== 'undefined' && module.exports) module.exports = API;
+if (typeof window !== 'undefined') window.FishPicker = API;

package/client/hitchhiker.js

@@ -0,0 +1,128 @@
+/*
+ * hitchhiker.js — the wiki-plugin-hitchhiker ITEM client.
+ *
+ * Unlike wiki-ux.js (injected farm-wide by wiki-security-hitchhiker), this
+ * file loads by the standard plugin route — /plugins/hitchhiker/hitchhiker.js
+ * — whenever a page carries a `hitchhiker` item. That makes it work on any
+ * farm the plugin is installed on, whatever its security plugin.
+ *
+ * First affordance: a thumb-sized FORK button in page content. The 18px ⚑
+ * flag in the journal strip is unusable on a phone; this button triggers the
+ * same native control, so the local/remote/recycler cases and all lineup
+ * bookkeeping stay the wiki-client's business. Forking needs login on the
+ * origin site — the server 403s otherwise and the flag isn't even rendered —
+ * so the button says "log in first" rather than dying silently.
+ *
+ * Item text is the house DSL (UPPERCASE first word = command):
+ *   FORK                    render the fork button
+ *   LABEL Fork this seal    override the button label (optional)
+ */
+;(function () {
+  'use strict'
+
+  var FORK_SVG =
+    '<svg viewBox="0 0 16 16" width="1em" height="1em" fill="currentColor" ' +
+    'style="vertical-align:-0.15em;margin-right:.4em" aria-hidden="true">' +
+    '<path d="M5 5.372v.878c0 .414.336.75.75.75h4.5a.75.75 0 0 0 .75-.75v-.878a2.25 2.25 0 1 1 1.5 0v.878a2.25 ' +
+    '2.25 0 0 1-2.25 2.25h-1.5v2.128a2.251 2.251 0 1 1-1.5 0V8.5h-1.5A2.25 2.25 0 0 1 3.5 6.25v-.878a2.25 2.25 0 1 1 ' +
+    '1.5 0ZM5 3.25a.75.75 0 1 0-1.5 0 .75.75 0 0 0 1.5 0Zm6.75.75a.75.75 0 1 0 0-1.5.75.75 0 0 0 0 1.5Zm-3 ' +
+    '8.75a.75.75 0 1 0-1.5 0 .75.75 0 0 0 1.5 0Z"></path></svg>'
+
+  // Thumb-sized: comfortably past the 44px minimum tap target.
+  var BIG_BTN =
+    'display:block;width:100%;box-sizing:border-box;min-height:48px;' +
+    'font-size:1.1em;padding:12px 16px;cursor:pointer;'
+  var STATUS = 'font-size:0.85em;color:#666;margin:6px 2px 0;'
+
+  var COMMANDS = { FORK: 'fork', LABEL: 'label' }
+
+  var parse = function (text) {
+    var conf = { fork: false, label: '' }
+    var lines = String(text || '').split('\n')
+    for (var i = 0; i < lines.length; i++) {
+      var line = lines[i].trim()
+      if (!line) continue
+      var words = line.split(/\s+/)
+      var key = words[0].replace(/:$/, '').toUpperCase()
+      if (COMMANDS[key] === 'fork') conf.fork = true
+      else if (COMMANDS[key] === 'label') conf.label = words.slice(1).join(' ')
+    }
+    return conf
+  }
+
+  var esc = function (s) {
+    return String(s || '').replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
+  }
+
+  var emit = function ($item, item) {
+    var conf = parse(item.text)
+    var $page = $item.parents('.page:first')
+    // wiki-plugin-hearth marks pages that must not offer forking.
+    if ($page.hasClass('hearth-page')) { $item.append('<div></div>'); return }
+    if (!conf.fork) {
+      $item.append('<p style="' + STATUS + '">hitchhiker item — no FORK command in its text</p>')
+      return
+    }
+    var host = location.host
+    var label = conf.label || 'Fork this page to ' + host
+    $item.append(
+      '<div class="hitchhiker-fork">' +
+        '<button class="hitchhiker-fork-button" style="' + BIG_BTN + '">' +
+        FORK_SVG + esc(label) + '</button>' +
+        '<p class="hitchhiker-fork-status" style="' + STATUS + '"></p>' +
+        '</div>'
+    )
+    var $status = $item.find('.hitchhiker-fork-status')
+    if (window.isAuthenticated !== true) {
+      $status.text('You are not logged in on ' + host + ' — log in first, then this button forks the page to your wiki.')
+    } else if (!$page.hasClass('remote') && !$page.hasClass('local')) {
+      $status.text('This page already lives on ' + host + '.')
+    }
+  }
+
+  var bind = function ($item, item) {
+    $item.on('dblclick', function () { wiki.textEditor($item, item) })
+    $item.find('.hitchhiker-fork-button').on('click', function (e) {
+      e.preventDefault()
+      e.stopPropagation()
+      var $page = $item.parents('.page:first')
+      var $status = $item.find('.hitchhiker-fork-status')
+      if ($page.hasClass('hearth-page')) return
+      var $flag = $page.find('.fork-page')
+      if ($flag.length) {
+        $flag.trigger('click')
+      } else if (window.isAuthenticated !== true) {
+        $status.text('You are not logged in on ' + location.host + ' — log in first, then tap again.')
+        return
+      } else if (/_rev\d+$/.test($page.attr('id') || '')) {
+        $status.text('This is an old revision — open the current page to fork it.')
+        return
+      } else {
+        // Logged in, but the "wiki" edit toggle is off, so the native flag
+        // isn't rendered. Fork directly — the same pageHandler call the flag
+        // makes; the server authorizes by session, not by the toggle.
+        var action = { type: 'fork' }
+        if ($page.hasClass('local')) {
+          $page.removeClass('local')
+        } else {
+          try {
+            var po = wiki.lineup.atKey($page.data('key'))
+            if (po && po.isRemote && po.isRemote()) action.site = po.getRemoteSite()
+          } catch (err) {}
+        }
+        $page.removeClass('ghost')
+        wiki.pageHandler.put($page, action)
+      }
+      $item.find('.hitchhiker-fork-button').prop('disabled', true).css('opacity', 0.6)
+      $status.text('Forked to ' + location.host + ' ✓')
+    })
+  }
+
+  if (typeof window !== 'undefined') {
+    window.plugins = window.plugins || {}
+    window.plugins.hitchhiker = { emit: emit, bind: bind }
+  }
+  if (typeof module !== 'undefined' && module.exports) {
+    module.exports = { parse: parse, emit: emit, bind: bind }
+  }
+})()

package/client/picker.html

@@ -0,0 +1,140 @@
+<!doctype html><html><head><meta charset="utf8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>Fish Picker</title>
+<style>
+ :root{--bg:#f4f2ee;--card:#fff;--line:#e5e1d8;--ink:#222;--mut:#777;--go:#2b6}
+ *{box-sizing:border-box}
+ html,body{margin:0;background:var(--bg);color:var(--ink);font:13.5px/1.4 system-ui,sans-serif}
+ .wrap{padding:12px;max-width:900px;margin:0 auto}
+ header{display:flex;align-items:baseline;justify-content:space-between;gap:8px;margin-bottom:8px}
+ header h1{font-size:15px;margin:0} header a{font-size:12px;color:var(--mut);text-decoration:none;white-space:nowrap}
+ header a:hover{color:var(--ink)}
+ .main{display:grid;grid-template-columns:1fr;gap:12px}
+ @media(min-width:680px){.main{grid-template-columns:300px 1fr}}
+ .card{background:var(--card);border:1px solid var(--line);border-radius:9px;padding:11px 12px}
+ .card h2{font-size:11px;margin:0 0 8px;text-transform:uppercase;letter-spacing:.04em;color:var(--mut)}
+ label{display:block;font-size:11px;color:var(--mut);margin:8px 0 3px}
+ input,select{width:100%;padding:6px 7px;border:1px solid var(--line);border-radius:6px;font:inherit;background:#fbfaf7}
+ .two{display:flex;gap:8px}.two>*{flex:1}
+ .seg{display:flex;border:1px solid var(--line);border-radius:6px;overflow:hidden}
+ .seg button{flex:1;padding:6px;border:0;background:#fbfaf7;cursor:pointer;font:inherit}
+ .seg button.on{background:var(--go);color:#fff}
+ .step{display:flex;align-items:center;gap:8px}.step button{width:28px;height:28px;border:1px solid var(--line);border-radius:6px;background:#fbfaf7;cursor:pointer;font-size:15px}
+ .row{display:flex;gap:12px;align-items:flex-end;flex-wrap:wrap}
+ figure{margin:0;text-align:center} .box{background:#fbfaf7;border:1px solid #eee;border-radius:6px;display:flex;align-items:center;justify-content:center}
+ figcaption{font-size:10px;color:var(--mut);margin-top:3px}
+ .note{color:var(--mut);font-size:11px;margin:6px 0 0}
+ details{margin-top:8px} summary{cursor:pointer;font-size:11px;color:var(--mut)}
+ pre{background:#f6f5f2;border-radius:6px;padding:8px;font-size:11px;max-height:130px;overflow:auto;margin:6px 0 0}
+ .save{display:flex;gap:10px;align-items:center;margin-top:10px}
+ .save button{padding:8px 16px;border:1px solid var(--go);border-radius:7px;background:var(--go);color:#fff;cursor:pointer;font:inherit}
+ #status{font-size:12px;color:var(--mut)}
+</style></head>
+<body><div class="wrap">
+<header><h1>&#128031; Fish Picker</h1><a id="fs" target="_blank" rel="noopener">&#10530; Full screen</a></header>
+<div class="main">
+ <div>
+  <div class="card">
+   <h2>Genome</h2>
+   <label>Domain</label><input id="domain" placeholder="david.fab.fish">
+   <div class="two"><div><label>Species</label><select id="species"></select></div><div><label>School</label><select id="topic"></select></div></div>
+   <label>Type</label><div class="seg"><button data-type="human" class="on">Human</button><button data-type="agent">Agent</button></div>
+   <label>Variant</label><div class="step"><button id="vd">&minus;</button><input id="v" value="0" readonly style="text-align:center"><button id="vu">+</button></div>
+   <label>Petname</label><input id="name" placeholder="David Bovill">
+   <div class="save"><button id="save">Save flag</button><span id="status"></span></div>
+   <p class="note" id="hint">Embed with a frame item · Save writes this site&rsquo;s flag (owner only).</p>
+  </div>
+ </div>
+ <div>
+  <div class="card"><h2>This flag</h2><div class="row" id="lod"></div></div>
+  <div class="card"><h2>Same school &mdash; the Mice</h2><div class="row" id="mice"></div>
+   <h2 style="margin-top:10px">Same person &mdash; other schools</h2><div class="row" id="schools"></div>
+   <details><summary>identity.json</summary><pre id="json"></pre></details>
+  </div>
+ </div>
+</div></div>
+<script src="fish.js"></script>
+<script>
+(function(){
+ var FP = window.FishPicker
+ var $ = function(s){ return document.querySelector(s) }
+ if(!FP){ document.body.innerHTML='<p style="padding:16px">Fish Picker generator failed to load (fish.js).</p>'; return }
+ var SPECIES=['koi','pufferfish','pike'], MICE=['david','max','mitch']
+ var st={ person:'david', species:'koi', topic:'fab', type:'human', variant:3, name:'David Bovill' }
+
+ $('#species').innerHTML = SPECIES.map(function(s){return '<option>'+s+'</option>'}).join('')
+ $('#topic').innerHTML = Object.keys(FP.SCHOOLS).map(function(t){return '<option>'+t+'</option>'}).join('')
+ $('#fs').href = location.href
+
+ function recId(p){ p=p||st.person; return st.type==='agent'? p+'-agent': p }
+ function ident(o){ o=o||{}; return { id:recId(o.person), name:st.name, type:st.type, topic:o.topic||st.topic, species:o.species||st.species, variant:st.variant } }
+ function box(o,size,cap){ return '<figure><div class="box" style="width:'+size+'px;height:'+size+'px">'+FP.fishSVG(o,size)+'</div><figcaption>'+cap+'</figcaption></figure>' }
+
+ function render(){
+  $('#person')&&($('#person').value=st.person)
+  $('#species').value=st.species; $('#topic').value=st.topic; $('#v').value=st.variant; $('#name').value=st.name
+  document.querySelectorAll('.seg button').forEach(function(b){ b.classList.toggle('on', b.dataset.type===st.type) })
+  $('#lod').innerHTML = [16,32,64,128].map(function(s){return box(ident(),s,s+'px')}).join('')
+  $('#mice').innerHTML = MICE.map(function(p){return box(ident({person:p,species:FP.speciesFor(p)}),52,p)}).join('')
+  $('#schools').innerHTML = ['fab','academy','myth'].map(function(t){return box(ident({topic:t}),52,t)}).join('')
+  $('#json').textContent = JSON.stringify({name:st.name,id:recId(),type:st.type,sponsor:st.type==='agent'?st.person:null,topicGroup:st.topic,species:st.species,variant:st.variant,publicKey:null}, null, 1)
+ }
+
+ $('#domain').addEventListener('input', function(e){ var p=e.target.value.split('.').filter(Boolean); if(p[0]){st.person=p[0];st.species=FP.speciesFor(p[0]);st.name=p[0]} var t=p.slice(1).find(function(x){return x in FP.SCHOOLS}); if(t)st.topic=t; render() })
+ $('#name').addEventListener('input', function(e){ st.name=e.target.value; render() })
+ $('#species').addEventListener('change', function(e){ st.species=e.target.value; render() })
+ $('#topic').addEventListener('change', function(e){ st.topic=e.target.value; render() })
+ document.querySelectorAll('.seg button').forEach(function(b){ b.addEventListener('click', function(){ st.type=b.dataset.type; render() }) })
+ $('#vu').addEventListener('click', function(){ st.variant++; render() })
+ $('#vd').addEventListener('click', function(){ st.variant=Math.max(0,st.variant-1); render() })
+ $('#save').addEventListener('click', saveFlag)
+ window.addEventListener('message', function(e){ var d=e.data; if(d&&d.type==='fishpicker:saved'){ status(d.ok?'🐟 saved to the site':('save failed'+(d.status===403?' — owner only':'')), !!d.ok); if(d.ok)bust() } })
+
+ // ---- persistence: POST to fedwiki's owner-gated /favicon.png, identity in a PNG tEXt chunk ----
+ var CRC=(function(){var t=[],c,n,k;for(n=0;n<256;n++){c=n;for(k=0;k<8;k++)c=c&1?0xedb88320^(c>>>1):c>>>1;t[n]=c>>>0}return t})()
+ function crc32(b){var c=0xffffffff;for(var i=0;i<b.length;i++)c=CRC[(c^b[i])&0xff]^(c>>>8);return (c^0xffffffff)>>>0}
+ function u32(n){return[(n>>>24)&255,(n>>>16)&255,(n>>>8)&255,n&255]}
+ function pngInsertText(png,kw,tx){var d=[],i;for(i=0;i<kw.length;i++)d.push(kw.charCodeAt(i)&255);d.push(0);for(i=0;i<tx.length;i++)d.push(tx.charCodeAt(i)&255);var body=[0x74,0x45,0x58,0x74].concat(d);var chunk=u32(d.length).concat(body).concat(u32(crc32(new Uint8Array(body))));var iend=png.length-12,out=new Uint8Array(png.length+chunk.length);out.set(png.subarray(0,iend),0);out.set(new Uint8Array(chunk),iend);out.set(png.subarray(iend),iend+chunk.length);return out}
+ function pngReadText(png,kw){var p=8;while(p+8<=png.length){var len=(png[p]<<24)|(png[p+1]<<16)|(png[p+2]<<8)|png[p+3];var ty=String.fromCharCode(png[p+4],png[p+5],png[p+6],png[p+7]);if(ty==='tEXt'){var s='';for(var i=0;i<len;i++)s+=String.fromCharCode(png[p+8+i]);var z=s.indexOf('\0');if(z!==-1&&s.slice(0,z)===kw)return s.slice(z+1)}if(ty==='IEND')break;p+=12+len}return null}
+ function b64(b){var s='';for(var i=0;i<b.length;i++)s+=String.fromCharCode(b[i]);return btoa(s)}
+ function status(msg,ok){ $('#status').textContent=msg; $('#status').style.color = ok?'#2b6':(ok===false?'#c33':'#777') }
+
+ function saveFlag(){
+  var identity={name:st.name,id:recId(),type:st.type,topicGroup:st.topic,species:st.species,variant:st.variant,publicKey:null}
+  var svg=FP.fishSVG(ident(),128), img=new Image()
+  status('saving…')
+  img.onload=function(){
+   var cv=document.createElement('canvas'); cv.width=cv.height=64; cv.getContext('2d').drawImage(img,0,0,64,64)
+   cv.toBlob(function(blob){ blob.arrayBuffer().then(function(ab){
+    var png=pngInsertText(new Uint8Array(ab),'fishpicker',encodeURIComponent(JSON.stringify(identity)))
+    var dataUri='data:image/png;base64,'+b64(png)
+    if(window.parent && window.parent!==window){
+     // embedded & sandboxed (no session in here) — ask the authenticated page to save.
+     window.parent.postMessage({type:'fishpicker:save', image:dataUri}, '*')
+     status('saving via the page…'); return
+    }
+    fetch('/favicon.png',{method:'POST',credentials:'include',headers:{'Content-Type':'application/json'},body:JSON.stringify({image:dataUri})})
+     .then(function(r){
+       if(r.ok){ status('🐟 saved to '+location.hostname, true); bust() }
+       else if(r.status===403){ status('sign in as the owner to save', false) }
+       else { status('save failed ('+r.status+') — downloaded instead', false); dl(new Blob([png],{type:'image/png'}),'favicon.png') }
+     }).catch(function(){ status('no wiki here — downloaded instead'); dl(new Blob([png],{type:'image/png'}),'favicon.png') })
+   }) }, 'image/png')
+  }
+  img.src='data:image/svg+xml;base64,'+btoa(unescape(encodeURIComponent(svg)))
+ }
+ function bust(){ try{ (parent.document||document).querySelectorAll('img.favicon').forEach(function(i){i.src='/favicon.png?t='+Date.now()}) }catch(e){} }
+ function dl(blob,name){ var a=document.createElement('a'); a.href=URL.createObjectURL(blob); a.download=name; a.click() }
+
+ // seed from the current favicon's embedded identity, else the domain
+ function seed(id){ if(id){ st.person=(id.id||st.person).replace(/-agent$/,''); st.name=id.name||st.name; st.type=id.type||st.type; st.topic=id.topicGroup||st.topic; st.species=id.species||st.species; if(id.variant!=null)st.variant=id.variant } render() }
+ fetch('/favicon.png?t='+Date.now()).then(function(r){return r.ok?r.arrayBuffer():null}).then(function(ab){
+   if(ab){ var t=pngReadText(new Uint8Array(ab),'fishpicker'); if(t){ try{ return seed(JSON.parse(decodeURIComponent(t))) }catch(e){} } }
+   // no wiki favicon → default from the frame's own host, if it looks like a site
+   var h=location.hostname.split('.').filter(Boolean); if(h[0]&&h[0]!=='localhost'){ st.person=h[0]; st.species=FP.speciesFor(h[0]); st.name=h[0]; var s=h.slice(1).find(function(x){return x in FP.SCHOOLS}); if(s)st.topic=s }
+   render()
+ }).catch(render)
+ render()
+})();
+</script>
+</body></html>