plexora 0.0.1__py3-none-any.whl

plexora/server/routes/page_routes.py

@@ -0,0 +1,139 @@
+from plexora import app, get_config, get_config_names, paths
+from plexora.server.models.project import (
+    Project, config_transaction, read_config, write_config,
+)
+from plexora.server import plugins as plugin_registry
+from flask import abort, render_template, send_from_directory, request
+from pathlib import Path
+import datetime
+import os
+
+
+def template_data(**values):
+    base_url = app.config.get('PLEXORA_BASE_URL', '')
+    data = {
+        'datasource': '',
+        'datasources': get_config_names(),
+        'is_docker': app.config.get('IS_DOCKER', False),
+        # Whether this process is a notebook sidecar or behind a hosted proxy.
+        # Templates use it to hide controls that act on the SERVER's machine --
+        # Quit, native file dialogs -- which in that mode is not the user's.
+        'notebook_mode': app.config.get('PLEXORA_NOTEBOOK_MODE', False),
+        'base_url': base_url,
+        # Menu entries contributed by installed plugins, as data rather than
+        # markup -- core renders them with its own classes. Filled in here, in
+        # the one place every page's context is built, because base.html's File
+        # menu is on every page and a key it reads must never be absent.
+        # Empty on a core-only build, where every consumer renders nothing.
+        'plugin_nav_items': plugin_registry.nav_items(app, base_url),
+        # Which tool this page view asked to open, and which tools the
+        # navbar should offer. Both are per-request: several plugins can be
+        # installed at once, and which of them apply depends on the
+        # datasource, so neither can be a process-wide flag.
+        'active_tool': '',
+        'available_tools': [],
+        # Assets and panel templates of the active plugin, so templates never
+        # name one. Empty on every page that has no tool open.
+        'active_tool_scripts': [],
+        'active_tool_styles': [],
+        'active_tool_panels': {},
+    }
+    data.update(values)
+    return data
+
+
+@app.route("/")
+def my_index():
+    return render_template("index.html", data=template_data())
+
+
+@app.route("/favicon.ico")
+def favicon():
+    return send_from_directory(
+        Path(app.config['CLIENT_PATH']) / 'src' / 'img', 'favicon.ico', conditional=True
+    )
+
+
+def _stamp_last_opened(datasource):
+    """Record when a project was last opened, for the Open Project page's
+    "Recently Opened" sort. Best-effort: a failure here should never break
+    opening the viewer itself.
+
+    Skipped outright for a project on a read-only shared root. Catching the
+    failure would be correct but slow: write_config retries for two seconds
+    past what looks like a transient Windows sharing violation, and paying that
+    on every open of a shared project would be a visible stall for a sort key.
+    """
+    config_file = Project.config_path_for(datasource)
+    if not paths.is_writable(config_file.parent):
+        return
+    try:
+        with config_transaction():
+            config_data = read_config(config_file)
+            if datasource in config_data:
+                config_data[datasource]['lastOpenedAt'] = datetime.datetime.now().isoformat()
+                write_config(config_file, config_data)
+    except (OSError, ValueError):
+        pass
+
+
+@app.route('/<string:datasource>')
+def image_viewer(datasource):
+    datasources = get_config_names()
+    if datasource not in datasources:
+        # This rule matches any single path segment, so it is the last thing
+        # standing between a wrong URL and a 404. It used to render the empty
+        # viewer instead, which meant a request for a route that does not exist
+        # -- a removed plugin's endpoint, a typo, a probe -- came back 200 with
+        # a full HTML page. Callers expecting JSON got HTML and no error.
+        abort(404)
+    _stamp_last_opened(datasource)
+    project = Project.load(datasource)
+    image_kind = project.image.kind
+
+    # Two different lists on purpose. The menu offers every tool COMPATIBLE
+    # with this datasource, including ones still missing an input -- opening
+    # those is how the user gets asked for it. A tool is only ACTIVATED if it
+    # can actually run, so a stale ?tool= link to an uninstalled, inapplicable
+    # or not-yet-ready tool renders the plain viewer rather than a panel that
+    # cannot work.
+    base_url = app.config.get('PLEXORA_BASE_URL', '')
+    offered = plugin_registry.tools_for(app, project)
+    ready = plugin_registry.ready_tools(app, project)
+    requested_tool = request.args.get('tool', '')
+    active_tool = requested_tool if any(p.name == requested_tool for p in ready) else ''
+
+    active = next((p for p in ready if p.name == active_tool), None)
+    return render_template(
+        'index.html',
+        data=template_data(
+            datasource=datasource,
+            datasources=datasources,
+            image_kind=image_kind,
+            active_tool=active_tool,
+            available_tools=[p.describe() for p in offered],
+            active_tool_scripts=active.asset_urls('scripts', base_url) if active else [],
+            active_tool_styles=active.asset_urls('styles', base_url) if active else [],
+            active_tool_panels=dict(active.panels) if active else {},
+        ),
+    )
+
+
+
+@app.route("/upload_page")
+def upload_page():
+    """The one import screen: image, optional mask, optional data.
+
+    It has no "attach to an existing project" mode any more. Adding data to a
+    project that already exists is an edit, and the edit page does it -- so
+    there is one place that knows how to change a project rather than an
+    import form with a second personality.
+    """
+    return render_template("upload.html", data=template_data())
+
+
+
+
+@app.route('/client/<path:filename>')
+def serveClient(filename):
+    return send_from_directory(app.config['CLIENT_PATH'], filename, conditional=True)

plexora/server/routes/project_routes.py

@@ -0,0 +1,438 @@
+# Open Project page -- lists prior projects with search/sort/grid-list view,
+# replacing the old inline project list in the File dropdown (base.html).
+from plexora import app, get_config, paths
+from plexora.server import plugins as plugin_registry
+from plexora.server.models import data_model
+from plexora.server.models.adapters.inspection import source_layers, source_obsm
+from plexora.server.models.project import ROLE_LABELS, ROLE_NAMES, Project
+from plexora.server.routes import tool_routes
+from plexora.server.routes.page_routes import template_data
+
+from flask import render_template, jsonify, redirect, request, send_file, abort
+from pathlib import Path
+import datetime
+import io
+import shutil
+
+
+def _base_url():
+    return app.config.get('PLEXORA_BASE_URL', '')
+
+_THUMBNAIL_CACHE_NAME = '.thumbnail.webp'
+
+
+@app.route('/open_project')
+def open_project_page():
+    return render_template('open_project.html', data=template_data())
+
+
+def _fallback_timestamp(name, home_root=None):
+    """Best-effort date for projects saved before createdAt/lastOpenedAt
+    existed: macOS reports true creation time via st_birthtime, everything
+    else falls back to st_ctime (metadata-change time, the closest
+    approximation available)."""
+    try:
+        stat = paths.project_dir(name, home_root).stat()
+    except OSError:
+        return None
+    seconds = getattr(stat, 'st_birthtime', stat.st_ctime)
+    return datetime.datetime.fromtimestamp(seconds).isoformat()
+
+
+@app.route('/projects')
+def list_projects():
+    config = get_config()
+    # Which root each name came from, read once for the whole listing rather
+    # than per project -- `shared` decides whether the card offers rename and
+    # delete, so it cannot be left for the client to guess.
+    homes = Project.load_roots()
+    own = paths.data_root()
+    projects = []
+    for name, entry in config.items():
+        entry = entry or {}
+        home_root = homes.get(name)
+        created_at = entry.get('createdAt') or _fallback_timestamp(name, home_root)
+        last_opened_at = entry.get('lastOpenedAt') or created_at
+        projects.append({
+            'name': name,
+            'createdAt': created_at,
+            'lastOpenedAt': last_opened_at,
+            'thumbnailUrl': f'/project_thumbnail/{name}',
+            'shared': home_root is not None and home_root != own,
+        })
+    return jsonify(projects)
+
+
+@app.route('/project_thumbnail/<string:name>')
+def project_thumbnail(name):
+    config = get_config()
+    if name not in config:
+        abort(404)
+
+    # A derived image, so it follows the same rule as every other derived
+    # artifact: beside the project when that root takes writes, in this user's
+    # own root when it does not.
+    cache_path = paths.derived_root(name) / _THUMBNAIL_CACHE_NAME
+    if cache_path.exists():
+        return send_file(cache_path, mimetype='image/webp')
+
+    result = data_model.generate_thumbnail(name)
+    if result is None:
+        abort(404)
+    encoded, mimetype = result
+    try:
+        cache_path.write_bytes(encoded)
+    except OSError:
+        pass  # Cache is best-effort -- still serve the freshly generated bytes.
+    return send_file(io.BytesIO(encoded), mimetype=mimetype)
+
+
+# --------------------------------------------------------------------------
+# Editing an existing project
+#
+# The old edit page read a project as if its source file were a CSV, rendered
+# the CSV column-matching screen, and posted to a handler that rebuilt the
+# config entry from `{}` -- which discarded the data type and the AnnData read
+# spec, repointed the source at a CSV that did not exist, and reported the
+# whole thing as HTTP 200. Editing an AnnData project destroyed it, silently.
+#
+# What replaces it is generated from the project record, so it shows only the
+# fields that project actually has, and saves through Project.patch(), which
+# merges. There is no code path here that can drop a key it did not name.
+# --------------------------------------------------------------------------
+
+@app.route('/edit_config/<string:name>')
+@app.route('/edit_config', methods=['GET'])
+def edit_project_page(name=None):
+    name = name or request.args.get('config')
+    project = Project.find(name) if name else None
+    if project is None:
+        return redirect(f"{_base_url()}/open_project")
+
+    return render_template('project_edit.html', data=template_data(
+        datasetName=name,
+        project=_describe(project),
+        needs=_needs_for_tool(project, request.args.get('needs')),
+    ))
+
+
+def known_layers(project):
+    """The project with `dataset.layers` filled in, reading the file when they
+    were never recorded.
+
+    In memory only -- nothing is written back, so this is safe on the GET paths
+    that render a picker. Shared with tool_routes, which needs the same list to
+    put the matrix question in the requirements modal: without the backfill, a
+    project imported before layers were recorded would be offered a choice of
+    one, which is exactly the project that most needs the choice.
+    """
+    if project.dataset and not project.dataset.layers:
+        return project.with_layers(source_layers(project.dataset))
+    return project
+
+
+def known_obsm(project):
+    """The project with `dataset.obsm` filled in, reading the file when it was
+    never recorded.
+
+    Exactly `known_layers`' job for the coordinate question, and needed more
+    urgently: a project imported before obsm was recorded had its coordinate
+    source chosen by a name heuristic and offers no way to see, let alone
+    correct, what was chosen.
+    """
+    if project.dataset and not project.dataset.obsm:
+        return project.with_obsm(source_obsm(project.dataset))
+    return project
+
+
+def _describe(project):
+    """The project as the edit page and the requirements modal consume it.
+
+    Deliberately not the raw entry: the page renders sections from `has`, so
+    what it asks about is decided here, once, from the record -- rather than by
+    a template guessing which fields might apply to which kind of project.
+    """
+    project = known_obsm(known_layers(project))
+    spec = project.dataset
+    layers = list(spec.layers) if spec else []
+    return {
+        "name": project.name,
+        "image": {
+            "src": project.image.src,
+            "kind": project.image.kind,
+            "channelCount": project.image.num_channels,
+            "size": [project.image.width, project.image.height],
+        },
+        "segmentation": {
+            "src": project.segmentation.source,
+            "available": project.segmentation.available,
+            "pending": project.segmentation.pending,
+            "mode": project.segmentation.mode,
+        },
+        "data": None if spec is None else {
+            "type": spec.type,
+            "src": spec.src,
+            "table": spec.table,
+            "coordinates": dict(spec.coordinates),
+            "features": dict(spec.features),
+            "subset": dict(spec.subset),
+            "isTransformed": spec.is_transformed,
+            "layers": layers,
+        },
+        # Which matrix the intensities are read from, in the same "X" /
+        # "layer:<name>" vocabulary the import form's picker uses, plus whether
+        # they are log1p'd on the way in. Two halves of one question -- what
+        # numbers is this project actually showing.
+        "featureSource": project.feature_source,
+        "featureOptions": project.feature_options,
+        "featureLog": project.log_transformed,
+        # Both, because they are different facts. `cellLayer` is what the
+        # project resolves to and is what the select shows; `cellLayerChoice`
+        # is whether that was a decision or a default, which is the difference
+        # between a form the user can leave alone and one that records an
+        # override every time it is saved.
+        "cellLayer": project.cell_layer,
+        "cellLayerChoice": project.cell_layer_choice,
+        "cellLayerOptions": project.cell_layer_options,
+        "roles": project.roles.to_dict(),
+        "roleLabels": dict(ROLE_LABELS),
+        # The role selects, in the vocabulary the question is asked in -- obs
+        # columns for AnnData and SpatialData, table columns for a CSV. See
+        # Project.role_columns; this page and the requirements modal render
+        # from the same three keys so they cannot drift.
+        "roleColumns": project.role_columns,
+        "roleAnswers": project.role_answers,
+        "roleDefaults": project.role_defaults,
+        # The coordinate question's own material: every obsm array with its
+        # shape, every obs column, and the source recorded now. Separate from
+        # the role keys because its answer is a read spec rather than a column
+        # name -- an obsm array supplies both axes at once.
+        "coordinateOptions": project.coordinate_options,
+        "singleImage": bool(spec and spec.single_image),
+        "rowNumberIds": bool(spec and spec.row_number_ids),
+        "editableRoles": _editable_roles(project),
+        "columns": {
+            "markers": list(project.columns.markers),
+            "metadata": list(project.columns.metadata),
+        },
+        # Which sections the page renders. A project with only an image has no
+        # roles to assign and no columns to classify, so it is not shown empty
+        # controls for them.
+        "has": {
+            "data": project.has_table,
+            "columns": project.has_table and spec.type == "csv",
+            "readSpec": project.has_table and spec.type in ("anndata", "spatialdata"),
+            "segmentation": project.segmentation.requested,
+            # Any project with a table. The matrix select needs more than one
+            # matrix to be worth showing -- the template guards it on
+            # `data.layers`, so a CSV gets the log switch alone -- but that
+            # switch is a real question for every format: whether the numbers
+            # are raw counts is not something the file says, and a CSV of raw
+            # counts is the commonest case of all. This used to be restricted
+            # to the formats that state their own marker split, which left CSV
+            # projects with no way to reach the transform at all.
+            "features": project.has_table,
+            # Offered only once there is something to choose between: a project
+            # with neither a mask nor coordinates cannot draw cells at all.
+            "cellLayer": bool(project.cell_layer_options),
+        },
+    }
+
+
+def _editable_roles(project):
+    """Which roles this project's user may reassign.
+
+    All of them, for every format. `cell_id`, `x` and `y` used to be withheld
+    from AnnData and SpatialData projects because the adapter synthesizes those
+    columns, so repointing the role named a column the loaded table did not
+    have. They are answerable now because the answer goes into the read spec
+    instead -- which is the only way to say "the mask's label values are in this
+    obs column", and without it a segmentation overlay could never line up.
+    """
+    return list(ROLE_NAMES) if project.has_table else []
+
+
+def _needs_for_tool(project, tool_name):
+    """The requirements a named tool is still missing, so the edit page can
+    highlight exactly those fields. This is the no-JavaScript twin of the
+    requirements modal -- same question, same answer, different surface."""
+    if not tool_name:
+        return None
+    plugin = plugin_registry.find(app, tool_name)
+    if plugin is None or not plugin.requires.applies_to(project):
+        return None
+    return {
+        "tool": plugin.name,
+        "label": plugin.label,
+        "missing": [r.describe() for r in plugin.requires.missing_from(project)],
+        "confirm": [r.describe() for r in plugin.requires.unconfirmed_from(project)],
+        "optional": [r.describe() for r in plugin.requires.optional_missing_from(project)],
+    }
+
+
+@app.route('/project/<string:name>', methods=['POST'])
+def save_project(name):
+    """Apply an edit. Everything except the image can change.
+
+    Merge semantics throughout: a key the request does not mention is carried
+    across untouched. The expensive work -- re-reading a new data file,
+    converting a new mask -- runs only when that input actually changed, which
+    is what makes saving an unchanged form free.
+    """
+    payload = request.get_json(silent=True) or {}
+    project = Project.find(name)
+    if project is None:
+        return jsonify(success=False, error="Unknown project"), 404
+
+    try:
+        changed = _apply_edit(project, payload)
+    except ValueError as exc:
+        # A bad path or an unreadable file is the user's to fix, and they need
+        # to be told which. The old handler returned success=False with HTTP
+        # 200 and no message, and the client navigated away regardless.
+        return jsonify(success=False, error=str(exc)), 400
+
+    if changed:
+        # An answer is only accepted once the file can be read with it, so a
+        # role that rewrites the read spec into something the adapter refuses
+        # is put back rather than left stored -- see tool_routes.
+        error = tool_routes._reload_or_restore(name, project)
+        if error:
+            return jsonify(success=False, error=error), 400
+
+    project = Project.find(name)
+    return jsonify(success=True, reloaded=changed,
+                   segmentation_pending=project.segmentation.pending)
+
+
+def _apply_edit(project, payload):
+    """Returns whether anything changed that needs a datasource reload."""
+    from plexora.server.routes import import_routes
+
+    changed = False
+
+    if "segmentation" in payload:
+        wanted = (payload.get("segmentation") or "").strip() or None
+        current = project.segmentation.source
+        if (wanted or None) != (current or None):
+            if wanted and not Path(wanted).expanduser().exists():
+                raise ValueError(f"No such segmentation mask: {wanted}")
+            import_routes.attach_segmentation(project.name, wanted)
+            changed = True
+
+    swapped = False
+    if "data" in payload:
+        wanted = (payload.get("data") or "").strip() or None
+        current = project.dataset.src if project.dataset else None
+        if (wanted or None) != (current or None):
+            import_routes.replace_project_data(project.name, wanted, payload)
+            changed = True
+            swapped = True
+
+    # Only when the file itself did not change: replace_project_data already
+    # reads `features_layer` out of this same payload, and applying it twice
+    # would validate the new choice against the old file's layer list.
+    if not swapped:
+        changed = apply_feature_choice(project, payload) or changed
+
+    roles = payload.get("roles")
+    columns = payload.get("columns")
+    coordinates = payload.get("coordinates")
+    single_image = payload.get("single_image")
+    row_number_ids = payload.get("row_number_ids")
+    # Presence, not truth: "" is the client saying "no override, draw whatever
+    # this project resolves to", which is a change worth applying and would be
+    # dropped by a plain truthiness test.
+    chose_layer = "cellLayer" in payload
+    cell_layer = payload.get("cellLayer")
+    confirm = payload.get("confirm")
+    if (roles or columns or coordinates or single_image or row_number_ids
+            or chose_layer or confirm):
+        def _apply(current):
+            if columns:
+                current = current.with_columns(columns.get("markers") or [],
+                                               columns.get("metadata") or [])
+            # The same helper the requirements modal applies its answers with,
+            # so the two surfaces cannot disagree about what a payload means.
+            current = tool_routes.apply_column_answers(current, payload)
+            if chose_layer:
+                current = current.with_cell_layer(cell_layer)
+            # Saving this page is the user looking at these values and
+            # accepting them, which is exactly what the requirements modal asks
+            # for -- so a tool opened afterwards must not ask again.
+            return current.with_confirmed(confirm or ())
+
+        Project.mutate(project.name, _apply)
+        # A cell-layer choice on its own changes nothing the datasource holds;
+        # it is read from the config by the viewer. Reloading for it would
+        # re-open the image to record a preference.
+        changed = changed or bool(roles or columns or coordinates
+                                  or row_number_ids)
+
+    return changed
+
+
+def apply_feature_choice(project, payload):
+    """Point the reader at a matrix and/or switch the log1p transform.
+
+    Shared with the requirements modal (tool_routes), because both surfaces ask
+    the same question and getting the answer to stick means the same two writes.
+    Returns whether anything changed -- both halves change what every number in
+    the app is, so either one needs the datasource re-read.
+    """
+    layer = payload.get("features_layer")
+    has_log = "features_log" in payload
+    log = bool(payload.get("features_log"))
+    wants_layer = bool(layer) and layer != project.feature_source
+    wants_log = has_log and log != project.log_transformed
+    if not wants_layer and not wants_log:
+        return False
+
+    # Read outside the write lock: the layer list may come off disk, and holding
+    # config.json's lock across a file read serializes every other writer behind
+    # it for no reason.
+    layers = source_layers(project.dataset) if wants_layer else None
+
+    def _change(current):
+        # The available list goes in first, so a project imported before it was
+        # recorded validates the choice against the file rather than against an
+        # empty tuple that would reject every layer.
+        if wants_layer:
+            current = current.with_layers(layers).with_feature_source(layer)
+        if wants_log:
+            current = current.with_log_transform(log)
+        return current
+
+    Project.mutate(project.name, _change)
+    return True
+
+
+@app.route('/project/<string:name>/delete', methods=['POST'])
+def delete_project(name):
+    """Remove a project and everything derived for it.
+
+    POST, not GET: this is an irreversible rmtree, and it used to sit behind a
+    link that any crawler, prefetcher or stale bookmark could follow.
+    """
+    project = Project.find(name)
+    if project is None:
+        return jsonify(success=False, error="Unknown project"), 404
+    if project.is_shared:
+        # A shared project belongs to whoever provisioned the root it sits on.
+        # Refused here rather than allowed to fail against a read-only
+        # filesystem, so the answer is a sentence rather than a traceback --
+        # and so a WRITABLE shared root cannot let one user delete a project
+        # every other user on the machine is working from.
+        return jsonify(
+            success=False,
+            error="This project is on a shared data directory and cannot be "
+                  "deleted from Plexora.",
+        ), 403
+
+    project.delete()
+    # Only this user's own copy of the project directory. For a project the
+    # user owns that is the whole of it; there is nothing else anywhere.
+    directory = paths.project_state_dir(name)
+    if directory.is_dir():
+        shutil.rmtree(directory, ignore_errors=True)
+    return jsonify(success=True)

plexora/server/routes/quick_view_routes.py

@@ -0,0 +1,62 @@
+# "Quick view" landing page: register a datasource from just a local image
+# path (no CSV/segmentation/h5ad) and hand the client a redirect straight
+# into the viewer. Paths only, never bytes -- see datasource.py's
+# register_image_datasource/register_rgb_datasource docstrings.
+
+from pathlib import Path
+
+from flask import jsonify, request, send_file
+
+from plexora import app, get_config, get_config_names
+from plexora.datasource import (
+    _dedupe_dataset_name,
+    _derive_dataset_name_from_path,
+    _find_existing_datasource_for_image,
+    _sniff_quick_view_kind,
+    register_image_datasource,
+    register_rgb_datasource,
+)
+from plexora.server.routes.import_routes import trim_filepath_quotes
+
+
+@app.route('/quick_view', methods=['POST'])
+def quick_view():
+    payload = request.get_json(silent=True) or {}
+    path = trim_filepath_quotes((payload.get('path') or '').strip())
+
+    if not path or not Path(path).is_file():
+        return jsonify(success=False, error="File does not exist."), 400
+
+    base_url = app.config.get('PLEXORA_BASE_URL', '')
+
+    # Same image already registered (quick-viewed before, or imported through
+    # the full wizard) -- reopen that project instead of creating a duplicate.
+    existing_name = _find_existing_datasource_for_image(path, get_config())
+    if existing_name:
+        return jsonify(success=True, name=existing_name, redirect=f"{base_url}/{existing_name}")
+
+    try:
+        kind = _sniff_quick_view_kind(path)
+    except ValueError as exc:
+        return jsonify(success=False, error=str(exc)), 400
+
+    name = _dedupe_dataset_name(_derive_dataset_name_from_path(path), get_config_names())
+
+    try:
+        if kind == 'ome_tiff':
+            register_image_datasource(name=name, image=path)
+        else:
+            register_rgb_datasource(name=name, image=path)
+    except Exception as exc:
+        return jsonify(success=False, error=str(exc)), 400
+
+    return jsonify(success=True, name=name, redirect=f"{base_url}/{name}")
+
+
+@app.route('/generated/rgb/<string:datasource>')
+def generate_rgb_image(datasource):
+    config = get_config()
+    entry = config.get(datasource)
+    if not entry or entry.get('image_kind') != 'rgb':
+        return jsonify(error="Not an RGB quick-view datasource."), 404
+    return send_file(entry['channelFile'])

plexora/server/routes/system_routes.py

@@ -0,0 +1,39 @@
+# Process lifecycle routes for the local desktop app (File > Quit).
+#
+# Plexora has no native window/process the frontend already controls -- it's
+# a headless waitress server the user opens in their own browser -- so Quit
+# has to be a request that tells this process to terminate itself. os._exit
+# skips normal interpreter teardown, which is fine here: waitress's serve()
+# loop never returns on its own, so there's no clean in-process shutdown path
+# to call instead, and the user closing the terminal/window today has the
+# same abrupt effect.
+from plexora import app
+from flask import Response, jsonify
+import os
+
+
+@app.route('/shutdown', methods=['POST'])
+def shutdown():
+    # In a notebook the server is a sidecar the kernel owns: it was started by
+    # PlexoraViewer, it is tracked in that module's registry, and atexit is
+    # what stops it. os._exit here would kill it behind the kernel's back,
+    # leaving a viewer object whose iframe silently stops loading and no way to
+    # get it back short of restarting the kernel. Under a hosted proxy it is
+    # worse still -- the "process" the button would end is one the hub spawned.
+    if app.config.get('PLEXORA_NOTEBOOK_MODE'):
+        return jsonify(error="Shutdown is managed by the notebook session."), 403
+    os._exit(0)
+    return Response(status=204)
+
+
+@app.route('/health', methods=['GET'])
+def health():
+    """Liveness probe for the navbar status indicator (appStatus.js).
+
+    Deliberately does no work -- not even touching the loaded datasource -- so
+    the 10 s poll can never contend with tile serving. It answers exactly one
+    question: is this process still accepting requests? An idle page issues no
+    other requests, so without this a server that died minutes ago would still
+    show as connected.
+    """
+    return Response(status=204)