Skip to content

Panel/control refactor 2026-07: Phases 1-4 + representation/index split#25

Closed
mnm-matin wants to merge 12 commits into
mainfrom
refactor/panel-control-2026-07-cont
Closed

Panel/control refactor 2026-07: Phases 1-4 + representation/index split#25
mnm-matin wants to merge 12 commits into
mainfrom
refactor/panel-control-2026-07-cont

Conversation

@mnm-matin

@mnm-matin mnm-matin commented Jul 4, 2026

Copy link
Copy Markdown
Member

Summary

Full panel/control refactor per docs/refactor-plan-2026-07.md, landed in phase order:

  • Phase 1 (7730be0): de-duplicated panel contracts (single-sourced from Python), de-legacied retrieval state, normalized command namespaces (workspace.* / panel.<type>.* / collection.*), CommandResult carries snapshots.
  • Phase 2 (7a8b88f): one panel render path behind PanelHost, thin panel SDK.
  • Phase 3 backend (1fc55fe): collections materialized behind paged GET /api/collections/{id}/items, replaying the same retrieval methods the collection.* commands use.
  • Phase 4 (6335a8f): hyperview export static bundle command + Session.export().
  • Phase 3 frontend (51a712f): useSamples(collectionId) now pages through the collections endpoint for all/filter/neighbors/search kinds — live and static bundles — instead of filtering the loaded sample page in memory. Adds scores/hasMore/loadMore to the hook.
  • Representation/index split, first landing (c90bfca): /api/dataset exposes derived representations[]/indexes[]; index_id (space:<space_key>) accepted at every retrieval boundary. Storage stays keyed by space_key.

Docs + .agents/skills/hyperview-cli updated to match (3e3d830, 7cfdcd7, 21951cf gap assessment).

Remaining follow-ups (named in the gap assessment)

  • Point the built-in Samples grid host view model at a collection_id.
  • Generic field mapping / typed Field discovery (own phase, Medium priority).
  • Eventually key storage by representation/index instead of space_key.

Test plan

  • uv run pytest: 151 passed.
  • cd frontend && npm run build (and npm run export for packaged static assets): green.
  • Static export bundle tests cover the exported api/collections/{id}/items.json read path.

🤖 Generated with Claude Code

mnm-matin and others added 11 commits July 4, 2026 00:38
@mnm-matin @claude
WIP snapshot: control command API, panel definitions, text retrieval,…
54a74b6 
… examples

Snapshot of uncommitted demo-driven work before panel/control refactor.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@mnm-matin @claude
Add panel/control refactor plan (July 2026)
8408f19 
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@mnm-matin @claude
Phase 1: de-duplicate panel contracts, de-legacy retrieval state, nor…
7730be0 
…malize commands

Implements Phase 1 of docs/refactor-plan-2026-07.md:
- Panel definitions are single-sourced from the runtime snapshot;
  frontend/src/panels/definitions.tsx is now only a panel_type->renderer map.
- ui.similarity_query mirror removed; retrieval state lives in
  ui.panels.samples.state.retrieval, with a one-way migration reader for
  workspaces persisted before July 2026.
- Command names normalized to workspace.*/panel.<type>.*/collection.*;
  old names dispatch via one alias table with deprecation warnings.
- CommandResult carries the runtime snapshot; the frontend command client
  applies it instead of re-fetching /api/runtime.
- Env hardening: system font stack instead of remote Google Fonts;
  datasets/torch shared-memory guard for restricted containers.

Tests: 139 passed. Frontend: next build green.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@mnm-matin @claude
Phase 2: one panel render path, thin panel SDK
7a8b88f 
Implements Phase 2 of docs/refactor-plan-2026-07.md:
- Runtime scatter panels, built-ins, and extension module panels all
  resolve through a single PanelHost component (PanelInstanceProvider
  moved to PanelHostContext); RuntimeBuiltInPanel and RuntimeModulePanel
  are removed.
- panel-sdk shrinks to the narrow surface: command client, usePanelState,
  useSelection, useCollection, useSamples, useHostAdapter. Store, Dockview
  context, and raw API helpers are no longer re-exported; built-in panels
  use app-local imports.

Tests: 139 passed. Frontend: next build (turbopack) + tsc --noEmit green.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@mnm-matin @claude
Phase 4: hyperview export static bundle command
6335a8f 
Implements docs/refactor-plan-2026-07.md Phase 4:
- 'hyperview export <workspace-id> --out <dir>' CLI + Session.export():
  writes the packaged static frontend, runtime snapshot, panel
  definitions, sample shards + per-sample JSON/media/thumbnails,
  precomputed embeddings per layout, materialized collections, similarity
  results, and copied extension panel modules into a self-contained
  bundle. Injects window.__HYPERVIEW_STATIC__ = true into index.html.
- Frontend static adapter (api.ts): when the static flag is set, GET
  routes resolve from the bundled JSON instead of hitting a server;
  mutating command calls no-op with a visible 'read-only demo — pip
  install hyperview for the full workbench' notice.
- Staged updated hyperview-cli skill docs under docs/_staging-skill-docs/
  (sandbox blocked writing .agents/ directly; needs manual promotion).

Tests: 141 passed (139 baseline + 2 export tests). Frontend: next build
green. Manually smoke-tested: exported a real in-memory workspace, served
the bundle with plain http.server, confirmed index.html/runtime.json/
sample content all resolve 200 and the static flag is present.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@mnm-matin @claude
Promote hyperview-cli skill docs to reflect Phase 1-4 changes
3e3d830 
The Phase 4 minion staged these under docs/_staging-skill-docs/ because
its sandbox blocked writes under .agents/; moving them into place here
since this session isn't sandboxed. Covers namespaced commands with
deprecated aliases, snapshot-carrying CommandResult, the thin panel SDK,
and 'hyperview export'.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@mnm-matin @claude
Phase 3 (scoped): materialize collections behind a paged REST endpoint
1fc55fe 
Implements the first two items of docs/refactor-plan-2026-07.md Phase 3:
- GET /api/collections/{id} and GET /api/collections/{id}/items?offset=&limit=
  resolve a CollectionState's membership on demand by replaying the same
  find_similar / find_similar_by_text / label-filter methods the
  collection.neighbors.create and collection.filter.set commands already use
  to build the collection's query, instead of duplicating retrieval logic.
- Label-filter collections page through the existing get_samples_paginated
  fast path when field=="label" and op=="eq" (the common case); other
  field/op combinations and "all" collections fall back to in-memory
  filtering, documented as a known tradeoff.
- "neighbors"/"search" collections are bounded by k and sliced in memory.

Out of scope for this pass (left for a follow-up): rewiring the frontend
Samples/ImageGrid panel to render by collection_id end-to-end, and splitting
space_key into representation/index (Phase 3 item 3). The existing
frontend panel-sdk useCollection/useSamples(collectionId) hooks still read
from client-side store state rather than this new endpoint — adopting it
there is a larger, riskier change to the primary UI that deserves its own
verified pass rather than being bundled in here.

Tests: 143 passed (139 baseline + 4 new collection-items tests).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@mnm-matin @claude
Add refactor gap assessment against AGENTS.md's fuller direction
21951cf 
Confirms provider registration, jobs, machine-readable CommandResult, and
runtime-managed layouts/embeddings are already adequate. Flags two real
remaining gaps: generic field mapping (own follow-up phase, Medium priority
per docs/architecture.md) and the frontend half of Phase 3 (collection_id-
driven Samples panel rendering), which is still open after 1fc55fe.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@mnm-matin @claude
Phase 3 frontend: useSamples pages through the collections endpoint
51a712f 
useSamples(collectionId) now materializes all/filter/neighbors/search
collections through GET /api/collections/{id}/items (paged, appending,
abortable) instead of filtering the client-side samples page in memory.
Static bundles read the exported api/collections/{id}/items.json and
page client-side. Non-materializable kinds (selection, lasso,
tool_result, extension) keep the legacy client-side filter. The hook
return gains scores/hasMore/loadMore; existing fields are unchanged.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@mnm-matin @claude
Phase 3: split space concept into representation/index contracts
c90bfca 
First landing of the representation/index split from docs/architecture.md,
kept additive so storage stays keyed by space_key:

- SpaceInfo derives to_representation_dict() (the vector field) and
  to_index_dict() (the searchable access path, id 'space:<space_key>',
  matching the indexId convention collection queries already emit).
- GET /api/dataset now exposes representations[] and indexes[] so agents
  and panels can discover them; index query_modes reflect space modality.
- index_id is accepted everywhere retrieval is addressed: the similar/text
  search endpoints, SimilarityQueryState command args, collection item
  materialization (server + static export). space_key remains the alias.

Full storage/table rename deferred; this makes the two concepts real at
the contract level per the plan's Phase 3 item 3.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@mnm-matin @claude
Update plan, gap assessment, and skill docs for Phase 3 completion
7cfdcd7 
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@mnm-matin @claude
Add architecture verdict + Encord/FiftyOne/Rerun parity assessment
3066ac9 
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@mnm-matin

mnm-matin commented Jul 5, 2026

Copy link
Copy Markdown
Member Author

Closing per repo cleanup; this project is not using PR flow for this branch.

@mnm-matin mnm-matin closed this Jul 5, 2026
@mnm-matin mnm-matin deleted the refactor/panel-control-2026-07-cont branch July 5, 2026 19:06
@github-project-automation github-project-automation Bot moved this from Backlog to Done in HyperView Main Dev Jul 5, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

HyperView Main Dev
Status: Done

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@mnm-matin