@hollis-labs/surface-page 0.0.0-stage → 0.2.0

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 (57) hide show
  1. package/README.md +24 -2
  2. package/dist/chunks/chunk-ZT6LTRMY.js +220 -0
  3. package/dist/gallery.js +1730 -0
  4. package/dist/index.js +2706 -0
  5. package/dist/registry-items.json +37 -0
  6. package/dist/sdk.js +24 -0
  7. package/dist/types/ade/Overlay.d.ts +4 -0
  8. package/dist/types/ade/hub.d.ts +5 -0
  9. package/dist/types/agent/AgentPanel.d.ts +24 -0
  10. package/dist/types/agent/api.d.ts +61 -0
  11. package/dist/types/agent/index.d.ts +2 -0
  12. package/dist/types/agent/items.d.ts +25 -0
  13. package/dist/types/agent/session.d.ts +34 -0
  14. package/dist/types/boot.d.ts +12 -0
  15. package/dist/types/cards/renderers.d.ts +22 -0
  16. package/dist/types/cards/store.d.ts +41 -0
  17. package/dist/types/cards/views.d.ts +9 -0
  18. package/dist/types/desk/AttentionBadge.d.ts +4 -0
  19. package/dist/types/desk/Confirm.d.ts +2 -0
  20. package/dist/types/desk/ContextInspector.d.ts +2 -0
  21. package/dist/types/desk/Desktop.d.ts +6 -0
  22. package/dist/types/desk/GhostCursor.d.ts +1 -0
  23. package/dist/types/desk/Palette.d.ts +9 -0
  24. package/dist/types/desk/ThemePicker.d.ts +3 -0
  25. package/dist/types/desk/attention.d.ts +17 -0
  26. package/dist/types/desk/commands.d.ts +13 -0
  27. package/dist/types/desk/composing.d.ts +10 -0
  28. package/dist/types/desk/coreViews.d.ts +2 -0
  29. package/dist/types/desk/keys.d.ts +12 -0
  30. package/dist/types/desk/moduleApi.d.ts +3 -0
  31. package/dist/types/desk/store.d.ts +123 -0
  32. package/dist/types/gallery/Gallery.d.ts +64 -0
  33. package/dist/types/gallery/Specimen.d.ts +22 -0
  34. package/dist/types/gallery/ade.d.ts +1 -0
  35. package/dist/types/gallery/approval.d.ts +1 -0
  36. package/dist/types/gallery/cards.d.ts +1 -0
  37. package/dist/types/gallery/chat.d.ts +1 -0
  38. package/dist/types/gallery/composer.d.ts +1 -0
  39. package/dist/types/gallery/controls.d.ts +1 -0
  40. package/dist/types/gallery/display.d.ts +1 -0
  41. package/dist/types/gallery/genui.d.ts +1 -0
  42. package/dist/types/gallery/index.d.ts +9 -0
  43. package/dist/types/gallery/overlays.d.ts +1 -0
  44. package/dist/types/gallery/theme.d.ts +19 -0
  45. package/dist/types/gallery/windows.d.ts +1 -0
  46. package/dist/types/genui/card.d.ts +2 -0
  47. package/dist/types/index.d.ts +15 -0
  48. package/dist/types/sdk/anchors.d.ts +8 -0
  49. package/dist/types/sdk/hooks.d.ts +11 -0
  50. package/dist/types/sdk/icon.d.ts +5 -0
  51. package/dist/types/sdk/index.d.ts +9 -0
  52. package/dist/types/sdk/marks.d.ts +10 -0
  53. package/dist/types/sdk/runtime.d.ts +40 -0
  54. package/dist/types/sdk/types.d.ts +99 -0
  55. package/package.json +71 -4
  56. package/vite.d.ts +3 -0
  57. package/vite.js +42 -0
@@ -0,0 +1 @@
1
+ export declare function Display(): import("react").JSX.Element;
@@ -0,0 +1 @@
1
+ export declare function Genui(): import("react").JSX.Element;
@@ -0,0 +1,9 @@
1
+ /**
2
+ * The Components window (`surface/gallery`): every registry component in its variants and states,
3
+ * from fixtures. Optional for an app: it needs every registry item installed.
4
+ */
5
+ import { Gallery } from "./Gallery";
6
+ export { Gallery };
7
+ export declare const galleryViews: {
8
+ "surface/gallery": typeof Gallery;
9
+ };
@@ -0,0 +1 @@
1
+ export declare function Overlays(): import("react").JSX.Element;
@@ -0,0 +1,19 @@
1
+ /** Theme: the palette in use, the tokens derived from it, how it reads, every shipped palette side by
2
+ * side, the two type styles, and reading a theme file. Design job d_97410e09, round 1. */
3
+ import { type Palette, type TypeStyle } from "@hollis-labs/surface-theme";
4
+ import { type ReactNode } from "react";
5
+ /** The gallery's palette and type style, chosen in its header. */
6
+ export declare const ThemeChoice: import("react").Context<{
7
+ palette: Palette;
8
+ type: TypeStyle;
9
+ setPalette: (p: Palette) => void;
10
+ setType: (t: TypeStyle) => void;
11
+ }>;
12
+ /** Draws its children in a palette (and type style) of their own. */
13
+ export declare function InPalette({ palette, type, children, className, }: {
14
+ palette: Palette;
15
+ type?: TypeStyle;
16
+ children: ReactNode;
17
+ className?: string;
18
+ }): import("react").JSX.Element;
19
+ export declare function Theme(): import("react").JSX.Element;
@@ -0,0 +1 @@
1
+ export declare function Windows(): import("react").JSX.Element;
@@ -0,0 +1,2 @@
1
+ import type { CardRendererProps } from "../cards/renderers";
2
+ export declare function GenuiCard({ card }: CardRendererProps): import("react").JSX.Element;
@@ -0,0 +1,15 @@
1
+ /**
2
+ * @hollis-labs/surface-page: the core of a Surface app's page. An app's entry is
3
+ *
4
+ * import { mountPage } from "@hollis-labs/surface-page"
5
+ * mountPage({ modules })
6
+ *
7
+ * with `modules` its modules' views. A module's own web code imports only
8
+ * "@hollis-labs/surface-page/sdk". The drawing is the app's installed registry components
9
+ * (`@/components/ui/*`); see registry/README.md, "Using it in an app".
10
+ */
11
+ export { mountPage, Page, type PageProps } from "./boot";
12
+ export { type CardRenderer, type CardRendererProps, registerCard } from "./cards/renderers";
13
+ export { CardHost, CardsWindow } from "./cards/views";
14
+ export { coreWeb } from "./desk/coreViews";
15
+ export { Desktop, type DesktopProps } from "./desk/Desktop";
@@ -0,0 +1,8 @@
1
+ import type { Win } from "./types";
2
+ /**
3
+ * Name an element of this window so the agent can point at it. Returns a ref for the
4
+ * element; the anchor goes when the element does.
5
+ */
6
+ export declare function useAnchor(win: Pick<Win, "id"> | string, name: string, label?: string): (el: HTMLElement | null) => (() => void) | undefined;
7
+ /** The element a window's anchor names, if it is on the page. The page's own, for drawing. */
8
+ export declare const anchorElement: (win: string, name: string) => HTMLElement | null;
@@ -0,0 +1,11 @@
1
+ import type { Mark, SurfaceEvent } from "./types";
2
+ /**
3
+ * Listen to the app's event bus. fn is called for each event whose topic is prefix or lies
4
+ * under it ("notes" takes "notes.saved"). This is how a view learns that the agent, a
5
+ * command or another window changed its data.
6
+ */
7
+ export declare function useEvent<T = unknown>(prefix: string, fn: (ev: SurfaceEvent<T>) => void): void;
8
+ /** A live setting by its full key ("scratch.show_done"). It follows changes, with no reload. */
9
+ export declare function useSetting<T = unknown>(fullKey: string): T | undefined;
10
+ /** The marks on a ref, kept current. */
11
+ export declare function useMarks(ref: string | undefined): Mark[];
@@ -0,0 +1,5 @@
1
+ import { type LucideProps } from "lucide-react";
2
+ /** A lucide icon by the name a manifest gives it ("sticky-note"). Unknown names draw a dot. */
3
+ export declare function Icon({ name, ...props }: {
4
+ name?: string;
5
+ } & LucideProps): import("react").JSX.Element;
@@ -0,0 +1,9 @@
1
+ /**
2
+ * @hollis-labs/surface-page/sdk: everything a module's web code may import from Surface.
3
+ */
4
+ export { useAnchor } from "./anchors";
5
+ export { useEvent, useMarks, useSetting } from "./hooks";
6
+ export { Icon } from "./icon";
7
+ export { addMark, replyMark, resolveMark } from "./marks";
8
+ export { ApiError, setSetting } from "./runtime";
9
+ export * from "./types";
@@ -0,0 +1,10 @@
1
+ import type { Mark } from "./types";
2
+ /** Pin a note of the owner's to a part of something. ref is what WindowContext.ref names. */
3
+ export declare const addMark: (m: {
4
+ ref: string;
5
+ body: string;
6
+ quote?: string;
7
+ anchor?: unknown;
8
+ }) => Promise<Mark>;
9
+ export declare const replyMark: (id: string, body: string) => Promise<Mark>;
10
+ export declare const resolveMark: (id: string) => Promise<void>;
@@ -0,0 +1,40 @@
1
+ /**
2
+ * The connection between the page and the app's server: one event stream, the settings as
3
+ * last heard, and plain JSON calls. The desk (../desk) builds on it; a module reaches it
4
+ * only through the hooks and what its views are handed.
5
+ */
6
+ import type { Mark, SurfaceEvent } from "./types";
7
+ export declare class ApiError extends Error {
8
+ status: number;
9
+ body: unknown;
10
+ constructor(message: string, status: number, body: unknown);
11
+ }
12
+ /** A JSON call to the app's server. Throws ApiError with the server's own words. */
13
+ export declare function call<T = unknown>(method: string, path: string, body?: unknown): Promise<T>;
14
+ type Listener = (ev: SurfaceEvent) => void;
15
+ /** Listen to the bus. Returns the function that stops listening. */
16
+ export declare function onEvent(prefix: string, fn: Listener): () => void;
17
+ /** Whether the event stream is up, and a way to hear when that changes. */
18
+ export declare const isConnected: () => boolean;
19
+ export declare function onConnection(fn: (up: boolean) => void): () => void;
20
+ /** Open the event stream (once). The server sends the desk's state first on every connect. */
21
+ export declare function connect(): void;
22
+ export interface SettingEntry {
23
+ scope: string;
24
+ key: string;
25
+ full_key: string;
26
+ title: string;
27
+ about?: string;
28
+ type: "string" | "bool" | "int" | "enum";
29
+ default: unknown;
30
+ options?: string[];
31
+ value: unknown;
32
+ set: boolean;
33
+ }
34
+ export declare function loadSettings(): Promise<SettingEntry[]>;
35
+ export declare const getSetting: (fullKey: string) => unknown;
36
+ export declare const allSettings: () => SettingEntry[];
37
+ /** Change a live setting by its full key ("files.show_hidden"). Every window hears it. */
38
+ export declare function setSetting(fullKey: string, value: unknown): Promise<void>;
39
+ export declare const listMarks: (ref: string) => Promise<Mark[]>;
40
+ export {};
@@ -0,0 +1,99 @@
1
+ /**
2
+ * The page's side of the module contract (Go: github.com/hollis-labs/surface/module).
3
+ *
4
+ * A module's web entry (modules/<id>/web/index.tsx) default-exports a ModuleWeb: the
5
+ * components for the views its manifest declares with module.Component("<entry>").
6
+ * A module imports only "@hollis-labs/surface-page/sdk"; the desk, the palette and the agent panel are the
7
+ * core's and are reached through what a view is handed.
8
+ */
9
+ import type { ComponentType } from "react";
10
+ /** One open window, as the server holds it (module.Window). */
11
+ export interface Win {
12
+ id: string;
13
+ view: string;
14
+ module: string;
15
+ title: string;
16
+ key?: string;
17
+ args: Record<string, unknown>;
18
+ state?: Record<string, unknown>;
19
+ focused: boolean;
20
+ }
21
+ export interface OpenOptions {
22
+ args?: Record<string, unknown>;
23
+ key?: string;
24
+ title?: string;
25
+ background?: boolean;
26
+ }
27
+ /** An event from the app's bus (module.Event). */
28
+ export interface SurfaceEvent<T = unknown> {
29
+ topic: string;
30
+ data: T;
31
+ }
32
+ /** What a view may ask of the desk. Every call goes to the server, which owns the state. */
33
+ export interface Desk {
34
+ open(view: string, opts?: OpenOptions): Promise<Win>;
35
+ close(winId: string): Promise<void>;
36
+ focus(winId: string): Promise<void>;
37
+ setTitle(winId: string, title: string): Promise<void>;
38
+ /** Replace what the window was opened with (the note it shows, the page it is on). */
39
+ setArgs(winId: string, args: Record<string, unknown>): Promise<void>;
40
+ /**
41
+ * Report what the window is showing right now (selection, position). Small. The agent
42
+ * and the context slots read it; call it when it changes, not on every keystroke.
43
+ */
44
+ report(winId: string, state: Record<string, unknown>): void;
45
+ /** Say whether the window holds unsaved work; closing it then asks first. */
46
+ setDirty(winId: string, dirty: boolean): void;
47
+ /**
48
+ * Open a file in the view that declares it opens such files (View.Opens, "*.md"). The
49
+ * first view that matches gets args as given. Resolves to null when no view in this app
50
+ * opens it, so a module can offer "open" without knowing which modules are present.
51
+ */
52
+ openFile(name: string, opts?: OpenOptions): Promise<Win | null>;
53
+ /** Run any command by id. */
54
+ run<T = unknown>(command: string, args?: Record<string, unknown>): Promise<T>;
55
+ /** Ask a yes/no question in a dialog on the desk. */
56
+ confirm(q: {
57
+ title: string;
58
+ message?: string;
59
+ confirmLabel?: string;
60
+ danger?: boolean;
61
+ }): Promise<boolean>;
62
+ windows(): Win[];
63
+ }
64
+ /** Calls to the module's own routes: path is relative to /api/m/<module>/. */
65
+ export interface ModuleAPI {
66
+ get<T = unknown>(path: string): Promise<T>;
67
+ post<T = unknown>(path: string, body?: unknown): Promise<T>;
68
+ put<T = unknown>(path: string, body?: unknown): Promise<T>;
69
+ del<T = unknown>(path: string): Promise<T>;
70
+ /** The absolute URL of a route, for an <img>, a frame or a download. */
71
+ url(path: string): string;
72
+ }
73
+ /** What a view's component receives. */
74
+ export interface ViewProps {
75
+ win: Win;
76
+ desk: Desk;
77
+ api: ModuleAPI;
78
+ }
79
+ /** A module's web entry. */
80
+ export interface ModuleWeb {
81
+ /** By Render.Entry. */
82
+ views: Record<string, ComponentType<ViewProps>>;
83
+ }
84
+ /** A mark (module.Mark). */
85
+ export interface Mark {
86
+ id: string;
87
+ ref: string;
88
+ anchor?: unknown;
89
+ quote?: string;
90
+ body: string;
91
+ author: "owner" | "agent";
92
+ status: "open" | "resolved";
93
+ created: string;
94
+ replies?: {
95
+ body: string;
96
+ author: string;
97
+ created: string;
98
+ }[];
99
+ }
package/package.json CHANGED
@@ -1,6 +1,73 @@
1
1
  {
2
2
  "name": "@hollis-labs/surface-page",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.2.0",
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
+ "license": "MIT",
6
+ "repository": {
7
+ "type": "git",
8
+ "url": "git+https://github.com/hollis-labs/surface.git",
9
+ "directory": "packages/page"
10
+ },
11
+ "homepage": "https://github.com/hollis-labs/surface/tree/main/packages/page#readme",
12
+ "bugs": {
13
+ "url": "https://github.com/hollis-labs/surface/issues"
14
+ },
15
+ "publishConfig": {
16
+ "access": "public",
17
+ "registry": "https://registry.npmjs.org/"
18
+ },
19
+ "type": "module",
20
+ "sideEffects": false,
21
+ "main": "./dist/index.js",
22
+ "types": "./dist/types/index.d.ts",
23
+ "exports": {
24
+ ".": {
25
+ "types": "./dist/types/index.d.ts",
26
+ "default": "./dist/index.js"
27
+ },
28
+ "./sdk": {
29
+ "types": "./dist/types/sdk/index.d.ts",
30
+ "default": "./dist/sdk.js"
31
+ },
32
+ "./gallery": {
33
+ "types": "./dist/types/gallery/index.d.ts",
34
+ "default": "./dist/gallery.js"
35
+ },
36
+ "./vite": {
37
+ "types": "./vite.d.ts",
38
+ "default": "./vite.js"
39
+ },
40
+ "./package.json": "./package.json"
41
+ },
42
+ "files": [
43
+ "dist",
44
+ "vite.js",
45
+ "vite.d.ts",
46
+ "README.md"
47
+ ],
48
+ "scripts": {
49
+ "build": "node build.mjs",
50
+ "prepack": "npm run build"
51
+ },
52
+ "dependencies": {
53
+ "@hollis-labs/ade-core": "0.1.0",
54
+ "@hollis-labs/surface-cards": "0.2.0",
55
+ "@hollis-labs/surface-chat": "0.2.0",
56
+ "@hollis-labs/surface-genui": "0.2.0",
57
+ "@hollis-labs/surface-theme": "0.2.0"
58
+ },
59
+ "peerDependencies": {
60
+ "lucide-react": ">=1",
61
+ "react": ">=19",
62
+ "react-dom": ">=19",
63
+ "vite": ">=6"
64
+ },
65
+ "surface": {
66
+ "registryItems": "dist/registry-items.json"
67
+ },
68
+ "peerDependenciesMeta": {
69
+ "vite": {
70
+ "optional": true
71
+ }
72
+ }
73
+ }
package/vite.d.ts ADDED
@@ -0,0 +1,3 @@
1
+ import type { Plugin } from "vite"
2
+ /** The Vite settings an app needs to build with @hollis-labs/surface-page. */
3
+ export declare function surfacePage(): Plugin
package/vite.js ADDED
@@ -0,0 +1,42 @@
1
+ // surfacePage(): the Vite settings an app needs to build with @hollis-labs/surface-page.
2
+ //
3
+ // import { surfacePage } from "@hollis-labs/surface-page/vite"
4
+ // export default defineConfig({ plugins: [tailwindcss(), surfacePage()], resolve: { alias: { "@": "src" } } })
5
+ //
6
+ // The page imports the app's own registry components (@/components/ui/*), so Vite must not
7
+ // pre-bundle it (that would put a second copy of those components inside the bundle). An excluded
8
+ // package's own imports are then pre-bundled here instead.
9
+
10
+ /** @returns {import("vite").Plugin} */
11
+ export function surfacePage() {
12
+ return {
13
+ name: "surface-page",
14
+ config() {
15
+ return {
16
+ optimizeDeps: {
17
+ exclude: ["@hollis-labs/surface-page"],
18
+ // What the page imports, pre-bundled for it (genui reaches ajv's CommonJS runtime).
19
+ include: [
20
+ "react",
21
+ "react/jsx-runtime",
22
+ "react-dom",
23
+ "react-dom/client",
24
+ "lucide-react",
25
+ ...["surface-chat", "surface-cards", "surface-genui", "ade-core"].map(
26
+ (p) => `@hollis-labs/surface-page > @hollis-labs/${p}`,
27
+ ),
28
+ ],
29
+ },
30
+ resolve: { dedupe: ["react", "react-dom"] },
31
+ }
32
+ },
33
+ configResolved(config) {
34
+ const aliased = config.resolve.alias.some((a) => a.find === "@" || String(a.find) === "/^@\\//")
35
+ if (!aliased) {
36
+ throw new Error(
37
+ 'surface-page: the page imports "@/components/ui/*" from the app. Set resolve.alias { "@": "<your src dir>" } in vite.config.',
38
+ )
39
+ }
40
+ },
41
+ }
42
+ }