@sudobility/sider_types 0.0.5 → 0.0.8

package/dist/actions.d.ts

@@ -27,3 +27,31 @@ export interface ReadPageResult {
     items: ExtractedItem[];
     count: number;
 }
+/**
+ * Icons a presented list may use.
+ *
+ * A closed set, not a free string: the panel maps each key to its own glyph, so
+ * the model cannot name an icon that does not exist or reach the DOM through it.
+ */
+export declare const PRESENT_LIST_ICONS: readonly ["briefcase", "document", "location", "calendar", "tag", "person", "building", "cart", "star", "search"];
+export type PresentListIcon = (typeof PRESENT_LIST_ICONS)[number];
+/** One row of a presented list. */
+export interface PresentedListItem {
+    title: string;
+    /** Short scalars shown under the title, e.g. ["Part time", "USF Hilltop Campus"]. */
+    meta?: string[];
+    /** Absolute URL, or a path resolved against the driven tab's origin. */
+    href?: string;
+    imageUrl?: string;
+}
+/**
+ * What the agent asks the panel to show.
+ *
+ * Data only — never markup. The agent decides WHAT matters; the panel decides
+ * how it looks.
+ */
+export interface PresentedListSpec {
+    title?: string;
+    icon?: PresentListIcon;
+    items: PresentedListItem[];
+}

package/dist/actions.js

@@ -1,4 +1,21 @@
 // Structured results for the three model-facing browser actions (callSiderTool,
 // readPage, siderDomAction). One shape so the agent can aggregate outcomes and
 // report a status summary (e.g. "added 3/5; 2 pre-order only").
-export {};
+/**
+ * Icons a presented list may use.
+ *
+ * A closed set, not a free string: the panel maps each key to its own glyph, so
+ * the model cannot name an icon that does not exist or reach the DOM through it.
+ */
+export const PRESENT_LIST_ICONS = [
+    "briefcase",
+    "document",
+    "location",
+    "calendar",
+    "tag",
+    "person",
+    "building",
+    "cart",
+    "star",
+    "search",
+];

package/dist/index.d.ts

@@ -6,3 +6,4 @@ export * from "./api";
 export * from "./actions";
 export * from "./templating";
 export * from "./recipe-hash";
+export * from "./observe";

package/dist/index.js

@@ -12,3 +12,4 @@ export * from "./api";
 export * from "./actions";
 export * from "./templating";
 export * from "./recipe-hash";
+export * from "./observe";

package/dist/observe.d.ts

@@ -0,0 +1,46 @@
+export type SnapshotActionKind = "navigate" | "submit" | "input" | "select" | "click";
+/** A control's SHAPE. The graph hashes `tag|role|name|actionKind` into view identity. */
+export interface SnapshotControl {
+    tag: string;
+    role?: string;
+    /** Accessible name, e.g. "Add to Cart". Plans reference controls by this. */
+    name?: string;
+    actionKind?: SnapshotActionKind;
+}
+/**
+ * A region of the page. Nesting matters: a region whose content-bearing children
+ * are all leaves sharing one shape collapses to a single repeat token, which is
+ * what stops a product list from changing the view's identity every time its
+ * contents change.
+ */
+export interface SnapshotRegion {
+    key: string;
+    role?: string;
+    controls?: SnapshotControl[];
+    children?: SnapshotRegion[];
+}
+export interface SnapshotLink {
+    toUrlPath: string;
+    label?: string;
+}
+export interface PageSnapshot {
+    /** Path with query VALUES dropped and keys kept: /search?q={q} */
+    urlPath: string;
+    title?: string;
+    regions: SnapshotRegion[];
+    links: SnapshotLink[];
+    /** Structural text only — headings, control names, link labels, item titles. */
+    contentMd?: string;
+    /** How the agent arrived here, when known. */
+    trigger?: {
+        kind: string;
+        label?: string;
+    } | null;
+}
+/** POST /api/v1/observe body. */
+export interface ObserveBody {
+    /** Assistant thread id — correlates the snapshot with its run. */
+    threadId: string;
+    siteOrigin: string;
+    snapshot: PageSnapshot;
+}

package/dist/observe.js

@@ -0,0 +1,8 @@
+// The page-observation seam between sider_extension and sider_api.
+//
+// Deliberately absent: CSS selectors and page body prose. Selectors are
+// regenerated per render and are useless to another user of the site; body prose
+// is the current user's own data (order history, addresses) and the graph it
+// would land in is shared with every other user of that site. Neither is omitted
+// by a filter — neither exists in these types.
+export {};

package/package.json

@@ -1,23 +1,23 @@
 {
-  "name": "@sudobility/sider_types",
-  "version": "0.0.5",
-  "description": "Shared domain types for Sider — AI assistance for generic web apps.",
-  "license": "BUSL-1.1",
-  "publishConfig": {
-    "access": "public"
-  },
-  "type": "module",
-  "main": "src/index.ts",
-  "types": "src/index.ts",
-  "files": [
-    "src",
-    "dist"
-  ],
-  "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "typecheck": "tsc --noEmit"
-  },
-  "devDependencies": {
-    "typescript": "^5.9.3"
-  }
+	"name": "@sudobility/sider_types",
+	"version": "0.0.8",
+	"description": "Shared domain types for Sider — AI assistance for generic web apps.",
+	"license": "BUSL-1.1",
+	"publishConfig": {
+		"access": "public"
+	},
+	"type": "module",
+	"main": "src/index.ts",
+	"types": "src/index.ts",
+	"files": [
+		"src",
+		"dist"
+	],
+	"scripts": {
+		"build": "tsc -p tsconfig.json",
+		"typecheck": "tsc --noEmit"
+	},
+	"devDependencies": {
+		"typescript": "^5.9.3"
+	}
 }

package/src/actions.ts

@@ -41,3 +41,46 @@ export interface ReadPageResult {
   items: ExtractedItem[];
   count: number;
 }
+
+/**
+ * Icons a presented list may use.
+ *
+ * A closed set, not a free string: the panel maps each key to its own glyph, so
+ * the model cannot name an icon that does not exist or reach the DOM through it.
+ */
+export const PRESENT_LIST_ICONS = [
+  "briefcase",
+  "document",
+  "location",
+  "calendar",
+  "tag",
+  "person",
+  "building",
+  "cart",
+  "star",
+  "search",
+] as const;
+
+export type PresentListIcon = (typeof PRESENT_LIST_ICONS)[number];
+
+/** One row of a presented list. */
+export interface PresentedListItem {
+  title: string;
+  /** Short scalars shown under the title, e.g. ["Part time", "USF Hilltop Campus"]. */
+  meta?: string[];
+  /** Absolute URL, or a path resolved against the driven tab's origin. */
+  href?: string;
+  imageUrl?: string;
+}
+
+/**
+ * What the agent asks the panel to show.
+ *
+ * Data only — never markup. The agent decides WHAT matters; the panel decides
+ * how it looks.
+ */
+export interface PresentedListSpec {
+  title?: string;
+  icon?: PresentListIcon;
+  items: PresentedListItem[];
+}

package/src/index.ts

@@ -13,3 +13,4 @@ export * from "./api";
 export * from "./actions";
 export * from "./templating";
 export * from "./recipe-hash";
+export * from "./observe";

package/src/observe.ts

@@ -0,0 +1,56 @@
+// The page-observation seam between sider_extension and sider_api.
+//
+// Deliberately absent: CSS selectors and page body prose. Selectors are
+// regenerated per render and are useless to another user of the site; body prose
+// is the current user's own data (order history, addresses) and the graph it
+// would land in is shared with every other user of that site. Neither is omitted
+// by a filter — neither exists in these types.
+
+export type SnapshotActionKind = "navigate" | "submit" | "input" | "select" | "click";
+
+/** A control's SHAPE. The graph hashes `tag|role|name|actionKind` into view identity. */
+export interface SnapshotControl {
+  tag: string;
+  role?: string;
+  /** Accessible name, e.g. "Add to Cart". Plans reference controls by this. */
+  name?: string;
+  actionKind?: SnapshotActionKind;
+}
+
+/**
+ * A region of the page. Nesting matters: a region whose content-bearing children
+ * are all leaves sharing one shape collapses to a single repeat token, which is
+ * what stops a product list from changing the view's identity every time its
+ * contents change.
+ */
+export interface SnapshotRegion {
+  key: string;
+  role?: string;
+  controls?: SnapshotControl[];
+  children?: SnapshotRegion[];
+}
+
+export interface SnapshotLink {
+  toUrlPath: string;
+  label?: string;
+}
+
+export interface PageSnapshot {
+  /** Path with query VALUES dropped and keys kept: /search?q={q} */
+  urlPath: string;
+  title?: string;
+  regions: SnapshotRegion[];
+  links: SnapshotLink[];
+  /** Structural text only — headings, control names, link labels, item titles. */
+  contentMd?: string;
+  /** How the agent arrived here, when known. */
+  trigger?: { kind: string; label?: string } | null;
+}
+
+/** POST /api/v1/observe body. */
+export interface ObserveBody {
+  /** Assistant thread id — correlates the snapshot with its run. */
+  threadId: string;
+  siteOrigin: string;
+  snapshot: PageSnapshot;
+}