@hollis-labs/surface-page 0.3.0 → 0.4.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (40) hide show
  1. package/dist/chunks/chunk-LODRWYOW.js +2060 -0
  2. package/dist/gallery.js +491 -310
  3. package/dist/index.js +385 -387
  4. package/dist/registry-items.json +3 -0
  5. package/dist/sdk.js +13 -1
  6. package/dist/types/agent/api.d.ts +34 -2
  7. package/dist/types/agent/session.d.ts +2 -5
  8. package/dist/types/cards/store.d.ts +13 -1
  9. package/dist/types/cards/views.d.ts +3 -2
  10. package/dist/types/cite/core/detect.d.ts +26 -0
  11. package/dist/types/cite/core/index.d.ts +17 -0
  12. package/dist/types/cite/core/kinds/caster.d.ts +3 -0
  13. package/dist/types/cite/core/kinds/fragment.d.ts +3 -0
  14. package/dist/types/cite/core/kinds/ops.d.ts +3 -0
  15. package/dist/types/cite/core/kinds/path.d.ts +8 -0
  16. package/dist/types/cite/core/kinds/registry.d.ts +3 -0
  17. package/dist/types/cite/core/kinds/tesseract.d.ts +11 -0
  18. package/dist/types/cite/core/kinds/tether.d.ts +4 -0
  19. package/dist/types/cite/core/kinds/torque.d.ts +11 -0
  20. package/dist/types/cite/core/kinds/url.d.ts +2 -0
  21. package/dist/types/cite/core/kinds/work.d.ts +3 -0
  22. package/dist/types/cite/core/preview.d.ts +8 -0
  23. package/dist/types/cite/core/registry.d.ts +19 -0
  24. package/dist/types/cite/core/resolver.d.ts +34 -0
  25. package/dist/types/cite/core/scan-utils.d.ts +9 -0
  26. package/dist/types/cite/core/tach.d.ts +3 -0
  27. package/dist/types/cite/core/types.d.ts +161 -0
  28. package/dist/types/cite/record.d.ts +11 -0
  29. package/dist/types/cite/remark.d.ts +32 -0
  30. package/dist/types/cite/store.d.ts +35 -0
  31. package/dist/types/cite/structured-view.d.ts +9 -0
  32. package/dist/types/cite/structured.d.ts +90 -0
  33. package/dist/types/cite/terminal.d.ts +15 -0
  34. package/dist/types/cite/ui.d.ts +52 -0
  35. package/dist/types/gallery/Gallery.d.ts +5 -0
  36. package/dist/types/gallery/cite.d.ts +1 -0
  37. package/dist/types/sdk/index.d.ts +3 -0
  38. package/dist/types/sdk/types.d.ts +37 -0
  39. package/package.json +5 -5
  40. package/dist/chunks/chunk-ZT6LTRMY.js +0 -220
@@ -0,0 +1,90 @@
1
+ /**
2
+ * A record whose text is a JSON document (a Caster doc a tool wrote, a registry profile, a
3
+ * delivery trace), as something to read rather than a wall of JSON: an object is labeled
4
+ * fields, a list of objects is a list of sub-cards titled by their most telling field, and
5
+ * a long string is text (Markdown when it looks like Markdown). Pure: structured-view.tsx draws it.
6
+ */
7
+ /** One value, shaped for reading. */
8
+ export type DocNode =
9
+ /** A short value on one line: a number, a word, an id, a date. */
10
+ {
11
+ type: "scalar";
12
+ text: string;
13
+ mono?: boolean;
14
+ iso?: string;
15
+ empty?: boolean;
16
+ }
17
+ /** A long string, or one with line breaks: a block of text. */
18
+ | {
19
+ type: "text";
20
+ text: string;
21
+ markdown: boolean;
22
+ }
23
+ /** An object: its fields, short ones first. */
24
+ | {
25
+ type: "fields";
26
+ fields: DocField[];
27
+ }
28
+ /** A list of objects: one sub-card each. */
29
+ | {
30
+ type: "list";
31
+ items: DocItem[];
32
+ }
33
+ /** A list of short values. */
34
+ | {
35
+ type: "values";
36
+ values: string[];
37
+ }
38
+ /** Too deep to lay out: shown as JSON. */
39
+ | {
40
+ type: "json";
41
+ text: string;
42
+ };
43
+ export interface DocField {
44
+ key: string;
45
+ label: string;
46
+ node: DocNode;
47
+ }
48
+ export interface DocItem {
49
+ title: string;
50
+ /** The item's id, when the title is another field. */
51
+ subtitle?: string;
52
+ fields: DocField[];
53
+ }
54
+ /** Text that is a JSON object or array, parsed; anything else (Markdown, a bare value, JSON cut short) is undefined. */
55
+ export declare function parseJSONDocument(text: string | undefined): object | undefined;
56
+ /** A JSON key as a label: "created_at" is "Created at", "messageId" is "Message id". */
57
+ export declare function humanize(key: string): string;
58
+ /** A string longer than this, or with a line break, is a block of text. */
59
+ export declare const LONG_TEXT = 120;
60
+ /** Whether a block of text reads as Markdown (a heading, a list, a fence, emphasis, a link). */
61
+ export declare function looksLikeMarkdown(s: string): boolean;
62
+ /** A sub-card's title and id, and which keys they came from. */
63
+ export declare function titleOf(o: Record<string, unknown>, index: number): {
64
+ title: string;
65
+ subtitle?: string;
66
+ used: string[];
67
+ };
68
+ /** Whether a field is drawn on one line (in the label/value grid) rather than as a section. */
69
+ export declare const isInline: (f: DocField) => boolean;
70
+ /** A JSON value shaped for reading. */
71
+ export declare function toDocNode(v: unknown, depth?: number): DocNode;
72
+ /** An object's fields: the one-line values first, then the blocks, each group in the document's order. */
73
+ export declare function fieldsOf(o: Record<string, unknown>, depth?: number): DocField[];
74
+ /**
75
+ * Markdown's YAML front matter, split off: its simple `key: value` lines as fields, and the
76
+ * text after it. Undefined when the text has none.
77
+ */
78
+ export declare function splitFrontMatter(text: string): {
79
+ fields: DocField[];
80
+ rest: string;
81
+ } | undefined;
82
+ /** Items of a list drawn before "Show more". */
83
+ export declare const LIST_PAGE = 50;
84
+ /** A document past either of these is shown raw, not laid out: drawing it would stall the page. */
85
+ export declare const MAX_LAYOUT_BYTES: number;
86
+ export declare const MAX_LAYOUT_VALUES = 5000;
87
+ /** Whether a document is small enough to lay out: its text and the number of values in it. */
88
+ export declare function fitsLayout(text: string, doc: unknown): boolean;
89
+ /** Text in a Markdown code fence its own backticks cannot close: shown exactly as it is. */
90
+ export declare function fenced(text: string, lang: string): string;
@@ -0,0 +1,15 @@
1
+ /**
2
+ * References in terminal output: a task id an agent printed is a link. Hovering shows the
3
+ * reference's card beside the pointer; activating it (a click) opens the record. Only kinds
4
+ * with a record behind them are linked: web addresses are the terminal's own web links, and
5
+ * paths would underline every listing.
6
+ *
7
+ * Ported from Basalisk (frontend/src/cite/terminal.ts). The card is one floating layer for
8
+ * the whole page (CiteFloat, mounted at the root), since a terminal's text is drawn on a
9
+ * canvas and has no element to hang a hover card on.
10
+ */
11
+ import type { ILinkProvider, Terminal } from "@xterm/xterm";
12
+ /** The link provider the terminal takes (registry Terminal, linkProviders). */
13
+ export declare function citeTerminalLinks(term: Terminal): ILinkProvider;
14
+ /** The floating card for references hovered in a terminal. Mounted once, at the page root. */
15
+ export declare function CiteFloat(): import("react").JSX.Element | null;
@@ -0,0 +1,52 @@
1
+ /**
2
+ * Cite in the page: a reference as a chip with a hover card (CiteRef), plain text with its
3
+ * references as chips (CiteText), and what Markdown needs to do the same (citeMarkdownExtensions).
4
+ */
5
+ import { type LucideIcon } from "lucide-react";
6
+ import { type ComponentProps, type ReactNode } from "react";
7
+ import { type RefIdentity } from "./core/index.ts";
8
+ export declare const iconFor: (kind: string) => LucideIcon;
9
+ /** "3m ago", from an ISO time. */
10
+ export declare function ago(iso?: string): string | undefined;
11
+ /** "updated 3m ago", as the card's foot says it. */
12
+ export declare const updatedAgo: (iso?: string) => string | undefined;
13
+ /** A subtitle worth showing: not the kind's own name again ("Torque task" under "TORQUE TASK"). */
14
+ export declare const subtitleFor: (kind: string, subtitle?: string) => string | undefined;
15
+ /** The hover card's body for a reference: what it is, as far as is known now. */
16
+ export declare function RefCard({ refId }: {
17
+ refId: RefIdentity;
18
+ }): import("react").JSX.Element;
19
+ /**
20
+ * A reference, inline: an icon and a label, with a card on hover or focus, opened on click.
21
+ * Once resolved the label is the record's own ("Task: Fix the thing"); until then it is what
22
+ * was written, or `label` (a Markdown link's text).
23
+ */
24
+ export declare function CiteRef({ refId, raw, label, mono, }: {
25
+ refId: RefIdentity;
26
+ raw?: string;
27
+ label?: string;
28
+ mono?: boolean;
29
+ }): import("react").JSX.Element;
30
+ /** Plain text with its references as chips. For text that is not Markdown. */
31
+ export declare function CiteText({ text }: {
32
+ text: string;
33
+ }): import("react").JSX.Element;
34
+ /** The remark plugin over the page's registry. */
35
+ export declare const remarkCite: () => (tree: unknown) => void;
36
+ /** The `cite` element remarkCite makes, drawn as a chip; any other <cite> as it is. */
37
+ declare function CiteElement({ node: _node, children, ...props }: ComponentProps<"cite"> & {
38
+ node?: unknown;
39
+ children?: ReactNode;
40
+ }): import("react").JSX.Element;
41
+ /**
42
+ * What Markdown needs to show references as chips: the remark plugin and the component that
43
+ * draws its element. For the Markdown component's `remarkPlugins` and `components`, or its
44
+ * MarkdownExtensions provider (every Markdown below it).
45
+ */
46
+ export declare const citeMarkdownExtensions: {
47
+ remarkPlugins: (() => (tree: unknown) => void)[];
48
+ components: {
49
+ cite: typeof CiteElement;
50
+ };
51
+ };
52
+ export {};
@@ -7,6 +7,7 @@ import type { ViewProps } from "@hollis-labs/surface-page/sdk";
7
7
  import { Ade } from "./ade";
8
8
  import { Cards } from "./cards";
9
9
  import { Chat } from "./chat";
10
+ import { Cite } from "./cite";
10
11
  import { Controls } from "./controls";
11
12
  import { Display } from "./display";
12
13
  import { Genui } from "./genui";
@@ -34,6 +35,10 @@ export declare const SECTIONS: readonly [{
34
35
  readonly id: "chat";
35
36
  readonly title: "Chat";
36
37
  readonly draw: typeof Chat;
38
+ }, {
39
+ readonly id: "cite";
40
+ readonly title: "Cite";
41
+ readonly draw: typeof Cite;
37
42
  }, {
38
43
  readonly id: "cards";
39
44
  readonly title: "Cards";
@@ -0,0 +1 @@
1
+ export declare function Cite(): import("react").JSX.Element;
@@ -1,6 +1,9 @@
1
1
  /**
2
2
  * @hollis-labs/surface-page/sdk: everything a module's web code may import from Surface.
3
3
  */
4
+ export { RecordBody } from "../cite/record.tsx";
5
+ export { citeTerminalLinks } from "../cite/terminal.tsx";
6
+ export { CiteRef, CiteText, citeMarkdownExtensions, remarkCite } from "../cite/ui.tsx";
4
7
  export { useAnchor } from "./anchors";
5
8
  export { useEvent, useMarks, useSetting } from "./hooks";
6
9
  export { Icon } from "./icon";
@@ -76,10 +76,47 @@ export interface ViewProps {
76
76
  desk: Desk;
77
77
  api: ModuleAPI;
78
78
  }
79
+ /** A card as a module's card renderer receives it (module.Card). */
80
+ export interface ModuleCard {
81
+ id: string;
82
+ kind: string;
83
+ version?: string;
84
+ title?: string;
85
+ source?: string;
86
+ subject?: string;
87
+ risk?: string;
88
+ blocking?: boolean;
89
+ payload?: Record<string, unknown>;
90
+ status?: string;
91
+ expires_at?: string;
92
+ }
93
+ /** An answer to a card (module.CardOutcome). */
94
+ export interface ModuleCardOutcome {
95
+ status: "submitted" | "canceled";
96
+ data?: Record<string, unknown>;
97
+ answers?: {
98
+ questionId: string;
99
+ value: unknown;
100
+ note?: string;
101
+ }[];
102
+ decisions?: {
103
+ itemId: string;
104
+ action: string;
105
+ note?: string;
106
+ }[];
107
+ }
108
+ /** What a module's card renderer receives: the card, how to answer it, and the module's routes. */
109
+ export interface CardProps {
110
+ card: ModuleCard;
111
+ respond: (outcome: ModuleCardOutcome) => Promise<void>;
112
+ api: ModuleAPI;
113
+ }
79
114
  /** A module's web entry. */
80
115
  export interface ModuleWeb {
81
116
  /** By Render.Entry. */
82
117
  views: Record<string, ComponentType<ViewProps>>;
118
+ /** Renderers for card kinds of the module's own, by kind (version 1), or "kind@version". */
119
+ cards?: Record<string, ComponentType<CardProps>>;
83
120
  }
84
121
  /** A mark (module.Mark). */
85
122
  export interface Mark {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@hollis-labs/surface-page",
3
- "version": "0.3.0",
3
+ "version": "0.4.1",
4
4
  "description": "The core of a Surface app's page: the desktop (bar, windows, palette), the agent panel, cards, generated surfaces, ADE's overlays, and the sdk a module's views import. It draws with the app's installed Surface registry components.",
5
5
  "license": "MIT",
6
6
  "repository": {
@@ -51,10 +51,10 @@
51
51
  },
52
52
  "dependencies": {
53
53
  "@hollis-labs/ade-core": "0.1.0",
54
- "@hollis-labs/surface-cards": "0.3.0",
55
- "@hollis-labs/surface-chat": "0.3.0",
56
- "@hollis-labs/surface-genui": "0.3.0",
57
- "@hollis-labs/surface-theme": "0.3.0"
54
+ "@hollis-labs/surface-cards": "0.4.1",
55
+ "@hollis-labs/surface-chat": "0.4.1",
56
+ "@hollis-labs/surface-genui": "0.4.1",
57
+ "@hollis-labs/surface-theme": "0.4.1"
58
58
  },
59
59
  "peerDependencies": {
60
60
  "lucide-react": ">=1",
@@ -1,220 +0,0 @@
1
- // ../../web/src/sdk/anchors.ts
2
- import { useCallback } from "react";
3
-
4
- // ../../web/src/sdk/runtime.ts
5
- var ApiError = class extends Error {
6
- status;
7
- body;
8
- constructor(message, status, body) {
9
- super(message);
10
- this.status = status;
11
- this.body = body;
12
- }
13
- };
14
- async function call(method, path, body) {
15
- const res = await fetch(path, {
16
- method,
17
- headers: body === void 0 ? void 0 : { "Content-Type": "application/json" },
18
- body: body === void 0 ? void 0 : JSON.stringify(body)
19
- });
20
- const text = await res.text();
21
- let data = null;
22
- try {
23
- data = text ? JSON.parse(text) : null;
24
- } catch {
25
- data = text;
26
- }
27
- if (!res.ok) {
28
- const msg = data?.error ?? `${res.status} ${res.statusText}`;
29
- throw new ApiError(msg, res.status, data);
30
- }
31
- return data;
32
- }
33
- var listeners = /* @__PURE__ */ new Set();
34
- var matches = (prefix, topic) => prefix === "" || topic === prefix || topic.startsWith(`${prefix}.`);
35
- function onEvent(prefix, fn) {
36
- const entry = { prefix, fn };
37
- listeners.add(entry);
38
- return () => {
39
- listeners.delete(entry);
40
- };
41
- }
42
- function dispatch(ev) {
43
- for (const l of [...listeners]) {
44
- if (!matches(l.prefix, ev.topic)) continue;
45
- try {
46
- l.fn(ev);
47
- } catch (err) {
48
- console.error("surface: an event listener failed", ev.topic, err);
49
- }
50
- }
51
- }
52
- var source = null;
53
- var connected = false;
54
- var connectionListeners = /* @__PURE__ */ new Set();
55
- var isConnected = () => connected;
56
- function onConnection(fn) {
57
- connectionListeners.add(fn);
58
- return () => {
59
- connectionListeners.delete(fn);
60
- };
61
- }
62
- function connect() {
63
- if (source) return;
64
- source = new EventSource("/api/events");
65
- source.addEventListener("surface", (e) => {
66
- if (!connected) {
67
- connected = true;
68
- for (const fn of connectionListeners) fn(true);
69
- }
70
- try {
71
- dispatch(JSON.parse(e.data));
72
- } catch (err) {
73
- console.error("surface: bad event", err);
74
- }
75
- });
76
- source.onopen = () => {
77
- connected = true;
78
- for (const fn of connectionListeners) fn(true);
79
- };
80
- source.onerror = () => {
81
- connected = false;
82
- for (const fn of connectionListeners) fn(false);
83
- };
84
- }
85
- var settings = /* @__PURE__ */ new Map();
86
- async function loadSettings() {
87
- const list = await call("GET", "/api/settings");
88
- settings.clear();
89
- for (const s of list) settings.set(s.full_key, s);
90
- return list;
91
- }
92
- var getSetting = (fullKey) => settings.get(fullKey)?.value;
93
- var allSettings = () => [...settings.values()];
94
- onEvent("config.changed", (ev) => {
95
- const d = ev.data;
96
- const s = settings.get(d.key);
97
- if (s) settings.set(d.key, { ...s, value: d.value, set: true });
98
- });
99
- async function setSetting(fullKey, value) {
100
- await call("PUT", `/api/settings/${encodeURIComponent(fullKey)}`, { value });
101
- }
102
- var listMarks = (ref) => call("GET", `/api/marks?ref=${encodeURIComponent(ref)}`);
103
-
104
- // ../../web/src/sdk/anchors.ts
105
- var byWindow = /* @__PURE__ */ new Map();
106
- var pending = /* @__PURE__ */ new Map();
107
- function report(win) {
108
- clearTimeout(pending.get(win));
109
- pending.set(
110
- win,
111
- setTimeout(() => {
112
- pending.delete(win);
113
- const list = [...byWindow.get(win)?.entries() ?? []].map(([name, e]) => ({ name, label: e.label }));
114
- void call("PUT", `/api/ade/anchors/${encodeURIComponent(win)}`, list).catch(() => {
115
- });
116
- }, 150)
117
- );
118
- }
119
- function useAnchor(win, name, label) {
120
- const id = typeof win === "string" ? win : win.id;
121
- return useCallback(
122
- (el) => {
123
- if (!el) return;
124
- let m = byWindow.get(id);
125
- if (!m) {
126
- m = /* @__PURE__ */ new Map();
127
- byWindow.set(id, m);
128
- }
129
- m.set(name, { el, label });
130
- report(id);
131
- return () => {
132
- const now = byWindow.get(id);
133
- if (now?.get(name)?.el !== el) return;
134
- now.delete(name);
135
- if (!now.size) byWindow.delete(id);
136
- report(id);
137
- };
138
- },
139
- [id, name, label]
140
- );
141
- }
142
- var anchorElement = (win, name) => byWindow.get(win)?.get(name)?.el ?? null;
143
-
144
- // ../../web/src/sdk/hooks.ts
145
- import { useEffect, useRef, useState } from "react";
146
- function useEvent(prefix, fn) {
147
- const ref = useRef(fn);
148
- ref.current = fn;
149
- useEffect(() => onEvent(prefix, (ev) => ref.current(ev)), [prefix]);
150
- }
151
- function useSetting(fullKey) {
152
- const [value, setValue] = useState(() => getSetting(fullKey));
153
- useEffect(() => {
154
- setValue(getSetting(fullKey));
155
- return onEvent("config.changed", (ev) => {
156
- const d = ev.data;
157
- if (d?.key === fullKey) setValue(d.value);
158
- });
159
- }, [fullKey]);
160
- return value;
161
- }
162
- function useMarks(ref) {
163
- const [marks, setMarks] = useState([]);
164
- useEffect(() => {
165
- if (!ref) {
166
- setMarks([]);
167
- return;
168
- }
169
- let live = true;
170
- const load = () => listMarks(ref).then((m) => {
171
- if (live) setMarks(m);
172
- });
173
- void load();
174
- const off = onEvent("marks.changed", (ev) => {
175
- if (ev.data?.ref === ref) void load();
176
- });
177
- return () => {
178
- live = false;
179
- off();
180
- };
181
- }, [ref]);
182
- return marks;
183
- }
184
-
185
- // ../../web/src/sdk/icon.tsx
186
- import { icons } from "lucide-react";
187
- import { jsx } from "react/jsx-runtime";
188
- var pascal = (name) => name.split("-").map((p) => p.charAt(0).toUpperCase() + p.slice(1)).join("");
189
- function Icon({ name, ...props }) {
190
- const Cmp = name ? icons[pascal(name)] : void 0;
191
- if (!Cmp) return /* @__PURE__ */ jsx(icons.Dot, { ...props });
192
- return /* @__PURE__ */ jsx(Cmp, { ...props });
193
- }
194
-
195
- // ../../web/src/sdk/marks.ts
196
- var addMark = (m) => call("POST", "/api/marks", m);
197
- var replyMark = (id, body) => call("POST", `/api/marks/${encodeURIComponent(id)}/replies`, { body });
198
- var resolveMark = (id) => call("POST", `/api/marks/${encodeURIComponent(id)}/resolve`);
199
-
200
- export {
201
- ApiError,
202
- call,
203
- onEvent,
204
- isConnected,
205
- onConnection,
206
- connect,
207
- loadSettings,
208
- getSetting,
209
- allSettings,
210
- setSetting,
211
- useAnchor,
212
- anchorElement,
213
- useEvent,
214
- useSetting,
215
- useMarks,
216
- Icon,
217
- addMark,
218
- replyMark,
219
- resolveMark
220
- };