@mcp-b/char 0.0.6 → 0.1.0

package/dist/display-mode-policy.d.ts

@@ -0,0 +1,82 @@
+
+//#region src/types.d.ts
+/**
+ * Allowed display modes for the host shell and embedded runtime.
+ *
+ * @public
+ */
+type CharDisplayMode = 'inline' | 'fullscreen' | 'pip';
+//#endregion
+//#region src/display-mode-policy.d.ts
+/**
+ * Default display modes advertised by Char hosts.
+ *
+ * Order matters for fallback behavior. When a preferred mode is unavailable,
+ * the first available mode is selected.
+ *
+ * @public
+ */
+declare const DEFAULT_AVAILABLE_DISPLAY_MODES: readonly ["inline", "fullscreen", "pip"];
+/**
+ * Runtime guard for Char display mode values.
+ *
+ * @param value - Raw value from host attributes, events, or external input.
+ * @returns `true` when the value is one of `inline`, `fullscreen`, or `pip`.
+ *
+ * @public
+ */
+declare function isDisplayMode(value: string | null | undefined): value is CharDisplayMode;
+/**
+ * Checks whether a display mode represents an expanded agent surface.
+ *
+ * Expanded modes are:
+ * - `inline` (panel-style)
+ * - `fullscreen` (viewport-filling)
+ *
+ * Collapsed mode is:
+ * - `pip` (launcher-only)
+ *
+ * @param mode - Current display mode from host context.
+ * @returns `true` for expanded modes and `false` for collapsed/undefined modes.
+ *
+ * @public
+ */
+declare function isExpandedDisplayMode(mode: CharDisplayMode | undefined): boolean;
+/**
+ * Resolves a preferred display mode against host-supported modes.
+ *
+ * An empty `availableModes` array means "no constraint" — the preferred mode
+ * is returned unconditionally. This is intentional: it allows callers to opt
+ * out of mode filtering without a separate code path.
+ *
+ * @param preferred - Preferred mode requested by host policy.
+ * @param availableModes - Supported modes advertised by the host.
+ * @returns Preferred mode when supported, otherwise the first available mode.
+ *
+ * @public
+ */
+declare function resolveSupportedDisplayMode(preferred: CharDisplayMode, availableModes?: readonly CharDisplayMode[]): CharDisplayMode;
+/**
+ * Resolves Char's standard host display-mode policy.
+ *
+ * Policy:
+ * - Closed state to `pip`
+ * - Open on desktop to `inline`
+ * - Open on narrow viewport to `fullscreen`
+ *
+ * The resolved mode is then constrained to `availableModes`.
+ *
+ * @param options - Host orchestration inputs: `open`, `isNarrowViewport`,
+ * and optional `availableModes`.
+ * @returns Final mode that satisfies policy and availability constraints.
+ *
+ * @public
+ */
+declare function resolvePolicyDisplayMode(options: {
+  open: boolean;
+  isNarrowViewport: boolean;
+  availableModes?: readonly CharDisplayMode[];
+}): CharDisplayMode;
+//#endregion
+export { type CharDisplayMode, DEFAULT_AVAILABLE_DISPLAY_MODES, isDisplayMode, isExpandedDisplayMode, resolvePolicyDisplayMode, resolveSupportedDisplayMode };
+//# sourceMappingURL=display-mode-policy.d.ts.map

package/dist/display-mode-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"display-mode-policy.d.ts","names":[],"sources":["../src/types.ts","../src/display-mode-policy.ts"],"mappings":";;;;;;;KAwEY,eAAA;;;;;;;;;;AC3DZ;cAAa,+BAAA;;;;AA2Bb;;;;;iBAAgB,aAAA,CACf,KAAA,8BACE,KAAA,IAAS,eAAA;;;;AAmBZ;;;;;AAiBA;;;;;;;iBAjBgB,qBAAA,CAAsB,IAAA,EAAM,eAAA;;;;;;;;AAiD5C;;;;;;iBAhCgB,2BAAA,CACf,SAAA,EAAW,eAAA,EACX,cAAA,YAAyB,eAAA,KACvB,eAAA;;;;;;;;;;;;;;;;;iBA6Ba,wBAAA,CAAyB,OAAA;EACxC,IAAA;EACA,gBAAA;EACA,cAAA,YAA0B,eAAA;AAAA,IACvB,eAAA"}

package/dist/display-mode-policy.js

@@ -0,0 +1,87 @@
+/*! @mcp-b/char | Copyright (c) 2025 Kukumis Inc. All rights reserved. | UNLICENSED */
+//#region src/display-mode-policy.ts
+/**
+* Default display modes advertised by Char hosts.
+*
+* Order matters for fallback behavior. When a preferred mode is unavailable,
+* the first available mode is selected.
+*
+* @public
+*/
+const DEFAULT_AVAILABLE_DISPLAY_MODES = [
+	"inline",
+	"fullscreen",
+	"pip"
+];
+/**
+* Runtime guard for Char display mode values.
+*
+* @param value - Raw value from host attributes, events, or external input.
+* @returns `true` when the value is one of `inline`, `fullscreen`, or `pip`.
+*
+* @public
+*/
+function isDisplayMode(value) {
+	return value === "inline" || value === "fullscreen" || value === "pip";
+}
+/**
+* Checks whether a display mode represents an expanded agent surface.
+*
+* Expanded modes are:
+* - `inline` (panel-style)
+* - `fullscreen` (viewport-filling)
+*
+* Collapsed mode is:
+* - `pip` (launcher-only)
+*
+* @param mode - Current display mode from host context.
+* @returns `true` for expanded modes and `false` for collapsed/undefined modes.
+*
+* @public
+*/
+function isExpandedDisplayMode(mode) {
+	return mode === "inline" || mode === "fullscreen";
+}
+/**
+* Resolves a preferred display mode against host-supported modes.
+*
+* An empty `availableModes` array means "no constraint" — the preferred mode
+* is returned unconditionally. This is intentional: it allows callers to opt
+* out of mode filtering without a separate code path.
+*
+* @param preferred - Preferred mode requested by host policy.
+* @param availableModes - Supported modes advertised by the host.
+* @returns Preferred mode when supported, otherwise the first available mode.
+*
+* @public
+*/
+function resolveSupportedDisplayMode(preferred, availableModes = DEFAULT_AVAILABLE_DISPLAY_MODES) {
+	if (availableModes.length === 0) return preferred;
+	if (availableModes.includes(preferred)) return preferred;
+	console.debug(`[Char] Display mode "${preferred}" not in available modes [${availableModes.join(", ")}], using "${availableModes[0]}"`);
+	return availableModes[0];
+}
+/**
+* Resolves Char's standard host display-mode policy.
+*
+* Policy:
+* - Closed state to `pip`
+* - Open on desktop to `inline`
+* - Open on narrow viewport to `fullscreen`
+*
+* The resolved mode is then constrained to `availableModes`.
+*
+* @param options - Host orchestration inputs: `open`, `isNarrowViewport`,
+* and optional `availableModes`.
+* @returns Final mode that satisfies policy and availability constraints.
+*
+* @public
+*/
+function resolvePolicyDisplayMode(options) {
+	const availableModes = options.availableModes ?? DEFAULT_AVAILABLE_DISPLAY_MODES;
+	return resolveSupportedDisplayMode(options.open ? options.isNarrowViewport ? "fullscreen" : "inline" : "pip", availableModes);
+}
+
+//#endregion
+export { DEFAULT_AVAILABLE_DISPLAY_MODES, isDisplayMode, isExpandedDisplayMode, resolvePolicyDisplayMode, resolveSupportedDisplayMode };
+//# sourceMappingURL=display-mode-policy.js.map

package/dist/display-mode-policy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"display-mode-policy.js","names":[],"sources":["../src/display-mode-policy.ts"],"sourcesContent":["import type { CharDisplayMode } from './types'\nexport type { CharDisplayMode } from './types'\n\ntype AssertTrue<T extends true> = T\n\n/**\n * Default display modes advertised by Char hosts.\n *\n * Order matters for fallback behavior. When a preferred mode is unavailable,\n * the first available mode is selected.\n *\n * @public\n */\nexport const DEFAULT_AVAILABLE_DISPLAY_MODES = [\n\t'inline',\n\t'fullscreen',\n\t'pip',\n] as const satisfies readonly CharDisplayMode[]\n\n/**\n * Allowed display mode values for Char host policy resolution.\n */\ntype DisplayModesFromDefaults = (typeof DEFAULT_AVAILABLE_DISPLAY_MODES)[number]\n\ntype _AssertDisplayModesStayInSync = AssertTrue<\n\t[DisplayModesFromDefaults] extends [CharDisplayMode]\n\t\t? [CharDisplayMode] extends [DisplayModesFromDefaults]\n\t\t\t? true\n\t\t\t: false\n\t\t: false\n>\n\n/**\n * Runtime guard for Char display mode values.\n *\n * @param value - Raw value from host attributes, events, or external input.\n * @returns `true` when the value is one of `inline`, `fullscreen`, or `pip`.\n *\n * @public\n */\nexport function isDisplayMode(\n\tvalue: string | null | undefined,\n): value is CharDisplayMode {\n\treturn value === 'inline' || value === 'fullscreen' || value === 'pip'\n}\n\n/**\n * Checks whether a display mode represents an expanded agent surface.\n *\n * Expanded modes are:\n * - `inline` (panel-style)\n * - `fullscreen` (viewport-filling)\n *\n * Collapsed mode is:\n * - `pip` (launcher-only)\n *\n * @param mode - Current display mode from host context.\n * @returns `true` for expanded modes and `false` for collapsed/undefined modes.\n *\n * @public\n */\nexport function isExpandedDisplayMode(mode: CharDisplayMode | undefined): boolean {\n\treturn mode === 'inline' || mode === 'fullscreen'\n}\n\n/**\n * Resolves a preferred display mode against host-supported modes.\n *\n * An empty `availableModes` array means \"no constraint\" — the preferred mode\n * is returned unconditionally. This is intentional: it allows callers to opt\n * out of mode filtering without a separate code path.\n *\n * @param preferred - Preferred mode requested by host policy.\n * @param availableModes - Supported modes advertised by the host.\n * @returns Preferred mode when supported, otherwise the first available mode.\n *\n * @public\n */\nexport function resolveSupportedDisplayMode(\n\tpreferred: CharDisplayMode,\n\tavailableModes: readonly CharDisplayMode[] = DEFAULT_AVAILABLE_DISPLAY_MODES,\n): CharDisplayMode {\n\tif (availableModes.length === 0) {\n\t\treturn preferred\n\t}\n\n\tif (availableModes.includes(preferred)) {\n\t\treturn preferred\n\t}\n\n\tconsole.debug(`[Char] Display mode \"${preferred}\" not in available modes [${availableModes.join(', ')}], using \"${availableModes[0]}\"`)\n\treturn availableModes[0]\n}\n\n/**\n * Resolves Char's standard host display-mode policy.\n *\n * Policy:\n * - Closed state to `pip`\n * - Open on desktop to `inline`\n * - Open on narrow viewport to `fullscreen`\n *\n * The resolved mode is then constrained to `availableModes`.\n *\n * @param options - Host orchestration inputs: `open`, `isNarrowViewport`,\n * and optional `availableModes`.\n * @returns Final mode that satisfies policy and availability constraints.\n *\n * @public\n */\nexport function resolvePolicyDisplayMode(options: {\n\topen: boolean\n\tisNarrowViewport: boolean\n\tavailableModes?: readonly CharDisplayMode[]\n}): CharDisplayMode {\n\tconst availableModes = options.availableModes ?? DEFAULT_AVAILABLE_DISPLAY_MODES\n\tconst preferred: CharDisplayMode = options.open\n\t\t? options.isNarrowViewport\n\t\t\t? 'fullscreen'\n\t\t\t: 'inline'\n\t\t: 'pip'\n\n\treturn resolveSupportedDisplayMode(preferred, availableModes)\n}\n"],"mappings":";;;;;;;;;;AAaA,MAAa,kCAAkC;CAC9C;CACA;CACA;CACA;;;;;;;;;AAuBD,SAAgB,cACf,OAC2B;AAC3B,QAAO,UAAU,YAAY,UAAU,gBAAgB,UAAU;;;;;;;;;;;;;;;;;AAkBlE,SAAgB,sBAAsB,MAA4C;AACjF,QAAO,SAAS,YAAY,SAAS;;;;;;;;;;;;;;;AAgBtC,SAAgB,4BACf,WACA,iBAA6C,iCAC3B;AAClB,KAAI,eAAe,WAAW,EAC7B,QAAO;AAGR,KAAI,eAAe,SAAS,UAAU,CACrC,QAAO;AAGR,SAAQ,MAAM,wBAAwB,UAAU,4BAA4B,eAAe,KAAK,KAAK,CAAC,YAAY,eAAe,GAAG,GAAG;AACvI,QAAO,eAAe;;;;;;;;;;;;;;;;;;AAmBvB,SAAgB,yBAAyB,SAIrB;CACnB,MAAM,iBAAiB,QAAQ,kBAAkB;AAOjD,QAAO,4BAN4B,QAAQ,OACxC,QAAQ,mBACP,eACA,WACD,OAE2C,eAAe"}