@timurproko/a1 0.1.8-dev.563 → 0.1.8-dev.573

package/dist/cli/dispatch.js

@@ -1,5 +1,5 @@
 import { interactiveLaunchIntent, parseSessionSelection } from "../features/launch/index.js";
-import { packageCommandHelp, renderPackageSyntax } from "./package-messages.js";
+import { packageCommandHelp, renderPackageSyntax, } from "./package-messages.js";
 import { PRODUCT_TEXT } from "../product-identity.js";
 export function cliUsage(capabilities) {
     return PRODUCT_TEXT.usage([
@@ -7,22 +7,19 @@ export function cliUsage(capabilities) {
         "--session <path|id>",
         "--session-dir <dir> --session <path|id>",
         ...(capabilities.developmentComparison ? ["pi"] : []),
-        "--help",
-        "-h",
-        "--version",
-        "-v",
+        "help",
+        "version",
         "update",
         "update --develop [preview-or-version]",
         "update --models",
+        "update --extensions",
+        "update <source>",
+        "install <source>",
+        "remove <source>",
+        "uninstall <source>",
+        "list",
         "session link-worktree <path>",
         "session unlink-worktree",
-        "pi install <source>",
-        "pi remove <source>",
-        "pi uninstall <source>",
-        "pi list",
-        "pi update --extensions",
-        "pi update --models",
-        "pi update <source>",
     ]);
 }
 export function cliHelp(capabilities) {
@@ -33,29 +30,26 @@ export function cliHelp(capabilities) {
         `  ${command} --session <path|id>`,
         `  ${command} --session-dir <dir> --session <path|id>`,
         ...(capabilities.developmentComparison ? [`  ${command} pi`] : []),
-        `  ${command} --help`,
-        `  ${command} -h`,
-        `  ${command} --version`,
-        `  ${command} -v`,
+        `  ${command} help`,
+        `  ${command} version`,
         "",
         "Update:",
         `  ${command} update`,
         `  ${command} update --develop [preview-or-version]`,
         `  ${command} update --models`,
+        `  ${command} update --extensions`,
+        `  ${command} update <source>`,
+        "",
+        "Packages:",
+        `  ${command} install <source>`,
+        `  ${command} remove <source>`,
+        `  ${command} uninstall <source>`,
+        `  ${command} list`,
         "",
         "Session context:",
         `  ${command} session link-worktree <path>`,
         `  ${command} session unlink-worktree`,
         "",
-        "Pi-compatible packages:",
-        `  ${command} pi install <source>`,
-        `  ${command} pi remove <source>`,
-        `  ${command} pi uninstall <source>`,
-        `  ${command} pi list`,
-        `  ${command} pi update --extensions`,
-        `  ${command} pi update --models`,
-        `  ${command} pi update <source>`,
-        "",
     ].join("\n");
 }
 const PROFILE_WORDS = new Set(["pi"]);
@@ -68,11 +62,11 @@ export async function dispatchCli(arguments_, handlers, output, capabilities) {
         return 0;
     }
     if (command.kind === "package-help") {
-        output.stdout(packageCommandHelp(command.verb));
+        output.stdout(packageCommandHelp(command.verb, command.namespace));
         return 0;
     }
     if (command.kind === "package-error") {
-        output.stderr(renderPackageSyntax(command.diagnostic));
+        output.stderr(renderPackageSyntax(command.diagnostic, command.namespace));
         return 2;
     }
     if (command.kind === "error") {
@@ -102,13 +96,16 @@ export function parseCliCommand(arguments_, capabilities) {
             return { kind: "error", message: PRODUCT_TEXT.diagnostic(`could not parse session launch: ${error instanceof Error ? error.message : String(error)}`) };
         }
     }
-    if (command === "--help" || command === "-h")
+    if (command === "help" || command === "--help" || command === "-h")
         return withoutArguments(rest, { kind: "help" });
-    if (command === "--version" || command === "-v")
+    if (command === "version" || command === "--version" || command === "-v")
         return withoutArguments(rest, { kind: "version" });
+    if (command === "install" || command === "remove" || command === "uninstall" || command === "list") {
+        return parsePackageCommand(arguments_, "direct");
+    }
     if (command === "pi") {
         if (rest.length > 0)
-            return parsePiPackageCommand(rest);
+            return parsePackageCommand(rest, "pi");
         return capabilities.developmentComparison ? { kind: "launch", profileId: "pi" } : { kind: "noop" };
     }
     if (command === "update")
@@ -143,6 +140,9 @@ function parseSessionContext(rest) {
  * operation that cannot be combined with either update channel.
  */
 function parseUpdate(rest) {
+    if (rest.some(value => value === "--help" || value === "-h")) {
+        return { kind: "package-help", verb: "update", namespace: "direct" };
+    }
     if (rest.length === 0)
         return { kind: "update", channel: "stable" };
     const [selector, ...values] = rest;
@@ -167,10 +167,9 @@ function parseUpdate(rest) {
     }
     if (selector === "pi")
         return pinnedPiUpdateError();
-    if (selector !== undefined && selector.startsWith("-"))
+    if (selector === "--self" || selector === "--all")
         return unknownOption(selector, "update");
-    // Rationale: positional update targets are reserved for a future A1-native plugin model.
-    return { kind: "noop" };
+    return parsePackageUpdate(rest, "direct");
 }
 function isDevelopmentTarget(target) {
     return /^[1-9]\d*$/.test(target) || /^\d+\.\d+\.\d+-dev\.[1-9]\d*$/.test(target);
@@ -178,48 +177,49 @@ function isDevelopmentTarget(target) {
 function updateGrammarError(detail) {
     return { kind: "error", message: PRODUCT_TEXT.diagnostic(`could not parse update: ${detail}`) };
 }
-function parsePiPackageCommand(arguments_) {
+function parsePackageCommand(arguments_, namespace) {
     const [verb, ...rest] = arguments_;
     if ((verb === "install" || verb === "remove" || verb === "uninstall" || verb === "list" || verb === "update")
         && rest.some(value => value === "--help" || value === "-h")) {
-        return { kind: "package-help", verb: verb === "uninstall" ? "remove" : verb };
+        return { kind: "package-help", verb: verb === "uninstall" ? "remove" : verb, namespace };
     }
     if (verb === "install" || verb === "remove" || verb === "uninstall") {
-        return parseSourceCommand(verb === "install" ? "install" : "remove", rest);
+        return parseSourceCommand(verb === "install" ? "install" : "remove", rest, namespace);
     }
     if (verb === "list") {
         const flag = rest.find(argument => argument.startsWith("-"));
         if (flag !== undefined)
-            return packageOptionError(flag, "list");
+            return packageOptionError(flag, "list", namespace);
         if (rest[0] !== undefined)
-            return packageSyntax({ verb: "list", kind: "unexpected-argument", value: rest[0] });
+            return packageSyntax({ verb: "list", kind: "unexpected-argument", value: rest[0] }, namespace);
         return { kind: "packages", request: { verb: "list", source: null } };
     }
     if (verb === "update")
-        return parsePiPackageUpdate(rest);
+        return parsePackageUpdate(rest, namespace);
     return { kind: "noop" };
 }
-function parsePiPackageUpdate(rest) {
+function parsePackageUpdate(rest, namespace) {
     if (rest.length === 0)
         return pinnedPiUpdateError();
     if (rest.length > 1) {
         const unknown = rest.find(value => value.startsWith("-") && !["--extensions", "--models", "--self", "--all"].includes(value));
         if (unknown !== undefined)
-            return packageOptionError(unknown, "update");
+            return packageOptionError(unknown, "update", namespace);
         if (rest.includes("--self") || rest.includes("--all") || rest.includes("self") || rest.includes("pi"))
             return pinnedPiUpdateError();
         if (rest.every(value => value === rest[0]) && rest[0]?.startsWith("-")) {
-            return { kind: "error", message: PRODUCT_TEXT.diagnostic("pi update accepts one target.") };
+            const command = namespace === "direct" ? "update" : "pi update";
+            return { kind: "error", message: PRODUCT_TEXT.diagnostic(`${command} accepts one target.`) };
         }
         const sources = rest.filter(value => !value.startsWith("-"));
         if (sources[1] !== undefined)
-            return packageSyntax({ verb: "update", kind: "unexpected-argument", value: sources[1] });
+            return packageSyntax({ verb: "update", kind: "unexpected-argument", value: sources[1] }, namespace);
         const message = rest.includes("--models")
             ? rest.includes("--extensions")
                 ? "--models cannot be combined with --self, --extensions, --all, or --extension"
                 : "--models cannot be combined with a positional source"
             : "positional update targets cannot be combined with --self, --extensions, or --all";
-        return packageSyntax({ verb: "update", kind: "conflict", message });
+        return packageSyntax({ verb: "update", kind: "conflict", message }, namespace);
     }
     const [target] = rest;
     if (target === "--extensions")
@@ -229,7 +229,7 @@ function parsePiPackageUpdate(rest) {
     if (target === "--self" || target === "--all" || target === "self" || target === "pi")
         return pinnedPiUpdateError();
     if (target === undefined || target.startsWith("-"))
-        return packageOptionError(target ?? "", "update");
+        return packageOptionError(target ?? "", "update", namespace);
     return { kind: "packages", request: { verb: "update", source: target } };
 }
 function pinnedPiUpdateError() {
@@ -239,35 +239,35 @@ function pinnedPiUpdateError() {
             PRODUCT_TEXT.diagnostic("pins its certified Pi runtime and cannot update it independently."),
             "Use:",
             `  ${PRODUCT_TEXT.commandName} update                    Update a1`,
-            `  ${PRODUCT_TEXT.commandName} pi update --extensions    Update Pi-compatible packages`,
-            `  ${PRODUCT_TEXT.commandName} pi update --models        Refresh model catalogs`,
+            `  ${PRODUCT_TEXT.commandName} update --extensions       Update Pi-compatible packages`,
+            `  ${PRODUCT_TEXT.commandName} update --models           Refresh model catalogs`,
         ].join("\n"),
     };
 }
-function parseSourceCommand(verb, rest) {
+function parseSourceCommand(verb, rest, namespace) {
     const flag = rest.find(argument => argument.startsWith("-"));
     if (flag !== undefined)
-        return packageOptionError(flag, verb);
+        return packageOptionError(flag, verb, namespace);
     const [source, extra] = rest;
     if (extra !== undefined)
-        return packageSyntax({ verb, kind: "unexpected-argument", value: extra });
+        return packageSyntax({ verb, kind: "unexpected-argument", value: extra }, namespace);
     if (source === undefined)
-        return packageSyntax({ verb, kind: "missing-source" });
+        return packageSyntax({ verb, kind: "missing-source" }, namespace);
     if (PROFILE_WORDS.has(source))
         return profileRejection(verb);
     return { kind: "packages", request: { verb, source } };
 }
-function packageSyntax(diagnostic) {
-    return { kind: "package-error", diagnostic };
+function packageSyntax(diagnostic, namespace) {
+    return { kind: "package-error", diagnostic, namespace };
 }
-function packageOptionError(option, verb) {
+function packageOptionError(option, verb, namespace) {
     if (option.startsWith("--profile") || option === "-l" || option === "--local")
         return profileRejection(verb);
     // Compatibility: these recognized Pi flags remain outside A1's supported subset.
     if (["--extension", "--approve", "--no-approve", "-a", "-na", "--force"].includes(option)) {
-        return unknownOption(option, `pi ${verb}`);
+        return unknownOption(option, namespace === "direct" ? verb : `pi ${verb}`);
     }
-    return packageSyntax({ verb, kind: "unknown-option", value: option });
+    return packageSyntax({ verb, kind: "unknown-option", value: option }, namespace);
 }
 function withoutArguments(rest, command) {
     if (rest.length === 0)

package/dist/cli/package-messages.d.ts

@@ -1,6 +1,7 @@
 import chalk from "chalk";
 /** Supported subset of pinned Pi's package-manager CLI presentation. */
 export type PackageCliVerb = "install" | "remove" | "list" | "update";
+export type PackageCommandNamespace = "direct" | "pi";
 export type PackageSyntaxDiagnostic = {
     readonly verb: PackageCliVerb;
     readonly kind: "missing-source";
@@ -18,9 +19,9 @@ export type PackageSyntaxDiagnostic = {
     readonly message: string;
 };
 type MessageStyle = Pick<typeof chalk, "red" | "dim" | "bold">;
-export declare function packageCommandUsage(verb: PackageCliVerb): string;
+export declare function packageCommandUsage(verb: PackageCliVerb, namespace?: PackageCommandNamespace): string;
 /** Diagnostic facts stay unstyled until the terminal boundary decides color support. */
-export declare function renderPackageSyntax(diagnostic: PackageSyntaxDiagnostic, style?: MessageStyle): string;
+export declare function renderPackageSyntax(diagnostic: PackageSyntaxDiagnostic, namespace?: PackageCommandNamespace, style?: MessageStyle): string;
 /** Pi's help layout, with unsupported options and examples deliberately absent. */
-export declare function packageCommandHelp(verb: PackageCliVerb, style?: MessageStyle): string;
+export declare function packageCommandHelp(verb: PackageCliVerb, namespace?: PackageCommandNamespace, style?: MessageStyle): string;
 export {};

package/dist/cli/package-messages.js

@@ -2,21 +2,26 @@
 // at 914cf1472e715297caa30db4b9535d534a9eb718 (MIT); grammar is restricted to A1's supported subset.
 import chalk from "chalk";
 import { PRODUCT_TEXT } from "../product-identity.js";
-export function packageCommandUsage(verb) {
-    const command = `${PRODUCT_TEXT.commandName} pi ${verb}`;
+export function packageCommandUsage(verb, namespace = "pi") {
+    const command = namespace === "direct"
+        ? `${PRODUCT_TEXT.commandName} ${verb}`
+        : `${PRODUCT_TEXT.commandName} pi ${verb}`;
     if (verb === "install" || verb === "remove")
         return `${command} <source>`;
+    if (verb === "update" && namespace === "direct") {
+        return `${command} [--develop [preview-or-version]|--models|--extensions|source]`;
+    }
     if (verb === "update")
         return `${command} [source|--extensions|--models]`;
     return command;
 }
 /** Diagnostic facts stay unstyled until the terminal boundary decides color support. */
-export function renderPackageSyntax(diagnostic, style = chalk) {
-    const usage = packageCommandUsage(diagnostic.verb);
+export function renderPackageSyntax(diagnostic, namespace = "pi", style = chalk) {
+    const usage = packageCommandUsage(diagnostic.verb, namespace);
     let message;
     if (diagnostic.kind === "unknown-option") {
         return `${style.red(`Unknown option ${diagnostic.value} for "${diagnostic.verb}".`)}\n`
-            + `${style.dim(`Use "${PRODUCT_TEXT.commandName} --help" or "${usage}".`)}\n`;
+            + `${style.dim(`Use "${PRODUCT_TEXT.commandName} help" or "${usage}".`)}\n`;
     }
     if (diagnostic.kind === "missing-source")
         message = `Missing ${diagnostic.verb} source.`;
@@ -27,9 +32,16 @@ export function renderPackageSyntax(diagnostic, style = chalk) {
     return `${style.red(message)}\n${style.dim(`Usage: ${usage}`)}\n`;
 }
 /** Pi's help layout, with unsupported options and examples deliberately absent. */
-export function packageCommandHelp(verb, style = chalk) {
-    const command = `${PRODUCT_TEXT.commandName} pi`;
-    const header = `${style.bold("Usage:")}\n  ${packageCommandUsage(verb)}\n\n`;
+export function packageCommandHelp(verb, namespace = "pi", style = chalk) {
+    const command = namespace === "direct" ? PRODUCT_TEXT.commandName : `${PRODUCT_TEXT.commandName} pi`;
+    const header = verb === "update" && namespace === "direct"
+        ? `${style.bold("Usage:")}\n`
+            + `  ${command} update\n`
+            + `  ${command} update --develop [preview-or-version]\n`
+            + `  ${command} update --models\n`
+            + `  ${command} update --extensions\n`
+            + `  ${command} update <source>\n\n`
+        : `${style.bold("Usage:")}\n  ${packageCommandUsage(verb, namespace)}\n\n`;
     switch (verb) {
         case "install":
             return header + `Install a package and add it to settings.
@@ -55,14 +67,14 @@ Examples:
         case "list":
             return header + "List installed packages from user settings.\n\n";
         case "update":
-            return header + `Update installed packages or model catalogs.
+            return header + `${namespace === "direct" ? "Update A1, installed packages, or model catalogs." : "Update installed packages or model catalogs."}
 
 Options:
-  --extensions            Update installed packages only
+${namespace === "direct" ? "  --develop [target]     Update to the development channel or one preview\n" : ""}  --extensions            Update installed packages only
   --models                Refresh model catalogs only
 
 Short forms:
-  ${command} update --extensions   Update installed packages only
+${namespace === "direct" ? `  ${command} update                Update A1 to the stable release\n  ${command} update --develop      Update A1 to the development preview\n` : ""}  ${command} update --extensions   Update installed packages only
   ${command} update --models       Refresh model catalogs only
   ${command} update <source>       Update one package
 

package/dist/contracts/owned-ui/index.d.ts

@@ -5,6 +5,8 @@ export type { OwnedUiBlockStatus, OwnedUiCommand, OwnedUiCommandOutcome, OwnedUi
 export { acceptsTranscriptUpdate, transcriptToolState } from "./transcript-lifecycle.js";
 export { ImageAttachmentError, MAX_CLIPBOARD_TEXT_BYTES, MAX_IMAGE_DATA_BYTES, MAX_PROMPT_IMAGES, assertImageEncodedSize, assertPromptImages, } from "./image-attachments.js";
 export { CONTEXTUAL_PROMPT_SUGGESTION_INSTRUCTION, normalizePromptSuggestionCandidate } from "./prompt-suggestions.js";
+export { canonicalPromptChipMatches, protectPromptChipWrapping, replaceCanonicalPromptChips } from "./prompt-chips.js";
+export type { PromptChipTextMatch, PromptChipWrapProtection } from "./prompt-chips.js";
 export { SUGGESTION_DECISION_REASONS, SUGGESTION_DIAGNOSTIC_EVENTS } from "./suggestion-diagnostics.js";
 export type { SuggestionDecision, SuggestionDecisionReason, SuggestionDiagnosticEvent, SuggestionDiagnosticObserver, SuggestionDiagnosticRecord, } from "./suggestion-diagnostics.js";
 export { PROMPT_HISTORY_EDITOR_REPLACEMENT, PROMPT_HISTORY_MAX_ENTRY_BYTES, PROMPT_HISTORY_MAX_PENDING, PROMPT_HISTORY_MAX_TEXT_BYTES, assertPromptHistorySubmission, } from "./prompt-history.js";

package/dist/contracts/owned-ui/index.js

@@ -3,6 +3,7 @@ export { OWNED_UI_CONTRACT_VERSION } from "./model.js";
 export { acceptsTranscriptUpdate, transcriptToolState } from "./transcript-lifecycle.js";
 export { ImageAttachmentError, MAX_CLIPBOARD_TEXT_BYTES, MAX_IMAGE_DATA_BYTES, MAX_PROMPT_IMAGES, assertImageEncodedSize, assertPromptImages, } from "./image-attachments.js";
 export { CONTEXTUAL_PROMPT_SUGGESTION_INSTRUCTION, normalizePromptSuggestionCandidate } from "./prompt-suggestions.js";
+export { canonicalPromptChipMatches, protectPromptChipWrapping, replaceCanonicalPromptChips } from "./prompt-chips.js";
 export { SUGGESTION_DECISION_REASONS, SUGGESTION_DIAGNOSTIC_EVENTS } from "./suggestion-diagnostics.js";
 export { PROMPT_HISTORY_EDITOR_REPLACEMENT, PROMPT_HISTORY_MAX_ENTRY_BYTES, PROMPT_HISTORY_MAX_PENDING, PROMPT_HISTORY_MAX_TEXT_BYTES, assertPromptHistorySubmission, } from "./prompt-history.js";
 export { assertOwnedUiCommand, assertOwnedUiCustomization, assertOwnedUiDiagnostics, assertOwnedUiEditorState, assertOwnedUiEvent, assertOwnedUiPromptSuggestionIdentity, assertOwnedUiPromptSuggestionRequest, assertOwnedUiPromptSuggestionResult, assertOwnedUiPromptSuggestionState, assertOwnedUiSessionViewModel, assertOwnedUiSnapshot, assertOwnedUiStatusView, assertOwnedUiTerminalSurface, assertOwnedUiTranscriptBlock, } from "./validation.js";

package/dist/contracts/owned-ui/prompt-chips.d.ts

@@ -0,0 +1,15 @@
+export interface PromptChipTextMatch {
+    readonly text: string;
+    readonly start: number;
+    readonly end: number;
+}
+export interface PromptChipWrapProtection {
+    readonly text: string;
+    restore(rendered: string): string;
+}
+/** Finds canonical prompt-chip labels without requiring their process-local backing values. */
+export declare function canonicalPromptChipMatches(text: string): readonly PromptChipTextMatch[];
+/** Replaces only canonical prompt-chip labels while preserving every intervening source byte. */
+export declare function replaceCanonicalPromptChips(text: string, replacement: (match: PromptChipTextMatch) => string): string;
+/** Protects fitting chip labels for Markdown wrapping and restores their exact visible source text. */
+export declare function protectPromptChipWrapping(text: string): PromptChipWrapProtection;

package/dist/contracts/owned-ui/prompt-chips.js

@@ -0,0 +1,59 @@
+const PROMPT_CHIP_PATTERN = /\[(?:paste #\d+ (?:\+\d+ lines|\d+ chars)|📷 [^\]]+|📁 [^\]]+|📄 [^\]]+|🖼 {1,2}[^\]]+|🔗 [^\]]+)\]/gu;
+const ZERO_WIDTH_MARKERS = ["\u2060", "\u200b", "\u200c", "\u200d", "\ufeff"];
+/** Finds canonical prompt-chip labels without requiring their process-local backing values. */
+export function canonicalPromptChipMatches(text) {
+    return [...text.matchAll(PROMPT_CHIP_PATTERN)].map(match => ({
+        text: match[0], start: match.index, end: match.index + match[0].length,
+    }));
+}
+/** Replaces only canonical prompt-chip labels while preserving every intervening source byte. */
+export function replaceCanonicalPromptChips(text, replacement) {
+    return text.replace(PROMPT_CHIP_PATTERN, (value, offset) => replacement({
+        text: value, start: offset, end: offset + value.length,
+    }));
+}
+/** Protects fitting chip labels for Markdown wrapping and restores their exact visible source text. */
+export function protectPromptChipWrapping(text) {
+    const matches = canonicalPromptChipMatches(text);
+    if (matches.length === 0)
+        return { text, restore: identity };
+    const spaceMarker = unusedPrivateMarker(text);
+    const boundaryMarker = unusedZeroWidthMarker(text);
+    let protectedText = "", cursor = 0;
+    for (const match of matches) {
+        protectedText += text.slice(cursor, match.start);
+        // Rationale: adjacent chips need a temporary break opportunity or Markdown treats the complete run as one word.
+        if (match.start === cursor && cursor > 0)
+            protectedText += `${boundaryMarker} `;
+        protectedText += match.text.replaceAll(" ", spaceMarker);
+        cursor = match.end;
+    }
+    protectedText += text.slice(cursor);
+    return {
+        text: protectedText,
+        restore: rendered => rendered
+            .replaceAll(`${boundaryMarker} `, "")
+            .replaceAll(boundaryMarker, "")
+            .replaceAll(spaceMarker, " "),
+    };
+}
+function unusedPrivateMarker(text) {
+    for (let codePoint = 0xe000; codePoint <= 0xf8ff; codePoint++) {
+        const marker = String.fromCodePoint(codePoint);
+        if (!text.includes(marker))
+            return marker;
+    }
+    throw new Error("Prompt chip text exhausts the private presentation marker range");
+}
+function unusedZeroWidthMarker(text) {
+    for (const marker of ZERO_WIDTH_MARKERS)
+        if (!text.includes(marker))
+            return marker;
+    for (const left of ZERO_WIDTH_MARKERS) {
+        for (const right of ZERO_WIDTH_MARKERS)
+            if (!text.includes(left + right))
+                return left + right;
+    }
+    throw new Error("Prompt chip text exhausts the zero-width presentation marker range");
+}
+function identity(value) { return value; }

package/dist/contracts/owned-ui/validation.js

@@ -353,7 +353,7 @@ export function assertOwnedUiStatusView(status) {
     assertBoundedText(status.title, "owned-UI status title", MAX_LABEL_LENGTH);
     assertOptionalText(status.workingMessage, "owned-UI working message", MAX_MESSAGE_LENGTH);
     if (status.workingProgress !== undefined && status.workingProgress !== null) {
-        assertIntegerInRange(status.workingProgress, 0, 99, "owned-UI working progress");
+        assertIntegerInRange(status.workingProgress, 0, 100, "owned-UI working progress");
     }
     assertCollection(status.diagnostics, "owned-UI status diagnostics", MAX_STATUS_DIAGNOSTICS);
     for (const diagnostic of status.diagnostics) {

package/dist/integrations/pi/components/index.d.ts

@@ -10,6 +10,7 @@ export { PINNED_PI_LAYOUT, applyConfiguredPiTheme, applyPiTheme, applyPiThemeIns
 export type { PiColorMode, PiTerminalTheme, PiTerminalThemeDetection, PiTerminalThemeDetector, PiThemeBackground, PiThemeResult } from "./theme.js";
 export { OwnedPiThemeController } from "./upstream/theme/theme-controller.js";
 export type { PiThemeRuntimePort, PiThemeSettingsPort } from "./upstream/theme/theme-controller.js";
+export { PI_MODAL_CONTENT_PADDING_X, PiModalFrame, PiModalHeader, addPiModalHeader, adoptPiModalFrame, adoptPiModalHeader, } from "./modal-frame.js";
 export { ModelsDialogComponent } from "./models-dialog.js";
 export type { ModelsDialogCallbacks, ModelsDialogConfig, ModelsDialogFilter, ModelsDialogModel } from "./models-dialog.js";
 export { CountdownTimer } from "./upstream/components/countdown-timer.js";

package/dist/integrations/pi/components/index.js

@@ -5,6 +5,7 @@ export { OWNED_BUILTIN_SLASH_COMMANDS, PINNED_PI_BUILTIN_SLASH_COMMANDS, compone
 export { renderPiShellHotkeySections } from "./shell-hotkey-sections.js";
 export { PINNED_PI_LAYOUT, applyConfiguredPiTheme, applyPiTheme, applyPiThemeInstance, currentPiThemeName, detectPiTerminalBackgroundFromEnv, detectPiTerminalBackgroundTheme, detectPiTerminalThemeForAuto, ensurePiTheme, getAvailablePiThemes, loadPiTheme, onPiThemeChange, parsePiAutoThemeSetting, piTheme, resolvePiThemeSetting, stopPiThemeWatcher, } from "./theme.js";
 export { OwnedPiThemeController } from "./upstream/theme/theme-controller.js";
+export { PI_MODAL_CONTENT_PADDING_X, PiModalFrame, PiModalHeader, addPiModalHeader, adoptPiModalFrame, adoptPiModalHeader, } from "./modal-frame.js";
 export { ModelsDialogComponent } from "./models-dialog.js";
 export { CountdownTimer } from "./upstream/components/countdown-timer.js";
 export { ExtensionEditorComponent } from "./upstream/components/extension-editor.js";

package/dist/integrations/pi/components/modal-frame.d.ts

@@ -0,0 +1,41 @@
+import { Container, type Component } from "@earendil-works/pi-tui";
+export declare const PI_MODAL_CONTENT_PADDING_X = 1;
+/** The semantic top rule/title pair used while a modal assembles its frame. */
+export declare class PiModalHeader implements Component {
+    readonly rule: Component;
+    readonly title: Component;
+    constructor(rule: Component, title: Component);
+    invalidate(): void;
+    render(width: number): string[];
+}
+/**
+ * Complete framed-modal chrome. Rules remain frame-wide; every semantic content component renders
+ * in the same one-cell-smaller rectangle and receives the same left inset.
+ */
+export declare class PiModalFrame implements Component {
+    #private;
+    constructor(topRule: Component, content: readonly Component[], bottomRule: Component, fullWidthContent?: readonly Component[], preInsetContent?: readonly Component[]);
+    invalidate(): void;
+    render(width: number): string[];
+}
+/** Add compact titled-modal chrome while a component assembles its semantic body. */
+export declare function addPiModalHeader(container: Container, rule: Component, title: Component): PiModalHeader;
+export interface PiModalFrameAdoption {
+    readonly topIndex: number;
+    readonly bottomIndex: number;
+    readonly header?: PiModalHeader;
+    readonly fullWidthContent?: readonly Component[];
+    /** Public pinned children that already own the same one-cell outer inset. */
+    readonly preInsetContent?: readonly Component[];
+}
+/**
+ * Replace explicitly identified structural modal children with the shared padded frame. Callers
+ * identify semantic rules/components; rendered text is never inspected or rewritten.
+ */
+export declare function adoptPiModalFrame(container: Container, adoption: PiModalFrameAdoption): PiModalFrame;
+/**
+ * Adopt a public component's semantic rule/title children at the bare-A1 boundary. Only an optional
+ * structural Spacer between those explicitly identified children is accepted; rendered text is
+ * never inspected or rewritten. The pinned comparison profile does not call this adapter.
+ */
+export declare function adoptPiModalHeader(container: Container, ruleIndex: number, titleIndex: number): PiModalHeader;

package/dist/integrations/pi/components/modal-frame.js

@@ -0,0 +1,110 @@
+import { Container, Spacer } from "@earendil-works/pi-tui";
+export const PI_MODAL_CONTENT_PADDING_X = 1;
+/** The semantic top rule/title pair used while a modal assembles its frame. */
+export class PiModalHeader {
+    rule;
+    title;
+    constructor(rule, title) {
+        this.rule = rule;
+        this.title = title;
+    }
+    invalidate() {
+        this.rule.invalidate();
+        this.title.invalidate();
+    }
+    render(width) {
+        return [...this.rule.render(width), ...this.title.render(width)];
+    }
+}
+/**
+ * Complete framed-modal chrome. Rules remain frame-wide; every semantic content component renders
+ * in the same one-cell-smaller rectangle and receives the same left inset.
+ */
+export class PiModalFrame {
+    #topRule;
+    #content;
+    #bottomRule;
+    #fullWidthContent;
+    #preInsetContent;
+    constructor(topRule, content, bottomRule, fullWidthContent = [], preInsetContent = []) {
+        this.#topRule = topRule;
+        this.#content = content;
+        this.#bottomRule = bottomRule;
+        this.#fullWidthContent = new Set(fullWidthContent);
+        this.#preInsetContent = new Set(preInsetContent);
+    }
+    invalidate() {
+        this.#topRule.invalidate();
+        for (const component of this.#content)
+            component.invalidate();
+        this.#bottomRule.invalidate();
+    }
+    render(width) {
+        const padding = Math.min(PI_MODAL_CONTENT_PADDING_X, Math.max(0, width));
+        const contentWidth = Math.max(0, width - padding);
+        const rows = [...this.#topRule.render(width)];
+        for (const component of this.#content) {
+            if (this.#fullWidthContent.has(component) || this.#preInsetContent.has(component)) {
+                rows.push(...component.render(width));
+            }
+            else if (component instanceof Spacer) {
+                rows.push(...component.render(contentWidth));
+            }
+            else {
+                rows.push(...component.render(contentWidth).map(row => `${" ".repeat(padding)}${row}`));
+            }
+        }
+        rows.push(...this.#bottomRule.render(width));
+        return rows;
+    }
+}
+/** Add compact titled-modal chrome while a component assembles its semantic body. */
+export function addPiModalHeader(container, rule, title) {
+    const header = new PiModalHeader(rule, title);
+    container.addChild(header);
+    return header;
+}
+/**
+ * Replace explicitly identified structural modal children with the shared padded frame. Callers
+ * identify semantic rules/components; rendered text is never inspected or rewritten.
+ */
+export function adoptPiModalFrame(container, adoption) {
+    const { topIndex, bottomIndex, header, fullWidthContent = [], preInsetContent = [] } = adoption;
+    if (topIndex < 0 || bottomIndex <= topIndex || bottomIndex >= container.children.length) {
+        throw new TypeError("invalid modal frame child positions");
+    }
+    const top = container.children[topIndex];
+    const bottom = container.children[bottomIndex];
+    const contentStart = topIndex + 1;
+    let topRule = top;
+    const content = [];
+    if (header !== undefined) {
+        if (top !== header)
+            throw new TypeError("modal header is not at the declared top position");
+        topRule = header.rule;
+        content.push(header.title);
+    }
+    content.push(...container.children.slice(contentStart, bottomIndex));
+    const frame = new PiModalFrame(topRule, content, bottom, fullWidthContent, preInsetContent);
+    container.children.splice(topIndex, bottomIndex - topIndex + 1, frame);
+    return frame;
+}
+/**
+ * Adopt a public component's semantic rule/title children at the bare-A1 boundary. Only an optional
+ * structural Spacer between those explicitly identified children is accepted; rendered text is
+ * never inspected or rewritten. The pinned comparison profile does not call this adapter.
+ */
+export function adoptPiModalHeader(container, ruleIndex, titleIndex) {
+    if (ruleIndex < 0 || titleIndex <= ruleIndex || titleIndex >= container.children.length) {
+        throw new TypeError("invalid modal rule/title child positions");
+    }
+    const between = container.children.slice(ruleIndex + 1, titleIndex);
+    if (between.length > 1 || between.some(child => !(child instanceof Spacer))) {
+        throw new TypeError("modal rule and title are not separated by an optional single Spacer");
+    }
+    const rule = container.children[ruleIndex];
+    const title = container.children[titleIndex];
+    const header = new PiModalHeader(rule, title);
+    container.children.splice(ruleIndex, titleIndex - ruleIndex + 1, header);
+    return header;
+}