feat(entity): Chunk #4 data layer + entity UI (characters & world-building)

Data layer:
- Fuzzy scorer (packages/core/src/fuzzy.ts) with index recovery + unit tests
- Backlink computation (packages/core/src/backlinks.ts) incl. entity-level backlinks
- Consistency checker (packages/core/src/consistency.ts) incl. reciprocity/scope + unit tests
- StorageAdapter contract extended with listEntities/searchEntities/saveEntity/deleteEntity;
  implemented in Local (Dexie) and Server adapters; contract tests cover entity CRUD + ?q= search
- WorldItem.fields now supports list values (keyPeople, rivals); expanded RelationshipKind
- @mention autocomplete extension + picker in the editor package

Entity UI (apps/web/src/features/entities/):
- Generic field renderer (EntityFields) driven by ENTITY_FIELDS/FieldDef
- Tabbed directory with fuzzy search + entity cards (EntitiesView)
- Create/edit/delete drawer (EntityEditor) reusing shared fields
- Relationship editor + force-directed SVG relationship map
- Entity engine stylesheet; wired into nav

Store: project-store entity methods (load/create/update/delete) over the StorageAdapter contract.

CI-green: typecheck, lint, 65 tests, and web build all pass.

packages/core/src/autosave.test.ts

@@ -29,6 +29,16 @@ function mockAdapter(): StorageAdapter & { saved: DocumentRef[] } {
       return null;
     },
     async saveEntity() {},
+    async listEntities() {
+      return [];
+    },
+    async getEntity() {
+      return null;
+    },
+    async deleteEntity() {},
+    async searchEntities() {
+      return [];
+    },
     async saveBoard() {},
     async saveAISession() {},
     async saveDocument(doc: DocumentRef) {

packages/core/src/backlinks.ts

@@ -82,3 +82,21 @@ export function docHasMentions(doc: ProseMirrorDoc): boolean {
   visit(doc.content ?? []);
   return found;
 }
+
+/**
+ * Compute the backlinks for a single entity across a set of chapters: every
+ * chapter that references it, with the node paths where it appears.
+ */
+export function backlinksForEntity(
+  chapters: Array<{ id: string; title: string; doc: ProseMirrorDoc }>,
+  entityId: string,
+): Backlink[] {
+  const links: Backlink[] = [];
+  for (const ch of chapters) {
+    const paths = findMentionsInDoc(ch.doc, new Set([entityId]), new Set());
+    if (paths.length > 0) {
+      links.push({ chapterId: ch.id, title: ch.title, paths });
+    }
+  }
+  return links;
+}

packages/core/src/consistency.test.ts

@@ -0,0 +1,171 @@
+import { describe, it, expect } from "vitest";
+import {
+  findOrphanedMentions,
+  parseRelationships,
+  findRelationshipAsymmetry,
+  findInconsistencies,
+  SYMMETRIC_RELATIONSHIPS,
+} from "./consistency.js";
+import type { Character, Entity, ProseMirrorDoc } from "./types.js";
+
+const doc = (entityId: string | null, name = "Mara"): ProseMirrorDoc => ({
+  type: "doc",
+  content: [
+    {
+      type: "paragraph",
+      content: [
+        { type: "text", text: "She said " },
+        { type: "CharacterMention", attrs: entityId ? { entityId, name } : { name } },
+      ],
+    },
+  ],
+});
+
+describe("findOrphanedMentions", () => {
+  it("flags a mention whose entity id is gone", () => {
+    const chapters = [{ id: "ch1", title: "Ch 1", doc: doc("ghost") }];
+    const issues = findOrphanedMentions(chapters, new Set(["ada"]));
+    expect(issues).toHaveLength(1);
+    expect(issues[0]).toMatchObject({ kind: "orphan-mention", entityId: "ghost", chapterId: "ch1" });
+  });
+
+  it("does not flag a mention whose entity still exists", () => {
+    const chapters = [{ id: "ch1", title: "Ch 1", doc: doc("ada") }];
+    expect(findOrphanedMentions(chapters, new Set(["ada"]))).toHaveLength(0);
+  });
+
+  it("does not flag a bare name mention (no entityId)", () => {
+    const chapters = [{ id: "ch1", title: "Ch 1", doc: doc(null) }];
+    expect(findOrphanedMentions(chapters, new Set(["ada"]))).toHaveLength(0);
+  });
+});
+
+describe("parseRelationships", () => {
+  it("parses the relationships array into a targetId map", () => {
+    const c: Character = {
+      id: "ada",
+      projectId: "p",
+      name: "Ada",
+      role: "",
+      bio: "",
+      appearance: "",
+      voice: "",
+      relationships: [
+        { targetId: "maria", kind: "sibling", note: "sisters" },
+        { targetId: "mark", kind: "ally", note: "" },
+      ],
+      arc: "",
+      status: "active",
+      tags: [],
+    };
+    expect(parseRelationships(c)).toEqual({
+      maria: { kind: "sibling", note: "sisters" },
+      mark: { kind: "ally", note: "" },
+    });
+  });
+});
+
+describe("findRelationshipAsymmetry", () => {
+  const ada: Character = {
+    id: "ada",
+    projectId: "p",
+    name: "Ada",
+    role: "",
+    bio: "",
+    appearance: "",
+    voice: "",
+    relationships: [{ targetId: "maria", kind: "sibling", note: "" }],
+    arc: "",
+    status: "active",
+    tags: [],
+  };
+  const maria: Character = {
+    id: "maria",
+    projectId: "p",
+    name: "Maria",
+    role: "",
+    bio: "",
+    appearance: "",
+    voice: "",
+    relationships: [],
+    arc: "",
+    status: "active",
+    tags: [],
+  };
+  const brad: Character = {
+    id: "brad",
+    projectId: "p",
+    name: "Brad",
+    role: "",
+    bio: "",
+    appearance: "",
+    voice: "",
+    relationships: [{ targetId: "ada", kind: "rival", note: "" }],
+    arc: "",
+    status: "active",
+    tags: [],
+  };
+  const adaBack: Character = {
+    ...ada,
+    relationships: [
+      { targetId: "maria", kind: "sibling", note: "" },
+      { targetId: "brad", kind: "rival", note: "" },
+    ],
+  };
+
+  it("reports a symmetric relationship that is not reciprocated", () => {
+    const issues = findRelationshipAsymmetry([ada, maria]);
+    expect(issues).toHaveLength(1);
+    expect(issues[0]).toMatchObject({ kind: "relationship-asymmetry", fromEntity: "ada", toEntity: "maria", relationship: "sibling" });
+  });
+
+  it("does not report when the symmetric relationship is reciprocated", () => {
+    const mariaBack: Character = {
+      ...maria,
+      relationships: [{ targetId: "ada", kind: "sibling", note: "" }],
+    };
+    const issues = findRelationshipAsymmetry([adaBack, mariaBack, brad]);
+    expect(issues).toHaveLength(0);
+  });
+
+  it("ignores directed (non-symmetric) relationship kinds", () => {
+    const mentor: Character = {
+      id: "m",
+      projectId: "p",
+      name: "Mentor",
+      role: "",
+      bio: "",
+      appearance: "",
+      voice: "",
+      relationships: [{ targetId: "ada", kind: "mentor", note: "" }],
+      arc: "",
+      status: "active",
+      tags: [],
+    };
+    expect(findRelationshipAsymmetry([ada, mentor])).toHaveLength(0);
+  });
+
+  it("exposes the symmetric kinds", () => {
+    expect(SYMMETRIC_RELATIONSHIPS.has("sibling")).toBe(true);
+    expect(SYMMETRIC_RELATIONSHIPS.has("mentor")).toBe(false);
+  });
+});
+
+describe("findInconsistencies", () => {
+  it("combines orphan-mention and relationship-asymmetry issues", () => {
+    const chapters = [{ id: "ch1", title: "Ch 1", doc: doc("ghost") }];
+    const ada: Character = {
+      id: "ada", projectId: "p", name: "Ada", role: "", bio: "", appearance: "", voice: "",
+      relationships: [{ targetId: "maria", kind: "sibling", note: "" }],
+      arc: "", status: "active", tags: [],
+    };
+    const maria: Character = {
+      id: "maria", projectId: "p", name: "Maria", role: "", bio: "", appearance: "", voice: "",
+      relationships: [], arc: "", status: "active", tags: [],
+    };
+    const entities: Entity[] = [ada, maria];
+    const issues = findInconsistencies(chapters, entities);
+    expect(issues.some((i) => i.kind === "orphan-mention")).toBe(true);
+    expect(issues.some((i) => i.kind === "relationship-asymmetry")).toBe(true);
+  });
+});

packages/core/src/consistency.ts

@@ -0,0 +1,130 @@
+/**
+ * Consistency checks across entities and chapters. These catch the kinds of
+ * contradictions that creep in as a manuscript grows: a character mentioned in
+ * prose whose entity was deleted, or a relationship that only one side records.
+ * See CHUNK #4 step 2.4.
+ */
+import type { Character, Entity, ProseMirrorDoc } from "./types.js";
+
+export type RelationshipSymmetry = "symmetric" | "directed";
+
+/**
+ * Relationship kinds that should hold in both directions. If Ada lists "Bram:
+ * sibling", then Bram should list "Ada: sibling" too.
+ */
+export const SYMMETRIC_RELATIONSHIPS = new Set(["sibling", "friend", "spouse", "partner", "family", "rival"]);
+
+export interface MentionIssue {
+  kind: "orphan-mention";
+  chapterId: string;
+  chapterTitle: string;
+  entityId: string;
+  /** The mention text, if any. */
+  name?: string | undefined;
+}
+
+export interface RelationshipIssue {
+  kind: "relationship-asymmetry";
+  fromEntity: string;
+  fromName: string;
+  toEntity: string;
+  toName: string;
+  relationship: string;
+}
+
+export type ConsistencyIssue = MentionIssue | RelationshipIssue;
+
+/**
+ * Find mention nodes that reference an entity id that no longer exists (e.g.
+ * the entity was deleted). Returns one issue per offending mention.
+ */
+export function findOrphanedMentions(
+  chapters: Array<{ id: string; title: string; doc: ProseMirrorDoc }>,
+  entityIds: Set<string>,
+): MentionIssue[] {
+  const issues: MentionIssue[] = [];
+  for (const ch of chapters) {
+    const visit = (content: unknown[], _path: number[]): void => {
+      for (const node of content as Record<string, unknown>[]) {
+        if (!node || typeof node !== "object") continue;
+        if (node.type === "CharacterMention") {
+          const attrs = node.attrs as { entityId?: string; name?: string } | undefined;
+          if (attrs?.entityId && !entityIds.has(attrs.entityId)) {
+            issues.push({
+              kind: "orphan-mention",
+              chapterId: ch.id,
+              chapterTitle: ch.title,
+              entityId: attrs.entityId,
+              name: attrs.name,
+            });
+          }
+        }
+        if (Array.isArray(node.content)) visit(node.content as unknown[], _path);
+      }
+    };
+    visit(ch.doc.content ?? [], []);
+  }
+  return issues;
+}
+
+/**
+ * Parse the `relationships` array of a character into
+ * `{ [targetId]: { kind, note } }`.
+ */
+export function parseRelationships(character: Character): Record<string, { kind: string; note: string }> {
+  const out: Record<string, { kind: string; note: string }> = {};
+  for (const r of character.relationships ?? []) {
+    out[r.targetId] = { kind: r.kind, note: r.note };
+  }
+  return out;
+}
+
+/**
+ * Find relationships recorded by one character but not reciprocated by the
+ * other, for symmetric relationship kinds. Returns one issue per asymmetric
+ * pair (reported once, from the recording side).
+ */
+export function findRelationshipAsymmetry(entities: Entity[]): RelationshipIssue[] {
+  const characters = entities.filter((e): e is Character => !("fields" in e) && !("body" in e));
+  // index by id -> character (targetId is an entity id)
+  const byId = new Map<string, Character>();
+  for (const c of characters) byId.set(c.id, c);
+
+  const issues: RelationshipIssue[] = [];
+  for (const c of characters) {
+    const rels = parseRelationships(c);
+    for (const [targetId, rel] of Object.entries(rels)) {
+      const sym = rel.kind.toLowerCase();
+      if (!SYMMETRIC_RELATIONSHIPS.has(sym)) continue;
+      const other = byId.get(targetId);
+      if (!other || other.id === c.id) continue;
+      // Does the other side record this character back with a symmetric kind?
+      const otherRel = parseRelationships(other);
+      const back = otherRel[c.id];
+      if (!back || !SYMMETRIC_RELATIONSHIPS.has(back.kind.toLowerCase())) {
+        issues.push({
+          kind: "relationship-asymmetry",
+          fromEntity: c.id,
+          fromName: c.name,
+          toEntity: other.id,
+          toName: other.name,
+          relationship: rel.kind,
+        });
+      }
+    }
+  }
+  return issues;
+}
+
+/** Run every consistency check and return the combined issue list. */
+export function findInconsistencies(
+  chapters: Array<{ id: string; title: string; doc: ProseMirrorDoc }>,
+  entities: Entity[],
+): ConsistencyIssue[] {
+  const entityIds = new Set(entities.map((e) => e.id));
+  const issues: ConsistencyIssue[] = [
+    ...findOrphanedMentions(chapters, entityIds),
+    ...findRelationshipAsymmetry(entities),
+  ];
+  return issues;
+}

packages/core/src/fuzzy.test.ts

@@ -0,0 +1,75 @@
+import { describe, it, expect } from "vitest";
+import { fuzzyScore, fuzzyMatch, fuzzySort } from "./fuzzy.js";
+
+describe("fuzzyScore", () => {
+  it("matches an empty query as no-match (score 0)", () => {
+    expect(fuzzyScore("", "mara").score).toBe(0);
+  });
+
+  it("matches a whole-string query at score 1", () => {
+    const r = fuzzyScore("mara", "Mara");
+    expect(r.score).toBe(1);
+    expect(r.indices).toEqual([0, 1, 2, 3]);
+  });
+
+  it("matches a subsequence in order", () => {
+    const r = fuzzyScore("mr", "Mara");
+    expect(r.score).toBeGreaterThan(0);
+    expect(r.indices).toEqual([0, 2]);
+  });
+
+  it("does not match a non-subsequence", () => {
+    expect(fuzzyScore("z", "Mara").score).toBe(0);
+    expect(fuzzyScore("marz", "Mara").score).toBe(0);
+  });
+
+  it("scores consecutive matches higher than scattered ones", () => {
+    const consecutive = fuzzyScore("mar", "maria").score;
+    const scattered = fuzzyScore("mr", "maria").score;
+    expect(consecutive).toBeGreaterThan(scattered);
+  });
+
+  it("scores word-start matches higher", () => {
+    const wordStart = fuzzyScore("h", "harbor").score;
+    const mid = fuzzyScore("r", "harbor").score;
+    expect(wordStart).toBeGreaterThan(mid);
+  });
+});
+
+describe("fuzzyMatch", () => {
+  it("is true for a subsequence and false otherwise", () => {
+    expect(fuzzyMatch("mr", "Mara")).toBe(true);
+    expect(fuzzyMatch("z", "Mara")).toBe(false);
+  });
+});
+
+describe("fuzzySort", () => {
+  const items = [
+    { id: "ada", name: "Ada Lovelace" },
+    { id: "maria", name: "Maria Harbor" },
+    { id: "mark", name: "Mark Twain" },
+  ];
+
+  it("returns all items for an empty query, preserving order", () => {
+    expect(fuzzySort(items, "", (i) => i.name).map((i) => i.id)).toEqual(["ada", "maria", "mark"]);
+  });
+
+  it("drops non-matches and orders by descending score", () => {
+    const sorted = fuzzySort(items, "mar", (i) => i.name);
+    expect(sorted.map((i) => i.id)).toContain("maria");
+    expect(sorted.map((i) => i.id)).not.toContain("ada");
+    // "Maria Harbor" (word start) should beat "Mark Twain" (word start) only on tie-break; both match.
+    expect(sorted.length).toBe(2);
+  });
+
+  it("is stable for equal scores", () => {
+    // "ada" and "amy" both score 2 for query "a" (word-start match); input
+    // order must be preserved.
+    const stable = [
+      { id: "a", name: "ada" },
+      { id: "b", name: "amy" },
+    ];
+    const sorted = fuzzySort(stable, "a", (i) => i.name);
+    expect(sorted.map((i) => i.id)).toEqual(["a", "b"]);
+  });
+});

packages/core/src/fuzzy.ts

@@ -0,0 +1,111 @@
+/**
+ * Dependency-light fuzzy scorer used for entity search and mention
+ * autocomplete.
+ *
+ * This is a subsequence scorer in the spirit of "sublime" / Fuse.js: a query is
+ * a sequence of characters that must appear (in order) within a target string.
+ * It scores matches so that:
+ *
+ *   - consecutive matches score higher than scattered ones,
+ *   - matches at the start of a word (after a separator) score higher,
+ *   - earlier matches in the string score higher.
+ *
+ * The result is a number in `[0, 1]` where `1` is a perfect (whole-string,
+ * case-insensitive, consecutive) match. It is intentionally allocation-light
+ * and fast enough to run on every keystroke against a few hundred entities
+ * well under the 50 ms budget the plan calls for.
+ */
+
+const WORD_SEP = /[^a-zA-Z0-9]+/;
+
+export interface FuzzyResult {
+  /** Match score in [0, 1]; 0 means no match. */
+  score: number;
+  /** Indices in `target` that were matched by the query, in order. */
+  indices: number[];
+}
+
+/** Score a single matched cell from its predecessor score. */
+function scoreCell(prev: number, consecutive: number, wordStart: number): number {
+  let s = prev + 1; // base reward for a match
+  if (consecutive) s *= 1.4; // multiplicative streak bonus
+  if (wordStart) s += 0.8; // word-start bonus
+  return s;
+}
+
+/** Normalize a raw score into [0, 1]. */
+function normalize(raw: number): number {
+  if (!isFinite(raw)) return 0;
+  return Math.max(0, Math.min(1, raw / 3));
+}
+
+/**
+ * Score `query` against `target`. Returns `{ score: 0 }` when the query is not a
+ * subsequence of the target (i.e. no match).
+ */
+export function fuzzyScore(query: string, target: string): FuzzyResult {
+  const q = query;
+  const t = target;
+  if (q.length === 0) return { score: 0, indices: [] };
+  if (q.length > t.length) return { score: 0, indices: [] };
+
+  const ql = q.length;
+  const tl = t.length;
+  const tq = q.toLowerCase();
+  const tt = t.toLowerCase();
+
+  // best[i] = best score having matched the first i query chars.
+  // where[i] = target index at which the i-th match landed (for recovery).
+  const best = new Float64Array(ql + 1).fill(-Infinity);
+  const where = new Int32Array(ql + 1);
+  const consec = new Uint8Array(ql + 1);
+  best[0] = 0;
+
+  for (let ti = 0; ti < tl; ti++) {
+    const tc = tt[ti]!;
+    // Walk from high to low so each cell reads the previous row only.
+    for (let i = ql; i >= 1; i--) {
+      const qc = tq[i - 1]!;
+      if (tc !== qc) continue;
+      const fromPrev = best[i - 1]!;
+      if (fromPrev <= -Infinity) continue;
+      const wordStart = ti === 0 || WORD_SEP.test(t[ti - 1]!) ? 1 : 0;
+      const c = consec[i - 1] ? 1 : 0;
+      const s = scoreCell(fromPrev, c, wordStart);
+      if (s > best[i]!) {
+        best[i] = s;
+        where[i] = ti;
+        consec[i] = c;
+      }
+    }
+  }
+
+  if (best[ql]! <= -Infinity) return { score: 0, indices: [] };
+
+  // Recover matched indices by walking `where` backwards.
+  const indices: number[] = [];
+  for (let i = ql; i >= 1; i--) {
+    indices.push(where[i]!);
+  }
+  indices.reverse();
+
+  return { score: normalize(best[ql]!), indices };
+}
+
+/** Convenience: does `query` match `target` as a subsequence? */
+export function fuzzyMatch(query: string, target: string): boolean {
+  return fuzzyScore(query, target).score > 0;
+}
+
+/**
+ * Sort `items` by descending fuzzy score against `query`, dropping non-matches.
+ * Stable: equal scores keep input order.
+ */
+export function fuzzySort<T>(items: T[], query: string, pick: (item: T) => string): T[] {
+  if (!query) return items.slice();
+  const scored = items
+    .map((item) => ({ item, res: fuzzyScore(query, pick(item)) }))
+    .filter((r) => r.res.score > 0);
+  scored.sort((a, b) => b.res.score - a.res.score);
+  return scored.map((r) => r.item);
+}

packages/core/src/index.ts

@@ -12,4 +12,6 @@ export * from "./schema.js";
 export * from "./schemas.js";
 export * from "./autosave.js";
 export * from "./backlinks.js";
+export * from "./fuzzy.js";
+export * from "./consistency.js";
 export * from "./storage-server.js";

packages/core/src/storage-local.ts

@@ -13,6 +13,7 @@ import type {
 import type { StorageAdapter } from "./storage.js";
 import { createUlid } from "./ids.js";
 import { nowIso } from "./time.js";
+import { fuzzySort } from "./fuzzy.js";
 
 interface EntityRec {
   key: string;
@@ -49,6 +50,35 @@ const entityKey = (projectId: string, kind: string, id: string): string =>
 const kindOf = (e: Entity): string =>
   "fields" in e ? "world" : "body" in e ? "note" : "character";
 
+/**
+ * Concatenate every human-readable field of an entity into a single searchable
+ * string (name + field values). Used by the fuzzy search index.
+ */
+function entitySearchText(e: Entity): string {
+  if ("fields" in e) {
+    // WorldItem
+    const parts = [e.name, e.kind];
+    for (const v of Object.values(e.fields)) if (typeof v === "string") parts.push(v);
+    return parts.join(" ");
+  }
+  if ("body" in e) {
+    // Note
+    return [e.body, ...e.tags].join(" ");
+  }
+  // Character
+  return [
+    e.name,
+    e.role,
+    e.bio,
+    e.appearance,
+    e.voice,
+    e.relationships,
+    e.arc,
+    e.status,
+    ...e.tags,
+  ].join(" ");
+}
+
 /**
  * The local (offline-first) `StorageAdapter`, backed by IndexedDB via Dexie.
  * Implements the exact `StorageAdapter` contract so the app can run fully
@@ -136,6 +166,30 @@ export const storageLocal: StorageAdapter = {
     await db.entities.put({ key: entityKey(e.projectId, kind, e.id), projectId: e.projectId, kind, data: e });
   },
 
+  async listEntities(projectId: string, kind?: string): Promise<Entity[]> {
+    const rows = await db.entities
+      .where("projectId")
+      .equals(projectId)
+      .toArray();
+    const filtered = kind ? rows.filter((r) => r.kind === kind) : rows;
+    return filtered.map((r) => r.data);
+  },
+
+  async getEntity(projectId: string, kind: string, id: string): Promise<Entity | null> {
+    const row = await db.entities.get(entityKey(projectId, kind, id));
+    return row ? row.data : null;
+  },
+
+  async deleteEntity(projectId: string, kind: string, id: string): Promise<void> {
+    await db.entities.delete(entityKey(projectId, kind, id));
+  },
+
+  async searchEntities(projectId: string, q: string): Promise<Entity[]> {
+    const all = await this.listEntities(projectId);
+    if (!q) return all;
+    return fuzzySort(all, q, entitySearchText);
+  },
+
   async saveBoard(b: Board): Promise<void> {
     await db.boards.put(b);
   },

packages/core/src/storage-server.ts

@@ -118,6 +118,41 @@ export function createServerClient(opts: ServerClientOptions): StorageAdapter {
       }
     },
 
+    async listEntities(projectId: string, kind?: string): Promise<Entity[]> {
+      const params = new URLSearchParams();
+      if (kind) params.set("kind", kind);
+      const qs = params.toString();
+      const res = await req<{ entities: Entity[] }>(
+        "GET",
+        `/api/projects/${projectId}/entities${qs ? `?${qs}` : ""}`,
+      );
+      return res.entities;
+    },
+
+    async getEntity(projectId: string, kind: string, id: string): Promise<Entity | null> {
+      try {
+        const res = await req<{ entity: Entity }>(
+          "GET",
+          `/api/projects/${projectId}/entities/${kind}/${id}`,
+        );
+        return res.entity;
+      } catch {
+        return null;
+      }
+    },
+
+    async deleteEntity(projectId: string, kind: string, id: string): Promise<void> {
+      await req("DELETE", `/api/projects/${projectId}/entities/${kind}/${id}`);
+    },
+
+    async searchEntities(projectId: string, q: string): Promise<Entity[]> {
+      const res = await req<{ entities: Entity[] }>(
+        "GET",
+        `/api/projects/${projectId}/entities?q=${encodeURIComponent(q)}`,
+      );
+      return res.entities;
+    },
+
     async saveBoard(b: Board): Promise<void> {
       await req("POST", `/api/projects/${b.projectId}/boards`, {
         id: b.id,

packages/core/src/storage.contract.test.ts

@@ -1,6 +1,6 @@
 import "fake-indexeddb/auto";
 import { describe, expect, it } from "vitest";
-import { createServerClient, type ProseMirrorDoc, type StorageAdapter } from "@pubscript/core";
+import { createServerClient, type ProseMirrorDoc, type Character, type StorageAdapter, type WorldItem } from "@pubscript/core";
 import { storageLocal } from "@pubscript/core/local";
 
 const doc = (text: string): ProseMirrorDoc => ({ type: "doc", content: [{ type: "text", text }] });
@@ -63,6 +63,31 @@ function mockServerFetch(): typeof fetch {
       entities.set(`${m[1]!}|${body.kind}|${e.id}`, e);
       return json({ entity: e });
     }
+    if (method === "GET" && m) {
+      const projectId = m[1]!;
+      const kind = u.searchParams.get("kind");
+      const q = u.searchParams.get("q") ?? "";
+      const all = [...entities.values()].filter((e) => e.projectId === projectId && (!kind || e.kind === kind));
+      const filtered = q
+        ? all.filter((e) => JSON.stringify(e).toLowerCase().includes(q.toLowerCase()))
+        : all;
+      return json({ entities: filtered });
+    }
+    m = u.pathname.match(/^\/api\/projects\/([^/]+)\/entities\/([^/]+)\/([^/]+)$/);
+    if (method === "GET" && m) {
+      const projectId = m[1]!;
+      const kind = m[2]!;
+      const id = m[3]!;
+      const e = entities.get(`${projectId}|${kind}|${id}`);
+      return e ? json({ entity: e }) : json({ error: "not_found" }, 404);
+    }
+    if (method === "DELETE" && m) {
+      const projectId = m[1]!;
+      const kind = m[2]!;
+      const id = m[3]!;
+      entities.delete(`${projectId}|${kind}|${id}`);
+      return json({ ok: true });
+    }
     m = u.pathname.match(/^\/api\/projects\/([^/]+)\/boards$/);
     if (method === "POST" && m) {
       const b = { id: body.id ?? id(), projectId: m[1]!, nodes: body.nodes ?? [], edges: body.edges ?? [] };
@@ -132,6 +157,85 @@ const EXPECTED = {
   chapterRev: 1,
 };
 
+/** Entity CRUD + search scenario both adapters must pass identically. */
+async function entityScenario(adapter: StorageAdapter) {
+  const projectId = "proj-ent";
+  await adapter.createProject({ title: "Entities" });
+
+  const ada: Character = {
+    id: "ada",
+    projectId,
+    name: "Ada Lovelace",
+    role: "protagonist",
+    bio: "A mathematician and first computer programmer.",
+    appearance: "sharp eyes, Victorian dress",
+    voice: "precise, confident",
+    relationships: [{ targetId: "babbage", kind: "ally", note: "worked together" }],
+    arc: "From curiosity to genius.",
+    status: "active",
+    tags: ["math", "victorian"],
+  };
+  const babbage: Character = {
+    id: "babbage",
+    projectId,
+    name: "Charles Babbage",
+    role: "mentor",
+    bio: "An obsessed inventor of computing machines.",
+    appearance: "bearded, bespectacled",
+    voice: "grumbly",
+    relationships: [],
+    arc: "",
+    status: "active",
+    tags: ["inventor"],
+  };
+  const clocktower: WorldItem = {
+    id: "clocktower",
+    projectId,
+    kind: "location",
+    name: "The Clocktower",
+    fields: { era: "1840s", significance: "meeting place" },
+  };
+
+  await adapter.saveEntity(ada);
+  await adapter.saveEntity(babbage);
+  await adapter.saveEntity(clocktower);
+
+  // list all
+  const all = await adapter.listEntities(projectId);
+  expect(all.map((e) => e.id).sort()).toEqual(["ada", "babbage", "clocktower"]);
+
+  // list by kind
+  const chars = await adapter.listEntities(projectId, "character");
+  expect(chars.map((e) => e.id).sort()).toEqual(["ada", "babbage"]);
+
+  // getEntity: found
+  expect(((await adapter.getEntity(projectId, "character", "ada")) as Character | null)?.name).toBe("Ada Lovelace");
+
+  // getEntity: not found
+  expect(await adapter.getEntity(projectId, "character", "nope")).toBeNull();
+
+  // search: fuzzy match, best-first
+  const babbageRes = await adapter.searchEntities(projectId, "babbage");
+  expect(babbageRes.map((e) => e.id)).toContain("babbage");
+  const adaRes = await adapter.searchEntities(projectId, "ada");
+  expect(adaRes[0]?.id).toBe("ada");
+
+  // search: empty returns all
+  expect((await adapter.searchEntities(projectId, "")).length).toBe(3);
+
+  // delete
+  await adapter.deleteEntity(projectId, "character", "ada");
+  expect(await adapter.getEntity(projectId, "character", "ada")).toBeNull();
+  expect((await adapter.listEntities(projectId)).map((e) => e.id)).toEqual(["babbage", "clocktower"]);
+}
+
+describe.each([
+  { name: "local (IndexedDB)", adapter: storageLocal },
+  { name: "server (REST)", adapter: createServerClient({ baseUrl: "http://test", fetch: mockServerFetch() }) },
+])("$name adapter honors the entity contract", async ({ adapter }) => {
+  it("lists, fetches, searches, and deletes entities", () => entityScenario(adapter));
+});
+
 describe("StorageAdapter contract (web/local vs server)", () => {
   it("local (IndexedDB) adapter honors the contract", async () => {
     await expect(runScenario(storageLocal)).resolves.toMatchObject(EXPECTED);

packages/core/src/storage.ts

@@ -40,6 +40,18 @@ export interface StorageAdapter {
   saveDocument(doc: DocumentRef): Promise<void>;
   getChapter(id: string): Promise<Chapter | null>;
   saveEntity(e: Entity): Promise<void>;
+  /**
+   * List entities for a project, optionally filtered by kind ("character" |
+   * "world" | "note"). Returns every entity when `kind` is omitted.
+   */
+  listEntities(projectId: string, kind?: string): Promise<Entity[]>;
+  getEntity(projectId: string, kind: string, id: string): Promise<Entity | null>;
+  deleteEntity(projectId: string, kind: string, id: string): Promise<void>;
+  /**
+   * Fuzzy search across an entity's name and field values. Returns matches
+   * ordered best-first; empty `q` returns all entities for the project.
+   */
+  searchEntities(projectId: string, q: string): Promise<Entity[]>;
   saveBoard(b: Board): Promise<void>;
   saveAISession(s: AISession): Promise<void>;
 

packages/core/src/types.ts

@@ -130,6 +130,10 @@ export type RelationshipKind =
   | "ally"
   | "rival"
   | "family"
+  | "sibling"
+  | "friend"
+  | "spouse"
+  | "partner"
   | "mentor"
   | "romantic"
   | "custom";
@@ -141,7 +145,7 @@ export interface WorldItem {
   projectId: string;
   kind: WorldItemKind;
   name: string;
-  fields: Record<string, string>;
+  fields: Record<string, string | string[]>;
 }
 
 export type BeatTemplate =