PyPI - estimating-tools - Versions diffs - 0.1.87__py3-none-any.whl - Mend

estimating-tools 0.1.87__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (156) hide show

estimating_tools/__init__.py +7 -0
estimating_tools/artifact_app/__init__.py +1 -0
estimating_tools/artifact_app/app.html +195 -0
estimating_tools/artifact_app/browser.py +194 -0
estimating_tools/artifact_app/server.py +311 -0
estimating_tools/artifact_common.py +56 -0
estimating_tools/artifacts.py +28 -0
estimating_tools/artifacts_html.py +391 -0
estimating_tools/assemblies/__init__.py +27 -0
estimating_tools/assemblies/artifact.py +420 -0
estimating_tools/assemblies/cli.py +54 -0
estimating_tools/assemblies/excel.py +293 -0
estimating_tools/assemblies/load_cli.py +72 -0
estimating_tools/assemblies/load_model.py +69 -0
estimating_tools/assemblies/model.py +42 -0
estimating_tools/assemblies/plan.py +396 -0
estimating_tools/auth/__init__.py +0 -0
estimating_tools/auth/cli.py +113 -0
estimating_tools/auth/m2m.py +55 -0
estimating_tools/calcbook/__init__.py +36 -0
estimating_tools/calcbook/formula.py +57 -0
estimating_tools/calcbook/recalc.py +45 -0
estimating_tools/calcbook/writer.py +148 -0
estimating_tools/costcodes/__init__.py +16 -0
estimating_tools/costcodes/cli.py +71 -0
estimating_tools/costcodes/excel.py +213 -0
estimating_tools/costcodes/model.py +51 -0
estimating_tools/costcodes/resolver.py +163 -0
estimating_tools/costcodes/strategies.py +131 -0
estimating_tools/directory/__init__.py +12 -0
estimating_tools/directory/cli.py +52 -0
estimating_tools/directory/diff.py +225 -0
estimating_tools/directory/excel.py +141 -0
estimating_tools/directory/model.py +63 -0
estimating_tools/directory/sync_cli.py +57 -0
estimating_tools/docgen/__init__.py +0 -0
estimating_tools/docgen/docxtpl_engine.py +103 -0
estimating_tools/docgen/letterhead_cli.py +111 -0
estimating_tools/docgen/report_engine.py +445 -0
estimating_tools/docgen/xlsx_populate.py +40 -0
estimating_tools/docgen/yaml_tree.py +50 -0
estimating_tools/estimate_spec/__init__.py +0 -0
estimating_tools/estimate_spec/_shared.py +20 -0
estimating_tools/estimate_spec/apply.py +286 -0
estimating_tools/estimate_spec/artifact.py +878 -0
estimating_tools/estimate_spec/build.py +709 -0
estimating_tools/estimate_spec/cip.py +518 -0
estimating_tools/estimate_spec/cli.py +496 -0
estimating_tools/estimate_spec/compact.py +525 -0
estimating_tools/estimate_spec/format_pack.py +359 -0
estimating_tools/estimate_spec/packs/README.md +173 -0
estimating_tools/estimate_spec/packs/demo/examples/demo-pipeline.estimate.yaml +91 -0
estimating_tools/estimate_spec/packs/demo/format.yaml +23 -0
estimating_tools/estimate_spec/packs/demo/recipes.yaml +61 -0
estimating_tools/estimate_spec/packs/demo/seed.yaml +45 -0
estimating_tools/estimate_spec/packs/demo/tokens.yaml +121 -0
estimating_tools/estimate_spec/packs/demo/units.yaml +218 -0
estimating_tools/estimate_spec/packs/demo/vocabulary.yaml +51 -0
estimating_tools/estimate_spec/recipe.py +207 -0
estimating_tools/estimate_spec/scaffold.py +506 -0
estimating_tools/estimate_spec/scaffold_save.py +98 -0
estimating_tools/estimate_spec/schema/skeleton.schema.json +208 -0
estimating_tools/estimate_spec/summarize.py +433 -0
estimating_tools/estimate_spec/sync.py +380 -0
estimating_tools/estimate_spec/sync_executor.py +405 -0
estimating_tools/estimate_spec/validate.py +75 -0
estimating_tools/excel/__init__.py +0 -0
estimating_tools/excel/excel_reader.py +119 -0
estimating_tools/historicals/__init__.py +0 -0
estimating_tools/historicals/cli.py +188 -0
estimating_tools/historicals/estimates.py +86 -0
estimating_tools/historicals/model.py +141 -0
estimating_tools/historicals/suggest.py +151 -0
estimating_tools/historicals/tabs.py +182 -0
estimating_tools/importers/__init__.py +11 -0
estimating_tools/importers/cli.py +51 -0
estimating_tools/importers/hcss.py +347 -0
estimating_tools/importers/mapping_artifact.py +184 -0
estimating_tools/importers/model.py +49 -0
estimating_tools/importers/pricing.py +102 -0
estimating_tools/importers/push.py +137 -0
estimating_tools/importers/registry.py +35 -0
estimating_tools/importers/schema/canonical-estimate.schema.json +47 -0
estimating_tools/importers/validate.py +20 -0
estimating_tools/intake/__init__.py +4 -0
estimating_tools/intake/bid_frame.py +124 -0
estimating_tools/intake/briefing.py +87 -0
estimating_tools/intake/cli.py +237 -0
estimating_tools/intake/manifest.py +111 -0
estimating_tools/pdf/__init__.py +0 -0
estimating_tools/pdf/extract_text.py +157 -0
estimating_tools/profiles/__init__.py +15 -0
estimating_tools/profiles/build.py +109 -0
estimating_tools/profiles/cli.py +73 -0
estimating_tools/profiles/loader.py +94 -0
estimating_tools/profiles/merge.py +25 -0
estimating_tools/profiles/model.py +22 -0
estimating_tools/profiles/scaffold.py +82 -0
estimating_tools/profiles/schema/profile.schema.json +69 -0
estimating_tools/profiles/trees/work-bid-layout.yaml +14 -0
estimating_tools/profiles/trees/work-project-layout.yaml +9 -0
estimating_tools/profiles/wires.py +57 -0
estimating_tools/quotes/__init__.py +16 -0
estimating_tools/quotes/model.py +32 -0
estimating_tools/quotes/plan.py +121 -0
estimating_tools/quotes/revision.py +58 -0
estimating_tools/quotespace/__init__.py +0 -0
estimating_tools/quotespace/cli.py +277 -0
estimating_tools/quotespace/conditions.py +111 -0
estimating_tools/quotespace/coverage.py +177 -0
estimating_tools/quotespace/itb.py +64 -0
estimating_tools/quotespace/model.py +143 -0
estimating_tools/rates/__init__.py +13 -0
estimating_tools/rates/cli.py +52 -0
estimating_tools/rates/excel.py +151 -0
estimating_tools/rates/model.py +56 -0
estimating_tools/rebar/__init__.py +4 -0
estimating_tools/rebar/cli.py +202 -0
estimating_tools/rebar/detailing.py +68 -0
estimating_tools/rebar/develop.py +54 -0
estimating_tools/rebar/ifc.py +223 -0
estimating_tools/rebar/model.py +69 -0
estimating_tools/rebar/schedule.py +205 -0
estimating_tools/reconcile/__init__.py +22 -0
estimating_tools/reconcile/diff.py +229 -0
estimating_tools/schedule/__init__.py +0 -0
estimating_tools/schedule/cli.py +227 -0
estimating_tools/schedule/costload.py +180 -0
estimating_tools/schedule/gantt_to_ganttwarrior.py +327 -0
estimating_tools/schedule/importers.py +13 -0
estimating_tools/schedule/model.py +9 -0
estimating_tools/schedule/render.py +73 -0
estimating_tools/schedule/scope.py +225 -0
estimating_tools/schedule/xer.py +371 -0
estimating_tools/spreads/__init__.py +16 -0
estimating_tools/spreads/award.py +184 -0
estimating_tools/spreads/conditions.py +251 -0
estimating_tools/spreads/item_quotes.py +96 -0
estimating_tools/spreads/level.py +139 -0
estimating_tools/spreads/model.py +83 -0
estimating_tools/spreads/render.py +156 -0
estimating_tools/takeoff/__init__.py +0 -0
estimating_tools/takeoff/audit.py +556 -0
estimating_tools/takeoff/audit_xlsx.py +127 -0
estimating_tools/takeoff/cli.py +180 -0
estimating_tools/takeoff/core.py +165 -0
estimating_tools/takeoff/earthwork.py +159 -0
estimating_tools/takeoff/model.py +79 -0
estimating_tools/takeoff/push.py +409 -0
estimating_tools/xlsx_determinism.py +38 -0
estimating_tools-0.1.87.dist-info/METADATA +72 -0
estimating_tools-0.1.87.dist-info/RECORD +156 -0
estimating_tools-0.1.87.dist-info/WHEEL +5 -0
estimating_tools-0.1.87.dist-info/entry_points.txt +24 -0
estimating_tools-0.1.87.dist-info/licenses/LICENSE +202 -0
estimating_tools-0.1.87.dist-info/top_level.txt +1 -0

estimating_tools/__init__.py ADDED Viewed

@@ -0,0 +1,7 @@
+"""Deterministic construction estimating and engineering tools."""
+from importlib.metadata import PackageNotFoundError, version
+try:
+    __version__ = version("estimating_tools")
+except PackageNotFoundError:  # running from source without an install
+    __version__ = "0.0.0+unknown"

estimating_tools/artifact_app/__init__.py ADDED Viewed

	@@ -0,0 +1 @@
1	+ """MCP App surface: stdio server + static editor app (io.modelcontextprotocol/ui)."""

estimating_tools/artifact_app/app.html ADDED Viewed

@@ -0,0 +1,195 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Estimating artifact editor</title>
+<style>
+body{font:14px/1.45 system-ui,"Segoe UI",sans-serif;margin:0;color:#1c2422;background:#fff}
+main{max-width:1100px;margin:0 auto;padding:0 20px 60px}
+header{position:sticky;top:0;background:#fff;border-bottom:1px solid #e2e6e4;padding:10px 20px;display:flex;gap:12px;align-items:center;z-index:2}
+header h1{font-size:17px;margin:0;flex:1}
+h2{font-size:15px;margin:18px 0 6px}
+h3,h4,h5,h6{font-size:14px;margin:14px 0 4px}
+table{border-collapse:collapse;margin:10px 0;width:100%}
+th,td{border:1px solid #d8dedb;padding:4px 8px;text-align:left;font-variant-numeric:tabular-nums;font-size:13px}
+th{background:#eef1ef;font-size:12px}
+td[contenteditable]:focus{outline:2px solid #0e6e63;background:#f4faf9}
+.ext{background:#f7f4ec;color:#6b5d33;font-style:italic}
+th.ext span{display:block;font-size:9px;font-weight:400;text-transform:uppercase;letter-spacing:.05em}
+td.ctl,th.ctl{border:none;background:none;width:26px;padding:0;text-align:center}
+.del{border:none;background:none;color:#b04a3a;cursor:pointer;font-size:14px}
+.add{margin:0 0 14px;border:1px dashed #9aa5a1;background:none;border-radius:4px;padding:2px 10px;cursor:pointer;color:#55605c;font-size:12px}
+#copy{background:#0e6e63;color:#fff;border:none;border-radius:6px;padding:8px 14px;cursor:pointer;font-weight:600}
+#out{display:none;width:100%;height:150px;margin:10px 0;font:12px/1.4 Consolas,monospace}
+blockquote{border-left:3px solid #0e6e63;margin:8px 0;padding:4px 10px;background:#f2f5f4}
+.hint{color:#55605c;font-size:12px;font-style:italic}
+tfoot td{font-weight:600}
+ul{margin:6px 0;padding-left:22px}
+#save{background:#0e6e63;color:#fff;border:none;border-radius:6px;padding:8px 14px;cursor:pointer;font-weight:600}
+#copy{background:none;color:#0e6e63;border:1px solid #0e6e63}
+</style>
+</head>
+<body>
+<header><h1 id="title">Artifact editor</h1><span id="toolbar"></span></header>
+<main>
+<textarea id="out" readonly></textarea>
+<div id="body"><p class="hint">Waiting for the artifact…</p></div>
+</main>
+<script>
+/* ---- MCP Apps postMessage bridge (app <-> host) ---- */
+let DOC = {lines: [], tables: []};
+let nextId = 1;
+const pending = new Map();
+function send(msg) { window.parent.postMessage(msg, "*"); }
+function request(method, params) {
+  return new Promise((resolve, reject) => {
+    const id = nextId++;
+    pending.set(id, {resolve, reject});
+    send({jsonrpc: "2.0", id, method, params});
+  });
+}
+function notify(method, params) { send({jsonrpc: "2.0", method, params}); }
+window.addEventListener("message", ev => {
+  if (ev.source !== window.parent) return;
+  const m = ev.data;
+  if (!m || m.jsonrpc !== "2.0") return;
+  if (m.id !== undefined && m.method === undefined) {              /* response */
+    const p = pending.get(m.id); if (!p) return;
+    pending.delete(m.id);
+    if (m.error) p.reject(m.error); else p.resolve(m.result);
+    return;
+  }
+  if (m.method === "ui/notifications/tool-input") return;          /* render comes from tool-result */
+  if (m.method === "ui/notifications/tool-result") {
+    const sc = m.params && m.params.structuredContent;
+    if (sc) initDoc(sc);
+    return;
+  }
+  if (m.method === "ui/resource-teardown" && m.id !== undefined) {
+    send({jsonrpc: "2.0", id: m.id, result: {}});
+  }
+});
+request("ui/initialize", {
+  appInfo: {name: "estimating-artifact-editor", version: "1.0.0"},
+  appCapabilities: {},
+  protocolVersion: "2026-01-26",
+}).then(res => {
+  const theme = res && res.hostContext && res.hostContext.theme;
+  if (theme) document.documentElement.dataset.theme = theme;
+  notify("ui/notifications/initialized", {});
+}, () => {});
+function initDoc(sc) {
+  DOC = {lines: sc.lines, tables: sc.tables};
+  document.title = sc.title || "Artifact";
+  document.getElementById("title").textContent = sc.title || "Artifact";
+  document.getElementById("body").innerHTML = sc.body;  /* server-escaped fragment */
+  const tb = document.getElementById("toolbar");
+  tb.textContent = "";
+  if (sc.editable) {
+    const save = document.createElement("button");
+    save.id = "save"; save.textContent = "Save & send to chat";
+    const copy = document.createElement("button");
+    copy.id = "copy"; copy.textContent = "Copy edited artifact";
+    tb.append(save, copy);
+  }
+  recompute();
+}
+document.addEventListener("click", e => {
+  if (e.target.id === "save") {
+    const md = exportMarkdown();
+    e.target.disabled = true;
+    request("ui/message", {role: "user", content: [{type: "text", text: md}]}).then(
+      res => {
+        if (res && res.isError) {                 /* McpUiMessageResult soft failure */
+          e.target.disabled = false; copyOut(e.target, md); return;
+        }
+        e.target.textContent = "Sent ✓ — check the chat";
+        e.target.disabled = false;                /* repeat Saves are supported */
+      },
+      () => { e.target.disabled = false; copyOut(e.target, md); });
+  }
+});
+/* GRID-CORE begin — byte-identical across surfaces (test-enforced) */
+function dataCells(tr) {
+  return [...tr.querySelectorAll("td")].filter(
+    td => !td.classList.contains("ext") && !td.classList.contains("ctl"));
+}
+function cellText(td) { return td.innerText.replace(/\n/g, " ").trim(); }
+function serializeRow(cells) {
+  return "| " + cells.map(c => c.replace(/\|/g, "\\|")).join(" | ") + " |";
+}
+function exportMarkdown() {
+  const lines = DOC.lines.slice();
+  [...DOC.tables].sort((a, b) => b.start - a.start).forEach(t => {
+    const body = [...document.querySelectorAll(
+      'table[data-t="' + t.t + '"] tbody tr')].map(
+      tr => serializeRow(dataCells(tr).map(cellText)));
+    lines.splice(t.start + 2, t.end - t.start - 2, ...body);
+  });
+  return lines.join("\n");
+}
+function money(x) { return isFinite(x) ? x.toFixed(2) : ""; }
+function recompute() {
+  DOC.tables.forEach(t => {
+    if (!t.computed) return;
+    let total = 0;
+    document.querySelectorAll('table[data-t="' + t.t + '"] tbody tr').forEach(tr => {
+      const cells = dataCells(tr);
+      const ext = tr.querySelector("td.ext");
+      const v = parseFloat(cellText(cells[t.computed[0]]).replace(/,/g, "")) *
+                parseFloat(cellText(cells[t.computed[1]]).replace(/,/g, ""));
+      if (isFinite(v)) { ext.textContent = money(v); total += v; }
+      else ext.textContent = "";
+    });
+    const tot = document.querySelector('table[data-t="' + t.t + '"] tfoot .total');
+    if (tot) tot.textContent = money(total);
+  });
+}
+function copyOut(btn, md) {
+  const out = document.getElementById("out");
+  out.value = md; out.style.display = "block";
+  const done = () => { btn.textContent = "Copied ✓ — paste into the chat"; };
+  const fallback = () => {
+    btn.textContent = "Copy the block below, then paste into the chat";
+    out.select();
+  };
+  if (navigator.clipboard && navigator.clipboard.writeText) {
+    navigator.clipboard.writeText(md).then(done, fallback);
+  } else { fallback(); }
+}
+document.addEventListener("input", recompute);
+document.addEventListener("focusin", e => {
+  /* select the cell's contents on focus: typing replaces the value (so the
+     add-row "-" placeholder never concatenates), tabbing through loses nothing */
+  const td = e.target;
+  if (!td.isContentEditable || td.tagName !== "TD") return;
+  const sel = window.getSelection(), r = document.createRange();
+  r.selectNodeContents(td); sel.removeAllRanges(); sel.addRange(r);
+});
+document.addEventListener("click", e => {
+  if (e.target.classList.contains("del")) {
+    e.target.closest("tr").remove(); recompute(); return;
+  }
+  if (e.target.classList.contains("add")) {
+    const t = DOC.tables.find(x => String(x.t) === e.target.dataset.t);
+    const tr = document.createElement("tr");
+    for (let i = 0; i < t.width; i++) {
+      const td = document.createElement("td");
+      td.contentEditable = "true"; td.textContent = "-"; tr.appendChild(td);
+    }
+    if (t.computed) {
+      const td = document.createElement("td"); td.className = "ext"; tr.appendChild(td);
+    }
+    const ctl = document.createElement("td"); ctl.className = "ctl";
+    ctl.innerHTML = '<button class="del" title="delete row">×</button>';
+    tr.appendChild(ctl);
+    document.querySelector('table[data-t="' + t.t + '"] tbody').appendChild(tr);
+    recompute(); return;
+  }
+  if (e.target.id === "copy") { copyOut(e.target, exportMarkdown()); }
+});
+/* GRID-CORE end */
+</script>
+</body>
+</html>

estimating_tools/artifact_app/browser.py ADDED Viewed

@@ -0,0 +1,194 @@
+"""Loopback browser surface for the artifact editor (non-Apps hosts).
+One process-lifetime HTTP server on 127.0.0.1:<random port>. Each
+``open_session`` mints a token-guarded session and supersedes the previous one
+(stale saves answer 409 so the page's copy fallback engages). Loopback bind +
+random URL token + Host-header check keep other local processes, other tabs,
+and DNS-rebinding pages out. Pure stdlib; the async MCP server awaits the
+threading.Event via ``anyio.to_thread``.
+"""
+from __future__ import annotations
+import secrets
+import threading
+import webbrowser
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+_MAX_SAVE_BYTES = 4 * 1024 * 1024
+class EditSession:
+    def __init__(self, page_html: str) -> None:
+        self.token = secrets.token_urlsafe(16)
+        self.page_html = page_html
+        self.url = ""                        # set by open_session
+        self.saved_markdown: str | None = None
+        self._saved = threading.Event()
+        self._lock = threading.Lock()
+    def record_save(self, markdown: str) -> None:
+        with self._lock:
+            self.saved_markdown = markdown   # repeat saves: latest wins
+        self._saved.set()
+    def wait_for_save(self, timeout: float) -> str | None:
+        if self._saved.wait(timeout):
+            with self._lock:
+                return self.saved_markdown
+        return None
+_lock = threading.Lock()
+_server: ThreadingHTTPServer | None = None
+_session: EditSession | None = None
+# Single-generation memory: only the immediately-previous session gets the
+# tailored 409; older tabs fall through to 404 and the page's copy fallback.
+_prev_token: str | None = None
+class _Handler(BaseHTTPRequestHandler):
+    def log_message(self, *args) -> None:      # stdio server: keep stderr quiet
+        pass
+    def _reply(self, code: int, body: str, ctype: str = "text/plain") -> None:
+        data = body.encode("utf-8")
+        self.send_response(code)
+        self.send_header("Content-Type", f"{ctype}; charset=utf-8")
+        self.send_header("Content-Length", str(len(data)))
+        self.send_header("Cache-Control", "no-store")
+        self.end_headers()
+        self.wfile.write(data)
+    def _drain_body(self) -> None:
+        """Read and discard the declared request body before an error reply.
+        Windows resets the connection if we close with unread data, so the
+        client would see ECONNABORTED instead of our status code. Bounded by
+        the declared Content-Length; chunked to avoid one giant allocation.
+        Capped at 2 * _MAX_SAVE_BYTES: legitimate clients (even a 413-bound
+        save just over the limit) stay under the cap and get clean replies;
+        a liar declaring more gets a fail-fast close instead of streaming
+        forever through the 403/404/409 paths.
+        """
+        try:
+            remaining = int(self.headers.get("Content-Length") or 0)
+        except ValueError:
+            self.close_connection = True     # undrainable: unknown length
+            return
+        if remaining > 2 * _MAX_SAVE_BYTES:
+            self.close_connection = True
+            return
+        while remaining > 0:
+            chunk = self.rfile.read(min(remaining, 65536))
+            if not chunk:
+                break
+            remaining -= len(chunk)
+    def _gate(self) -> EditSession | None:
+        """Return the live session for this request path, else reply and None."""
+        host = (self.headers.get("Host") or "").rsplit(":", 1)[0]
+        if host not in ("127.0.0.1", "localhost"):
+            self._drain_body()
+            self._reply(403, "forbidden")
+            return None
+        with _lock:
+            session, prev = _session, _prev_token
+        token = self.path.split("/", 2)[1] if self.path.count("/") >= 2 else ""
+        # compare_digest: constant-time; bytes form tolerates non-ASCII paths.
+        token_b = token.encode("utf-8")
+        if session is not None and secrets.compare_digest(token_b, session.token.encode("utf-8")):
+            return session
+        self._drain_body()
+        if prev is not None and secrets.compare_digest(token_b, prev.encode("utf-8")):
+            self._reply(409, "session superseded — reopen the editor from the conversation")
+        else:
+            self._reply(404, "not found")
+        return None
+    def do_GET(self) -> None:
+        session = self._gate()
+        if session is None:
+            return
+        if self.path == f"/{session.token}/":
+            self._reply(200, session.page_html, ctype="text/html")
+        else:
+            self._drain_body()
+            self._reply(404, "not found")
+    def do_POST(self) -> None:
+        session = self._gate()
+        if session is None:
+            return
+        if self.path != f"/{session.token}/save":
+            self._drain_body()
+            self._reply(404, "not found")
+            return
+        try:
+            length = int(self.headers.get("Content-Length") or 0)
+        except ValueError:
+            # Unknown length: can't drain meaningfully — reply and hard-close.
+            self.close_connection = True
+            self._reply(400, "bad request")
+            return
+        if length < 0:
+            self.close_connection = True
+            self._reply(400, "bad request")
+            return
+        if length > _MAX_SAVE_BYTES:
+            self._drain_body()               # drain before the reply (RST fix)
+            self._reply(413, "artifact too large")
+            return
+        try:
+            markdown = self.rfile.read(length).decode("utf-8")
+        except UnicodeDecodeError:
+            self._reply(400, "bad request")  # body fully read — no drain needed
+            return
+        session.record_save(markdown)
+        self._reply(200, "saved")
+def _start_server() -> ThreadingHTTPServer:
+    server = ThreadingHTTPServer(("127.0.0.1", 0), _Handler)
+    threading.Thread(target=server.serve_forever, daemon=True).start()
+    return server
+def open_session(page_html: str) -> tuple[EditSession, str]:
+    """Serve ``page_html`` under a fresh token, superseding any prior session."""
+    global _server, _session, _prev_token
+    with _lock:
+        if _server is None:
+            _server = _start_server()
+        if _session is not None:
+            _prev_token = _session.token
+        session = EditSession(page_html)
+        port = _server.server_address[1]
+        session.url = f"http://127.0.0.1:{port}/{session.token}/"
+        _session = session
+        return session, session.url
+def current_session() -> EditSession | None:
+    with _lock:
+        return _session
+def await_save(session: EditSession, timeout: float) -> str | None:
+    return session.wait_for_save(timeout)
+def open_browser(url: str) -> bool:
+    try:
+        return webbrowser.open(url)
+    except Exception:
+        return False
+def shutdown() -> None:
+    """Tear down server + sessions (tests; harmless if never started)."""
+    global _server, _session, _prev_token
+    with _lock:
+        server, _server, _session, _prev_token = _server, None, None, None
+    if server is not None:
+        server.shutdown()
+        server.server_close()