@memnest/ui-core 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Memnest contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,44 @@
+# @memnest/ui-core
+
+Framework-free UI logic for Memnest: the controllers behind the dashboard's views, graph layout, topic clustering, viewport math, hit-testing and canvas drawing. No React, no Vue, no DOM: every controller is `getState()` plus `subscribe(listener)`, so a framework wrapper is a few lines (`@memnest/ui-react` is one).
+
+```ts
+import { createMemnestClient } from '@memnest/client';
+import { createWorkspace } from '@memnest/ui-core';
+
+const workspace = createWorkspace({ client: createMemnestClient({ baseUrl: '' }), containerTag: 'user:123' });
+
+workspace.trace.setQuery('what database does this user use?');
+workspace.trace.setTokenBudget(200);
+await workspace.trace.run();
+workspace.trace.getState().rows; // every candidate, why it was included or excluded, and the budget line
+
+workspace.select(memoryId);       // detail and lineage load; the graph highlights it
+workspace.detail.requestForget();
+await workspace.detail.confirmForget(); // trace, finder, timeline and graph refresh
+```
+
+`client` is any `MemnestApi`, including the embedded engine, so the same controllers run in tests with no server.
+
+| Controller | What it holds |
+|---|---|
+| `graph` | The global graph: filter, clusters above 2,000 matching memories, force layout, viewport, selection, lineage overlay, hover |
+| `lineage` | One memory's lineage as a layered (Sugiyama-style) DAG |
+| `trace` | A search's candidates joined with their text, cumulative tokens and the budget line |
+| `timeline` | A topic's facts over time: version chains as lanes, each switch dated |
+| `detail` | A memory, its version history, relations and sources; two-step forget |
+| `finder` | Search or browse memories |
+
+**Layout.** `computeLayout(nodes, edges, { algorithm: 'force' | 'layered' })` is deterministic for a seed. For large graphs, run it in a worker:
+
+```ts
+// layout.worker.ts
+import { serveLayoutRequests } from '@memnest/ui-core';
+serveLayoutRequests(self);
+
+// app
+const layout = createWorkerLayoutRunner(new Worker(new URL('./layout.worker.ts', import.meta.url), { type: 'module' }));
+createWorkspace({ client, containerTag, layout }); // graphs of 500+ nodes lay out off the main thread
+```
+
+**Drawing.** `buildGraphScene(state, theme)` turns graph state into circles and lines, and `drawScene(ctx, scene, viewport, size, theme)` paints them on any 2D canvas context. Labels are culled and capped per frame.