@hollis-labs/surface-page 0.0.0-stage → 0.1.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 (47) hide show
  1. package/README.md +24 -2
  2. package/dist/chunks/chunk-ZT6LTRMY.js +220 -0
  3. package/dist/gallery.js +1016 -0
  4. package/dist/index.js +2000 -0
  5. package/dist/registry-items.json +36 -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 +57 -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/boot.d.ts +12 -0
  14. package/dist/types/cards/renderers.d.ts +22 -0
  15. package/dist/types/cards/store.d.ts +41 -0
  16. package/dist/types/cards/views.d.ts +9 -0
  17. package/dist/types/desk/Confirm.d.ts +2 -0
  18. package/dist/types/desk/Desktop.d.ts +6 -0
  19. package/dist/types/desk/Palette.d.ts +9 -0
  20. package/dist/types/desk/commands.d.ts +9 -0
  21. package/dist/types/desk/coreViews.d.ts +2 -0
  22. package/dist/types/desk/keys.d.ts +12 -0
  23. package/dist/types/desk/moduleApi.d.ts +3 -0
  24. package/dist/types/desk/store.d.ts +107 -0
  25. package/dist/types/gallery/Gallery.d.ts +49 -0
  26. package/dist/types/gallery/Specimen.d.ts +12 -0
  27. package/dist/types/gallery/ade.d.ts +1 -0
  28. package/dist/types/gallery/cards.d.ts +1 -0
  29. package/dist/types/gallery/chat.d.ts +1 -0
  30. package/dist/types/gallery/controls.d.ts +1 -0
  31. package/dist/types/gallery/display.d.ts +1 -0
  32. package/dist/types/gallery/genui.d.ts +1 -0
  33. package/dist/types/gallery/index.d.ts +9 -0
  34. package/dist/types/gallery/overlays.d.ts +1 -0
  35. package/dist/types/gallery/windows.d.ts +1 -0
  36. package/dist/types/genui/card.d.ts +2 -0
  37. package/dist/types/index.d.ts +15 -0
  38. package/dist/types/sdk/anchors.d.ts +8 -0
  39. package/dist/types/sdk/hooks.d.ts +11 -0
  40. package/dist/types/sdk/icon.d.ts +5 -0
  41. package/dist/types/sdk/index.d.ts +9 -0
  42. package/dist/types/sdk/marks.d.ts +10 -0
  43. package/dist/types/sdk/runtime.d.ts +40 -0
  44. package/dist/types/sdk/types.d.ts +99 -0
  45. package/package.json +70 -4
  46. package/vite.d.ts +3 -0
  47. package/vite.js +42 -0
@@ -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,72 @@
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.1.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.1.0",
55
+ "@hollis-labs/surface-chat": "0.1.0",
56
+ "@hollis-labs/surface-genui": "0.1.0"
57
+ },
58
+ "peerDependencies": {
59
+ "lucide-react": ">=1",
60
+ "react": ">=19",
61
+ "react-dom": ">=19",
62
+ "vite": ">=6"
63
+ },
64
+ "surface": {
65
+ "registryItems": "dist/registry-items.json"
66
+ },
67
+ "peerDependenciesMeta": {
68
+ "vite": {
69
+ "optional": true
70
+ }
71
+ }
72
+ }
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
+ }