rvlib-shipkit 1.1.1 → 1.3.0

package/src/serve/hub-app/machine-st.ts

@@ -0,0 +1,333 @@
+// the machine, as a page on the home sees it: every repo's hub state and the
+// active flags from the daemon's /api/home.json, the widgets from its
+// /api/home/widgets.json, the global processes and pm's children from pm's
+// /api/pm/status.json. A node of the page tree
+// (home-st.ts): the root reads it for the list's dots, and says loudly when the
+// daemon behind the page does not answer. A hub serving on its own has none
+// of this (HomeSt.machine is null).
+import { makeAutoObservable, observableRef, runInAction } from 'mobx'
+import type { HomeAnswer, WidgetsAnswer } from '../../home/home-routes.ts'
+import type { WorkerView } from '../../home/hubs.ts'
+import type { ResourceView } from '../../home/resources.ts'
+import type { PmAnswer, Role } from '../../home/pm.ts'
+import { processGroups, type ProcessGroup } from '../../home/process-rows.ts'
+import { ClockSvc } from './clock-svc.ts'
+import type { HomeSt } from './home-st.ts'
+import type { HubDot } from './projects-svc.ts'
+
+export const MACHINE_POLL_MS = 1_500
+/** past the web's own wait on the daemon (serve-web.ts MACHINE_ANSWER_MS), so
+ *  a hung daemon reads in its words, and a hung web still reads as down */
+export const MACHINE_TIMEOUT_MS = 8_000
+
+/** where this browser keeps the machine as it last read it, painted at once
+ *  on the next load (the overview) while the daemon and pm are asked again */
+export const MACHINE_KEY = 'hub:machine'
+
+/** how long a copied pid says so */
+export const COPIED_MS = 1_200
+
+/** how open opens a global process's url, kept per browser */
+export const OPEN_HOW_KEY = 'hub:open-how'
+export type OpenHow = 'browser' | 'app'
+
+function loadOpenHow(): OpenHow {
+    try {
+        return globalThis.localStorage?.getItem(OPEN_HOW_KEY) === 'app' ? 'app' : 'browser'
+    } catch {
+        return 'browser'
+    }
+}
+
+type Kept = { data: HomeAnswer | null; pm: PmAnswer | null; widgets: WidgetsAnswer | null }
+
+function loadKept(): Kept | null {
+    try {
+        const v = JSON.parse(globalThis.localStorage?.getItem(MACHINE_KEY) ?? 'null') as Kept | null
+        return v != null && typeof v === 'object' && (v.data == null || Array.isArray(v.data.workers)) ? v : null
+    } catch {
+        return null
+    }
+}
+
+/** the poll failed because nothing behind the page answers, not on an error of an answer */
+class DownError extends Error {}
+
+export type MachineOpts = { reload?: () => void; timeoutMs?: number }
+
+export class MachineSt {
+    data: HomeAnswer | null = null
+    /** pm's answer: the resources and the daemon and web states */
+    pm: PmAnswer | null = null
+    /** every house repo's widgets, as the daemon last rendered them */
+    widgets: WidgetsAnswer | null = null
+    /** why pm did not answer the last poll, or '' while it does */
+    pmDown = ''
+    /** the last action that failed */
+    error = ''
+    /** where open sends a global process's url: the default browser, or a
+     *  shipkit app window */
+    openHow: OpenHow = loadOpenHow()
+    /** why the daemon did not answer the last poll, or '' while it does */
+    down = ''
+    /** the daemon answered once since the load: until then data, pm and
+     *  widgets are what this browser kept, shown but never acted on */
+    fresh = false
+    /** the one second the process ages move on, ticking while the machine polls */
+    clock: ClockSvc
+    /** the pid a click just copied, which says so for COPIED_MS */
+    copiedPid: number | null = null
+    private copiedTimer: ReturnType<typeof setTimeout> | null = null
+    /** what was last kept, so an unchanged machine is not written again */
+    private kept = ''
+    private timer: ReturnType<typeof setInterval> | null = null
+    private wasDown = false
+    private polling = false
+    private widgetsPolling = false
+    /** `error` holds a poll's error, which the next good poll clears */
+    private pollError = false
+
+    constructor(private st: HomeSt, private o: MachineOpts = {}) {
+        this.clock = new ClockSvc()
+        const k = loadKept()
+        if (k != null) {
+            this.data = k.data
+            this.pm = k.pm
+            this.widgets = k.widgets
+        }
+        makeAutoObservable<this, 'st' | 'timer' | 'copiedTimer' | 'wasDown' | 'polling' | 'widgetsPolling' | 'pollError' | 'o' | 'kept' | 'keep'>(this, { st: false, clock: false, timer: false, copiedTimer: false, wasDown: false, polling: false, widgetsPolling: false, pollError: false, o: false, kept: false, keep: false, data: observableRef, pm: observableRef, widgets: observableRef })
+    }
+
+    /** the repo the page shows, null on the overview and the plan */
+    get repo(): string | null {
+        return this.st.page === 'repo' ? this.st.selected : null
+    }
+
+    worker(name: string | null): WorkerView | null {
+        return name == null ? null : this.data?.workers.find((w) => w.repo === name) ?? null
+    }
+
+    get shown(): WorkerView | null {
+        return this.worker(this.repo)
+    }
+
+    /** the processes table: shipkit's own first, then one group per repo in
+     *  the project list's order, one row per process (process-rows.ts, what
+     *  `shipkit global-processes` prints) */
+    get processGroups(): ProcessGroup[] {
+        return processGroups(this.pm, this.st.projects.list.map((p) => p.name), { daemonVersion: this.data?.version ?? null })
+    }
+
+    resource(id: string): ResourceView | null {
+        return this.pm?.resources.find((r) => r.id === id) ?? null
+    }
+
+    dotOf(name: string): HubDot {
+        const s = this.worker(name)?.status
+        return s === 'starting' || s === 'crashed' ? s : null
+    }
+
+    /** the resources this repo uses that are not up, as one line */
+    warnOf(name: string): string | null {
+        const off = (this.worker(name)?.uses ?? []).filter((id) => this.resource(id)?.status !== 'up')
+        return off.length === 0 ? null : `needs ${off.join(', ')}, which ${off.length === 1 ? 'is' : 'are'} off`
+    }
+
+    isActive(name: string): boolean {
+        return this.data?.active.includes(name) === true
+    }
+
+    boot(): void {
+        void this.load().then(() => {
+            // a repo page asks its hub to load when it is down
+            if (this.repo != null && this.data != null) void this.hub(this.repo, 'ensure')
+        })
+        this.timer = setInterval(() => void this.load(), MACHINE_POLL_MS)
+        this.clock.start()
+    }
+
+    stop(): void {
+        if (this.timer != null) clearInterval(this.timer)
+        this.clock.stop()
+    }
+
+    /** pm is polled beside the daemon: either one down leaves the other shown */
+    private async loadPm(): Promise<void> {
+        try {
+            const r = await fetch('/api/pm/status.json', { signal: AbortSignal.timeout(this.o.timeoutMs ?? MACHINE_TIMEOUT_MS) })
+            if (!r.ok) throw new Error(await r.text())
+            const j = (await r.json()) as PmAnswer
+            runInAction(() => {
+                this.pm = j
+                this.pmDown = ''
+            })
+        } catch (e) {
+            runInAction(() => {
+                this.pm = null
+                this.pmDown = (e as Error).message
+            })
+        }
+    }
+
+    /** a widget poll that fails keeps the last html shown: the daemon's own
+     *  poll says why */
+    private async loadWidgets(): Promise<void> {
+        try {
+            const r = await fetch('/api/home/widgets.json', { signal: AbortSignal.timeout(this.o.timeoutMs ?? MACHINE_TIMEOUT_MS) })
+            if (!r.ok) return
+            const j = (await r.json()) as WidgetsAnswer
+            runInAction(() => { this.widgets = j })
+        } catch {
+            // the daemon poll beside it reports a daemon that does not answer
+        }
+    }
+
+    async load(): Promise<void> {
+        // a stalled poll is not stacked on
+        if (this.polling) return
+        this.polling = true
+        const pm = this.loadPm()
+        // never held on: a widget that answers late only shows late
+        if (!this.widgetsPolling) {
+            this.widgetsPolling = true
+            void this.loadWidgets().finally(() => { this.widgetsPolling = false })
+        }
+        try {
+            let r: Response
+            try {
+                r = await fetch('/api/home.json', { signal: AbortSignal.timeout(this.o.timeoutMs ?? MACHINE_TIMEOUT_MS) })
+            } catch (e) {
+                throw new DownError(`the home does not answer: ${(e as Error).message}`)
+            }
+            if (r.headers.get('x-shipkit-daemon') === 'down') throw new DownError(await r.text())
+            if (!r.ok) throw new Error(`/api/home.json answered ${r.status}: ${await r.text()}`)
+            const j = (await r.json()) as HomeAnswer
+            const back = this.wasDown
+            const cleared = this.pollError
+            this.wasDown = false
+            this.pollError = false
+            runInAction(() => {
+                this.data = j
+                this.down = ''
+                this.fresh = true
+                if (cleared) this.error = ''
+            })
+            // the shown repo starts once its hub answers
+            this.st.wake()
+            // and every other one is read ahead behind it
+            void this.st.prefetch()
+            // what the page loaded while the daemon was away failed: start over
+            if (back) this.reload()
+        } catch (e) {
+            const msg = (e as Error).message
+            if (e instanceof DownError) {
+                this.wasDown = true
+                runInAction(() => { this.down = msg })
+            } else {
+                this.pollError = true
+                runInAction(() => {
+                    this.down = ''
+                    this.error = msg
+                })
+            }
+        } finally {
+            await pm
+            this.polling = false
+            this.keep()
+        }
+    }
+
+    /** the machine as read now, kept for the next load. Only a change is written */
+    private keep(): void {
+        if (!this.fresh) return
+        try {
+            // the log tails change on every poll and only show on a hover: not kept
+            const pm = this.pm == null ? null : { ...this.pm, children: this.pm.children.map((c) => ({ ...c, tail: [] })), resources: this.pm.resources.map((r) => ({ ...r, tail: [] })) }
+            const s = JSON.stringify({ data: this.data, pm, widgets: this.widgets } satisfies Kept)
+            if (s === this.kept) return
+            globalThis.localStorage?.setItem(MACHINE_KEY, s)
+            this.kept = s
+        } catch { /* private window or blocked site data: the next load waits on the daemon */ }
+    }
+
+    private reload(): void {
+        if (this.o.reload != null) this.o.reload()
+        else window.location.reload()
+    }
+
+    private async post(path: string, body: unknown): Promise<boolean> {
+        try {
+            const r = await fetch(path, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(body) })
+            if (!r.ok) throw new Error(await r.text())
+            this.pollError = false
+            runInAction(() => { this.error = '' })
+            void this.load()
+            return true
+        } catch (e) {
+            runInAction(() => { this.error = (e as Error).message })
+            return false
+        }
+    }
+
+    hub(name: string, act: 'ensure' | 'restart'): Promise<boolean> {
+        return this.post('/api/home/hub', { name, act })
+    }
+
+    setActive(name: string, on: boolean): Promise<boolean> {
+        return this.post('/api/home/active', { name, on })
+    }
+
+    /** a global process: start, stop, restart, take over the copy started
+     *  elsewhere, open its url in the default browser or as an app window
+     *  (started first when it is down), or run one of its actions */
+    processAct(id: string, act: 'start' | 'stop' | 'restart' | 'takeover' | 'open' | 'app' | 'action', action?: string): Promise<boolean> {
+        return this.post('/api/pm/resource', { id, act, action })
+    }
+
+    /** the url of a global process, the way this browser picked (started
+     *  first when it is down) */
+    openProcess(id: string): Promise<boolean> {
+        return this.processAct(id, this.openHow === 'app' ? 'app' : 'open')
+    }
+
+    /** a process's pid to the clipboard, and the "copied" flash on it; a
+     *  refusal (plain http, an unfocused page) is said in the strip */
+    async copyPid(pid: number): Promise<void> {
+        try {
+            if (globalThis.navigator?.clipboard == null) throw new Error('this page has no clipboard')
+            await navigator.clipboard.writeText(String(pid))
+        } catch (e) {
+            runInAction(() => { this.error = `could not copy pid ${pid}: ${(e as Error).message}` })
+            return
+        }
+        runInAction(() => { this.copiedPid = pid })
+        if (this.copiedTimer != null) clearTimeout(this.copiedTimer)
+        this.copiedTimer = setTimeout(() => runInAction(() => { this.copiedPid = null }), COPIED_MS)
+    }
+
+    setOpenHow(how: OpenHow): void {
+        this.openHow = how
+        try {
+            globalThis.localStorage?.setItem(OPEN_HOW_KEY, how)
+        } catch { /* private window or blocked site data: the pick lasts the tab */ }
+    }
+
+    /** restart the daemon or the web through pm */
+    restartChild(id: Role): Promise<boolean> {
+        return this.post('/api/pm/child', { id, act: 'restart' })
+    }
+
+    modernize(name: string): Promise<boolean> {
+        return this.post('/api/home/modernize', { name })
+    }
+
+    /** one more window on this page. In a gui window (a Chrome app) a popup
+     *  opens as its own app window */
+    newWindow(): void {
+        window.open(`${window.location.origin}${window.location.pathname}`, '_blank', 'popup,width=1400,height=900')
+    }
+
+    openInCode(name: string): void {
+        void this.st.projects.open(name)
+    }
+}

package/src/serve/hub-app/md.ts

@@ -8,13 +8,15 @@ import sanitizeHtml from 'sanitize-html'
 
 marked.use({ gfm: true, breaks: false, async: false })
 
+const CARD_TAGS = [
+    'h1', 'h2', 'h3', 'h4', 'p', 'ul', 'ol', 'li',
+    'table', 'thead', 'tbody', 'tr', 'th', 'td',
+    'code', 'pre', 'strong', 'em', 'b', 'i', 'a', 'br', 'blockquote', 'hr',
+]
+
 export const renderMd = (src: string): string =>
     sanitizeHtml(marked.parse(src) as string, {
-        allowedTags: [
-            'h1', 'h2', 'h3', 'h4', 'p', 'ul', 'ol', 'li',
-            'table', 'thead', 'tbody', 'tr', 'th', 'td',
-            'code', 'pre', 'strong', 'em', 'b', 'i', 'a', 'br', 'blockquote', 'hr',
-        ],
+        allowedTags: CARD_TAGS,
         allowedAttributes: { a: ['href', 'target', 'rel'] },
         allowedSchemes: ['http', 'https'],
         allowProtocolRelative: false,
@@ -37,3 +39,34 @@ export const renderMdInline = (src: string): string =>
             a: (tagName, attribs) => ({ tagName, attribs: { ...attribs, target: '_blank', rel: 'noreferrer' } }),
         },
     })
+
+/** where a README image loads from: an http(s) url as written, a path
+ *  relative to the repo root through `fileUrl`, anything else (data:, file:,
+ *  `//host`) nowhere */
+export const readmeImageSrc = (src: string, fileUrl: (rel: string) => string): string | null => {
+    const s = src.trim()
+    if (/^https?:\/\//i.test(s)) return s
+    if (s === '' || s.startsWith('//') || /^[a-z][a-z0-9+.-]*:/i.test(s)) return null
+    const rel = s.replace(/[?#].*$/, '').replace(/^(\.\/|\/)+/, '')
+    return rel === '' ? null : fileUrl(rel.split('/').map(encodeURIComponent).join('/'))
+}
+
+/** a whole README: the card allowlist plus images and the few tags READMEs
+ *  lean on. A relative image is rewritten to the repo's file route, an image
+ *  with no loadable source is dropped */
+export const renderReadme = (src: string, fileUrl: (rel: string) => string): string =>
+    sanitizeHtml(marked.parse(src) as string, {
+        allowedTags: [...CARD_TAGS, 'h5', 'h6', 'img', 'details', 'summary', 'kbd', 'sup', 'sub', 'del'],
+        allowedAttributes: { a: ['href', 'target', 'rel'], img: ['src', 'alt', 'title', 'width', 'height'] },
+        allowedSchemes: ['http', 'https'],
+        allowProtocolRelative: false,
+        transformTags: {
+            a: (tagName, attribs) => ({ tagName, attribs: { ...attribs, target: '_blank', rel: 'noreferrer' } }),
+            img: (tagName, attribs) => {
+                const { src: raw, ...rest } = attribs
+                const src = readmeImageSrc(raw ?? '', fileUrl)
+                return { tagName, attribs: src == null ? rest : { ...rest, src } }
+            },
+        },
+        exclusiveFilter: (frame) => frame.tag === 'img' && (frame.attribs.src ?? '') === '',
+    })

package/src/serve/hub-app/media-svc.ts

@@ -4,27 +4,15 @@
 // structure is read-only (kit.ts is code-reviewed); this edits WORKSPACE
 // state: picks, alts, prompt overlays, meta sidecars, geometry rects.
 import { makeAutoObservable, runInAction } from 'mobx'
-import type { HubSt } from './hub-st.ts'
+import type { RepoSt } from './repo-st.ts'
 import type { AssetDetail, CatRow, Rect, SideAsset } from './hub-types.ts'
 
-const MEDIA = '/media'
 // thumbs change in place when a pick changes → ~8s cache buckets; roll
 // files are immutable (one name = one file forever), so their URLs carry
 // no bust — an <audio> src that never changes never restarts playback
 const V = (): number => Date.now() >> 13
-export const rollUrl = (id: string, name: string): string => `${MEDIA}/img?id=${encodeURIComponent(id)}&name=${encodeURIComponent(name)}`
-export const thumbUrl = (id: string): string => `${MEDIA}/api/thumb?id=${encodeURIComponent(id)}&t=${V()}`
 export const isAud = (n: string): boolean => ['mp3', 'wav', 'ogg', 'm4a'].includes(String(n ?? '').split('.').pop() ?? '')
 
-const j = async (u: string): Promise<any> => {
-    const r = await fetch(MEDIA + u)
-    if (!r.ok) throw new Error(`${u}: ${r.status}`)
-    return r.json()
-}
-const post = async (u: string, b?: unknown): Promise<any> => {
-    const r = await fetch(MEDIA + u, { method: 'POST', body: JSON.stringify(b ?? {}) })
-    return r.json()
-}
 
 export class MediaSvc {
     assets: SideAsset[] = []
@@ -80,7 +68,7 @@ export class MediaSvc {
     /** stage overlay root (the image box) — registered by AssetStage, DOM only */
     overlayHost: HTMLElement | null = null
 
-    constructor(private st: HubSt) {
+    constructor(private st: RepoSt) {
         makeAutoObservable<this, 'st' | 'hbTimer' | 'rectTimer' | 'promptTimer' | 'savedPrompt' | 'overlayHost'>(
             this, { st: false, hbTimer: false, rectTimer: false, promptTimer: false, savedPrompt: false, overlayHost: false })
         if (typeof localStorage !== 'undefined') {
@@ -102,15 +90,41 @@ export class MediaSvc {
     }
 
     start(): void {
+        if (this.hbTimer != null || this.dead != null) return
         void this.heartbeat()
         this.hbTimer = setInterval(() => void this.heartbeat(), 1500)
     }
-    dispose(): void {
+    /** polling only: a pending prompt or rect save still lands */
+    stop(): void {
         if (this.hbTimer != null) clearInterval(this.hbTimer)
+        this.hbTimer = null
+    }
+    dispose(): void {
+        this.stop()
         if (this.rectTimer != null) clearTimeout(this.rectTimer)
         if (this.promptTimer != null) clearTimeout(this.promptTimer)
     }
 
+    /** the media API, under this repo's base */
+    private get api(): string {
+        return this.st.url('/media')
+    }
+    rollUrl(id: string, name: string): string {
+        return `${this.api}/img?id=${encodeURIComponent(id)}&name=${encodeURIComponent(name)}`
+    }
+    thumbUrl(id: string): string {
+        return `${this.api}/api/thumb?id=${encodeURIComponent(id)}&t=${V()}`
+    }
+    private async j(u: string): Promise<any> {
+        const r = await fetch(this.api + u)
+        if (!r.ok) throw new Error(`${u}: ${r.status}`)
+        return r.json()
+    }
+    private async post(u: string, b?: unknown): Promise<any> {
+        const r = await fetch(this.api + u, { method: 'POST', body: JSON.stringify(b ?? {}) })
+        return r.json()
+    }
+
     get curId(): string | null {
         return this.st.sel?.t === 'asset' ? this.st.sel.id : null
     }
@@ -145,7 +159,7 @@ export class MediaSvc {
         if (this.dead != null) return
         let s: any
         try {
-            const r = await fetch(MEDIA + '/api/state')
+            const r = await fetch(this.api + '/api/state')
             if (r.status === 404) {
                 // the mount failed at boot — it will not come back without a
                 // restart; say so once, loudly, and stop wasting the wire
@@ -174,6 +188,7 @@ export class MediaSvc {
         })
         if (this.curId != null) await this.refreshRolls()
         if (this.catMode != null) await this.fillCat()
+        this.st.cols.mediaListed()
         this.st.afterFirstBeat()
     }
 
@@ -184,7 +199,7 @@ export class MediaSvc {
         this.statusLine = ''
         const a = this.assets.find((x) => x.id === id)
         if (a != null) this.openCats.add(a.cat)
-        const r = (await j(`/api/asset?id=${encodeURIComponent(id)}`)) as AssetDetail
+        const r = (await this.j(`/api/asset?id=${encodeURIComponent(id)}`)) as AssetDetail
         if (this.curId !== id) return // selection changed mid-fetch — never clobber
         runInAction(() => {
             this.detail = r
@@ -206,7 +221,7 @@ export class MediaSvc {
     async refreshRolls(): Promise<void> {
         const id = this.curId
         if (id == null) return
-        const r = (await j(`/api/asset?id=${encodeURIComponent(id)}`)) as AssetDetail
+        const r = (await this.j(`/api/asset?id=${encodeURIComponent(id)}`)) as AssetDetail
         if (this.curId !== id) return
         runInAction(() => {
             if (this.detail == null) this.detail = r
@@ -223,23 +238,23 @@ export class MediaSvc {
 
     async generate(): Promise<void> {
         if (this.curId == null) return
-        await post('/api/generate', { id: this.curId, prompt: this.prompt, count: +this.n })
+        await this.post('/api/generate', { id: this.curId, prompt: this.prompt, count: +this.n })
         void this.heartbeat()
     }
     async genCat(cat: string, count: number): Promise<void> {
-        const r = await post('/api/generate-cat', { cat, count })
+        const r = await this.post('/api/generate-cat', { cat, count })
         if (r?.error != null) runInAction(() => { this.statusLine = r.error })
         void this.heartbeat()
     }
     clearQueue(): void {
-        void post('/api/queue/clear')
+        void this.post('/api/queue/clear')
     }
     stopCurrent(): void {
-        void post('/api/interrupt')
+        void this.post('/api/interrupt')
     }
 
     async pick(name: string): Promise<void> {
-        const res = await post('/api/pick', { id: this.curId, name })
+        const res = await this.post('/api/pick', { id: this.curId, name })
         runInAction(() => {
             this.statusLine = res.error != null ? `ship FAILED: ${res.error}` : res.shipped != null ? `shipped → ${res.shipped}` : 'picked (pick.json)'
             this.active = name
@@ -247,11 +262,11 @@ export class MediaSvc {
         await this.refreshRolls()
     }
     async alt(name: string): Promise<void> {
-        await post('/api/alt', { id: this.curId, name })
+        await this.post('/api/alt', { id: this.curId, name })
         await this.refreshRolls()
     }
     async discard(name: string): Promise<void> {
-        await post('/api/discard', { id: this.curId, name })
+        await this.post('/api/discard', { id: this.curId, name })
         runInAction(() => {
             if (this.active === name) this.active = null
             // the ✕ sits on the hovered tile and its unmount fires no
@@ -267,7 +282,7 @@ export class MediaSvc {
             const fd = new FormData()
             fd.append('id', this.curId)
             fd.append('file', f)
-            const r = await fetch(`${MEDIA}/api/upload`, { method: 'POST', body: fd }).then((x) => x.json()).catch((e: Error) => ({ error: String(e) }))
+            const r = await fetch(`${this.api}/api/upload`, { method: 'POST', body: fd }).then((x) => x.json()).catch((e: Error) => ({ error: String(e) }))
             if (r.error != null) runInAction(() => { this.statusLine = `upload FAIL: ${r.error}` })
         }
         await this.refreshRolls()
@@ -290,7 +305,7 @@ export class MediaSvc {
             const text = this.prompt
             if (text === this.savedPrompt) return // unchanged — not a save
             void (async () => {
-                const r = await post('/api/prompt', { id, prompt: text })
+                const r = await this.post('/api/prompt', { id, prompt: text })
                 runInAction(() => {
                     if (this.curId !== id) return // selection moved while the POST flew — a late response must not corrupt the new asset's baseline
                     if (r.error != null) {
@@ -330,7 +345,7 @@ export class MediaSvc {
         }
         const id = this.curId
         const name = this.active
-        const r = await j(`/api/rect?id=${encodeURIComponent(id)}&name=${encodeURIComponent(name)}`).catch(() => null)
+        const r = await this.j(`/api/rect?id=${encodeURIComponent(id)}&name=${encodeURIComponent(name)}`).catch(() => null)
         if (this.curId !== id || this.active !== name) return // roll switched mid-fetch
         runInAction(() => {
             this.rect = r?.rect ?? null
@@ -349,7 +364,7 @@ export class MediaSvc {
         if (this.rectTimer != null) clearTimeout(this.rectTimer)
         this.rectTimer = setTimeout(() => {
             void (async () => {
-                const r = await post('/api/rect', { id, name, rect })
+                const r = await this.post('/api/rect', { id, name, rect })
                 runInAction(() => {
                     if (this.curId !== id || this.active !== name) return // selection moved on — never adopt a stale rect
                     if (r.rect != null) this.rect = r.rect
@@ -360,7 +375,7 @@ export class MediaSvc {
     }
     async legsDefault(): Promise<void> {
         if (this.curId == null || this.active == null) return
-        const r = await post('/api/legs-default', { id: this.curId, name: this.active })
+        const r = await this.post('/api/legs-default', { id: this.curId, name: this.active })
         if (r.rect != null) runInAction(() => { this.rect = r.rect })
     }
     removeLegs(): void {
@@ -374,7 +389,7 @@ export class MediaSvc {
     async fillCat(): Promise<void> {
         const mode = this.catMode
         if (mode == null) return
-        const r = await j(`/api/catrects?cat=${encodeURIComponent(mode)}`)
+        const r = await this.j(`/api/catrects?cat=${encodeURIComponent(mode)}`)
         if (this.catMode !== mode) return // navigated away mid-fetch
         runInAction(() => { this.catRows = r.rows ?? [] })
     }
@@ -384,10 +399,10 @@ export class MediaSvc {
         const nv = Math.max(0.1, v || row.rect.size)
         if (nv === row.rect.size) return // blur without a change is not a save
         row.rect.size = nv
-        await post('/api/rect', { id, name, rect: row.rect })
+        await this.post('/api/rect', { id, name, rect: row.rect })
     }
     async toggleFlip(id: string, name: string): Promise<void> {
-        await post('/api/flip', { id, name })
+        await this.post('/api/flip', { id, name })
         await this.fillCat()
     }
     async applyAllSize(): Promise<void> {
@@ -397,7 +412,7 @@ export class MediaSvc {
         // one action for all mutations (post-await writes would land outside
         // it — mobx strict mode), then the POSTs
         runInAction(() => { for (const row of rows) row.rect!.size = v })
-        for (const row of rows) await post('/api/rect', { id: row.id, name: row.name, rect: row.rect })
+        for (const row of rows) await this.post('/api/rect', { id: row.id, name: row.name, rect: row.rect })
         runInAction(() => { this.allMsg = 'applied' })
         setTimeout(() => runInAction(() => { this.allMsg = '' }), 1200)
         await this.fillCat()
@@ -433,12 +448,16 @@ export class MediaSvc {
         if (kind != null && typeof localStorage !== 'undefined') localStorage.setItem(`hub:tools:${kind}`, [...this.tools].join(','))
         this.syncHash()
     }
-    /** the hash carries the working state: #<assetId>?tools=a,b — shareable, restored on load */
-    private syncHash(): void {
-        if (typeof location === 'undefined' || this.curId == null) return
+    /** the hash carries the working state: #<assetId>?tools=a,b — shareable,
+     *  restored on load. null while no asset is open */
+    get hash(): string | null {
+        if (this.curId == null) return null
         const t = [...this.tools].join(',')
-        const h = `${this.curId}${t === '' ? '' : `?tools=${t}`}`
-        if (location.hash.slice(1) !== h) history.replaceState(null, '', `#${h}`)
+        return `${this.curId}${t === '' ? '' : `?tools=${t}`}`
+    }
+    private syncHash(): void {
+        const h = this.hash
+        if (h != null) this.st.replaceHash(h)
     }
     /** tabs = kit-declared presets first, then autos for tools no tab covers.
      *  a tab swaps the enabled tool SET — the canvas underneath never moves */
@@ -493,12 +512,12 @@ export class MediaSvc {
     }
     async loadMeta(): Promise<void> {
         this.jsonMsg = ''
-        const r = this.curId != null && this.active != null ? await post('/api/meta', { id: this.curId, name: this.active }) : { text: '' }
+        const r = this.curId != null && this.active != null ? await this.post('/api/meta', { id: this.curId, name: this.active }) : { text: '' }
         runInAction(() => { this.jsonText = r.text ?? '' })
     }
     async saveMeta(): Promise<void> {
         if (this.curId == null || this.active == null) return
-        const r = await post('/api/meta', { id: this.curId, name: this.active, text: this.jsonText })
+        const r = await this.post('/api/meta', { id: this.curId, name: this.active, text: this.jsonText })
         runInAction(() => { this.jsonMsg = r.error != null ? `FAIL: ${r.error}` : 'saved' })
     }
     /** frozen per mount: a roll/asset switch remounts with a fresh api */
@@ -513,14 +532,14 @@ export class MediaSvc {
             /** the PICKED roll's name (null before any pick) — editors that
              *  target shipped art can warn when the shown roll differs */
             picked: this.detail?.rolls.find((x) => x.picked)?.name ?? null,
-            imgUrl: rollUrl(id, name),
+            imgUrl: this.rollUrl(id, name),
             getMeta: async () => {
-                const r = await post('/api/meta', { id, name })
+                const r = await this.post('/api/meta', { id, name })
                 if (r.error != null) throw new Error(r.error)
                 return r.text ? JSON.parse(r.text) : null
             },
             saveMeta: async (data: unknown) => {
-                const r = await post('/api/meta', { id, name, text: JSON.stringify(data) })
+                const r = await this.post('/api/meta', { id, name, text: JSON.stringify(data) })
                 if (r.error != null) throw new Error(r.error)
             },
             // an element covering the DISPLAYED roll image, so an editor can