3lc-compute-plugin-sdk 0.3.1__tar.gz → 0.3.2__tar.gz

{3lc_compute_plugin_sdk-0.3.1 → 3lc_compute_plugin_sdk-0.3.2}/.github/workflows/docs.yml

@@ -1,10 +1,11 @@
 name: docs
 
 # Build the Sphinx docs and publish to GitHub Pages.
-# Manual-only by choice: run from the Actions tab (or `gh workflow run docs`)
-# when the docs should go out — pushes to main do NOT redeploy.
-# One-time setup: repo Settings -> Pages -> Source = "GitHub Actions".
+# Deploys automatically on every release tag, or manually from the Actions tab
+# (`gh workflow run docs`). One-time setup: repo Settings -> Pages -> Source = "GitHub Actions".
 on:
+  push:
+    tags: ["v*"]
   workflow_dispatch:
 
 # Least-privilege token for the Pages deploy.

3lc_compute_plugin_sdk-0.3.2/1.0-READINESS.md

@@ -0,0 +1,434 @@
+# 1.0 readiness report — 3lc-compute-plugin-sdk
+
+*Audit of SDK `main` @ `576bcd5` (0.2.0, includes JS_CONTRACT 0.2 / PR #8), host `3lc-compute` @ `bbf2aed`,
+Hub frontend, and all 9 first-party plugins (exporter, importer, merger, splitter, image-metrics,
+table-statistics, timm, sam3, yolo). Line numbers reference those revisions. Uncommitted working doc.*
+
+**Framing** (per the pre-1.0 window): all consumers are in-house, so breaking is cheap *now* —
+grep-and-fix across our own repos, coordinated via editable overlays and the frontend contract test.
+Every breaking proposal below states who migrates and roughly how.
+
+---
+
+## The shape of the problem (executive summary)
+
+1. **The contract that's written down is healthy; the contract that's *lived* is bigger and undeclared.**
+   The `PluginApi` top level matches the d.ts exactly (the conformance test passes), but the surface
+   plugins actually depend on includes `openTablePicker` (7 of 8 UI plugins), 13 SDK-injected `_tlc*`
+   globals (6 of 8 plugins), `CancelJob`, bare `showToast`, `cssVar`, `plugin-common.css` classes, and
+   an `allowErrorStatus` fetch option the host itself uses 13×. None of that is in the d.ts. 1.0 should
+   be the moment the declared contract and the lived contract become the same thing.
+2. **The job-reporting API is fought by its heaviest users.** `ctx.result(run_url=)` is called by only
+   2 of 7 job plugins — all three GPU trainers smuggle their result URL through `ctx.emit`/`ctx.metric`
+   instead; failure reporting is hand-rolled (`ctx.emit("job_failed", ...)` + `raise`) in duplicate;
+   the failure message rides `PluginJobUpdate.subtitle`. These are the exact warts that freeze at 1.0.
+3. **The version story has three axes and one consumer.** `PY_CONTRACT`/`JS_CONTRACT` are read by
+   nobody (host compares `sdk_version` only; zero plugin references); the manifest `sdk_version` the
+   SDK docstring promises is read by nobody; and `PLUGIN_API.contractVersion` is `''` in every
+   production frontend container. Consolidate to one axis and make it actually reach production.
+4. **Live pin defect, before anything else:** the host and the plugins umbrella pin
+   `3lc-compute-plugin-sdk[shared]>=0.1.0,<0.2.0` — which *excludes the current 0.2.0 release* — so
+   three shipped 0.2 features (host-mode GPU reclaim, `/reclaim`, `/health` skew detection) are inert
+   in the resolved lock (host `pyproject.toml:24`, acknowledged at `job_manager.py:59-71`).
+5. **Ceremony is measurable.** 8/9 plugins repeat the same `_ui_cache` + `Path(__file__)` +
+   `read_text` block; 5/9 implement `compute()` as a dead stub; script injection exists in **four**
+   idioms (two of them the exact footgun `ui_inject.py` was written to eliminate, one injection dead
+   on both ends); the config-CRUD route quartet is copy-pasted 4×; yolo reimplements
+   `PluginConfigStore` wholesale.
+
+---
+
+## A. Break at 1.0 (ranked by leverage)
+
+### A1. Reshape job *reporting*: `result`, failure, and the error field
+
+- **What/where:** `src/tlc_plugin_sdk/job_context.py:75-87` (`result(*, run_url)`),
+  `contract/plugin-api.d.ts` `PluginJobUpdate` (failure message documented as riding `subtitle`),
+  host translation `3lc-compute/src/tlc_compute/plugins/job_manager.py:461-479`.
+- **Why it hurts:** the name `run_url` is wrong for half the producers (importers/exporters/mergers
+  produce *tables*), and the evidence says the API lost its users: only merger (`__init__.py:147`) and
+  importer (`:1553`) call `ctx.result`; timm ships the URL via `ctx.emit("job_completed", {..., "run_url"})`
+  (`timm/__init__.py:258-261`), yolo likewise (`:299-308`), and sam3 abuses `ctx.metric("run", str(run.url))`
+  (`:393-394`) — so the generic panel's "open result" link works for 2 of 7 job plugins. Failure has no
+  first-class API at all: timm `:266-269` and yolo `:311-313` both hand-emit `job_failed` + `raise`, and
+  the frontend reads the failure message out of `subtitle`. All of this freezes at 1.0 if untouched.
+- **Proposed 1.0 shape:**
+  - `ctx.result(url: str, *, kind: str = "run")` (or just `url=`); keep emitting `run_url` on the wire
+    *or* rename the wire field to `result_url` in the same coordinated set.
+  - Add `error` to the generic job record/`PluginJobUpdate` (host sets it from the terminal `error`
+    event); keep `subtitle` as display text. Optionally add `ctx.fail(message)` sugar (equivalent to
+    raising, for validation paths) — that part is additive.
+  - Document `percent=-1` (indeterminate) in `JobContext.progress` itself — today it's only in the
+    guide (`docs/plugin-guide.md:530`), and importer relies on it (`:1578,1621`).
+- **Additive or breaking:** breaking (kwarg rename + wire-field addition/rename).
+- **Who migrates:** SDK (`job_context.py`, d.ts `PluginJobUpdate`); host (`job_manager.py:473-474`,
+  `_Job.to_generic` `:109-122`); frontend (queue-panel/cancel-job read of `run_url`/`subtitle`);
+  plugins: merger + importer one line each, then timm/yolo/sam3 *adopt* `ctx.result` and delete their
+  workarounds (a net simplification, not just a rename).
+- **Effort:** M.
+
+### A2. Collapse the three version axes to one, and make it reach production
+
+- **What/where:** `src/tlc_plugin_sdk/__init__.py:39-56` (`PY_CONTRACT`, `JS_CONTRACT`),
+  `asgi_app.py:52-59` (`/health` reports all three), frontend `app.py:22-28` + `pyproject.toml:17-34`.
+- **Why it hurts:** `PY_CONTRACT`/`JS_CONTRACT` have **zero consumers** — the host's skew check
+  compares only `sdk_version` (`3lc-compute/plugins/versioning.py:128-164`), no plugin reads them, and
+  the frontend's use of `JS_CONTRACT` is broken in production: the SDK is a dev-group-only dependency
+  (`frontend/pyproject.toml:33`), the Docker image installs only `[project.dependencies]`, so
+  **`PLUGIN_API.contractVersion === ''` in every shipped container** and all documented 0.2
+  feature-detection (`location`, `resolveLocation?`, `getLocations?`) reports "pre-0.1 host". Three
+  axes is bookkeeping we pay on every release for a distinction nothing exercises. Also: the SDK
+  docstring's claim that plugins declare `sdk_version` in their manifest (`__init__.py:32-33`) is
+  fiction — no manifest has it, no host code reads it.
+- **Proposed 1.0 shape:** `SDK_CONTRACT_VERSION` is the one version. Delete `PY_CONTRACT`/`JS_CONTRACT`
+  exports; the d.ts header states the package version it shipped in. `/health` reports `sdk_version`
+  only. The frontend derives `contractVersion` from the *compute service* (it already calls
+  `GET /api/plugins/` and `/health`) instead of a locally-installed Python package — that fixes the
+  production hole structurally rather than by promoting the SDK to a frontend runtime dep. Fix or
+  delete the `sdk_version`-manifest docstring claim (see A6).
+- **Additive or breaking:** breaking (removes two public constants and two `/health` fields).
+- **Who migrates:** SDK (`__init__.py`, `asgi_app.py`, d.ts header, guide's "Two version axes"
+  section); frontend (`app.py`, `base.html:48`, `plugin-loader.js:210` → read from compute);
+  host: nothing (never consumed them). Plugins: nothing.
+- **Effort:** M (the frontend sourcing change is the real work).
+
+### A3. Bring the escaped browser surface into the contract; kill the bare globals
+
+- **What/where:** frontend `static/js/table-picker.js:62` (`openTablePicker`, used by **7 of 8** UI
+  plugins), `cancel-job.js:29` (`CancelJob`, yolo+timm), `main.js:202/170` (bare `showToast`, `cssVar`);
+  SDK-injected `_tlc*` globals — 13 functions across `shared/alias_ui.py`, `alias_override_ui.py`,
+  `config_ui.py`, used by 6 of 8 plugins, none declared in the d.ts.
+- **Why it hurts:** this is contract-shaped surface with no contract: no d.ts entry, no conformance
+  gate, no stability tier. `openTablePicker(targetInputId)` additionally couples via a global DOM id
+  (`table-picker.js:308` reaches out of the plugin container), and the host fires both `input` *and*
+  `change` events because five named plugins disagree on which to listen for (`table-picker.js:308-317`).
+  The underscore prefix on `_tlc*` says "private" while the usage pattern is "public API".
+- **Proposed 1.0 shape:**
+  - `PLUGIN_API.pickers.table(options) → Promise<string|null>` (promise-returning, no DOM-id
+    coupling; frontend wraps the existing picker). There is no run picker today — declare only what
+    exists, add `pickers.run` later additively.
+  - `PLUGIN_API.jobs.cancelDialog(jobId, opts)` or declare `CancelJob` as-is in the d.ts; plugins
+    already use `PLUGIN_API.showToast`, so delete the bare-global usage (importer ×3).
+  - Rename the injected `_tlc*` families under one declared namespace (e.g. `window.TlcPluginUi.alias.*`,
+    `.aliasOverride.*`, `.configBar(...)`) with d.ts declarations; ship thin deprecated aliases during
+    the migration window, drop the bare `_tlc*` names at 1.0.
+- **Additive or breaking:** additive to introduce, breaking to remove the old globals at 1.0 (that
+  removal is the point — otherwise the undeclared surface stays load-bearing forever).
+- **Who migrates:** frontend (implement `pickers`, declare members, then delete the legacy event
+  double-fire once all plugins use the promise API); SDK (rename injected JS + d.ts declarations);
+  plugins: mechanical sweep — `openTablePicker` call sites in 7 plugins, `_tlc*` call sites in 5.
+- **Effort:** M–L (mechanical but wide; the contract-test extension in C3 keeps it honest).
+
+### A4. Make the SDK own the manifest schema — and fix the doc/code lies about it
+
+- **What/where:** manifest parsing lives host-side (`3lc-compute/plugins/manifest.py:140-248`) with
+  no schema, while the SDK documents it (`docs/plugin-guide.md:104-157`). Confirmed divergences:
+  - `isolation` default: guide says `venv` is the default (`plugin-guide.md:130`); host code defaults
+    to **`host`** (`registry.py:392`) — the opposite, and the dangerous direction (in-process import).
+  - `socketio_namespace`: guide says declare-to-override (`:134-137`); host **hardcodes** `f"/{pid}"`
+    and never reads the key (`manifest.py:219-221`).
+  - `provision_extra`: guide says REQUIRED for venv (`:133,140`); host treats it as optional and
+    silently falls back to in-place resolution (`worker_spec.py:351-397`).
+  - Undocumented keys the host reads: `runtime.auth_exempt_paths`, `runtime.venv_python`,
+    `runtime.python`, `runtime.training`, `ui.min_input_count`, `ui.action_param_names`,
+    `ui.quick_action_label/description` (`manifest.py:191-216`).
+  - Documented keys nothing reads: `sdk_version`, `ui.fragment`, `display_mode = "hidden"` (no host
+    branch on it).
+  - No `max_input_count`: image-metrics encodes "1–10 tables" as `input_types = ["table"] × 10`
+    (`tlc_plugin_image_metrics/plugin.toml:13`).
+  - No reserved-id list: `id = "jobs"` (or `manifest`, `by-resource`, `install`, …) passes the id
+    pattern (`identity.py:52`) and is then unroutable under `/api/plugins`.
+  - A TOML parse error makes the plugin **vanish silently** (`manifest.py:115-121`) — contradicting
+    the stated design goal of "listed greyed-out, never vanishing".
+  - `contract.py:8-9` says the manifest is "`[tool.tlc-compute]` in plugin.toml" — all 9 real
+    manifests are bare top-level `plugin.toml`; the `[tool.tlc-compute]` form only applies to
+    `pyproject.toml`.
+- **Why it hurts:** the manifest *is* contract surface — every key an author writes is a promise —
+  and right now the source of truth is a host file the SDK repo can't see, with drift in both
+  directions and no validation (string `priority` takes down `GET /api/plugins` wholesale,
+  `registry.py:725`).
+- **Proposed 1.0 shape:** a typed `tlc_plugin_sdk.manifest` module (dataclass + `parse()` +
+  validation errors) that the **host imports** — SDK is already the root of the dependency graph, so
+  this is the natural home. In the same move: require `isolation` explicitly (all 9 manifests already
+  declare it — zero real migration); either implement `socketio_namespace` override or delete it from
+  the schema/docs (recommend delete — nothing has ever overridden it); make `provision_extra`
+  actually required for venv (validation error); add `max_input_count`; reserve the literal path
+  segments (`jobs`, `manifest`, `by-resource`, `venv`, …) in id validation; document the rest.
+  Also add `/venv` to the reserved-route list in `contract.py:105` (host owns
+  `GET /api/plugins/{id}/venv`; a plugin's `@get("/venv")` is silently shadowed today).
+- **Additive or breaking:** breaking (required `isolation`, dropped dead keys, host adopts SDK parser).
+- **Who migrates:** host (manifest.py becomes a consumer of the SDK schema — the big piece);
+  plugins: none in practice; docs: guide's manifest section becomes generated-from/checked-against
+  the schema.
+- **Effort:** L (mostly host-side; the SDK module itself is S–M).
+
+### A5. Prune and re-tier `shared.*` (the graduation question)
+
+- **What/where & evidence (usage census across all 9 plugins + host):**
+  - `shared/modality.py` (551 lines — the largest shared module): plugins use exactly **one** of its
+    five public functions (`detect_modality_from_table`, 5 plugins). `detect_modality_from_url` has
+    **zero references anywhere**; `detect_modality_from_schema` and `classify_metrics_columns` are
+    internal/host-only. It is 551 lines of heuristics (7-step fallback chains, name conventions)
+    published as forever-contract.
+  - `shared/labels.py`: three plugins use one distinct function each, no overlap;
+    `candidate_label_paths`/`find_label_path`/`get_label_map` have no external callers.
+  - `shared/generic_job.epoch_progress`: 2 users (timm, yolo) — and **both** also maintain a private
+    `_timing` dict + hand-rolled elapsed/avg/ETA computation + a local `avg_epoch_s → avg_step_s`
+    remap (`yolo/__init__.py:184-191`, `timm/__init__.py:144-154`) because the helper only formats,
+    it doesn't *track*. The abstraction is at the wrong altitude.
+  - `shared/url_utils.normalize_url`: adoption ~25% (29 bypassing `tlc.Table.from_url` calls vs ~9
+    using it), and its heuristics are platform folklore — `url.startswith(("Users/", "home/"))`
+    re-adds a lost leading slash (`url_utils.py:37-39`), macOS/Linux-specific, silently wrong
+    elsewhere.
+  - `shared/model_storage.py`: 2 users (timm, yolo); `on_status: Any` where it means
+    `Callable[[str], None]`; contains an `except AttributeError` probe for a `tlc.Url` method.
+  - `shared/config_store.py`: healthy (3 users + yolo's clone proves demand) but leans on
+    `# type: ignore[attr-defined]` ×5 for the id/created/last_run envelope — the repo's own
+    CLAUDE.md bans that.
+- **Proposed 1.0 shape:**
+  - **Graduate (stable core):** `ui_inject`, `job_tracker`, `config_store` (with a typed envelope —
+    a `PluginConfigBase` dataclass or Protocol killing the `type: ignore`s), `aliases`, `images`,
+    `labels` (public trio only), `naming`.
+  - **Trim:** delete `detect_modality_from_url` (zero users); underscore
+    `detect_modality_from_schema`, `candidate_label_paths`, `find_label_path` (internal helpers).
+  - **Mark experimental:** `modality` detection heuristics — either a `shared.experimental` namespace
+    or an explicit "best-effort, may change in minors" tier in the docstring + docs, mirroring the
+    `libs` tier precedent. Freezing 551 lines of heuristics at 1.0 is the single biggest frozen-wart
+    risk in the package.
+  - **Replace:** `epoch_progress` with an `EpochTimer` that owns the timing dict + ETA math both
+    trainers reimplement (additive add, breaking delete of `epoch_progress` — 2 trivial migrations).
+    `normalize_url` → either push proper resolution into `tlc` core or reduce it to the defensible
+    subset (absolute-ize + project-root resolution) and delete the "Users/" folklore.
+  - **Tighten:** `model_storage` signatures (`on_status: Callable[[str], None] | None`).
+  - **The `[shared]` extra:** keep the split. The pyproject "direction" note (`pyproject.toml:43`)
+    says `3lc` likely returns to base — but the frontend is a real bare-SDK consumer (it installs the
+    SDK purely for the d.ts). Recommend deleting that direction note and declaring the split
+    permanent at 1.0.
+- **Additive or breaking:** mixed; the deletions/underscorings are breaking.
+- **Who migrates:** essentially nobody for the deletions (zero external users, verified); timm+yolo
+  for `epoch_progress`; call-site sweep for `normalize_url` semantics (5 plugins, host insights
+  plugins).
+- **Effort:** M.
+
+### A6. Fix `contractVersion`'s meaning and the d.ts's own identity strings
+
+- **What/where:** the d.ts references the **pre-rename distribution name** `3lc-plugin-sdk` in three
+  places (`plugin-api.d.ts:26, 353, 416`); the guide (`plugin-guide.md:313`) and `docs/api.md:32` say
+  `/// <reference types="3lc-compute-plugin-sdk/contract/plugin-api" />` while the d.ts header
+  (`:24-27`) explains at length why it must be the *import* name `tlc_plugin_sdk`. The guide's
+  version table (`plugin-guide.md:785-787`) still says JS_CONTRACT 0.1 / package 0.1.0. README says
+  "0.1 is the released contract line" and that the base deps include `3lc` (`README.md:46,52`) —
+  both wrong.
+- **Why it hurts:** the contract document contradicting itself about its own name and version is
+  exactly the kind of thing a first external plugin author trips on day one.
+- **Proposed 1.0 shape:** one pass fixing every self-reference; if A2 lands, the "Two version axes"
+  section collapses to one paragraph. Decide the `<reference>` path question once (test both forms in
+  an editor, document the winner, delete the loser).
+- **Additive or breaking:** docs-only (bundled here because it must land *with* A2's reshape).
+- **Effort:** S.
+
+---
+
+## B. Additive anytime (ranked)
+
+### B1. Auto-inject the SDK client scripts at serve time (kill the injection ceremony)
+
+- **What/where:** every job-using plugin must remember
+  `inject_scripts(raw, job_tracker_script())`. Reality check across 9 plugins: **four different
+  idioms** — `inject_scripts` (4 plugins); the literal `raw.replace("<script>", ...)` footgun that
+  `ui_inject.py:16-22` was written to eliminate (sam3 `__init__.py:50-55`); a brittle 3-line-exact
+  source-string match (importer `:1691-1694`); wholesale script-block prepending (merger `:104`,
+  splitter `:157`). Plus one **dead** injection: exporter injects `alias_override_ui_script()` into a
+  `ui.html` that never references any alias function (`exporter/__init__.py:381-386`).
+- **Proposal:** `build_plugin_app`'s `/ui` handler (`asgi_app.py:64-66`) — and the host's in-process
+  ui path — injects `JOB_TRACKER_JS` automatically. The client is already idempotent
+  (`if (window.PluginJobs) return;`, `job_tracker.py:33`), so existing plugins keep working and can
+  delete their injection lines at leisure. Alias/config UI injection becomes a manifest opt-in
+  (`[ui] inject = ["alias", "alias_override", "config_bar"]`) or stays manual — either way documented.
+- **Effort:** S–M. Migration: none required; cleanup sweep optional.
+
+### B2. De-abstract `compute()`
+
+- **What/where:** `contract.py:56-59` makes `compute()` abstract; 5 of 9 plugins implement it as a
+  dead stub (timm `:56` returns `{"status": "Use /api/plugins/timm/* endpoints"}`, etc.). The
+  `/compute` route also injects a magic `params.setdefault("url", "")` (`asgi_app.py:71`).
+- **Proposal:** give it a default returning `{"error": "<id> does not implement compute()"}` —
+  mirroring `run_job`'s default — so `get_ui_fragment` is the only abstract. Drop the magic `url`
+  defaulting (let plugins read their own params). Deleting five stubs is optional cleanup.
+- **Effort:** S. (The `url` defaulting change is technically behavior-breaking for any plugin relying
+  on the key existing — grep says none do.)
+
+### B3. Ship the missing batteries the plugins keep hand-rolling
+
+Evidence-ranked by duplication count:
+
+| Gap | Duplication evidence | Proposal |
+|---|---|---|
+| HTML-escape helper in JS | identical `_esc` in **8/8** ui.html files | ship in the injected client (`TlcPluginUi.esc`) and declare it |
+| Plugin-scoped fetch | 8/8 re-derive `getConfig('compute_service_url') + '/api/plugins/<id>/...'`; timm/yolo/sam3/image-metrics each wrap it 2–3× with per-plugin timeouts; sam3 hardcodes a `localhost:5020` fallback (`sam3/ui.html:296`) | `PLUGIN_API.pluginFetch(path, opts)` — pre-scoped to the mounted plugin's route root, with a venv-aware default timeout (timm's comment at `ui.html:474-477` documents why 10s is wrong for cold-start workers) |
+| Config CRUD routes | the same `GET/POST /configs`, `GET /configs/{id}`, `POST /configs/{id}/delete` quartet 4× (image_metrics, timm, sam3, yolo), with **three different** dataclass↔dict marshalling answers | `shared.config_routes.make_config_routes(store) -> list[BaseRouteHandler]` — pairs with the graduated `config_store`; also removes yolo's incentive to keep its `ProjectStore` clone (97 lines) |
+| Alias-override lifecycle | identical `apply_alias_overrides → try → finally: restore_aliases` 4×, with **three different** param keys (`_alias_overrides` popped / gotten, `alias_overrides`) | `with alias_overrides(params) as ...:` context manager + one blessed param key |
+| Duration/ETA/log-pane UI | duration formatter 4×, timing-strip renderer 3×, log-pane appender 4×, config-picker-with-localStorage ~100 lines × 3 (only image_metrics uses `_tlcPluginConfig`) | fold into the declared injected client (per A3's namespace) |
+| Table identity | `getattr(table, "project_name", "") or ""` ×6 across timm/yolo/image_metrics | tiny `shared.tables.table_identity(table)` helper (or a `tlc` core ask) |
+| Task detection | `timm/task_detection.py` ≈ `yolo/task_detection.py` (same 60 lines, different tail) | `shared.modality.detect_task(table, mapping)` |
+
+- **Effort:** M total; each row is S. All additive.
+
+### B4. `PluginJobs` v2 — close the gap that makes GPU plugins hand-roll sockets
+
+- **What/where:** all four plugins that need custom events (`timm`, `yolo`, `sam3`, `image_metrics`)
+  bypass `PluginJobs` entirely — hand-rolled `io(...)` connections with a copy-pasted options object
+  (`timm/ui.html:511-522`, `yolo:330-350`, `image_metrics:614-620`; sam3 connects to the **root**
+  namespace with no namespace at all, `sam3/ui.html:792-794`) and hand-rolled `POST .../run` +
+  `POST .../jobs/{id}/cancel`. The Python side achieved "a plugin never opens its own SocketIO
+  connection" (`job_context.py:97`); the JS side did not.
+- **Proposal:** extend `PluginJobs.run(pluginId, params, handlers)` with `handlers.on = {eventName: fn}`
+  (custom `ctx.emit` events on the same managed socket, subscribed before `/run` fires — the ordering
+  footgun `PluginJobs.on` currently documents away). Add reconnection options matching what the
+  plugins standardized on. Then the four hand-rolled stacks collapse onto the client.
+- Also: stop plugins re-stamping `job_id` into every `ctx.emit` payload (15 occurrences) — the sink
+  already `setdefault`s it (`job_context.py:115`); document that payloads arrive with `job_id`.
+- **Effort:** M. Additive.
+
+### B5. d.ts truth pass (declare what exists, decide what doesn't)
+
+- Add `allowErrorStatus` to `PluginFetchOptions` (implemented at `api-client.js:172-183`, used 13×
+  by the host's own pages) — and note `authFetch`'s auth-blocking and Response-destroying error
+  behavior (`api-client.js:132-140, 182-194`).
+- Complete `TlcLocationApi` (`rowsSpanLocations`, `shortLabel` — `location.js:38-63`) or explicitly
+  tier them out; reconcile ambient `TlcApi` (declares 6 members, implementation exports 20, and the
+  d.ts doc-comment references `encodeObjectUrl`, which it never declares).
+- `libs.cytoscape` is **unconditionally `null`** for plugins — the vendor file is loaded only on
+  `project_detail.html:15`, never on `plugin_host.html`. It's best-effort tier, so: either load it on
+  the plugin page or delete the member at 1.0. Also decide `TlcPptx` (a full deck-builder global on
+  the plugin page with no tier at all) — declare best-effort or hide.
+- Declare the fragment-shape contract prose in the guide: `.plugin-hero h2` rewriting
+  (`plugin-loader.js:244-254`), `[data-provisioning]` lifecycle (`:267-301`), and `plugin-common.css`
+  class stability.
+- **Effort:** S–M. Additive.
+
+### B6. Export the job-runner core to de-duplicate host↔worker terminal logic
+
+- **What/where:** the terminal-event synthesis (`done/cancelled/error` + message format), GPU-reclaim
+  ordering, and the `job_update` reserved-name check exist **twice**: SDK `worker.py:158-171` /
+  `job_context.py:108-110` and host `job_manager.py:262-274, 83, 436-442` — byte-similar
+  reimplementations that must drift-proof by hand.
+- **Proposal:** export `run_job_and_stream(plugin, job_id, params, state_dir, sink, cancel_event)`
+  from the SDK (the `_Job._run` body, made public); host mode calls it too. One implementation of the
+  terminal contract.
+- **Effort:** M (host adopts). Additive.
+
+### B7. Docs drift batch (everything not already inside A6)
+
+- README: base-deps claim (`README.md:46-47` says `3lc` is base), Status section ("0.1 line").
+- `contract.py:8-9` manifest-location claim; delete the orphaned `_ICON_SVG` (`contract.py:32` —
+  guide says "no `_ICON_SVG` import anymore", nothing imports it).
+- `__init__.py:32-33` `sdk_version` manifest claim (per A2/A4 decision).
+- Guide: document undocumented-but-real manifest keys (A4 list) in the interim, fix the
+  `min_input_count = 0` falsy-default footgun host-side (`manifest.py:210` — explicit 0 is silently
+  replaced), correct the isolation-default row until A4 decides it.
+- `frontend/API.md:294-302` stale "add location in the same PR" instruction (already done).
+- **Effort:** S.
+
+---
+
+## C. Process & CI
+
+### C1. Fix the live pins — today, independent of 1.0
+
+- Host + plugins umbrella: `3lc-compute-plugin-sdk[shared]>=0.1.0,<0.2.0` excludes 0.2.0
+  (`3lc-compute/pyproject.toml:24`, `3lc-compute-plugins/pyproject.toml:23`); resolved lock is 0.1.1,
+  so host-mode GPU reclaim, worker `/reclaim`, and `/health` skew-detection are all dead in practice.
+  Bump to `>=0.2.0,<0.3.0`, re-lock, verify the contract test.
+- Frontend: decide the production `contractVersion` story (A2's compute-derived value is the fix; the
+  dev-group-only SDK dep is fine for the d.ts + test).
+- **Effort:** S. Do this first — it's also the dry run for the 1.0 cross-repo bump.
+
+### C2. Mechanical additive-only enforcement (the known wishlist item — confirmed absent)
+
+- CI job in this repo that diffs, against the last release tag: `tlc_plugin_sdk.__all__` + public
+  module symbols (a simple import-and-introspect script), the d.ts interface member sets (extend the
+  frontend's regex parser or use a real TS parser), and — once A4 lands — the manifest schema fields.
+  Removals/renames fail unless the version bump is major. This is what makes "additive-only" and the
+  post-1.0 freeze a property of the repo instead of a promise in the README.
+- **Effort:** M.
+
+### C3. Deepen the frontend conformance test
+
+- `frontend/test_plugin_contract.py` diffs **top-level `PluginApi` names only**. Confirmed blind
+  spots: nested `libs`/`context` shapes, `getConfig` key set, every referenced interface
+  (`TlcData`, `TlcLocationApi`, `TlcApi`, `PluginFetchOptions`, `PluginJobsApi`), signatures, and a
+  second `window.PLUGIN_API` assignment. Dropping `libs.io` — the one STABLE lib — would pass today.
+  Extend to nested object literals and the `getConfig` key union at minimum; `PluginJobsApi` needs a
+  gate on the SDK side (its implementation and declaration live in the same wheel — a unit test
+  comparing `JOB_TRACKER_JS`'s exported names to the d.ts is cheap).
+- **Effort:** M.
+
+### C4. Test the contract itself in this repo
+
+Current suite: 2 files (import-light + GPU reclaim), both good, neither about the contract. Add:
+- `JobContext` event golden-shapes test (each method → exact wire dict; `job_id` stamping; the
+  reserved-name rejection) — this is the schema the host, frontend, and plugins all parse.
+- Worker NDJSON protocol test (start → events → terminal; cancel; the `error` message format) —
+  doubles as the conformance suite the host can run against its in-process runner (B6).
+- `inject_scripts` edge cases; `config_store` round-trip/migration; manifest schema round-trip
+  (post-A4).
+- CI: add a second job with `--extra shared` so mypy actually checks `shared.*` against a real `tlc`
+  (today `tlc`/`PIL`/`torch` are `Any` in CI, which is how `on_status: Any` survives --strict).
+- **Effort:** M.
+
+### C5. Write the release-train checklist
+
+- The 0.2 pin miss (C1) happened because the bump dance spans four repos with no checklist. One page
+  in this repo: bump order (SDK tag → host pin+lock → plugins pin → frontend dev pin), the contract
+  test loop, and the editable-overlay verification recipe.
+- **Effort:** S.
+
+### C6. State the plugin trust model explicitly
+
+- Fragments execute with **full host origin** — `innerHTML` + script re-execution
+  (`plugin-loader.js:198, 257-261`), no iframe/shadow-DOM/CSP anywhere, `TlcAuth` (raw JWT) reachable.
+  With a catalog/install flow shipping (guide's "Publishing via a Catalog"), 1.0 must say out loud:
+  *installing a plugin is executing trusted code in the Hub's origin* — in the guide and the catalog
+  docs. Actual sandboxing is a large frontend project; the honest documented stance is the 1.0
+  deliverable, sandboxing a post-1.0 decision.
+- **Effort:** S (doc) / L (sandboxing, out of scope).
+
+---
+
+## Suggested one-week sequencing
+
+Cross-repo sets are ordered so the contract test + editable overlays keep SDK, host, and frontend
+green at every step. Breaking work lands in two coordinated waves, not a trickle.
+
+**Day 1 — make the current state true (no breaks).**
+C1 pin fixes across host + plugins umbrella (re-lock, contract test). B7 + A6 docs/d.ts truth batch.
+B5 d.ts truth pass. Start C2 freeze-check script (it gates the rest of the week).
+
+**Day 2–3 — breaking wave 1: the reporting/version core (SDK-led).**
+A1 (`ctx.result`/error field) + A2 (version-axis collapse) + A5 prunes/underscorings + B2
+(de-abstract `compute`) land in the SDK as `1.0.0rc1`. Same-day coordinated PRs: host
+(`job_manager` translation + pin `>=1.0.0rc1`), frontend (error field in the panel,
+compute-derived `contractVersion`), plugins (merger/importer `result` rename; timm/yolo/sam3 adopt
+`ctx.result` + delete `job_failed` hand-rolls). Overlay-verify a GPU job end-to-end.
+
+**Day 3–4 — breaking wave 2: the browser surface (frontend-led).**
+A3: frontend implements `PLUGIN_API.pickers.table` + declares CancelJob/toast surface; SDK renames
+`_tlc*` under the declared namespace (aliases kept for the sweep); B1 auto-injection + B4
+`PluginJobs` v2 ship alongside. Then the mechanical plugin sweep (7 plugins × pickers, 5 × `_tlc*`,
+4 × hand-rolled sockets → `PluginJobs`), deleting the four injection idioms and the dead exporter
+injection as you pass through.
+
+**Day 4–5 — the manifest + batteries.**
+A4 `tlc_plugin_sdk.manifest` module; host adopts it (the week's biggest single PR — can trail into
+the next week without blocking the tag if rc-gated). B3 config-route factory + alias context manager
++ `pluginFetch`; delete yolo's store clone and the CRUD quartets in the same sweep.
+
+**Day 5 — lock it.**
+C3 contract-test deepening + C4 golden-shape tests written against the *new* surface (cheaper than
+writing them twice). C2 freeze-check turned on against `v1.0.0`. C5 checklist + C6 trust-model
+paragraph. Tag `1.0.0`.
+
+**Explicitly deferred (fine post-1.0, all additive):** run picker, sandboxing, `modality`
+graduation into `tlc` core (the porting notes in `shared/images.py:13-37` are the plan of record),
+B6 job-runner unification (safe any time).

{3lc_compute_plugin_sdk-0.3.1 → 3lc_compute_plugin_sdk-0.3.2}/CHANGELOG.md

@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+_Nothing yet._
+
+## [0.3.2] - 2026-08-31
+
+### Fixed
+- Data-source browse fields with a comma-separated `accept` (e.g. `*.yaml,*.yml`, `*.pt,*.pth`)
+  now list matching files; previously they showed none. `/browse` was matching the whole
+  `accept` string as one literal glob pattern instead of any pattern in the list.
+  ([#28](https://github.com/3lc-ai/3lc-compute-plugin-sdk/pull/28))
+
 ## [0.3.1] - 2026-08-27
 
 A patch on the 0.3 line, additive and pin-compatible (`>=0.3.0,<0.4.0` resolves it). The SDK now

{3lc_compute_plugin_sdk-0.3.1 → 3lc_compute_plugin_sdk-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: 3lc-compute-plugin-sdk
-Version: 0.3.1
+Version: 0.3.2
 Summary: Public Python SDK for building 3LC compute-service plugins.
 Project-URL: Homepage, https://github.com/3lc-ai/3lc-compute-plugin-sdk
 Project-URL: Repository, https://github.com/3lc-ai/3lc-compute-plugin-sdk

{3lc_compute_plugin_sdk-0.3.1 → 3lc_compute_plugin_sdk-0.3.2}/docs/plugin-guide.md

@@ -642,143 +642,194 @@ needs to render a good, navigation-proof view.
 
 ---
 
-## CSS Conventions
+## Styling & UI Conventions
 
-Plugin UI fragments inherit all CSS from `main.css` (via `base.html`) and `plugin-common.css` (via `plugin_host.html`). Use these shared patterns:
+A plugin's `ui.html` gets the host's entire design system for free — and the host counts on it using that system rather than reinventing it. This section is the class catalog and the rules that keep every plugin looking like one product, in every theme.
 
-| Class | Purpose |
-|---|---|
-| `.plugin-page` | Max-width 1200px container |
-| `.plugin-page-narrow` | Max-width 700px container |
-| `.card` | Standard card with shadow |
-| `.btn`, `.btn-sm`, `.btn-primary` | Buttons |
-| `.plugin-hero` | Hero section with accent background |
-| `.plugin-form-grid` | 2-column responsive form layout |
-| `.plugin-form-grid-3` | 3-column responsive form layout |
-| `.plugin-param-group` | Titled section within a card |
-| `.plugin-action-bar` | Submit/cancel row with spinner |
-| `.plugin-metric-card` | Metric display card |
-| `.plugin-progress-wrap` + `.plugin-progress-bar` | Progress bar |
-| `.plugin-log-area` | Monospace log output |
-| `.plugin-two-col` | Sidebar + main layout |
-| `.plugin-three-col` | Sidebar + main + preview layout |
-| `.plugin-config-item` | Selectable list item |
-
-Use CSS variables for colors — never hardcode:
+### Why the shared classes are available (no import, no build step)
+
+The frontend mounts a plugin by injecting its fragment straight into the host page — `containerEl.innerHTML = fragment` (see [How a fragment reaches the browser](#how-a-fragment-reaches-the-browser)). There is **no iframe and no shadow DOM**, so the fragment lands inside the host document and inherits its two stylesheets:
+
+- `main.css` — the base design system (forms, buttons, cards, spinners, theme tokens)
+- `plugin-common.css` — the plugin page scaffolding (hero, workflow, metric cards, viewer)
+
+Write `class="btn btn-primary"` or `class="form-control"` and you get the fully themed, dark-mode-correct component with zero CSS of your own. The flip side: your fragment shares the global namespace. Prefix any bespoke class with your plugin id (`.myplugin-…`) and never restyle a shared class globally — you'd repaint every other plugin.
+
+> **Only `main.css` and `plugin-common.css` are inherited.** Styles defined inside a host *template* — for example the `.pbadge` badges in `settings/plugins.html` — live in that page's own `<style>` block and are **not** available to a mounted fragment. Don't reach for them.
+
+### Theme tokens — never hardcode a color
+
+Every color, in both light and dark mode, comes from a CSS variable. Hardcoding a hex value produces a control that looks wrong the moment the user switches theme.
 
 ```css
-color: var(--text);             /* Primary text */
-color: var(--text-muted);       /* Secondary text */
-background: var(--bg);          /* Background */
-background: var(--bg-card);     /* Card background */
-border-color: var(--border);    /* Border */
-color: var(--accent);           /* Accent color (#2a4a61) */
+color: var(--text);            /* primary text                    */
+color: var(--text-secondary);  /* secondary text                  */
+color: var(--text-muted);      /* de-emphasized / helper text     */
+color: var(--accent);          /* accent (light mode #2a4a61)     */
+background: var(--bg);         /* recessed page ground            */
+background: var(--bg-card);    /* ELEVATED surface (raised cards) */
+border-color: var(--border);
+border-color: var(--border-light);
 ```
 
----
+`--bg` and `--bg-card` are the pair that matters most: `--bg-card` is an *elevated* surface, `--bg` the *recessed* page ground. In dark mode they are visibly different depths, and swapping them inverts every affordance on the page (see **Cards**, below). Also available: `--accent-light` (tinted wash), `--error` / `--danger`, and the `--badge-<color>-bg` / `--badge-<color>-text` pairs. Never use the legacy teal `#5a9aad` — `var(--accent)` is the accent.
 
-## Existing Plugins Reference
+### Forms
 
-| Plugin ID | display_mode | Section | GPU | Description |
-|---|---|---|---|---|
-| `importer` | sidebar | Data Ops | — | Import data (YOLO, COCO, Folder, CSV, Unlabeled) |
-| `exporter` | sidebar | Data Ops | — | Export tables to CSV, XLSX, YOLO, COCO |
-| `splitter` | sidebar | Data Ops | — | Split tables into train/val/test sets |
-| `merger` | sidebar | Data Ops | — | Merge 2 tables by column join |
-| `image-metrics` | sidebar | Data Ops | GPU | Image quality metrics (brightness, sharpness, noise, etc.) |
-| `yolo` | sidebar | AI Tools | GPU | Ultralytics YOLO training + metrics collection |
-| `sam3` | sidebar | AI Tools | GPU | Auto-labeling with SAM3/GroundingDINO |
-| `timm` | sidebar | AI Tools | GPU | Image classification with timm models |
-| `table-statistics` | hidden | Analysis | — | Per-column stats & image thumbnails (API-only) |
-| `run-insights` | action | Analysis | — | Run statistics, health scores, per-class metrics |
-| `table-insights` | action | Analysis | — | GT-only data quality analysis (bbox sizes, balance, etc.) |
+Wrap each field in `.form-group`; label it with `.form-label`; use `.form-control` for text inputs and `<textarea>`, `.form-select` for `<select>`; add `.form-help` for a line of helper text. For multi-field layouts, `.plugin-form-grid` (2-col) and `.plugin-form-grid-3` (3-col) are responsive grids.
 
----
+```html
+<div class="form-group">
+  <label class="form-label required">Dataset name</label>
+  <input type="text" class="form-control" required placeholder="my-dataset">
+  <div class="form-help">Lowercase, no spaces.</div>
+</div>
+```
+
+- `.form-label.required` appends a red `*`.
+- Placeholders render dimmed + italic automatically.
+- **Required-field cue — worth adopting:** put both `required` **and** a `placeholder` on a required text field. While the field is empty (its placeholder still showing) the host paints it with a muted red wash (`:required:placeholder-shown`), which clears the instant the user types. A free "you still need to fill this in" signal — no JS.
+
+### Buttons
+
+Use `.btn` plus one variant. Never define your own button styles.
 
-## UI Consistency Guide
+| Class | Use |
+|---|---|
+| `.btn` | base — required on every button |
+| `.btn-primary` | the one main action (Run, Import) |
+| `.btn-secondary` | secondary action |
+| `.btn-ghost` | low-emphasis / borderless |
+| `.btn-danger` | destructive |
+| `.btn-plugin` | accent-styled plugin action |
+| `.btn-sm` / `.btn-lg` | size modifiers, combine with the above |
+
+### Page scaffolding (`plugin-common.css`)
 
-All plugin UIs should look like they belong to the same product. Follow these patterns
-from the existing plugins (SAM3, YOLO, timm are the reference implementations).
+| Class | Purpose |
+|---|---|
+| `.plugin-page` | max-width page container — wrap the whole fragment in it |
+| `.plugin-hero` | intro banner (accent-tinted); put `<h2>` + `<p>` inside |
+| `.plugin-hero-badge` | informational "what this does" tile — flat, recessed, **non-interactive** |
+| `.plugin-workflow` / `.plugin-workflow-step` | numbered step strip (`.num` child is the circle) |
+| `.plugin-param-group` / `.plugin-param-group-label` | titled section inside a card |
+| `.plugin-form-grid` / `.plugin-form-grid-3` | 2- and 3-column responsive form layouts |
+| `.plugin-action-bar` | submit/cancel row |
+| `.plugin-config-item` | selectable list item |
+| `.plugin-metric-card` (+ `-label` / `-value`) | scalar metric tile |
+| `.plugin-progress-wrap` + `.plugin-progress-bar` | progress bar |
+| `.plugin-log-area` | monospace log output |
+| `.plugin-two-col` / `.plugin-three-col` | sidebar + main (+ preview) layouts |
+| `.plugin-viewer-card` (+ `-header` / `-toolbar` / `-viewport` / `-footer`) | image viewer shell |
+| `.spinner` / `.spinner-lg` | loading spinner |
 
-### Page Structure
+### Cards: interactive vs. informational — the one distinction to get right
 
-Every sidebar plugin UI should follow this structure:
+Two kinds of tile look superficially similar but must read differently:
+
+- **Interactive / selectable** — something the user clicks or picks (a config item, a selectable tile). These sit on the **raised** surface: `--bg-card` + a drop shadow, with a `.selected` / `.active` state. The generic `.card` / `.card-header` / `.card-title` / `.card-body` panel is the standard raised container for config forms.
+- **Informational** — pure display, not clickable (the hero "what this does" badges). These stay **flat and recessed**: use `.plugin-hero-badge`, which the host styles on `--bg` with **no shadow**. That flatness is exactly what marks it as "not a button".
+
+Get these backwards and a static badge invites a click it won't answer. The mistake is nearly invisible in light mode and obvious in dark mode, where `--bg-card` is a distinctly elevated surface — so **verify your plugin in dark mode.**
+
+> **Don't inline surface styles.** `.plugin-hero-badge` carries its whole look, so write `class="plugin-hero-badge"` and nothing else. Several plugins once inlined `style="background:var(--bg-card);box-shadow:…"` on it, and because inline styles outrank the host stylesheet, those badges kept the raised, clickable look the class was written to remove — the exact dark-mode bug above. Keep background, elevation, and color out of your `style=` attributes and let the class do the work. (`.plugin-hero-badge-card` is a deprecated alias kept only for backward compatibility — prefer `.plugin-hero-badge` alone.)
+
+### Page structure
+
+A sidebar plugin UI follows this shape:
 
 ```html
-<style>/* Plugin-specific styles only — use shared classes for everything else */</style>
+<style>
+  /* Plugin-specific rules only — layout for your own elements. Everything
+     visual (surface, color, elevation) comes from the shared classes. */
+  .myplugin-badges { display: grid; grid-template-columns: repeat(3, 1fr); gap: 8px; margin-top: 12px; }
+</style>
 
-<div class="plugin-page-narrow">       <!-- Centered 700px container -->
-  <div class="plugin-hero">            <!-- Accent-tinted header -->
+<div class="plugin-page">
+  <div class="plugin-hero">
     <h2>🎯 Plugin Name</h2>
     <p>Short description of what this plugin does.</p>
 
-    <!-- Feature badges — 3 items in a grid -->
-    <div style="display:grid;grid-template-columns:repeat(3,1fr);gap:8px;margin-top:12px">
-      <div class="plugin-hero-badge">Feature 1</div>
-      <div class="plugin-hero-badge">Feature 2</div>
-      <div class="plugin-hero-badge">Feature 3</div>
+    <!-- Informational badges — flat, non-interactive -->
+    <div class="myplugin-badges">
+      <div class="plugin-hero-badge">Fast</div>
+      <div class="plugin-hero-badge">No config</div>
+      <div class="plugin-hero-badge">Exports CSV</div>
     </div>
 
-    <!-- Workflow steps (optional) -->
+    <!-- Numbered workflow (optional) -->
     <div class="plugin-workflow">
-      <span class="plugin-workflow-step active">1. Configure</span>
-      <span class="plugin-workflow-arrow">→</span>
-      <span class="plugin-workflow-step">2. Run</span>
-      <span class="plugin-workflow-arrow">→</span>
-      <span class="plugin-workflow-step">3. Results</span>
-    </div>
-  </div>
-
-  <!-- Config bar (for plugins with saved configs) -->
-  <div class="card" style="margin-bottom:12px;padding:10px 14px">
-    <div style="display:flex;align-items:center;gap:8px">
-      <select id="config-select">...</select>
-      <button class="btn btn-sm">Load</button>
-      <button class="btn btn-sm btn-primary">Save</button>
+      <div class="plugin-workflow-step"><span class="num">1</span> Configure</div>
+      <div class="plugin-workflow-step"><span class="num">2</span> Run</div>
+      <div class="plugin-workflow-step"><span class="num">3</span> Results</div>
     </div>
   </div>
 
   <!-- Main form -->
-  <div class="card" style="padding:16px">
-    <div class="plugin-param-group">
-      <div class="plugin-param-group-title">Section Title</div>
-      <div class="plugin-form-grid">
-        <!-- Form fields -->
+  <div class="card">
+    <div class="card-header"><span class="card-title">Configuration</span></div>
+    <div class="card-body">
+      <div class="plugin-param-group">
+        <div class="plugin-param-group-label">Source</div>
+        <div class="form-group">
+          <label class="form-label required">Table name</label>
+          <input id="myplugin-name" type="text" class="form-control" required placeholder="my-table">
+          <div class="form-help">The table to analyze.</div>
+        </div>
+      </div>
+      <div class="plugin-action-bar">
+        <button id="myplugin-run" class="btn btn-primary">Run</button>
+        <span class="spinner" style="display:none"></span>
       </div>
-    </div>
-
-    <div class="plugin-action-bar">
-      <button class="btn btn-primary">Run</button>
-      <span class="spinner" style="display:none"></span>
     </div>
   </div>
 
   <!-- Results area (appears after execution) -->
-  <div id="results" class="card" style="display:none;padding:16px;margin-top:12px">
-  </div>
+  <div id="myplugin-results" class="card" style="display:none"></div>
 </div>
 ```
 
-### Visual Consistency Rules
+### Visual rules
+
+1. **Container** — wrap the fragment in `.plugin-page`.
+2. **Hero** — `.plugin-hero` with icon + title + description, optionally three `.plugin-hero-badge` tiles.
+3. **Accent** — `var(--accent)`; never the legacy teal `#5a9aad`.
+4. **Cards** — group content in `.card`; raised for interactive, flat `.plugin-hero-badge` for informational.
+5. **Forms** — `.form-group` + `.form-control` / `.form-select`, laid out with `.plugin-form-grid` where useful.
+6. **Buttons** — `.btn` + one variant; the primary action gets `.btn-primary`.
+7. **Spinners** — `<span class="spinner"></span>` (defined in `main.css`).
+8. **Toasts** — `PLUGIN_API.showToast(msg, 'success'|'error'|'info')` for feedback.
+9. **Dark mode** — must work; only `var(--*)` colors, and confirm the raised/flat card distinction actually reads.
+
+### What NOT to do
+
+- Don't hardcode colors — always a `var(--…)` token.
+- Don't inline surface/elevation styles (`background`, `box-shadow`) on shared classes — let the class do it.
+- Don't define custom button, input, or card styles — the shared classes exist.
+- Don't restyle a shared class globally, and prefix your own classes with the plugin id.
+- Don't reach for host-template-only classes like `.pbadge` — they aren't inherited.
+- Don't create custom modal/dialog implementations — use `.card` with show/hide.
+- Don't use `position: fixed` — it breaks the plugin container.
+- Don't add font sizes below 10px or custom scrollbars.
+- Don't skip a dark-mode check.
 
-1. **Container**: Use `.plugin-page-narrow` (700px) for form-based plugins, `.plugin-page` (1200px) for data-heavy plugins like run-insights.
-2. **Hero section**: Always include `.plugin-hero` with icon + title + description + 3 feature badges.
-3. **Color**: Use `var(--accent)` (#2a4a61) as the accent. Never use teal (#5a9aad).
-4. **Cards**: Wrap all content sections in `.card`. Use `margin-bottom:12px` between cards.
-5. **Forms**: Use `.plugin-form-grid` (2-col) or `.plugin-form-grid-3` (3-col) for form layouts.
-6. **Buttons**: Primary actions get `.btn-primary`. Secondary actions get plain `.btn`.
-7. **Spinners**: Use `<span class="spinner"></span>` (defined in main.css).
-8. **Toasts**: Use `PLUGIN_API.showToast(msg, 'success'|'error'|'info')` for feedback.
-9. **Config bar**: Plugins with saved configurations (YOLO, SAM3, timm) should have a config select/save/delete bar below the hero.
-10. **Dark mode**: All CSS must work in dark mode. Use `var(--text)`, `var(--bg)`, `var(--border)`, etc. Never hardcode colors.
+---
 
-### What NOT to Do
+## Existing Plugins Reference
 
-- Don't define custom button styles — use `.btn`, `.btn-sm`, `.btn-primary`.
-- Don't use inline colors — always use CSS variables.
-- Don't create custom modal/dialog implementations — use `.card` with show/hide.
-- Don't add custom scrollbar styles or font sizes below 10px.
-- Don't use `position: fixed` — it breaks the plugin container layout.
+| Plugin ID | display_mode | Section | GPU | Description |
+|---|---|---|---|---|
+| `importer` | sidebar | Data Ops | — | Import data (YOLO, COCO, Folder, CSV, Unlabeled) |
+| `exporter` | sidebar | Data Ops | — | Export tables to CSV, XLSX, YOLO, COCO |
+| `splitter` | sidebar | Data Ops | — | Split tables into train/val/test sets |
+| `merger` | sidebar | Data Ops | — | Merge 2 tables by column join |
+| `image-metrics` | sidebar | Data Ops | GPU | Image quality metrics (brightness, sharpness, noise, etc.) |
+| `yolo` | sidebar | AI Tools | GPU | Ultralytics YOLO training + metrics collection |
+| `sam3` | sidebar | AI Tools | GPU | Auto-labeling with SAM3/GroundingDINO |
+| `timm` | sidebar | AI Tools | GPU | Image classification with timm models |
+| `table-statistics` | hidden | Analysis | — | Per-column stats & image thumbnails (API-only) |
+| `run-insights` | action | Analysis | — | Run statistics, health scores, per-class metrics |
+| `table-insights` | action | Analysis | — | GT-only data quality analysis (bbox sizes, balance, etc.) |
 
 ---
 
@@ -964,7 +1015,7 @@ If your entry doesn't show up after that, check that the tester's compute-servic
 - [ ] Job progress follows the generic schema (no plugin-specific fields in frontend)
 - [ ] If GPU-bound: `requires_gpu = true` in `[runtime]`; long work is `run_job(ctx)` — never grab a queue
 - [ ] If creating tables from images: registers URL aliases via `tlc_plugin_sdk/shared/aliases.py` + `tlc_plugin_sdk/shared/alias_ui.py` (inject with `inject_scripts()`)
-- [ ] UI follows the page structure from "UI Consistency Guide" above
+- [ ] UI follows the page structure and card conventions from "Styling & UI Conventions" above
 - [ ] Hero section with icon, title, description, and 3 feature badges
 - [ ] Config bar if plugin has saved configurations
 - [ ] Dark mode works correctly (no hardcoded colors)

{3lc_compute_plugin_sdk-0.3.1 → 3lc_compute_plugin_sdk-0.3.2}/pyproject.toml

@@ -7,7 +7,7 @@ name = "3lc-compute-plugin-sdk"
 # The plugin-contract (ABI) version. This IS tlc_plugin_sdk.SDK_CONTRACT_VERSION
 # (read back via importlib.metadata) — one source of truth. SemVer MAJOR.MINOR.PATCH;
 # the 0.x line is additive-only (see README → Status).
-version = "0.3.1"
+version = "0.3.2"
 description = "Public Python SDK for building 3LC compute-service plugins."
 requires-python = ">=3.10"
 readme = "README.md"

{3lc_compute_plugin_sdk-0.3.1 → 3lc_compute_plugin_sdk-0.3.2}/src/tlc_plugin_sdk/shared/data_source_routes.py

@@ -176,7 +176,9 @@ def data_source_route_handlers() -> list[BaseRouteHandler]:
 
         Query params:
             path: Directory to list. Empty or ``~`` opens the first allowed root.
-            glob: Optional glob pattern to filter files (e.g. ``*.yaml``).
+            glob: Optional glob pattern(s) to filter files, comma-separated for more than
+                one (e.g. ``*.yaml`` or ``*.yaml,*.yml`` — matches the widget's ``accept``
+                config verbatim). A file is kept if it matches *any* pattern in the list.
             show_hidden: Whether to include dotfiles (default ``false``).
             purpose: ``input`` (default) or ``output``. In ``output`` mode the response
                 additionally reports writability (see below); ``input`` mode skips that
@@ -196,7 +198,9 @@ def data_source_route_handlers() -> list[BaseRouteHandler]:
 
         roots = allowed_browse_roots()
         raw_path = request.query_params.get("path", "").strip()
-        glob_pattern = request.query_params.get("glob", "")
+        # Comma-separated, matching the widget's "accept" config (e.g. "*.yaml,*.yml") —
+        # a bare fnmatch against the joined string would only match a literal comma.
+        glob_patterns = [g.strip() for g in request.query_params.get("glob", "").split(",") if g.strip()]
         show_hidden = request.query_params.get("show_hidden", "false").lower() == "true"
         purpose = request.query_params.get("purpose", "input")
         want_writable = purpose == "output"
@@ -224,7 +228,11 @@ def data_source_route_handlers() -> list[BaseRouteHandler]:
             for entry in sorted(os.scandir(expanded), key=lambda e: (not e.is_dir(), e.name.lower())):
                 if not show_hidden and entry.name.startswith("."):
                     continue
-                if glob_pattern and not entry.is_dir() and not fnmatch.fnmatch(entry.name, glob_pattern):
+                if (
+                    glob_patterns
+                    and not entry.is_dir()
+                    and not any(fnmatch.fnmatch(entry.name, pattern) for pattern in glob_patterns)
+                ):
                     continue
                 try:
                     stat = entry.stat()

{3lc_compute_plugin_sdk-0.3.1 → 3lc_compute_plugin_sdk-0.3.2}/tests/test_data_source_routes.py

@@ -100,6 +100,14 @@ class TestBrowseConfinement:
         body = _browse(client, path=str(root / "sub"), glob="*.yaml")
         assert [e["name"] for e in body["entries"]] == ["table.yaml"]
 
+    def test_glob_accepts_comma_separated_patterns(self, client: TestClient[Litestar], root: Path) -> None:
+        # Matches the widget's "accept" config verbatim (e.g. "*.yaml,*.yml") — a file
+        # is kept if it matches ANY pattern in the list, not the joined string literally.
+        body = _browse(client, path=str(root / "sub"), glob="*.yaml,*.yml")
+        assert [e["name"] for e in body["entries"]] == ["table.yaml"]
+        body = _browse(client, path=str(root), glob="*.csv,*.json")
+        assert [e["name"] for e in body["entries"]] == ["sub", "data.csv"]
+
 
 class TestBrowseAccessibility:
     """Each dir entry is tagged with whether it can actually be opened for listing."""

{3lc_compute_plugin_sdk-0.3.1 → 3lc_compute_plugin_sdk-0.3.2}/uv.lock

@@ -84,7 +84,7 @@ pandas = [
 
 [[package]]
 name = "3lc-compute-plugin-sdk"
-version = "0.3.1"
+version = "0.3.2"
 source = { editable = "." }
 dependencies = [
     { name = "3lc", extra = ["pandas"] },