@smartmemory/wiki-components 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,91 @@
+Business Source License 1.1
+
+Parameters
+
+Licensor:             Regression Analytics LLC
+Licensed Work:        @smartmemory/wiki-components. The Licensed Work is (c) 2026 Regression
+                      Analytics LLC.
+Additional Use Grant: You may make production use of the Licensed Work,
+                      provided that the total revenue of you and your
+                      affiliates in your most recently completed fiscal
+                      year did not exceed USD 1,000,000.
+Change Date:          Four years from the date the specific version of the
+                      Licensed Work is first publicly distributed under
+                      this License.
+Change License:       Apache License, Version 2.0
+
+For information about alternative licensing arrangements for the Licensed
+Work, including production use above the Additional Use Grant, contact
+help@smartmemory.ai.
+
+Notice
+
+License text copyright © 2017 MariaDB Corporation Ab, All Rights Reserved.
+"Business Source License" is a trademark of MariaDB Corporation Ab.
+
+Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative
+works, redistribute, and make non-production use of the Licensed Work. The
+Licensor may make an Additional Use Grant, above, permitting limited
+production use.
+
+Effective on the Change Date, or the fourth anniversary of the first publicly
+available distribution of a specific version of the Licensed Work under this
+License, whichever comes first, the Licensor hereby grants you rights under
+the terms of the Change License, and the rights granted in the paragraph
+above terminate.
+
+If your use of the Licensed Work does not comply with the requirements
+currently in effect as described in this License, you must purchase a
+commercial license from the Licensor, its affiliated entities, or authorized
+resellers, or you must refrain from using the Licensed Work.
+
+All copies of the original and modified Licensed Work, and derivative works
+of the Licensed Work, are subject to this License. This License applies
+separately for each version of the Licensed Work and the Change Date may vary
+for each version of the Licensed Work released by Licensor.
+
+You must conspicuously display this License on each original or modified copy
+of the Licensed Work. If you receive the Licensed Work in original or
+modified form from a third party, the terms and conditions set forth in this
+License apply to your use of that work.
+
+Any use of the Licensed Work in violation of this License will automatically
+terminate your rights under this License for the current and all other
+versions of the Licensed Work.
+
+This License does not grant you any right in any trademark or logo of
+Licensor or its affiliates (provided that you may use a trademark or logo of
+Licensor as expressly required by this License).
+
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON
+AN “AS IS” BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS,
+EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND
+TITLE.
+
+MariaDB hereby grants you permission to use this License’s text to license
+your works, and to refer to it using the trademark “Business Source License”,
+as long as you comply with the Covenants of Licensor below.
+
+Covenants of Licensor
+
+In consideration of the right to use this License’s text and the “Business
+Source License” name and trademark, Licensor covenants to MariaDB, and to all
+other recipients of the licensed work to be provided by Licensor:
+
+1. To specify as the Change License the GPL Version 2.0 or any later version,
+   or a license that is compatible with GPL Version 2.0 or a later version,
+   where “compatible” means that software provided under the Change License can
+   be included in a program with software provided under GPL Version 2.0 or a
+   later version. Licensor may specify additional Change Licenses without
+   limitation.
+
+2. To either: (a) specify an additional grant of rights to use that does not
+   impose any additional restriction on the right granted in this License, as
+   the Additional Use Grant; or (b) insert the text “None”.
+
+3. To specify a Change Date.
+
+4. Not to modify this License in any other way.

package/README.md

@@ -1,3 +1,63 @@
-# Temporary Holding Version
+# @smartmemory/wiki-components
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The wiki's **feature hub** and **search** screens as router-free React components (WIKI-UI-COMPONENTS-1). Every byte of data
+comes from an injected `DataClient`; no component fetches, imports a router, or uses react-query. The wiki's own `/ui/` app
+renders them through thin route wrappers (`ui/src/pages/FeatureHub.jsx`, `ui/src/pages/SearchPage.jsx`) with a fetch-based
+client (`ui/src/api/dataClient.jsx`). Compose's wiki tab (COMPOSE-WIKI-TAB-1) supplies its own client.
+
+## Using @smartmemory/wiki-components
+
+Published on npm under the `@smartmemory` scope (WIKI-COMPONENTS-PUBLISH-1, BUSL-1.1, see `LICENSE`).
+
+```sh
+npm install @smartmemory/wiki-components react react-dom date-fns lucide-react
+```
+
+- **What ships:** `src/` as plain ESM JSX plus the hand-written `.d.ts` files, `README.md`, `LICENSE`. There is no build
+  step and no `dist/`: the wiki's own `/ui/` app consumes the same `src/` through its `file:` dependency, so one tree
+  serves both, and the only npm host (Compose) is a Vite app that transforms JSX from `node_modules` itself.
+- **Host must bundle JSX:** a Vite (or other bundler) host with the React plugin. Node cannot import the package directly.
+- **One React copy:** installed from npm the package's bare imports already resolve from the host's `node_modules`; keep
+  `react`, `react-dom`, `lucide-react`, `date-fns` in `resolve.dedupe` so a linked checkout behaves the same.
+- **Tailwind:** add `node_modules/@smartmemory/wiki-components/src/**/*.{js,jsx}` to `content` (Compose does this through
+  its scoped `wiki-tab.tailwind.config.js`).
+- **Releasing:** the owner publishes from a local checkout (`cd ui/packages/wiki-components && npm pack --dry-run && npm
+  publish --access public`); bump `version` here and the dependency range in Compose's `package.json` together.
+
+## Contract
+
+`src/data-client.d.ts` is the contract: four calls (`identity`, `featureHub`, `decisions`, `search`), the endpoint and
+request body each maps to on the wiki API, and the result types (from `wiki/contracts/query.schema.json`). The same list is
+runtime data in `DATA_CLIENT_CALLS`; `ui/test/wiki-components.test.jsx` pins the typed file, the table and the app's client
+to each other. `<WikiDataProvider>` refuses a client missing a method.
+
+## Use
+
+```jsx
+import { WikiDataProvider, FeatureHub, Search, wikiPath } from "@smartmemory/wiki-components";
+
+<WikiDataProvider client={myClient}>
+  <FeatureHub featureId="CORE-1" workspace="wiki-eng" />
+  <Search query="recall" workspaces={["wiki-eng", "wiki-gtm"]}
+    onNavigate={(target) => /* {kind: "search", query?, workspace?} | {kind: "note", workspace, docId} */ go(target)}
+    hrefFor={(target) => `http://127.0.0.1:8791/ui${wikiPath(target)}`} />
+</WikiDataProvider>
+```
+
+- `workspace` / `workspaces` are optional: without them a screen calls `client.identity()` and uses the caller's grants
+  (FeatureHub the first one).
+- `onNavigate(target)` receives a plain left click on a link and the search box's submit. `hrefFor(target)` is each link's
+  href (modified clicks, open in new tab); `wikiPath(target)` is the target's path in the wiki's own `/ui/` app.
+
+## Host requirements
+
+- **Peers:** `react` and `react-dom` `>=18 <20`, `date-fns` 3, `lucide-react`. The package ships JSX source (no build step);
+  a Vite host transforms it (installed from npm or linked). Consumed as `file:` dependency, its bare imports resolve from its real path, so a host outside
+  this repo must list `react`, `react-dom` (and `lucide-react`, `date-fns`) in `resolve.dedupe` or it loads the wiki's
+  React 18 copy next to its own.
+- **Styles:** Tailwind classes. Add `<this dir>/src/**/*.{js,jsx}` to the host's Tailwind `content`. Colours read the wiki's
+  CSS variables through its Tailwind theme (`ui/tailwind.config.js` `colors`: `ground`, `ink`, `ink2`, `onblue`, and the
+  remapped `neutral`/`blue`/`red`/`emerald`/`amber`/`violet`/`orange` scales over `--lp-*` and `--w-*`, defined in
+  `ui/src/index.css` and the design system's `landing.css`). Search's list layout uses `.list-page` / `.list-scroll` from
+  `ui/src/index.css`. A host that wants the wiki look maps those variables (or the same Tailwind colour names) to its own
+  tokens.

package/package.json

@@ -1,6 +1,40 @@
 {
   "name": "@smartmemory/wiki-components",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "The wiki's feature hub and search screens as router-free React components fed by an injected DataClient (WIKI-UI-COMPONENTS-1). Ships JSX source for a bundler host (Vite).",
+  "license": "BUSL-1.1",
+  "author": "Regression Analytics LLC",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/smartmemory/smart-memory-wiki.git",
+    "directory": "ui/packages/wiki-components"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "src/index.js",
+  "types": "src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./data-client": {
+      "types": "./src/data-client.d.ts"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "peerDependencies": {
+    "react": ">=18 <20",
+    "react-dom": ">=18 <20",
+    "date-fns": "^3.6.0",
+    "lucide-react": ">=0.475.0"
+  },
+  "sideEffects": false
+}

package/src/FeatureHub.jsx

@@ -0,0 +1,74 @@
+import React from "react";
+import { useClientCall, useDataClient, useWorkspaces } from "./data-client";
+import ErrorBox from "./parts/ErrorBox";
+import Section from "./parts/Section";
+import DocRow from "./parts/DocRow";
+import Loading from "./parts/Loading";
+import StatusChip from "./parts/StatusChip";
+import EntryRows from "./parts/EntryRows";
+import FeatureSummary from "./parts/FeatureSummary";
+
+/** True when a product's only evidence is the feature id's prefix (the weakest kind, WIKI-FEATURE-ASPECTS-1). */
+export const prefixOnly = (feature, product) => {
+  const ev = feature.product_evidence?.[product] || [];
+  return ev.length > 0 && ev.every((e) => e.startsWith("id-prefix"));
+};
+
+/** The index facets of one feature: products (primary bold, hollow on prefix-only evidence), categories, initiatives. */
+function FacetChips({ feature }) {
+  const tag = (text, cls, title) => <span key={text} title={title} className={`inline-flex whitespace-nowrap rounded-full border px-2 py-0.5 text-[11px] ${cls}`}>{text}</span>;
+  const products = (feature.products || []).map((p) => tag(
+    p,
+    `${p === feature.primary_product ? "font-semibold" : "font-medium"} ${prefixOnly(feature, p) ? "border-dashed border-violet-300 bg-transparent text-violet-600" : "border-violet-200 bg-violet-50 text-violet-700"}`,
+    `product${p === feature.primary_product ? " (primary)" : ""}: ${(feature.product_evidence?.[p] || []).join(", ") || "no evidence"}`,
+  ));
+  const plain = (xs, kind) => (xs || []).map((x) => tag(x, "font-medium border-neutral-200 bg-neutral-50 text-neutral-600", kind));
+  const chips = [...products, ...plain(feature.categories, "category"), ...plain(feature.initiatives, "initiative")];
+  return chips.length ? <div data-testid="facet-chips" className="mt-2 flex flex-wrap items-center gap-1.5">{chips}</div> : null;
+}
+
+/** One feature: its docs grouped by kind, then its decisions. `workspace` is the workspace to read (default: the caller's
+ *  first grant, from the DataClient's identity()). Data: DataClient featureHub + decisions. No links, so no onNavigate. */
+export default function FeatureHub({ featureId, workspace }) {
+  const client = useDataClient();
+  const ws = useWorkspaces(workspace === undefined ? undefined : [workspace]);
+  const on = ws.workspaces?.[0];
+  const hub = useClientCall(["feature_hub", on, featureId], () => client.featureHub({ workspace: on, featureId }), { enabled: !!on, keepPrevious: true });
+  const decisions = useClientCall(["decisions", on, featureId], () => client.decisions({ workspace: on, featureId }), { enabled: !!on, keepPrevious: true });
+  const loading = ws.isLoading || hub.isLoading;
+  const feature = hub.data?.feature;
+  const docs = hub.data?.items || [];
+  const kinds = [...new Set(docs.map((d) => d.kind))];
+
+  return (
+    <div>
+      <header className="mb-10">
+        <div className="mb-1 text-xs font-medium uppercase tracking-wider text-neutral-400">Feature hub</div>
+        <h1 className="font-mono text-2xl font-semibold tracking-tight">{featureId}</h1>
+        {feature ? (
+          <>
+            <p className="mt-1 text-[15px] text-neutral-700">{feature.title}</p>
+            <FeatureSummary feature={feature} className="mt-1 max-w-3xl" />
+            <div className="mt-3 flex flex-wrap items-center gap-3">
+              <StatusChip status={feature.roadmap_status} />
+              {feature.status_source === "none" && <span className="text-xs font-medium text-amber-700">untracked</span>}
+              <span className="text-xs text-neutral-500">{feature.doc_count} docs</span>
+              {feature.owner && <span className="text-xs text-neutral-500">owner {feature.owner}</span>}
+            </div>
+            <FacetChips feature={feature} />
+          </>
+        ) : !loading && <p className="mt-1 text-sm text-neutral-400">Not on the roadmap.</p>}
+      </header>
+      <ErrorBox error={ws.error || hub.error} />
+      {loading ? <Loading /> : kinds.map((k) => (
+        <Section key={k} title={k} meta={docs.filter((d) => d.kind === k).length}>
+          {docs.filter((d) => d.kind === k).map((d) => <DocRow key={d.doc_id} doc={d} />)}
+        </Section>
+      ))}
+      <Section title="Decisions" meta={decisions.data?.total}>
+        <ErrorBox error={decisions.error} />
+        <EntryRows entries={decisions.data?.items || []} empty="No decisions recorded." />
+      </Section>
+    </div>
+  );
+}

package/src/Search.jsx

@@ -0,0 +1,85 @@
+import React from "react";
+import { useClientCall, useDataClient, useWorkspaces } from "./data-client";
+import ErrorBox from "./parts/ErrorBox";
+import SearchBox from "./parts/SearchBox";
+import PageHeader from "./parts/PageHeader";
+import Loading from "./parts/Loading";
+import ListPage from "./parts/ListPage";
+import SearchGroup from "./parts/SearchGroup";
+import NavLink from "./parts/NavLink";
+import { wsName } from "./lib";
+
+const chip = (on) => `rounded-full border px-3 py-1 text-[13px] transition-colors ${on ? "border-blue-500 bg-blue-500 text-onblue" : "border-neutral-200 text-ink2 hover:border-blue-500 hover:text-ink"}`;
+
+/** The search screen. `query` is the search text (capped at 256 characters, as the search query allows). `workspace`
+ *  searches that one workspace; without it, every workspace in `workspaces` (default: the caller's grants, from the
+ *  DataClient's identity()), in parallel, one section per workspace. A workspace outside the grants is ignored.
+ *  Each hit, each scope chip and the search box are NavTargets: `onNavigate(target)` follows one, `hrefFor(target)` is
+ *  its href. Data: DataClient search, one call per workspace. */
+export default function Search({ query = "", workspace: only = null, workspaces: given, onNavigate, hrefFor }) {
+  const client = useDataClient();
+  const ws = useWorkspaces(given);
+  const workspaces = ws.workspaces || [];
+  const q = String(query || "").slice(0, 256); // the search query allows 1 to 256 characters
+  const scope = workspaces.includes(only) ? [only] : workspaces;
+  const call = useClientCall(
+    ["search", scope, q],
+    () => Promise.allSettled(scope.map((w) => client.search({ workspace: w, q }))),
+    { enabled: !!q && scope.length > 0 },
+  );
+  const runs = scope.map((_, i) => {
+    const r = call.data?.[i];
+    return { data: r?.status === "fulfilled" ? r.value : undefined, error: r?.status === "rejected" ? r.reason : null };
+  });
+  const scoped = (w) => ({ kind: "search", ...(q ? { query: q } : {}), ...(w ? { workspace: w } : {}) });
+  const loading = ws.isLoading || (!!q && call.isLoading);
+  const found = runs.some((r) => r.data?.groups?.length);
+  const link = { onNavigate, hrefFor };
+
+  return (
+    <ListPage
+      header={(
+        <>
+          <PageHeader title="Search" />
+          <div className="max-w-2xl"><SearchBox key={q + (only || "")} initial={q} autoFocus workspace={scope.length === 1 && workspaces.length > 1 ? only : undefined} onNavigate={onNavigate} /></div>
+          {workspaces.length > 1 && (
+            <div className="mt-4 flex flex-wrap gap-2" aria-label="Search in">
+              <NavLink {...link} target={scoped(null)} className={chip(scope.length > 1)}>All workspaces</NavLink>
+              {workspaces.map((w) => <NavLink {...link} key={w} target={scoped(w)} className={chip(scope.length === 1 && scope[0] === w)}>{wsName(w)}</NavLink>)}
+            </div>
+          )}
+        </>
+      )}
+    >
+      <div className="mt-6">
+        <ErrorBox error={ws.error} className="mb-4" />
+        {runs.map((r, i) => <ErrorBox key={scope[i]} error={r.error} className="mb-4" />)}
+        {!q ? <p className="text-sm text-neutral-400">Type a query and press Enter.</p>
+          : loading ? <Loading text="Searching…" />
+          : !found ? <p className="text-sm text-neutral-400">No results for “{q}”.</p>
+          : runs.map((r, i) => {
+              const w = scope[i];
+              const groups = r.data?.groups || [];
+              if (!groups.length) return null;
+              return (
+                <section key={w} className="mb-10">
+                  {scope.length > 1 && <h2 className="mb-2 text-lg font-semibold tracking-tight text-ink">{wsName(w)} <span className="font-mono text-xs font-normal text-neutral-500">{w}</span></h2>}
+                  {groups.map((g) => (
+                    <SearchGroup key={g.label} title={g.label} total={g.total} items={g.items.map((h) => (
+                      <NavLink {...link} key={h.doc_id} target={{ kind: "note", workspace: w, docId: h.doc_id }} className="grid grid-cols-[1fr_auto] gap-3 rounded-md px-3 py-2 hover:bg-neutral-50">
+                        <div className="min-w-0">
+                          <div className="truncate font-medium text-ink">{h.title}</div>
+                          <div className="truncate font-mono text-xs text-neutral-500">{h.path}</div>
+                          <div className="mt-0.5 text-[13px] text-neutral-600">{h.snippet}</div>
+                        </div>
+                        <span className="text-xs tabular-nums text-neutral-400">rank {h.rank}</span>
+                      </NavLink>
+                    ))} />
+                  ))}
+                </section>
+              );
+            })}
+      </div>
+    </ListPage>
+  );
+}

package/src/data-client.d.ts

@@ -0,0 +1,117 @@
+// WIKI-UI-COMPONENTS-1: the DataClient contract. Every call the FeatureHub and Search screens make, and nothing else.
+// A host (the wiki's /ui/ app, Compose's wiki tab) passes one object with these async methods to <WikiDataProvider>.
+// The components never fetch: each call below is the whole of their I/O.
+//
+// Traced from the pages as they were before the move (ui/src/pages/FeatureHub.jsx, ui/src/pages/SearchPage.jsx at c1fea67)
+// through ui/src/api/hooks.jsx (useNamedQuery, IdentityProvider) to ui/src/api/client.js (query, identity):
+//
+//   method       endpoint                     request body (the Query envelope, wiki/contracts/query.schema.json)
+//   identity     GET  /identity               (none)  -> identity_response, wiki/contracts/identity.schema.json
+//   featureHub   POST /query/feature_hub      {query: "feature_hub", workspace, filters: {feature_id}, page: {size: 200}}
+//   decisions    POST /query/decisions        {query: "decisions",   workspace, filters: {feature_id}, page: {size: 50}}
+//   search       POST /query/search           {query: "search",      workspace, filters: {q},          page: {}}
+//
+// The same table is runtime data in data-client.jsx (DATA_CLIENT_CALLS); a test pins the two to each other.
+// A rejected call should reject with an Error carrying `code` (the query_error code) so the screens can show it.
+
+/** A workspace id the caller holds, e.g. "wiki-eng". */
+export type Workspace = string;
+
+/** GET /identity (identity.schema.json identity_response). */
+export interface Identity {
+  principal: string;
+  workspaces: Workspace[];
+}
+
+/** query.schema.json $defs/doc_item */
+export interface DocItem {
+  doc_id: string;
+  source_id: string;
+  path: string;
+  title: string;
+  kind: string;
+  feature_ids: string[];
+  areas: string[];
+  mtime: string;
+  text_mode: string;
+  missing_reason: string | null;
+}
+
+/** query.schema.json $defs/feature_item (the fields beyond `required` are optional on older hosts). */
+export interface FeatureItem {
+  feature_id: string;
+  title: string;
+  roadmap_status: string;
+  folder: string;
+  owner: string | null;
+  current_decision_ref: string | null;
+  latest_output_ref: string | null;
+  doc_count: number;
+  areas: string[];
+  products?: string[];
+  primary_product?: string | null;
+  product_evidence?: Record<string, string[]>;
+  categories?: string[];
+  initiatives?: string[];
+  repos?: string[];
+  status_source?: string | null;
+  summary?: string;
+  archived?: boolean;
+}
+
+/** query.schema.json $defs/entry_item */
+export interface EntryItem {
+  entry_id: string;
+  parent_doc_id: string;
+  kind: string;
+  ts: string;
+  text: string;
+  refs: string[];
+  status?: string;
+}
+
+/** query.schema.json $defs/search_hit */
+export interface SearchHit {
+  doc_id: string;
+  title: string;
+  path: string;
+  snippet: string;
+  rank: number;
+}
+
+/** query.schema.json $defs/query_result */
+export interface QueryResult<T> {
+  items: T[];
+  total: number;
+  next_cursor: string | null;
+  unresolved_count?: number;
+  generated_at: string;
+}
+
+/** x-named-queries.feature_hub.result: the feature's docs plus the feature itself (null when it is not on the roadmap). */
+export interface FeatureHubResult extends QueryResult<DocItem> {
+  feature: FeatureItem | null;
+}
+
+/** x-named-queries.search.result (a grouped_result). */
+export interface SearchResult {
+  groups: { label: string; items: SearchHit[]; total: number; next_cursor: string | null }[];
+  generated_at: string;
+}
+
+export interface DataClient {
+  /** GET /identity: who the caller is and which workspaces it holds. Asked only when a screen is not given its workspace(s). */
+  identity(): Promise<Identity>;
+  /** POST /query/feature_hub, filters {feature_id}, page {size: 200}. */
+  featureHub(args: { workspace: Workspace; featureId: string }): Promise<FeatureHubResult>;
+  /** POST /query/decisions, filters {feature_id}, page {size: 50}. */
+  decisions(args: { workspace: Workspace; featureId: string }): Promise<QueryResult<EntryItem>>;
+  /** POST /query/search, filters {q} (1 to 256 characters), page {}. One call per workspace searched. */
+  search(args: { workspace: Workspace; q: string }): Promise<SearchResult>;
+}
+
+/** Where a screen asks the host to go (Search only; FeatureHub has no links). The host maps it to its own route
+ *  (the /ui/ app: wikiPath()). */
+export type NavTarget =
+  | { kind: "search"; query?: string; workspace?: Workspace }
+  | { kind: "note"; workspace: Workspace; docId: string };

package/src/data-client.jsx

@@ -0,0 +1,57 @@
+import React, { createContext, useContext, useEffect, useRef, useState } from "react";
+
+// The DataClient's calls as data (types and the traced endpoints: data-client.d.ts). `endpoint` and `page` say what the
+// host's client must send, so a host can be checked against the screens' needs without rendering them.
+export const DATA_CLIENT_CALLS = [
+  { method: "identity", endpoint: "GET /identity" },
+  { method: "featureHub", endpoint: "POST /query/feature_hub", query: "feature_hub", page: { size: 200 } },
+  { method: "decisions", endpoint: "POST /query/decisions", query: "decisions", page: { size: 50 } },
+  { method: "search", endpoint: "POST /query/search", query: "search", page: {} },
+];
+
+const Ctx = createContext(null);
+
+/** Hands `client` (a DataClient) to every screen inside. A client missing a method is refused here, not on first use. */
+export function WikiDataProvider({ client, children }) {
+  const missing = DATA_CLIENT_CALLS.map((c) => c.method).filter((m) => typeof client?.[m] !== "function");
+  if (missing.length) throw new Error(`WikiDataProvider: the DataClient has no ${missing.join(", ")}`);
+  return <Ctx.Provider value={client}>{children}</Ctx.Provider>;
+}
+
+export function useDataClient() {
+  const client = useContext(Ctx);
+  if (!client) throw new Error("wiki components need a <WikiDataProvider client={...}> above them");
+  return client;
+}
+
+/** One DataClient call keyed by `key` (any JSON value): `{data, error, isLoading}`. A new key asks again; an answer for a
+ *  key no longer current is dropped. `keepPrevious` shows the last answer while the next loads (react-query's
+ *  keepPreviousData, which the feature hub used before the move). `enabled: false` asks nothing. */
+export function useClientCall(key, run, { enabled = true, keepPrevious = false } = {}) {
+  const k = JSON.stringify(key);
+  const runRef = useRef(run);
+  runRef.current = run;
+  const [state, setState] = useState({ key: undefined, data: undefined, error: null });
+  useEffect(() => {
+    if (!enabled) return undefined;
+    let live = true;
+    Promise.resolve()
+      .then(() => runRef.current())
+      .then(
+        (data) => { if (live) setState({ key: k, data, error: null }); },
+        (error) => { if (live) setState({ key: k, data: undefined, error }); },
+      );
+    return () => { live = false; };
+  }, [k, enabled]);
+  const current = state.key === k;
+  const data = current || keepPrevious ? state.data : undefined;
+  return { data, error: current ? state.error : null, isLoading: enabled && !current && data === undefined };
+}
+
+/** The workspace(s) a screen works in: the host's, when it passes them, else the caller's grants from `identity()`. */
+export function useWorkspaces(given) {
+  const client = useDataClient();
+  const id = useClientCall(["identity"], () => client.identity(), { enabled: given === undefined });
+  if (given !== undefined) return { workspaces: given, error: null, isLoading: false };
+  return { workspaces: id.data?.workspaces, error: id.error, isLoading: id.isLoading };
+}

package/src/index.d.ts

@@ -0,0 +1,27 @@
+// Types for @smartmemory/wiki-components. The DataClient contract and NavTarget: data-client.d.ts.
+import type { ReactElement, ReactNode } from "react";
+import type { DataClient, NavTarget, Workspace } from "./data-client";
+
+export * from "./data-client";
+
+export interface NavProps {
+  /** Follow a target (a plain left click, or a search box submit). */
+  onNavigate?: (target: NavTarget) => void;
+  /** The href a target's link carries (open in new tab, status bar). Default "#". */
+  hrefFor?: (target: NavTarget) => string;
+}
+
+export function WikiDataProvider(props: { client: DataClient; children?: ReactNode }): ReactElement;
+export function useDataClient(): DataClient;
+
+/** One feature's docs (grouped by kind) and decisions. `workspace` default: the first of identity().workspaces. */
+export function FeatureHub(props: { featureId: string; workspace?: Workspace }): ReactElement;
+
+/** Search across `workspaces` (default: identity().workspaces), or only `workspace` when it is one of them. */
+export function Search(props: { query?: string; workspace?: Workspace | null; workspaces?: Workspace[] } & NavProps): ReactElement;
+
+export const DATA_CLIENT_CALLS: { method: keyof DataClient; endpoint: string; query?: string; page?: Record<string, number> }[];
+
+/** A NavTarget as a path of the wiki's /ui/ app (relative to its basename, e.g. "/search?q=x"). */
+export function wikiPath(target: NavTarget): string;
+export function wsName(workspace: Workspace): string;

package/src/index.js

@@ -0,0 +1,20 @@
+// @smartmemory/wiki-components (WIKI-UI-COMPONENTS-1): the wiki's feature hub and search screens, router-free, with all
+// data from an injected DataClient (data-client.d.ts). The wiki's /ui/ app and Compose's wiki tab both render these.
+export { default as FeatureHub, prefixOnly } from "./FeatureHub";
+export { default as Search } from "./Search";
+export { WikiDataProvider, useDataClient, useClientCall, DATA_CLIENT_CALLS } from "./data-client";
+export { wikiPath, wsName, wsUrl, noteUrl, toDate, fmtDate, summaryOf } from "./lib";
+// The parts the screens are built from; the /ui/ app's other pages use them too (ui/src/components/wiki/* re-export them).
+export { default as ErrorBox } from "./parts/ErrorBox";
+export { default as Section } from "./parts/Section";
+export { default as DocRow } from "./parts/DocRow";
+export { default as TypeBadge } from "./parts/TypeBadge";
+export { default as Loading } from "./parts/Loading";
+export { default as StatusChip } from "./parts/StatusChip";
+export { default as EntryRows } from "./parts/EntryRows";
+export { default as FeatureSummary } from "./parts/FeatureSummary";
+export { default as PageHeader } from "./parts/PageHeader";
+export { default as ListPage } from "./parts/ListPage";
+export { default as SearchGroup } from "./parts/SearchGroup";
+export { default as SearchBox } from "./parts/SearchBox";
+export { default as NavLink } from "./parts/NavLink";

package/src/lib.js

@@ -0,0 +1,28 @@
+import { format } from "date-fns";
+
+// Helpers the screens share with the rest of the /ui/ app (ui/src/lib/wiki.js re-exports them: one home).
+
+// WIKI-LANDING-UI-1: workspaces under human names. The id itself stays visible next to the name (small, mono). The table
+// names the shared workspaces only: any other id reads as its title-cased tail, so no private name is in the bundle.
+const WS_NAMES = { eng: "Engineering", gtm: "Go-to-market" };
+export const wsName = (ws) => {
+  const tail = String(ws || "").replace(/^wiki-/, "");
+  return WS_NAMES[tail] || tail.split(/[-_]+/).filter(Boolean).map((w) => w[0].toUpperCase() + w.slice(1)).join(" ") || "Workspace";
+};
+export const wsUrl = (ws) => `/w/${encodeURIComponent(ws)}`;
+export const noteUrl = (ws, id) => `${wsUrl(ws)}/note?id=${encodeURIComponent(id)}`;
+
+export const toDate = (d) => (d ? new Date(d.length <= 10 || /([zZ]|[+-]\d\d:?\d\d)$/.test(d) ? d : d + "Z") : null);
+export const fmtDate = (d) => (d ? format(toDate(d), "MMM d, yyyy") : "—");
+/** A feature's index summary: the trimmed string, or null when absent or blank (nothing is drawn for null). */
+export const summaryOf = (feature) => (typeof feature?.summary === "string" && feature.summary.trim() ? feature.summary.trim() : null);
+
+/** A NavTarget (data-client.d.ts) as a route of the wiki's own /ui/ app, relative to its basename. */
+export function wikiPath(target) {
+  if (target.kind === "note") return noteUrl(target.workspace, target.docId);
+  if (target.kind === "search") {
+    const p = new URLSearchParams({ ...(target.query ? { q: target.query } : {}), ...(target.workspace ? { workspace: target.workspace } : {}) });
+    return `/search?${p}`;
+  }
+  throw new Error(`wikiPath: unknown target kind ${target.kind}`);
+}

package/src/parts/DocRow.jsx

@@ -0,0 +1,15 @@
+import React from "react";
+import TypeBadge from "./TypeBadge";
+import { fmtDate } from "../lib";
+
+export default function DocRow({ doc, right }) {
+  return (
+    <div className="grid items-center gap-3 rounded-md px-3 py-2 hover:bg-neutral-50 grid-cols-[6.5rem_1fr_auto] sm:grid-cols-[6.5rem_1fr_16rem_6.5rem]">
+      <TypeBadge type={doc.kind} />
+      <span className="truncate font-medium text-neutral-900">{doc.title}</span>
+      <span className="hidden truncate font-mono text-xs text-neutral-500 sm:block" title={doc.path}>{doc.path}</span>
+      <span className="hidden text-right text-xs tabular-nums text-neutral-500 sm:block">{fmtDate(doc.mtime)}</span>
+      {right}
+    </div>
+  );
+}

package/src/parts/EntryRows.jsx

@@ -0,0 +1,12 @@
+import React from "react";
+import { fmtDate } from "../lib";
+
+export default function EntryRows({ entries, empty = "No entries." }) {
+  if (!entries.length) return <p className="px-3 text-sm text-neutral-400">{empty}</p>;
+  return entries.map((e) => (
+    <div key={e.entry_id} className="grid grid-cols-[6.5rem_1fr] gap-3 px-3 py-1.5 text-[13px]">
+      <span className="text-xs tabular-nums text-neutral-500">{fmtDate(e.ts)}</span>
+      <span className="text-neutral-800">{e.text}</span>
+    </div>
+  ));
+}

package/src/parts/ErrorBox.jsx

@@ -0,0 +1,10 @@
+import React from "react";
+
+export default function ErrorBox({ error, className = "" }) {
+  if (!error) return null;
+  return (
+    <div role="alert" className={`rounded-md border border-red-200 bg-red-50 px-3 py-2 text-sm text-red-700 ${className}`}>
+      {error.message} <span className="font-mono text-xs text-red-500">({error.code || "error"})</span>
+    </div>
+  );
+}

package/src/parts/FeatureSummary.jsx

@@ -0,0 +1,8 @@
+import React from "react";
+import { summaryOf } from "../lib";
+
+/** The one-line summary the features index carries (WIKI-FEATURE-VIEWS-FU-1): a muted line, or nothing when absent. */
+export default function FeatureSummary({ feature, className = "" }) {
+  const text = summaryOf(feature);
+  return text ? <p data-testid="feature-summary" className={`text-xs text-neutral-500 ${className}`}>{text}</p> : null;
+}

package/src/parts/ListPage.jsx

@@ -0,0 +1,15 @@
+import React from "react";
+
+/** The one layout of every long list page (WIKI-UNCLASSIFIED-OVERFLOW-1): the header, the filters and the pager stay put
+ *  and the rows scroll inside their own panel, so the page itself never grows with the list. Height and scrolling are
+ *  CSS (`.list-page`, `.list-scroll` in index.css). A table inside keeps its column heads pinned (Table). */
+export default function ListPage({ header, filters, foot, children }) {
+  return (
+    <div className="list-page">
+      {header}
+      {filters && <div className="mb-3 shrink-0">{filters}</div>}
+      <div className="list-scroll" data-testid="list-scroll">{children}</div>
+      {foot}
+    </div>
+  );
+}

package/src/parts/Loading.jsx

@@ -0,0 +1,5 @@
+import React from "react";
+
+export default function Loading({ text = "Loading…" }) {
+  return <div className="py-6 text-sm text-neutral-400">{text}</div>;
+}

package/src/parts/NavLink.jsx

@@ -0,0 +1,13 @@
+import React from "react";
+
+/** A link to a NavTarget without a router. `href` (from the host's `hrefFor`) keeps open-in-new-tab and the status-bar URL;
+ *  ("#" without one, so the link still takes focus); a plain left click is handed to `onNavigate` instead, as react-router's <Link> does (modified clicks go to the browser). */
+export default function NavLink({ target, hrefFor, onNavigate, children, ...rest }) {
+  const click = (e) => {
+    if (e.defaultPrevented || e.button !== 0 || e.metaKey || e.altKey || e.ctrlKey || e.shiftKey) return;
+    if (!onNavigate) return;
+    e.preventDefault();
+    onNavigate(target);
+  };
+  return <a href={hrefFor ? hrefFor(target) : "#"} onClick={click} {...rest}>{children}</a>;
+}

package/src/parts/PageHeader.jsx

@@ -0,0 +1,11 @@
+import React from "react";
+
+export default function PageHeader({ eyebrow, title, children }) {
+  return (
+    <header className="mb-10 shrink-0">
+      {eyebrow && <div className="mb-1 text-xs font-medium uppercase tracking-wider text-neutral-400">{eyebrow}</div>}
+      <h1 className="text-2xl font-semibold tracking-tight text-neutral-900">{title}</h1>
+      {children && <div className="mt-2 text-neutral-500">{children}</div>}
+    </header>
+  );
+}

package/src/parts/SearchBox.jsx

@@ -0,0 +1,21 @@
+import React, { useState } from "react";
+import { Search } from "lucide-react";
+
+/** Submits a search: `onNavigate({kind: "search", query, workspace})`. `workspace` scopes it to one workspace; without it the
+ *  search page searches every granted one. No router here: the host turns the target into a route. */
+export default function SearchBox({ initial = "", autoFocus, workspace, placeholder, big, onNavigate }) {
+  const [q, setQ] = useState(initial);
+  const submit = (e) => {
+    e.preventDefault();
+    if (!q.trim()) return;
+    onNavigate?.({ kind: "search", query: q.trim(), ...(workspace ? { workspace } : {}) });
+  };
+  return (
+    <form role="search" onSubmit={submit} className="relative">
+      <Search className={`pointer-events-none absolute left-3.5 top-1/2 -translate-y-1/2 text-neutral-400 ${big ? "h-5 w-5" : "h-4 w-4"}`} />
+      <input value={q} onChange={(e) => setQ(e.target.value)} autoFocus={autoFocus} aria-label="Search"
+        placeholder={placeholder || "Search titles, summaries, paths, feature IDs…"}
+        className={`w-full rounded-lg border border-neutral-200 bg-ground pr-3 text-ink outline-none transition placeholder:text-neutral-400 focus:border-blue-500 focus:ring-2 focus:ring-blue-500/25 ${big ? "h-12 pl-11 text-[15px]" : "h-10 pl-10 text-sm"}`} />
+    </form>
+  );
+}

package/src/parts/SearchGroup.jsx

@@ -0,0 +1,11 @@
+import React from "react";
+import Section from "./Section";
+
+export default function SearchGroup({ title, total, items }) {
+  if (!items?.length) return null;
+  return (
+    <Section title={title} meta={total != null && `${total.toLocaleString()} matches`}>
+      {items}
+    </Section>
+  );
+}

package/src/parts/Section.jsx

@@ -0,0 +1,13 @@
+import React from "react";
+
+export default function Section({ title, meta, children, className = "" }) {
+  return (
+    <section className={`mt-12 first:mt-0 ${className}`}>
+      <div className="mb-3 flex items-baseline justify-between border-b border-neutral-100 pb-2">
+        <h2 className="text-[13px] font-semibold uppercase tracking-wider text-neutral-500">{title}</h2>
+        {meta && <span className="text-xs text-neutral-400">{meta}</span>}
+      </div>
+      {children}
+    </section>
+  );
+}

package/src/parts/StatusChip.jsx

@@ -0,0 +1,20 @@
+import React from "react";
+
+const GREEN = "bg-emerald-50 text-emerald-700 border-emerald-200";
+const BLUE = "bg-blue-50 text-blue-700 border-blue-200";
+const AMBER = "bg-amber-50 text-amber-700 border-amber-200";
+const ORANGE = "bg-orange-50 text-orange-700 border-orange-200";
+const RED = "bg-red-50 text-red-700 border-red-200";
+const GREY = "bg-neutral-50 text-neutral-500 border-neutral-200";
+
+const STYLES = {
+  active: GREEN, done: BLUE, superseded: AMBER, stale: ORANGE, unknown: GREY,
+  complete: GREEN, in_progress: BLUE, partial: ORANGE, planned: GREY, open: AMBER, killed: RED,
+  junk: RED, archived: GREY, new: BLUE, triaged: AMBER, adopted: GREEN, rejected: RED,
+  accepted: GREEN, proposed: AMBER, logged: GREY, ok: GREEN, error: RED,
+};
+
+export default function StatusChip({ status = "unknown" }) {
+  const key = String(status || "unknown").toLowerCase();
+  return <span className={`inline-flex whitespace-nowrap rounded-full border px-2 py-0.5 text-[11px] font-medium ${STYLES[key] || GREY}`}>{key.replace("_", " ")}</span>;
+}

package/src/parts/TypeBadge.jsx

@@ -0,0 +1,9 @@
+import React from "react";
+
+export default function TypeBadge({ type }) {
+  return (
+    <span data-testid="type-badge" className="inline-flex min-w-[4.25rem] max-w-full justify-center truncate rounded border border-neutral-200 bg-neutral-50 px-1.5 py-0.5 font-mono text-[10.5px] uppercase tracking-wide text-neutral-600">
+      {type || "—"}
+    </span>
+  );
+}