@livespace/plugin-studio 0.1.0 → 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.
package/README.md CHANGED
@@ -69,6 +69,11 @@ top, so any plugin page works, a deployed one included.
69
69
  Livespace can.
70
70
  - **Messages**: every message, both ways, in a pane on the right. Its button in the top bar hides
71
71
  it, and its edge resizes it.
72
+ - **The browser console** gets the same log, one line per entry, prefixed `[studio]`, for the
73
+ browser tools coding agents use. The studio's notes (what it refused or dropped as Livespace
74
+ would, timeouts, what the address set) are warnings. The plugin's messages are `debug`, hidden
75
+ unless asked for: Chrome's "Verbose" level, or `level: "debug"` in the Playwright MCP's
76
+ `browser_console_messages`. Payloads over 4000 characters are cut.
72
77
 
73
78
  `--url` fills in the address (default: Vite's `http://localhost:5173` or Bun's
74
79
  `http://localhost:3000`, from the project; outside one, the page asks). `--port` moves the
@@ -76,6 +81,36 @@ studio, and `--client-id` sets the starting client id (default: the manifest's `
76
81
  `plugin:dev`). The sidebar, the address and the layout are kept in your browser; what you save on
77
82
  the settings page lives in the studio's memory, so a restart starts that afresh.
78
83
 
84
+ ## Setting up a state from the address
85
+
86
+ The address can set up a state in one go, which is quicker for a coding agent than clicking
87
+ through the sidebar. Params go after the page in the hash, `#?…` for the profile page and
88
+ `#settings?…` for the settings page:
89
+
90
+ ```
91
+ http://localhost:5190/#?type=none&viewer=&display=fullscreen&token=forbidden
92
+ http://localhost:5190/#settings?preferences=en-US&width=320
93
+ ```
94
+
95
+ | Param | Values | Sets |
96
+ |---|---|---|
97
+ | `type` | `deal`, `company`, `person`, `space`, `none` (the apps menu) | Where it's installed. A type the plugin can't be installed on gives way, as in the sidebar. |
98
+ | `viewer` | A user id; empty for no user | The viewer. |
99
+ | `preferences` | `pl`, `en-US`, `none` (an older Livespace) | The preferences preset. |
100
+ | `width` | `320`, `420`, `640`, `full` | The slot's column width. |
101
+ | `height` | Pixels, 40–2000 | The plugin's inline height. |
102
+ | `display` | `inline`, `dialog`, `fullscreen` | The profile page's display, for its next embed if none is open. |
103
+ | `credentials` | `bad_request`, `unauthenticated`, `forbidden`, `not_found`, `conflict`, `server_error`, `no-answer` | How `api.call`'s credentials are refused. |
104
+ | `token` | `token`, `every-other-expired`, a refusal code above or `not_purchased`, `no-answer` | How plugin tokens are answered. |
105
+
106
+ - **Set once, then dropped.** What's set is kept as if chosen in the sidebar, and the params
107
+ leave the address, so a reload or Back never sets them again. The message log notes what was
108
+ set, and what was ignored and why.
109
+ - **This browser's state only.** The saved settings, the stored secrets and the exchange's
110
+ refusal live in the studio's memory, so everyone using that studio shares them: a plugin's
111
+ backend reads them without a browser. The address never sets them. Use the settings form and
112
+ the Switches section instead.
113
+
79
114
  ## Flags
80
115
 
81
116
  | Flag | What it does |
@@ -0,0 +1,79 @@
1
+ /**
2
+ * The studio's address: the page, and a one-off instruction to set up a state, so a coding agent
3
+ * opens one URL per state instead of clicking through the sidebar. E.g.
4
+ * `#settings?type=company&preferences=en-US`, or `#?type=deal&display=dialog` for the profile.
5
+ * Only what this browser keeps: the saved settings, secrets and the exchange's refusal are the
6
+ * server's, shared by everyone on the studio. No DOM here.
7
+ */
8
+ import { COLUMN_WIDTHS } from "./display.js";
9
+ import { CREDENTIALS_CHOICES, TOKEN_CHOICES } from "./failures.js";
10
+ import { MAX_HEIGHT_PX, MIN_HEIGHT_PX } from "./slot-store.js";
11
+ import { PREFERENCE_PRESETS, RECORD_CHOICES, } from "./view-data.js";
12
+ const DISPLAYS = ["inline", "dialog", "fullscreen"];
13
+ const widthText = (width) => width === null ? "full" : String(width);
14
+ const oneOf = (values, set) => (value) => values.includes(value)
15
+ ? { ok: true, set: set(value) }
16
+ : { ok: false, reason: `one of ${values.join(", ")}` };
17
+ const READERS = {
18
+ type: oneOf(RECORD_CHOICES.map((c) => c.value), (type) => ({ type })),
19
+ viewer: (viewer) => ({ ok: true, set: { viewer: viewer.trim() } }),
20
+ preferences: oneOf(PREFERENCE_PRESETS.map((p) => p.value), (preferences) => ({ preferences })),
21
+ width: (value) => {
22
+ const width = COLUMN_WIDTHS.find((w) => widthText(w.value) === value);
23
+ return width === undefined
24
+ ? {
25
+ ok: false,
26
+ reason: `one of ${COLUMN_WIDTHS.map((w) => widthText(w.value)).join(", ")}`,
27
+ }
28
+ : { ok: true, set: { width: width.value } };
29
+ },
30
+ height: (value) => {
31
+ const height = Number(value);
32
+ return /^\d+$/.test(value) &&
33
+ height >= MIN_HEIGHT_PX &&
34
+ height <= MAX_HEIGHT_PX
35
+ ? { ok: true, set: { height } }
36
+ : { ok: false, reason: `pixels, ${MIN_HEIGHT_PX}–${MAX_HEIGHT_PX}` };
37
+ },
38
+ display: oneOf(DISPLAYS, (display) => ({ display })),
39
+ credentials: oneOf(CREDENTIALS_CHOICES.map((c) => c.value), (credentials) => ({ credentials })),
40
+ token: oneOf(TOKEN_CHOICES.map((c) => c.value), (token) => ({ token })),
41
+ };
42
+ /** Kept on the server, so never set from an address: say why, rather than "unknown". */
43
+ const SERVER_SIDE = {
44
+ config: "the saved settings are the studio server's: use the settings form",
45
+ exchange: "the exchange's refusal is the studio server's: use the Switches section",
46
+ };
47
+ export function readAddress(hash) {
48
+ const text = hash.startsWith("#") ? hash.slice(1) : hash;
49
+ const at = text.indexOf("?");
50
+ const path = at === -1 ? text : text.slice(0, at);
51
+ const page = path === "settings" ? "settings" : "profile";
52
+ const address = {
53
+ page,
54
+ changes: {},
55
+ applied: [],
56
+ ignored: [],
57
+ clean: page === "settings" ? "#settings" : "",
58
+ };
59
+ if (at === -1) {
60
+ return address;
61
+ }
62
+ new URLSearchParams(text.slice(at + 1)).forEach((value, name) => {
63
+ const read = READERS[name];
64
+ if (read === undefined) {
65
+ address.ignored.push(`${name} (${SERVER_SIDE[name] ?? "unknown"})`);
66
+ return;
67
+ }
68
+ const result = name === "display" && page === "settings"
69
+ ? { ok: false, reason: "the profile page's alone" }
70
+ : read(value);
71
+ if (!result.ok) {
72
+ address.ignored.push(`${name}=${value} (${result.reason})`);
73
+ return;
74
+ }
75
+ Object.assign(address.changes, result.set);
76
+ address.applied.push(`${name}=${value}`);
77
+ });
78
+ return address;
79
+ }
@@ -1,6 +1,7 @@
1
1
  /** Which page is shown: the profile, or the settings screen. It follows the address's hash. */
2
2
  import { signal } from "@preact/signals";
3
- export const pageFor = (hash) => hash === "#settings" ? "settings" : "profile";
3
+ /** The page a hash names; what follows a `?` is the address's params (address.ts). */
4
+ export const pageFor = (hash) => hash.split("?")[0] === "#settings" ? "settings" : "profile";
4
5
  export class NavigationStore {
5
6
  #page;
6
7
  constructor(hash) {
@@ -8,6 +8,10 @@ import { SurfaceStore } from "./surface-store.js";
8
8
  export class ProfileStore {
9
9
  deps;
10
10
  surface;
11
+ /** Embeds open now: none while the settings page shows, or before the first. */
12
+ #live = 0;
13
+ /** Asked for with no embed to show it: the next one starts there. */
14
+ #pending = null;
11
15
  constructor(deps) {
12
16
  this.deps = deps;
13
17
  this.surface = new SurfaceStore({ log: deps.log.append }, deps.slot.size);
@@ -16,6 +20,32 @@ export class ProfileStore {
16
20
  connect = (post) => {
17
21
  this.surface.reset();
18
22
  this.deps.toasts.reset();
19
- return new ProfileSession({ ...this.deps, surface: this.surface, post });
23
+ if (this.#pending !== null) {
24
+ this.surface.show(this.#pending);
25
+ this.#pending = null;
26
+ }
27
+ const session = new ProfileSession({
28
+ ...this.deps,
29
+ surface: this.surface,
30
+ post,
31
+ });
32
+ this.#live++;
33
+ return {
34
+ receive: session.receive,
35
+ loaded: session.loaded,
36
+ dispose: () => {
37
+ this.#live--;
38
+ session.dispose();
39
+ },
40
+ };
41
+ };
42
+ /** Shows the plugin inline, in its dialog or fullscreen: now, or as the next embed starts. */
43
+ show = (display) => {
44
+ if (this.#live > 0) {
45
+ this.surface.show(display);
46
+ }
47
+ else {
48
+ this.#pending = display;
49
+ }
20
50
  };
21
51
  }
@@ -3,6 +3,7 @@
3
3
  * transport it needs. Components reach it through `StudioContext` (ui/context.ts).
4
4
  */
5
5
  import { BrowserStorage } from "../transport/browser-storage.js";
6
+ import { readAddress } from "./address.js";
6
7
  import { timers } from "./draft.js";
7
8
  import { FailuresStore } from "./failures-store.js";
8
9
  import { LayoutStore } from "./layout-store.js";
@@ -83,6 +84,46 @@ export class Studio {
83
84
  failures: this.failures,
84
85
  });
85
86
  }
87
+ /**
88
+ * The address changed, or the page opened on it: the page follows its hash, and what its params
89
+ * ask for is set as if chosen in the sidebar, with a note in the log. Returns the hash to leave
90
+ * in the address, without the params, so a reload never sets them again.
91
+ */
92
+ followAddress = (hash) => {
93
+ const { page, changes, applied, ignored, clean } = readAddress(hash);
94
+ this.navigation.follow(page === "settings" ? "#settings" : "");
95
+ if (changes.type !== undefined) {
96
+ this.view.choose(changes.type);
97
+ }
98
+ if (changes.viewer !== undefined) {
99
+ this.view.viewer.set(changes.viewer);
100
+ }
101
+ if (changes.preferences !== undefined) {
102
+ this.view.choosePreset(changes.preferences);
103
+ }
104
+ if (changes.width !== undefined) {
105
+ this.slot.setWidth(changes.width);
106
+ }
107
+ if (changes.height !== undefined) {
108
+ this.slot.setHeight(changes.height);
109
+ }
110
+ if (changes.display !== undefined) {
111
+ this.profile.show(changes.display);
112
+ }
113
+ if (changes.credentials !== undefined) {
114
+ void this.failures.set("credentials", changes.credentials);
115
+ }
116
+ if (changes.token !== undefined) {
117
+ void this.failures.set("token", changes.token);
118
+ }
119
+ if (applied.length > 0) {
120
+ this.log.append("note", `From the address: ${applied.join(", ")}`);
121
+ }
122
+ if (ignored.length > 0) {
123
+ this.log.append("note", `From the address, ignored: ${ignored.join("; ")}`);
124
+ }
125
+ return clean;
126
+ };
86
127
  /** Reads what the server holds: the plugin, its saved settings, and the switched failures. */
87
128
  async start() {
88
129
  await Promise.all([
package/dist/page/main.js CHANGED
@@ -6,6 +6,7 @@ import { jsx as _jsx } from "preact/jsx-runtime";
6
6
  import { signal } from "@preact/signals";
7
7
  import { render } from "preact";
8
8
  import { Studio } from "./domain/studio.js";
9
+ import { mirrorToConsole } from "./transport/console-mirror.js";
9
10
  import { StudioApi } from "./transport/studio-api.js";
10
11
  import { boot } from "./ui/boot.js";
11
12
  import { StudioContext } from "./ui/context.js";
@@ -26,6 +27,17 @@ const studio = new Studio({
26
27
  hash: window.location.hash,
27
28
  viewportWidth,
28
29
  });
29
- window.addEventListener("hashchange", () => studio.navigation.follow(window.location.hash));
30
+ // Before anything is logged, so the console has it all.
31
+ mirrorToConsole(studio.log);
32
+ // The address's params are set once, then dropped, so a reload never sets them again.
33
+ const followAddress = () => {
34
+ const clean = studio.followAddress(window.location.hash);
35
+ if (clean !== window.location.hash) {
36
+ const { pathname, search } = window.location;
37
+ history.replaceState(history.state, "", `${pathname}${search}${clean}`);
38
+ }
39
+ };
40
+ followAddress();
41
+ window.addEventListener("hashchange", followAddress);
30
42
  window.addEventListener("pagehide", studio.flush);
31
43
  render(_jsx(StudioContext.Provider, { value: studio, children: _jsx(Root, { phase: boot(studio, root) }) }), root);
@@ -0,0 +1,48 @@
1
+ /**
2
+ * The message log, mirrored to the browser console, where the browser tools coding agents use
3
+ * read it. One line per entry, prefixed `[studio]`. The plugin's messages are `debug`, which
4
+ * consoles hide unless asked (Chrome's "Verbose"; the Playwright MCP's `level: "debug"`); the
5
+ * studio's notes are warnings, since that's where a plugin's mistakes show.
6
+ */
7
+ import { effect } from "@preact/signals";
8
+ /** Past this, a payload is cut: a record can be long, and one line should stay readable. */
9
+ export const MAX_PAYLOAD_CHARS = 4000;
10
+ const ARROWS = { in: "←", out: "→", note: "·" };
11
+ /** An entry as one console line. */
12
+ export function consoleLine(entry) {
13
+ const parts = ["[studio]", ARROWS[entry.direction], entry.type];
14
+ if (entry.source !== undefined) {
15
+ parts.push(`(${entry.source})`);
16
+ }
17
+ if (entry.payload !== undefined) {
18
+ let json;
19
+ try {
20
+ json = JSON.stringify(entry.payload) ?? String(entry.payload);
21
+ }
22
+ catch {
23
+ json = String(entry.payload);
24
+ }
25
+ parts.push(json.length > MAX_PAYLOAD_CHARS
26
+ ? `${json.slice(0, MAX_PAYLOAD_CHARS)}… (${json.length - MAX_PAYLOAD_CHARS} more characters)`
27
+ : json);
28
+ }
29
+ return parts.join(" ");
30
+ }
31
+ /** Mirrors each entry as it's logged, those already logged first. Returns a stop. */
32
+ export function mirrorToConsole(log, out = console) {
33
+ let lastId = 0;
34
+ return effect(() => {
35
+ for (const entry of log.entries.value) {
36
+ if (entry.id > lastId) {
37
+ lastId = entry.id;
38
+ const line = consoleLine(entry);
39
+ if (entry.direction === "note") {
40
+ out.warn(line);
41
+ }
42
+ else {
43
+ out.debug(line);
44
+ }
45
+ }
46
+ }
47
+ });
48
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@livespace/plugin-studio",
3
- "version": "0.1.0",
3
+ "version": "0.2.0",
4
4
  "description": "Plugin Studio: try and debug a Livespace plugin locally, embedded as Livespace embeds it.",
5
5
  "author": "LS FE team",
6
6
  "license": "MIT",