@jini-ai/ui 0.4.7 → 0.4.9

package/dist/features/execution/react/components/LocalCliAgentSettings.js

@@ -0,0 +1,20 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { agentHandleProps, agentSubHandle } from '@jini-ai/agentic';
+import { useT } from '../../../i18n/index.js';
+import { CUSTOM_MODEL_SENTINEL } from '../../constants.js';
+import { AgentCliEnvFields } from './AgentCliEnvFields.js';
+import { SearchableModelSelect } from './SearchableModelSelect.js';
+/**
+ * The selected CLI's settings, stacked inside its own card.
+ *
+ * Owner, 2026-10-09: both the full-row card and the separate settings strip
+ * spread selection beyond its own column. Keep full-width controls and a
+ * visible provenance sentence inside the card so only that card grows taller.
+ */
+export function LocalCliAgentSettings({ agent, config, card, cliEnvFields, onModelChange, onEnvChange, agentHandle, }) {
+    const t = useT();
+    const { reasoning, source, sourceLabel, sourceHint, result, repair, repairField } = card;
+    const { hasModels, hasReasoning, reasoningOptions, reasoningValue, reasoningDisabled, allowCustomModel, customActive, modelChoices, selectValue, customModelInputValue, } = reasoning;
+    return (_jsxs("div", { className: "jini-agent-settings", role: "group", "aria-label": agent.label, "data-testid": `jini-agent-settings-${agent.id}`, children: [_jsxs("div", { className: "jini-agent-settings-row", children: [hasModels ? (_jsxs("div", { className: "jini-agent-settings-field jini-agent-settings-model", children: [_jsxs("div", { className: "jini-agent-settings-label", children: [_jsx("span", { className: "jini-field-label", children: t('Model') }), sourceLabel ? (_jsx("span", { className: `jini-agent-model-source ${source}`, children: sourceLabel })) : null] }), _jsx(SearchableModelSelect, { className: "jini-input jini-agent-model-select", ariaLabel: t('Model'), searchPlaceholder: t('Search models'), testId: `jini-agent-model-${agent.id}`, searchInputTestId: `jini-agent-model-search-${agent.id}`, ...(agentHandle ? { agentHandle: agentSubHandle({ base: agentHandle, action: 'model' }) } : {}), value: selectValue, models: modelChoices, additionalOptions: allowCustomModel ? [{ value: CUSTOM_MODEL_SENTINEL, label: t('Custom…') }] : undefined, onChange: card.selectModel }), sourceHint ? _jsx("p", { className: "jini-field-hint", children: sourceHint }) : null] })) : null, customActive ? (_jsxs("label", { className: "jini-agent-settings-field", children: [_jsx("span", { className: "jini-field-label", children: t('Custom model id') }), _jsx("input", { className: "jini-input jini-agent-settings-custom", type: "text", "data-testid": `jini-agent-model-custom-${agent.id}`, value: customModelInputValue, placeholder: t('e.g. my-fine-tuned-model'), spellCheck: false, onChange: (event) => onModelChange(agent.id, event.target.value.trim()), ...agentHandleProps({}, { base: agentHandle, ...({ action: 'custom-model', role: 'field', label: t('Custom model id') }) }) })] })) : null, hasReasoning ? (_jsxs("label", { className: "jini-agent-settings-field", children: [_jsx("span", { className: "jini-field-label", children: t('Reasoning effort') }), _jsx("select", { className: "jini-input jini-agent-settings-reasoning", "data-testid": `jini-agent-reasoning-${agent.id}`, value: reasoningValue, disabled: reasoningDisabled, onChange: (event) => card.selectReasoning(event.target.value), ...agentHandleProps({}, { base: agentHandle, ...({ action: 'reasoning', role: 'field', label: t('Reasoning effort') }) }), children: reasoningOptions.map((option) => (_jsx("option", { value: option.id, children: option.label }, option.id))) })] })) : null] }), result ? (_jsx("p", { className: 'jini-agent-card-test-result is-' + result.status, role: result.status === 'error' ? 'alert' : 'status', children: result.message ?? (result.status === 'ok' ? t('Agent is ready.') : t('Agent check failed')) })) : null, repair && repairField ? (_jsxs("div", { className: "jini-agent-card-path-repair", children: [_jsx("span", { className: "jini-field-hint", children: t('A custom path override did not work, so this used the automatically detected binary instead.') }), _jsxs("div", { className: "jini-agent-card-path-repair-actions", children: [repair.canUseDetected ? (_jsx("button", { type: "button", className: "jini-btn", "data-testid": `jini-agent-path-repair-use-${agent.id}`, onClick: () => onEnvChange(agent.id, repairField.envKey, repair.detectedPath), children: t('Use detected path') })) : null, _jsx("button", { type: "button", className: "jini-btn jini-btn-ghost", "data-testid": `jini-agent-path-repair-clear-${agent.id}`, onClick: () => onEnvChange(agent.id, repairField.envKey, ''), children: t('Clear custom path') })] })] })) : null, _jsx(AgentCliEnvFields, { agentId: agent.id, fields: cliEnvFields, config: config, onChange: onEnvChange })] }));
+}
+//# sourceMappingURL=LocalCliAgentSettings.js.map

package/dist/features/execution/react/hooks/use-byok-field-validation.hooks.d.ts

@@ -0,0 +1,24 @@
+import type { ByokConfig, ProviderPreset } from '../../types.js';
+type Field = 'apiKey' | 'baseUrl' | 'model';
+/** Keeps required-field gates immediate while optionally waiting for blur to paint errors.
+ * Stored keys satisfy only the key requirement; touching one provider never marks another.
+ * @complexity Time/space: O(1), bounded by the three required fields.
+ */
+export declare function useByokFieldValidation(required: {
+    config: ByokConfig;
+    preset: ProviderPreset | null;
+    apiKeyStoredExternally: boolean;
+}, optional?: {
+    deferMissingFeedback?: boolean;
+}): {
+    missing: Set<import("../../types.js").ByokRequiredField>;
+    baseUrlInvalid: boolean;
+    isMissing: ({ field }: {
+        field: Field;
+    }, _options?: Record<string, never>) => boolean;
+    markTouched: ({ field }: {
+        field: Field;
+    }, _options?: Record<string, never>) => void;
+};
+export {};
+//# sourceMappingURL=use-byok-field-validation.hooks.d.ts.map

package/dist/features/execution/react/hooks/use-byok-field-validation.hooks.js

@@ -0,0 +1,27 @@
+import { useState } from 'react';
+import { isBaseUrlInvalid, missingRequiredFields } from '../../rules.js';
+/** Keeps required-field gates immediate while optionally waiting for blur to paint errors.
+ * Stored keys satisfy only the key requirement; touching one provider never marks another.
+ * @complexity Time/space: O(1), bounded by the three required fields.
+ */
+export function useByokFieldValidation(required, optional = {}) {
+    const { config, preset, apiKeyStoredExternally } = required;
+    const [touched, setTouched] = useState({ providerId: config.providerId, fields: new Set() });
+    const missing = new Set(missingRequiredFields(config, preset));
+    if (apiKeyStoredExternally)
+        missing.delete('apiKey');
+    const baseUrlInvalid = isBaseUrlInvalid(config);
+    return {
+        missing,
+        baseUrlInvalid,
+        isMissing: ({ field }, _options = {}) => (missing.has(field) || (field === 'baseUrl' && baseUrlInvalid)) &&
+            (!optional.deferMissingFeedback || (touched.providerId === config.providerId && touched.fields.has(field))),
+        markTouched: ({ field }, _options = {}) => {
+            setTouched(current => ({
+                providerId: config.providerId,
+                fields: new Set([...(current.providerId === config.providerId ? current.fields : []), field]),
+            }));
+        },
+    };
+}
+//# sourceMappingURL=use-byok-field-validation.hooks.js.map

package/dist/features/execution/react/hooks/useExecutionTab.js

@@ -37,14 +37,17 @@ export function useExecutionTab({ port, autoDetect = true, describeProbeError =
     /** The host's describer as of the latest render — see `UseExecutionTabOptions.describeProbeError`. */
     const describeProbeErrorRef = useRef(describeProbeError);
     describeProbeErrorRef.current = describeProbeError;
+    const detectionTimer = useRef(undefined);
     const alive = useRef(true);
     useEffect(() => {
         alive.current = true;
         return () => {
             alive.current = false;
+            clearTimeout(detectionTimer.current);
         };
     }, []);
     const runDetection = useCallback((detect) => {
+        clearTimeout(detectionTimer.current);
         const ticket = ++detectionTicket.current;
         const isCurrent = () => alive.current && detectionTicket.current === ticket;
         setScan({ status: 'scanning' });
@@ -54,12 +57,18 @@ export function useExecutionTab({ port, autoDetect = true, describeProbeError =
             const sorted = sortDetectedAgents(found);
             setAgents(sorted);
             setScan({ status: 'ok', count: sorted.filter((agent) => agent.installed).length });
+            if (found.some(agent => agent.discoveryPending)) {
+                detectionTimer.current = setTimeout(() => {
+                    if (isCurrent())
+                        runDetection(() => port.detectLocalAgents());
+                }, 1000);
+            }
         }, (error) => {
             if (!isCurrent())
                 return;
             setScan({ status: 'error', message: describeErrorMessage(error) });
         });
-    }, []);
+    }, [port]);
     useEffect(() => {
         if (!autoDetect)
             return;

package/dist/features/execution/react/hooks/useLocalCliAgentCard.d.ts

@@ -0,0 +1,48 @@
+import { agentExecutableRepairState } from '../../rules.js';
+import type { AgentCliEnvFieldSpec, AgentTestState, DetectedAgent, LocalCliConfig } from '../../types.js';
+import { type UseReasoningControlResult } from './useReasoningControl.js';
+type Translate = (key: string) => string;
+export interface UseLocalCliAgentCardInput {
+    agent: DetectedAgent;
+    config: LocalCliConfig;
+    agentTest: AgentTestState;
+    cliEnvFields: readonly AgentCliEnvFieldSpec[];
+    onModelChange: (agentId: string, model: string) => void;
+    onReasoningChange: (agentId: string, reasoning: string) => void;
+    onRescan?: (() => void) | undefined;
+    /** Only its presence matters here: a Test button alone is enough to show the settings strip. */
+    onTest?: ((agent: DetectedAgent) => void) | undefined;
+    t: Translate;
+}
+export interface UseLocalCliAgentCardResult {
+    reasoning: UseReasoningControlResult;
+    /** Whether the selected card's settings strip has anything to show; without this it rendered
+     *  as an empty bordered box for a CLI with no models, effort, Test or env fields. */
+    hasSettings: boolean;
+    /** `agent.modelsSource`, passed through for the badge's modifier class. */
+    source: DetectedAgent['modelsSource'];
+    sourceLabel: string;
+    sourceHint: string;
+    testing: boolean;
+    result: Extract<AgentTestState, {
+        status: 'ok' | 'error';
+    }> | null;
+    repair: ReturnType<typeof agentExecutableRepairState>;
+    repairField: AgentCliEnvFieldSpec | null;
+    diagnosticHandlers: {
+        onRescan: (() => void) | undefined;
+        onOpenInstall: (() => void) | undefined;
+        onOpenDocs: (() => void) | undefined;
+    };
+    /** The model picker's change handler, including its "Custom…" sentinel. */
+    selectModel: (nextValue: string) => void;
+    /** The reasoning picker's change handler, including the model-suffix shape. */
+    selectReasoning: (nextValue: string) => void;
+}
+/**
+ * Everything `LocalCliAgentCard` and its settings strip derive from one agent, kept out of the
+ * `.tsx` so both render from the same values.
+ */
+export declare function useLocalCliAgentCard({ agent, config, agentTest, cliEnvFields, onModelChange, onReasoningChange, onRescan, onTest, t, }: UseLocalCliAgentCardInput): UseLocalCliAgentCardResult;
+export {};
+//# sourceMappingURL=useLocalCliAgentCard.d.ts.map

package/dist/features/execution/react/hooks/useLocalCliAgentCard.js

@@ -0,0 +1,110 @@
+import { useState } from 'react';
+import { CUSTOM_MODEL_SENTINEL } from '../../constants.js';
+import { agentExecutableRepairState, binPathEnvField, cliEnvFieldsForAgent } from '../../rules.js';
+import { useReasoningControl } from './useReasoningControl.js';
+/**
+ * Everything `LocalCliAgentCard` and its settings strip derive from one agent, kept out of the
+ * `.tsx` so both render from the same values.
+ */
+export function useLocalCliAgentCard({ agent, config, agentTest, cliEnvFields, onModelChange, onReasoningChange, onRescan, onTest, t, }) {
+    // Whether the operator explicitly opened the free-text "Custom" entry via
+    // the model picker's own "Custom…" option — distinct from "the saved model
+    // simply isn't in the known list" (`shouldShowCustomModelInput` covers
+    // both, but only THIS one needs to be remembered as a UI-local toggle,
+    // since it is not itself persisted config: see `LocalCliConfig`, which has
+    // nowhere for "the operator is mid-typing a custom id" to live). Scoped to
+    // this card instance, so switching to a different agent and back does not
+    // leak one agent's custom-mode toggle onto another.
+    const [explicitCustomMode, setExplicitCustomMode] = useState(false);
+    const reasoning = useReasoningControl({
+        agent,
+        config,
+        explicitCustomMode,
+        onReasoningChange: (next) => onReasoningChange(agent.id, next),
+    });
+    // `modelsSource` is optional in the contract, so an absent value means the
+    // host did not say where the list came from — NOT that it came from a
+    // built-in fallback. Defaulting to 'fallback' rendered "Built-in list" over
+    // a list that may well be live, and told the operator to Rescan to fix a
+    // problem they do not have. Unknown provenance shows no badge and no claim.
+    const source = agent.modelsSource;
+    const sourceLabel = source === 'live' ? t('Live from CLI') : source === 'fallback' ? t('Built-in list') : '';
+    const sourceHint = source === 'live'
+        ? t("Model list comes from this CLI. Default uses the CLI's own config.")
+        : source === 'fallback'
+            ? t('Showing built-in defaults. Click Rescan to pull live models from the CLI.')
+            : '';
+    // The test result belongs to whichever agent was probed, so a stale verdict
+    // from a previously-tested CLI never renders under this one.
+    const testing = agentTest.status === 'testing' && agentTest.agentId === agent.id;
+    const result = (agentTest.status === 'ok' || agentTest.status === 'error') && agentTest.agentId === agent.id
+        ? agentTest
+        : null;
+    // The "use the binary that actually ran" / "clear the override" repair
+    // affordance — only meaningful when a successful test silently fell back
+    // off a configured override, AND this agent's catalog names which field
+    // that override lives in. See `agentExecutableRepairState`'s doc.
+    //
+    // `AgentTestState`'s 'ok' variant spells success as `status: 'ok'`, not an
+    // `ok: true` field — `agentExecutableRepairState` takes the latter (it
+    // mirrors `ExecutionPort.testAgent`'s raw resolved shape, one layer below
+    // this state union), so the two must be translated explicitly here rather
+    // than passing `result` straight through.
+    const repair = result?.status === 'ok'
+        ? agentExecutableRepairState({
+            ok: true,
+            usedExecutableSource: result.usedExecutableSource,
+            detectedExecutablePath: result.detectedExecutablePath,
+        })
+        : null;
+    const repairField = repair ? binPathEnvField(cliEnvFields, agent.id) : null;
+    const openUrl = (url) => {
+        if (!url)
+            return;
+        window.open(url, '_blank', 'noopener,noreferrer');
+    };
+    const diagnosticHandlers = {
+        onRescan,
+        onOpenInstall: agent.installUrl ? () => openUrl(agent.installUrl) : undefined,
+        onOpenDocs: agent.docsUrl ? () => openUrl(agent.docsUrl) : undefined,
+    };
+    const selectModel = (nextValue) => {
+        if (nextValue === CUSTOM_MODEL_SENTINEL) {
+            setExplicitCustomMode(true);
+            onModelChange(agent.id, '');
+            return;
+        }
+        setExplicitCustomMode(false);
+        onModelChange(agent.id, reasoning.resolveNextModelId(nextValue));
+    };
+    const selectReasoning = (nextValue) => {
+        // A model-suffix agent has no reasoning value of its own to record: the choice
+        // is which model id runs, so it goes back out through `onModelChange`.
+        const suffixModelId = reasoning.resolveReasoningModelId(nextValue);
+        if (suffixModelId !== null) {
+            onModelChange(agent.id, suffixModelId);
+            return;
+        }
+        onReasoningChange(agent.id, nextValue);
+    };
+    const hasSettings = reasoning.hasModels ||
+        reasoning.hasReasoning ||
+        Boolean(onTest) ||
+        result !== null ||
+        cliEnvFieldsForAgent(cliEnvFields, agent.id).length > 0;
+    return {
+        reasoning,
+        hasSettings,
+        source,
+        sourceLabel,
+        sourceHint,
+        testing,
+        result,
+        repair,
+        repairField,
+        diagnosticHandlers,
+        selectModel,
+        selectReasoning,
+    };
+}
+//# sourceMappingURL=useLocalCliAgentCard.js.map

package/dist/features/execution/react/hooks/useLocalCliAgentList.d.ts

@@ -0,0 +1,19 @@
+import type { DetectedAgent } from '../../types.js';
+export interface UseLocalCliAgentListResult {
+    /** Installed CLIs plus the current pick: always rendered. */
+    visible: DetectedAgent[];
+    /** Not-installed CLIs: rendered only while `showCollapsed`. */
+    collapsed: DetectedAgent[];
+    showCollapsed: boolean;
+    toggleCollapsed: () => void;
+}
+/**
+ * Disclosure state for the CLI grid's not-installed tail. Collapsed by default: those cards
+ * cannot be picked until installed, and a dozen of them pushed every setting below the grid
+ * off-screen. See `partitionAgentsByInstalled` for what stays visible.
+ */
+export declare function useLocalCliAgentList({ agents, selectedAgentId }: {
+    agents: readonly DetectedAgent[];
+    selectedAgentId: string | null;
+}): UseLocalCliAgentListResult;
+//# sourceMappingURL=useLocalCliAgentList.d.ts.map

package/dist/features/execution/react/hooks/useLocalCliAgentList.js

@@ -0,0 +1,13 @@
+import { useState } from 'react';
+import { partitionAgentsByInstalled } from '../../rules.js';
+/**
+ * Disclosure state for the CLI grid's not-installed tail. Collapsed by default: those cards
+ * cannot be picked until installed, and a dozen of them pushed every setting below the grid
+ * off-screen. See `partitionAgentsByInstalled` for what stays visible.
+ */
+export function useLocalCliAgentList({ agents, selectedAgentId }) {
+    const [showCollapsed, setShowCollapsed] = useState(false);
+    const { visible, collapsed } = partitionAgentsByInstalled(agents, selectedAgentId);
+    return { visible, collapsed, showCollapsed, toggleCollapsed: () => setShowCollapsed((open) => !open) };
+}
+//# sourceMappingURL=useLocalCliAgentList.js.map

package/dist/features/execution/rules.d.ts

@@ -125,6 +125,19 @@ export declare function sortDetectedAgents<T extends {
     installed: boolean;
     label: string;
 }>(agents: readonly T[]): readonly T[];
+/**
+ * Splits the CLI grid into what to show up front and what sits behind the "Show N not installed"
+ * toggle. Installed CLIs are the ones an operator can pick, so a long tail of uninstalled cards
+ * buried every setting below the grid. The selected agent always stays visible even when it is
+ * not installed (a stale pick after an uninstall), so the current choice is never hidden.
+ */
+export declare function partitionAgentsByInstalled<T extends {
+    id: string;
+    installed: boolean;
+}>(agents: readonly T[], selectedAgentId: string | null | undefined): {
+    visible: T[];
+    collapsed: T[];
+};
 /**
  * Strips a redundant trailing agent name from a CLI's `--version` output, so
  * "1.2.3 (Claude Code)" renders as "1.2.3" beside a card already titled

package/dist/features/execution/rules.js

@@ -282,6 +282,20 @@ export function sortDetectedAgents(agents) {
         return a.label.localeCompare(b.label);
     });
 }
+/**
+ * Splits the CLI grid into what to show up front and what sits behind the "Show N not installed"
+ * toggle. Installed CLIs are the ones an operator can pick, so a long tail of uninstalled cards
+ * buried every setting below the grid. The selected agent always stays visible even when it is
+ * not installed (a stale pick after an uninstall), so the current choice is never hidden.
+ */
+export function partitionAgentsByInstalled(agents, selectedAgentId) {
+    const visible = [];
+    const collapsed = [];
+    for (const agent of agents) {
+        (agent.installed || agent.id === selectedAgentId ? visible : collapsed).push(agent);
+    }
+    return { visible, collapsed };
+}
 /**
  * Strips a redundant trailing agent name from a CLI's `--version` output, so
  * "1.2.3 (Claude Code)" renders as "1.2.3" beside a card already titled

package/dist/features/execution/types.d.ts

@@ -182,6 +182,8 @@ export type AgentSupportsCustomModel = boolean;
  * the route boundary throws away data the card is built to render.
  */
 export interface DetectedAgent {
+    /** Cached inventory is usable now; retry a normal read until background discovery settles. */
+    discoveryPending?: boolean;
     id: string;
     label: string;
     installed: boolean;

package/dist/features/html-editor/canvas-embed-placeholders.d.ts

@@ -36,7 +36,8 @@
  * Re-entrancy (defensive, mirroring `canvas-content-wrapper.ts`'s own `WRAPPER_ROOT_MARKER` guard): a
  * marker already sitting inside a placeholder card (`el.closest('[' + CARD_ROOT_MARKER + ']')`) is
  * skipped, so a second call — or a caller's own `load` handler firing twice — cannot nest a second card
- * around an already-decorated marker.
+ * around an already-decorated marker. Only a runtime card's direct marker is described again, to
+ * refresh its footprint after theme styles settle; card chrome is always skipped.
  */
 /** What to show on one embed's placeholder card — supplied per-element by the host's own `describe`
  *  callback, since only the host knows the marker convention (attribute name, JSON shape, and how to
@@ -47,7 +48,18 @@ export interface CanvasEmbedPlaceholderDescriptor {
     /** Human-identifiable target, shown under the heading — e.g. a name, or a truncated id, or a note
      *  that none was set. Never fetched by this module; the host decides what's cheap enough to show. */
     identityLabel: string;
+    /** Runtime blocks use the same card with a bounded view-only footprint and locked guidance. */
+    presentation?: 'embed' | 'runtime';
+    guidanceLabel?: string;
+    inline?: boolean | undefined;
+    declaredHeight?: number | undefined;
 }
+/** Finite positive declared/native geometry wins, otherwise use the bounded runtime fallback. */
+export declare function editorBlockHeight({ declaredHeight, nativeHeight, inline }: {
+    declaredHeight?: number | undefined;
+    nativeHeight?: number | undefined;
+    inline?: boolean | undefined;
+}, _options?: object): number;
 /**
  * Scans every element under `body` once and, for each one `describe` recognizes (returns a descriptor
  * for), replaces its visible slot with an explicit placeholder card — see this file's header for the

package/dist/features/html-editor/canvas-embed-placeholders.js

@@ -36,12 +36,20 @@
  * Re-entrancy (defensive, mirroring `canvas-content-wrapper.ts`'s own `WRAPPER_ROOT_MARKER` guard): a
  * marker already sitting inside a placeholder card (`el.closest('[' + CARD_ROOT_MARKER + ']')`) is
  * skipped, so a second call — or a caller's own `load` handler firing twice — cannot nest a second card
- * around an already-decorated marker.
+ * around an already-decorated marker. Only a runtime card's direct marker is described again, to
+ * refresh its footprint after theme styles settle; card chrome is always skipped.
  */
+/** Finite positive declared/native geometry wins, otherwise use the bounded runtime fallback. */
+export function editorBlockHeight({ declaredHeight, nativeHeight, inline }, _options = {}) {
+    const height = [declaredHeight, nativeHeight].find(value => typeof value === 'number' && Number.isFinite(value) && value > 0);
+    return Math.max(inline ? 48 : 96, Math.min(inline ? 160 : 960, height ?? (inline ? 64 : 280)));
+}
 /** Marks a placeholder card's own root, so a later pass (this function called again, or a re-entrant
  *  `load`) can recognize an already-decorated marker via `el.closest` and skip it — see this file's
  *  header. */
 const CARD_ROOT_MARKER = 'data-jini-embed-placeholder-root';
+/** Canvas-only flag permitting footprint refreshes without describing embed cards or chrome again. */
+const CARD_RUNTIME_MARKER = 'data-jini-embed-placeholder-runtime';
 /** Flags every child the card itself builds (icon, text), so the one unflagged child is always the
  *  marker. {@link OVERLAY_RULE} and the stale-card check in `removeStaleCards` both rely on it. */
 const CARD_CHROME_MARKER = 'data-jini-embed-placeholder-chrome';
@@ -110,20 +118,22 @@ function buildPlaceholderIcon(doc) {
  *  `textContent`, never string-concatenated markup, so a marker's own config values (which flow into
  *  `descriptor.identityLabel`) can never be interpreted as HTML. */
 function buildPlaceholderCard(doc, descriptor) {
-    const card = doc.createElement('div');
+    const card = doc.createElement(descriptor.inline ? 'span' : 'div');
     card.setAttribute(CARD_ROOT_MARKER, '');
+    if (descriptor.presentation === 'runtime')
+        card.setAttribute(CARD_RUNTIME_MARKER, '');
     card.setAttribute('style', CARD_STYLE);
     const text = doc.createElement('div');
     text.setAttribute(CARD_CHROME_MARKER, '');
     const heading = doc.createElement('div');
     heading.setAttribute('style', 'font-weight:600;');
-    heading.textContent = `Placeholder — ${descriptor.kindLabel}`;
+    heading.textContent = descriptor.presentation === 'runtime' ? descriptor.kindLabel : `Placeholder — ${descriptor.kindLabel}`;
     const identity = doc.createElement('div');
     identity.setAttribute('style', 'opacity:.8;margin-top:2px;');
     identity.textContent = descriptor.identityLabel;
     const note = doc.createElement('div');
     note.setAttribute('style', 'opacity:.6;margin-top:4px;font-size:11px;');
-    note.textContent = 'Shown here for editing only — the real content renders on the published page.';
+    note.textContent = descriptor.guidanceLabel ?? 'Shown here for editing only — the real content renders on the published page.';
     text.append(heading, identity, note);
     const icon = buildPlaceholderIcon(doc);
     icon.setAttribute(CARD_CHROME_MARKER, '');
@@ -156,9 +166,10 @@ function buildPlaceholderCard(doc, descriptor) {
  * behavior every existing caller of this module had before this function existed.
  */
 function applyResolvedMaxWidth(marker, card) {
-    if (typeof getComputedStyle !== 'function')
+    const win = marker.ownerDocument.defaultView;
+    if (!win)
         return;
-    const maxWidth = getComputedStyle(marker).maxWidth;
+    const maxWidth = win.getComputedStyle(marker).maxWidth;
     if (maxWidth && maxWidth !== 'none')
         card.style.setProperty('max-width', maxWidth);
 }
@@ -210,15 +221,20 @@ export function applyCanvasEmbedPlaceholders(body, describe) {
     // `body.childNodes` for the same reason.
     const candidates = Array.from(body.querySelectorAll('*'));
     for (const el of candidates) {
-        // Already inside a placeholder card from an earlier pass over this same element — see this file's
-        // header on re-entrancy. Checked via ancestor lookup rather than a marker attribute on `el` itself,
-        // so a decorated marker's own attributes stay completely untouched by this function, not just its
-        // children.
-        if (el.closest(`[${CARD_ROOT_MARKER}]`))
+        // Skip existing embed cards and all chrome before calling the host. Runtime cards still
+        // re-describe their direct marker so theme changes can refresh its bounded footprint.
+        const existingCard = el.closest(`[${CARD_ROOT_MARKER}]`);
+        if (existingCard && (!existingCard.hasAttribute(CARD_RUNTIME_MARKER)
+            || el.parentElement !== existingCard || el.hasAttribute(CARD_CHROME_MARKER)))
             continue;
         const descriptor = describe(el);
         if (!descriptor)
             continue;
+        if (existingCard) {
+            if (descriptor.presentation === 'runtime')
+                applyRuntimeFootprint(el, existingCard, descriptor);
+            continue;
+        }
         const parent = el.parentNode;
         if (!parent)
             continue; // Unreachable for a live `body` descendant; defensive only.
@@ -229,12 +245,45 @@ export function applyCanvasEmbedPlaceholders(body, describe) {
         // author set that `CARD_STYLE` doesn't touch (like `max-width`) still applies unopposed. Guarded
         // on presence so a marker with no `style` attribute at all is a no-op, not a leading `;`.
         const authoredStyle = el.getAttribute('style');
-        if (authoredStyle)
+        if (authoredStyle && descriptor.presentation !== 'runtime')
             card.setAttribute('style', `${authoredStyle};${card.getAttribute('style')}`);
         applyResolvedMaxWidth(el, card);
+        if (descriptor.presentation === 'runtime')
+            applyRuntimeFootprint(el, card, descriptor);
         parent.insertBefore(card, el);
         card.appendChild(el); // Moves the SAME node (auto-detaches from `parent`) — never cloned.
         ensureOverlayRule(doc);
     }
 }
+/** Geometry belongs to canvas DOM only; arbitrary transforms/min-height cannot defeat the clamp. */
+function applyRuntimeFootprint(el, card, descriptor) {
+    // Re-measure the authored shell after theme links settle, without our selection overlay's
+    // !important auto-height masking its declarations. No component/model styles are changed.
+    const overlay = el.ownerDocument.head.querySelector(`style[${OVERLAY_STYLE_MARKER}]`);
+    const sheet = overlay?.sheet;
+    const wasDisabled = sheet?.disabled;
+    let resolved;
+    try {
+        if (sheet)
+            sheet.disabled = true;
+        resolved = el.ownerDocument.defaultView?.getComputedStyle(el).height;
+    }
+    finally {
+        if (sheet)
+            sheet.disabled = wasDisabled ?? false;
+    }
+    const native = el.getAttribute('height');
+    const declared = descriptor.declaredHeight ?? (resolved?.endsWith('px') ? Number.parseFloat(resolved) : undefined);
+    card.style.height = `${editorBlockHeight({ declaredHeight: declared, nativeHeight: native ? Number(native) : undefined, inline: descriptor.inline }, {})}px`;
+    card.style.minHeight = '0';
+    card.style.maxHeight = descriptor.inline ? '160px' : '960px';
+    card.style.overflow = 'hidden';
+    if (descriptor.inline) {
+        card.style.display = 'inline-flex';
+        card.style.verticalAlign = 'middle';
+    }
+    // The marker is the selectable hit surface, never an authored layout/transform or media view.
+    el.style.setProperty('transform', 'none', 'important');
+    el.style.setProperty('overflow', 'hidden', 'important');
+}
 //# sourceMappingURL=canvas-embed-placeholders.js.map

package/dist/features/html-editor/dom.d.ts

@@ -12,4 +12,9 @@
  * that checks attributes should use this instead of `el.hasAttribute` directly.
  */
 export declare function hasAttributeOnAnyNodeShape(el: Element, attr: string): boolean;
+/** DOM-free compatibility view for the existing host attribute describer/predicate seam. */
+export declare function sourceElementAttributeView({ tagName, attributes }: {
+    tagName: string;
+    attributes: Readonly<Record<string, string>>;
+}, _options?: object): Element;
 //# sourceMappingURL=dom.d.ts.map

package/dist/features/html-editor/dom.js

@@ -17,4 +17,14 @@ export function hasAttributeOnAnyNodeShape(el, attr) {
     const attributes = el.attributes;
     return !!attributes && Object.prototype.hasOwnProperty.call(attributes, attr);
 }
+/** DOM-free compatibility view for the existing host attribute describer/predicate seam. */
+export function sourceElementAttributeView({ tagName, attributes }, _options = {}) {
+    return {
+        tagName: tagName.toUpperCase(),
+        nodeType: 1,
+        attributes,
+        getAttribute: (name) => attributes[name.toLowerCase()] ?? null,
+        hasAttribute: (name) => Object.prototype.hasOwnProperty.call(attributes, name.toLowerCase()),
+    };
+}
 //# sourceMappingURL=dom.js.map

package/dist/features/html-editor/editor-blocks.d.ts

@@ -0,0 +1,71 @@
+import type { CanvasEmbedPlaceholderDescriptor } from './canvas-embed-placeholders.js';
+import { type ElementOuterRange, type SourceElement } from './source-splice.js';
+export type EditorBlockReason = 'kuinetic' | 'canvas' | 'autoplay-video' | 'scripted' | 'embed';
+export interface EditorBlock extends ElementOuterRange {
+    readonly tagName: string;
+    readonly id?: string | undefined;
+    readonly reason: EditorBlockReason;
+    readonly descriptor: CanvasEmbedPlaceholderDescriptor;
+    readonly element: SourceElement;
+}
+export interface EditorBlockOptions {
+    /** Attribute-only compatibility view, matching the existing DOM/parsed-node host seam. */
+    describeHostElement?: ((el: Element) => CanvasEmbedPlaceholderDescriptor | undefined) | undefined;
+    isProtectedElement?: ((el: Element) => boolean) | undefined;
+    translate?: ((key: string) => string) | undefined;
+}
+export interface EditorHtmlTarget {
+    /** Zero-based occurrence among source elements sharing tagName and (when supplied) id. */
+    occurrenceIndex: number;
+    tagName: string;
+    id?: string;
+}
+export type RequestEditHtml = (target: EditorHtmlTarget, options: object) => void | Promise<void>;
+/** Outermost disjoint roots; explicit live islands veto aggregation but never host embed safety. */
+export declare function detectEditorBlocks({ html }: {
+    html: string;
+}, options?: EditorBlockOptions): {
+    ok: true;
+    blocks: EditorBlock[];
+    elements: SourceElement[];
+} | {
+    ok: false;
+    problem: string;
+};
+export interface RawSourceInstance extends ElementOuterRange {
+    readonly originalHtml: string;
+    readonly openingTag: string;
+    readonly tagName: string;
+    readonly id?: string | undefined;
+    readonly nonvisual: boolean;
+    readonly descriptor?: CanvasEmbedPlaceholderDescriptor;
+}
+export interface PreparedEditorSource {
+    readonly ok: true;
+    readonly html: string;
+    readonly markerAttribute: string;
+    readonly instances: readonly RawSourceInstance[];
+    readonly canvasCss: string;
+}
+export type EditorSourcePlan = PreparedEditorSource | {
+    readonly ok: false;
+    readonly html: string;
+    readonly problem: string;
+};
+/**
+ * Capture before GrapesJS parses. Only a mount-private lookup token reaches the parser; authored
+ * source stays in model metadata. Style/script atoms use inert spans, never executable source tags.
+ */
+export declare function prepareEditorSource({ html }: {
+    html: string;
+}, options?: EditorBlockOptions): EditorSourcePlan;
+/** Exact authored opening tag and its source offsets; no regex-based HTML parsing or id guessing. */
+export declare function findEditorBlockOpening({ html, target }: {
+    html: string;
+    target: EditorHtmlTarget;
+}, _options?: object): {
+    start: number;
+    end: number;
+    openingTag: string;
+} | undefined;
+//# sourceMappingURL=editor-blocks.d.ts.map