// The page's URL route model (L6). Pure and DOM-free: the parser is total (a // malformed or unknown location resolves to the default Pipelines list), and the // serialiser is its inverse for every route the page can produce. // // The Android app's `pipelines://run/` deep link becomes a real page route, // and every destination the app has becomes a URL: // // /pipelines Pipelines list // /pipelines/:id pipeline detail, latest version // /pipelines/:id/:version pipeline detail at a version (0 = latest) // /pipelines/:id[/:version]/stage/:key the definition pane's stage // /runs Runs list // /runs/:id run detail (optional ?action=decide) // /runs/:id/stage/:key[?visit=N] one visit's stage pane // /chat Chat list // /chat/:id one chat session // /templates template gallery // /templates/:key template detail // /settings Settings // /settings/templates[/:key] aliases for the two template routes // // Where a section sits inside a detail (Summary/Graph/Source, run tabs) is // in-place state, not a route: only the two stage panes are deep-linkable. Search // is query state owned by the search panel and is never part of a route; unknown // query parameters are ignored. `/templates` and `/templates/:key` are the // canonical forms the serialiser emits; the `/settings/...` aliases still parse // and round-trip to the same route. /** The destination an unknown or malformed location opens. */ export const DEFAULT_ROUTE = Object.freeze({ kind: "pipelines" }); const ID_PATTERN = /^[0-9]+$/; /** Decode one path segment, or null when the percent escapes are malformed. */ function decodeSegment(segment) { try { return decodeURIComponent(segment); } catch { return null; } } /** A positive safe integer id, or null. Mirrors runLinkFromDeepLink's id > 0. */ function parseId(value) { if (!ID_PATTERN.test(value)) return null; const id = Number(value); return Number.isSafeInteger(id) && id > 0 ? id : null; } /** A non-negative safe integer (a pipeline version; 0 means latest), or null. */ /** A chat session id segment: nonempty, bounded, URL-safe. */ function parseChatId(value) { const id = String(value ?? ""); return id !== "" && id.length <= 200 && /^[A-Za-z0-9_-]+$/.test(id) ? id : null; } function parseVersion(value) { if (!ID_PATTERN.test(value)) return null; const version = Number(value); return Number.isSafeInteger(version) ? version : null; } /** The `action` query value verbatim, or null; only `decide` has an effect. */ function parseAction(params) { if (!params) return null; const action = params.get("action"); return action != null && action !== "" ? action : null; } /** * The zero-based visit index from `?visit=`, or null. A negative, non-integer or * absent value drops the query while keeping the stage route, exactly as the * Android extra is optional. */ function parseVisit(params) { if (!params) return null; const raw = params.get("visit"); if (raw == null || raw === "") return null; return parseVersion(raw); } function parseParams(search) { if (!search) return null; const text = String(search).replace(/^\?/, ""); if (!text) return null; try { return new URLSearchParams(text); } catch { return null; } } /** * Parse a location-style pathname (and optional search) into a route. Total: * anything unrecognised — an unknown path, a malformed percent escape, a zero or * negative run id, a non-numeric version — returns DEFAULT_ROUTE and never * throws. Unknown query parameters are ignored; `visit` is dropped when invalid. */ export function parseRoute(pathname, search = "") { let raw = pathname == null ? "" : String(pathname); let query = search == null ? "" : String(search); // A full URL is accepted too (the smoke and a pasted link use one); its own // path and query stand in for the arguments. if (/^[a-z][a-z0-9+.-]*:\/\//i.test(raw)) { try { const url = new URL(raw); if (!query) query = url.search; raw = url.pathname; } catch { return DEFAULT_ROUTE; } } const hash = raw.indexOf("#"); if (hash !== -1) raw = raw.slice(0, hash); const mark = raw.indexOf("?"); if (mark !== -1) { if (!query) query = raw.slice(mark); raw = raw.slice(0, mark); } if (!query && typeof search === "string") query = search; // Normalise trailing slashes: `/runs/` is `/runs`. const trimmed = raw.replace(/\/+$/, ""); const segments = trimmed.split("/").filter((segment, index) => index > 0 || segment !== ""); if (trimmed === "" || trimmed === "/") return { ...DEFAULT_ROUTE }; const decoded = []; for (const segment of segments) { const value = decodeSegment(segment); if (value == null || value === "") return { ...DEFAULT_ROUTE }; decoded.push(value); } const params = parseParams(query); const [head, second, third, fourth, fifth, ...rest] = decoded; if (rest.length) return { ...DEFAULT_ROUTE }; if (head === "pipelines" && second == null) return { kind: "pipelines" }; if (head === "runs" && second == null) { const pipelineId = parseId(params?.get("pipeline") ?? ""); return pipelineId == null ? { kind: "runs" } : { kind: "runs", pipelineId }; } if (head === "chat") { if (second == null) return { kind: "chat" }; if (third == null) { const id = parseChatId(second); return id == null ? { ...DEFAULT_ROUTE } : { kind: "chatSession", id }; } return { ...DEFAULT_ROUTE }; } if (head === "settings" && second == null) return { kind: "settings" }; if (head === "templates") { if (second == null) return { kind: "templates" }; if (third == null) return { kind: "template", key: second }; return { ...DEFAULT_ROUTE }; } if (head === "settings" && second === "templates") { if (third == null) return { kind: "templates" }; if (fourth == null) return { kind: "template", key: third }; return { ...DEFAULT_ROUTE }; } if (head === "pipelines") { const id = parseId(second); if (id == null) return { ...DEFAULT_ROUTE }; if (third == null) return { kind: "pipeline", id, version: 0 }; if (third === "stage" && fourth != null && fifth == null) { return { kind: "pipelineStage", id, version: 0, stageKey: fourth }; } const version = parseVersion(third); if (version == null) return { ...DEFAULT_ROUTE }; if (fourth == null) return { kind: "pipeline", id, version }; if (fourth === "stage" && fifth != null) { return { kind: "pipelineStage", id, version, stageKey: fifth }; } return { ...DEFAULT_ROUTE }; } if (head === "runs") { const id = parseId(second); if (id == null) return { ...DEFAULT_ROUTE }; if (third == null) { const action = parseAction(params); return action == null ? { kind: "run", id } : { kind: "run", id, action }; } if (third === "stage" && fourth != null && fifth == null) { const visit = parseVisit(params); return visit == null ? { kind: "runStage", id, stageKey: fourth } : { kind: "runStage", id, stageKey: fourth, visit }; } return { ...DEFAULT_ROUTE }; } return { ...DEFAULT_ROUTE }; } function encode(value) { return encodeURIComponent(String(value)); } /** * An id the parser will accept back (a positive safe integer), or null. A * numeric string is accepted like the parser's own digit-only form. */ function serialId(value) { if (typeof value === "number") { return Number.isSafeInteger(value) && value > 0 ? value : null; } if (typeof value === "string" && ID_PATTERN.test(value)) { const id = Number(value); return Number.isSafeInteger(id) && id > 0 ? id : null; } return null; } /** * A version the parser will accept back (a non-negative safe integer), or null * when the value cannot describe one; the caller then emits the latest form so * the URL still parses to a canonical route. */ function serialVersion(value) { if (value == null) return 0; if (typeof value === "number") { return Number.isSafeInteger(value) && value >= 0 ? value : null; } if (typeof value === "string" && ID_PATTERN.test(value)) { const version = Number(value); return Number.isSafeInteger(version) ? version : null; } return null; } /** * Serialise a route to a path + query. Total: an unrecognised object serialises * to the default Pipelines route rather than throwing. Version 0/absent is * omitted (it means latest), an absent visit is omitted, and `action` is emitted * only when present. */ export function serializeRoute(route) { const r = route ?? DEFAULT_ROUTE; switch (r.kind) { case "pipelines": return "/pipelines"; case "runs": return parseId(String(r.pipelineId ?? "")) == null ? "/runs" : `/runs?pipeline=${r.pipelineId}`; case "chat": return "/chat"; case "chatSession": { const id = parseChatId(r.id); return id == null ? "/chat" : `/chat/${encode(id)}`; } case "settings": return "/settings"; case "templates": return "/templates"; case "template": return typeof r.key === "string" && r.key ? `/templates/${encode(r.key)}` : "/templates"; case "pipeline": { const id = serialId(r.id); if (id == null) return "/pipelines"; const version = serialVersion(r.version) ?? 0; return version > 0 ? `/pipelines/${id}/${version}` : `/pipelines/${id}`; } case "pipelineStage": { const id = serialId(r.id); if (id == null || typeof r.stageKey !== "string" || !r.stageKey) return "/pipelines"; const version = serialVersion(r.version) ?? 0; const base = version > 0 ? `/pipelines/${id}/${version}` : `/pipelines/${id}`; return `${base}/stage/${encode(r.stageKey)}`; } case "run": { const id = serialId(r.id); if (id == null) return "/runs"; const base = `/runs/${id}`; return r.action ? `${base}?${new URLSearchParams({ action: r.action }).toString()}` : base; } case "runStage": { const id = serialId(r.id); if (id == null || typeof r.stageKey !== "string" || !r.stageKey) return "/runs"; const base = `/runs/${id}/stage/${encode(r.stageKey)}`; // A valid visit is a non-negative integer; anything else is omitted. const visit = Number.isSafeInteger(r.visit) && r.visit >= 0 ? r.visit : null; return visit == null ? base : `${base}?visit=${visit}`; } default: return "/pipelines"; } } /** Two routes are the same when their canonical serialisations agree. */ export function sameRoute(a, b) { return serializeRoute(a) === serializeRoute(b); }