Apps

These are the generally available capabilities. Each still requires the corresponding manifest and hosting context:

Anything outside that set is an extension:

Debug from the earliest broken boundary rather than changing the App by default:

The boundary that produced the bad result owns the fix. An App must still present a safe fallback when a Homepage API or provider fails.

For hosted Apps, Homepage owns the timeline for presentation values that it animates. See Inbound: host contextInbound: host context for the field reference.

App Coder may keep source, tests, requirements, documents, and logs beside the distribution. Homepage consumes only the publishable distribution:

The exact App Coder workspace may differ, but the boundary does not: dist is what Homepage discovers, copies, serves, and publishes. Homepage Builder does not create the App source or repair App behavior that belongs in App Coder.

This is a hosted-capable example, not a requirement that every App use every field:

runtime and resources are declarations in the distribution manifest. They do not dynamically create permissions or routes.

Homepage currently:

An invalid manifest, missing entry, unsupported context, missing bridge declaration, or missing required asset prevents that App from becoming a valid registry entry. Do not place API keys, provider secrets, login tokens, or other credentials in dist.

resources.apiRoutes is the registration source for an App's named Homepage API dependencies. It remains declarative: the Backend preserves the metadata in the generated App registry, while each actual Homepage route is explicitly implemented and registered by Homepage.

Credentialed host-provided routes must declare a stable capability and logical credential identifier:

capabilityId is the semantic contract consumed by the App handshake. id identifies the technical resource; it must not be used as permission to create a route. required is separate from requiresCredentials: a credentialed resource may be optional in a future App. The current Image Generator pilot resolves openai-image to the global APIs Preferences group and never exposes the key itself.

direct and full are not synonyms. direct describes how the App is reached as a route. From the App's perspective, the direct route currently uses the full hosting context; full also describes an authored full Embed.

Homepage has three App entry contexts: direct, inline, and full. Direct is a Homepage route; inline and full are authored Embed modes. A standalone dist/index.html served outside Homepage is a development or diagnostic context, not a fourth Homepage mode. Do not treat /app/<slug> and the standalone distribution entry as interchangeable.

The local URL identifies who owns the surrounding runtime:

When testing in the Codex or in-app browser environment, use port 5174. Do not infer Homepage hosting from the standalone App URL.

The authored Element identifies the App and supplies App-specific input:

An Orgs Embed uses the same required name key for its Preferences heading and lifecycle Toasts:

Homepage interprets these host keys:

For an authored Embed, configuration reaches the App in this order:

In Element YAML, an unquoted // starts a comment and the rest of that line is removed. Quote URLs and other values containing // when they are meant to reach the App. Quoted // is preserved.

Generated presentation files are outputs of make generate. Inspect them when debugging the path, but do not edit them by hand; fix the authored Content, generator, or App distribution that produced them.

Homepage generates the instanceId for an embedded occurrence. Treat it as opaque: do not parse its path, derive a durable identifier from its format, or use another instance's value.

For an inline App:

A full App does not use inline height handling. A full App Slide contains exactly one full App Embed among its body elements. screen: true opts that full App into the responsive screen presentation.

The direct /app/<slug> route uses the same full-context surface without ordinary Content padding: its iframe fills the available route-frame width and viewport height, while the route frame continues to reserve the Preferences area and Homepage Chrome remains available as an overlay. This direct-host rule does not change inline App embeds or the dedicated direct Maps surface.

The current hosted sequence is:

The direct route follows the full branch below: Homepage owns the route and creates the managed full-surface frame without an authored Embed Element.

The handshake confirms that both sides have initialized the same embedded instance:

Standalone Apps ignore both handshake messages. An App must install its listener early and tolerate the initial snapshots arriving before or after its visual runtime is ready.

For a hosted entry document, Homepage can place a base64url-encoded hostContext query parameter on the App URL. When the value is valid, the App asset route injects a small script into index.html before the first stylesheet:

An App that needs to avoid a flash of the wrong theme should apply this bootstrap context before rendering, without animating to it. The live homepage/app/context message remains authoritative after load. The bootstrap is a host-provided optimization, not a substitute for the bridge listener. See Host presentation timingHost presentation timing.

The Maps distribution uses js/host-context-bootstrap.js for this purpose. A future generalized bootstrap package is not yet a separate platform contract.

For hosted Maps, the App waits for homepage/app/config before preparing authored map content. This is a good general pattern when an App cannot render meaningful content without authored configuration.

The bridge uses window.postMessage. Hosted Apps currently run at the same origin as Homepage. The App therefore uses its own current origin as the expected Homepage origin; it does not learn a trusted origin from the parent.

For messages received from Homepage, an App should:

For messages sent to Homepage, use window.parent.postMessage with window.location.origin. Do not use an origin supplied by the parent, document.referrer, or the first incoming message. A wildcard target is not an accepted contract. Cross-origin hosting would require a separate explicit allowlist or handshake design.

Homepage validates frame source, origin, App path, slug, and, where applicable, instance identity. Unknown or malformed messages are ignored; there is no generic error response.

Every bridge message is a flat object. The shared fields are:

homepage/app/context is the host-context message. The embedMode field in homepage/app/config and homepage/app/layout is the embed mode: inline or full. Do not use context for the embed mode.

Use these terms consistently:

Use state only for a current condition, event for something that happened, command for an instruction, and request for an App-to-Homepage ask.

This is the smallest useful hosted listener pattern. The helper functions are App-owned; the checks and message names are the current host contract.

`js [v nowrap] Generic bridge listener
const hostOrigin = window.location.origin; const appSlug = "example"; let instanceId = null;

function trustedHostMessage(event) {
return window.parent !== window
&& event.source === window.parent
&& event.origin === hostOrigin
&& event.data && typeof event.data === "object"; }

function onHostMessage(event) {
if (!trustedHostMessage(event)) return; const message = event.data; if (message.slug && message.slug !== appSlug) return;

if (message.type === "homepage/app/config") {
if (message.embedMode !== "inline" && message.embedMode !== "full") return; instanceId = message.instanceId; applyConfig(message.config || {}, message.preferences || {}); } else if (message.type === "homepage/app/context") {
applyHostContext(message); } else if (
message.type === "homepage/app/preference"
&& message.instanceId === instanceId
&& message.source === "host-preferences"
) {
applyPreference(message.preferenceId, message.value); }
}

window.addEventListener("message", onHostMessage); window.addEventListener("pagehide", () => {
window.removeEventListener("message", onHostMessage); }); `

Treat this as a pattern, not a platform helper. Add handling for layout, lifecycle, and App-specific messages only when the App declares and needs them.

The table is the compact parameter reference. The sections below provide semantics and examples. Rows whose message names include /maps/ are Maps extension examples, not requirements for every App.

Apps may report an event that has occurred using the flat homepage/app/track message. This is optional for each App; it does not add an App-specific CDP client or bypass MTAM.

The App uses its current instanceId and window.location.origin. Homepage accepts the request only from the expected iframe, origin, App slug, and exact active instance. It validates the event name (non-empty, no control characters, at most 100 characters) and optional JSON-object properties (at most 16 KiB when serialized), then writes a cdpEventType: "track" event to window.dataLayer. Homepage assigns appSlug from the validated App identity; that property is reserved and any App-provided value is discarded.

MTAM's CDP agent alone calls analytics.track(eventName, { ...properties, appSlug }), after the initial Homepage identify(). Events received while Analytics.js is loading are queued. Do not load or call the CDP SDK from an App. Track properties must not contain credentials, secrets, generated image bytes, private prompts, or other sensitive request data.

homepage/app/config is sent to embedded instances. It carries the host identity, authored configuration, and saved Preference values:

Homepage removes app, slug, mode, screen, and height from authored input before putting the remaining keys into config. Capability status is recomputed when the App loads and after relevant Homepage Preferences changes. Homepage never sends credentials or raw keys.

homepage/app/context is sent at initialization and when relevant Homepage presentation context changes:

Current semantic fields are theme, brightness, brightnessPreference, accent, onAccent, onAccentColor, accentText, optional accentTarget and accentTargetText, accentRevision, and cssVars. accent and its text color are the values currently displayed by Homepage, including intermediate values while an accent transition is running. Embedded Apps must use those fields for visible styling and must not replace them with the optional target values. Homepage may send context updates for each animation frame during the transition. See Host presentation timingHost presentation timing for the ownership rule.

The current allowlisted CSS variable set includes:

The App should use semantic fields first and treat cssVars as host styling context. The current generic host message does not include reducedMotion, textScale, or devMode. Current App distributions must not declare or depend on those fields; adding one requires a separately coordinated host-and-App contract change.

homepage/app/layout is sent to an embedded instance when the usable layout or safe area changes:

safeArea contains numeric CSS-pixel insets. A direct App does not receive an instance-scoped layout message.

homepage/app/preference is sent after a hosted Preference is committed:

value is currently a string, number, or boolean. The App should update its runtime when the Preference is intended to be live. The current host emits changes according to each control's commit behavior; text currently commits on blur.

Homepage may send these commands after an App has registered lifecycle controls:

Commands are instance-scoped. The App must keep its reported state accurate and must not expose a control it cannot honor.

An inline App with smartHeight true may send:

Homepage accepts the request only for an inline instance with no authored height, validates the exact instanceId, and clamps the result to the current 360px–560px range.

An App may contribute sections and controls through homepage/app/preferences. The manifest can provide the initial contribution, and the App can send a runtime contribution when its available controls change.

Homepage binds an accepted runtime contribution to the current frame's instance. Invalid sections or incomplete Preference records are dropped. A later accepted contribution for the same App and instance replaces the earlier contribution.

The Image Generator uses a separate message when a hosted template changes its Output defaults. This is not a replacement Preferences contribution and does not represent a manual Homepage control change.

Homepage accepts this message only from the expected Image Generator frame and exact active instance. It validates the mode, source, known Output ids, allowlisted values, and the active image-generation section's Homepage-persisted select declarations. quality is accepted only when that hosted section declares it. Accepted values update the saved instance snapshot and the visible controls together; invalid or stale messages are ignored and ordinary contributions and manual preference changes keep their existing behavior.

An App may seed footer links in the manifest's top-level supportLinks array and may replace them at runtime with homepage/app/support-links. Homepage accepts the runtime contribution only from the expected App frame, origin, slug, and exact instanceId.

presentation: "main-footer" renders in the main Homepage footer. presentation: "preferences-footer", or an omitted presentation, renders in the Preferences footer. Relative links resolve to the App route; root-relative and absolute links remain unchanged. A later accepted contribution replaces all footer links for that App instance, and sending links: [] clears them.

An embedded App registers the controls it wants Homepage to show:

state is ready, running, or paused. At least one of startPause and restart must be true. Homepage accepts the registration only for the exact App and embedded instance.

An App reports a named API operation when it fails or recovers. The message is flat and instance-scoped:

Apps should report failed for a network failure, non-2xx response, unreadable response, or API envelope with ok: false. They should report resolved after a successful retry using the same operation name. A hosted App must wait until its active instanceId is established before sending the report.

Homepage accepts the report only from the configured App origin and exact iframe source, slug, and instanceId. A failed report creates or updates one coordinated parent Toast and one live Warning per App instance and operation. A resolved report closes the Toast and removes the Warning. Navigation away from the App does not clear its parent Toast or unresolved Warning; reloading or replacing the App iframe clears that App-instance state. The active Warning is not stored in Homepage Preferences.

Request feedback and handle one user action.

An App may request a parent-owned Toast after its active instanceId is established:

An active warning/error creates or updates the corresponding Warnings issue. A resolved report uses the same issueId, clears the issue, and does not create a new Toast. Info/success Toasts must not include issue fields. Homepage owns placement, timing, queueing, grouping, accessibility, and text truncation; Apps send no HTML, callbacks, unvalidated URLs, placement, or styling instructions.

When an action includes href, Homepage opens internal paths and hashes in the current tab and opens external http/https URLs in a new tab. Homepage handles that URL action locally and does not send homepage/app/toast-action. Without href, the action uses the App-owned homepage/app/toast-action flow described below.

When the user invokes an action, Homepage sends:

The App validates event.source === window.parent, the same-origin event.origin, slug, exact instance, expected issue, and known action ID. It ignores stale or unknown actions, performs the operation, and reports recovery separately. The command is not a callback or permission grant.

Toasts and unresolved issues survive Homepage navigation but are cleared when the App iframe is actually reloaded or replaced. Toast dismissal or expiry does not resolve an issue. Homepage may queue, group, rate-limit, or dismiss a request; an App must not depend on immediate Toast visibility. Standalone Apps must retain an App-owned fallback.

For a named API failure, the App sends only homepage/app/api-status; Homepage creates the coordinated parent Toast and Warnings issue. A matching resolved API-status report closes the Toast and clears the issue.

App-owned Preferences remain App-owned. The Image Generator uses the existing sectionId: image-generation request for its output settings.

For a registered capability, an App may request the corresponding setup target with only the semantic capability ID:

Homepage validates the iframe source, same-origin target, exact App slug, instance, and mode, then resolves the capability through the registered manifest metadata. The App cannot choose an arbitrary Preferences group, section, or credential ID. The Image Generator pilot resolves this request to the global APIs group and focuses openai-image.

A recovery report uses the same operation identity:

The baseline contract should omit details unless a reviewed App needs safe diagnostics. When used, details are limited to at most eight { label, value } entries, with labels bounded to 60 characters and values bounded to 240 characters; labels and values must be allowlisted, user-safe, and free of credentials, authored secrets, request data, provider URLs, and raw upstream responses.

If the host does not yet support this extension, the App must retain a safe in-App fallback.

Use Homepage Preferences when a setting is:

Keep a setting inside the App when it is:

This is a design policy, not a technical restriction. An App may deviate when it documents why host Preferences would make the workflow less clear or less safe.

When an App contributes a hosted Preference, the embedded App must not show a second control that changes the same value. The App may show the resulting state or provide a different, non-duplicative action.

This applies to settings, view choices, and App-specific navigation exposed through Homepage Preferences. Direct mode may still show the App-owned control. A richer embedded control is an App-specific deviation and belongs in the App extension documentation.

A contribution contains collapsible sections:

Each Preference has:

The current Homepage renderer supports:

The shared target vocabulary also mentions checkbox, date, datetime, email, number, password, textarea, time, and url. Those are not current Homepage-rendered App controls. Use the seven general controls above. navigation-list is Maps-specific and requires the Maps extension.

Homepage Apps are first-party, curated distributions created by App Coder and reviewed before integration. They are not third-party plugins.

Hosted Apps currently run in a same-origin, unsandboxed iframe. The bridge validates messages, but it is not a sandbox or permission boundary. Treat App client code as trusted Homepage code: review it before integration, keep secrets out of dist/, and use named Homepage APIs for server-backed work.

Apps must not depend on direct DOM or storage access. Same-origin access is an implementation consequence of the current trusted-App model, not a permission grant. Use explicit bridge and API contracts instead.

Homepage provides a named API when repeated use, provider abstraction, normalization, server-side credentials, or security makes a capability worthwhile.

An App must not:

Maps is the current example of a named same-origin Homepage API. This call shows the general request shape; the Maps route catalogue appears in the Maps reference:

`js [< nowrap] Calling a Homepage API
const response = await fetch("/api/maps/address", {
method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ address: "Berlin, Germany" })
});

const result = await response.json();

if (!response.ok || !result.ok) {
throw new Error(result.error?.message || "Homepage API request failed."); }

const point = result.data; `

The current response envelope is:

Failures use ok: false, data: null, and an error object containing a stable code, a user-safe message, and optional details. When an App surfaces that failure to the host, it should report only a bounded safe summary through homepage/app/api-status; provider credentials, raw upstream payloads, authored secrets, and arbitrary URLs must stay out of the bridge.

The Image Generator uses the named same-origin route POST /api/image-generator. The route is a single-purpose Homepage adapter; it is not a generic provider proxy. Its request uses only provider-neutral values:

operation is generate or edit; edit requests may include sourceImage. The allowed semantic values are default|fast|quality, png|jpeg|webp, auto|square|landscape|portrait, auto|low|medium|high, and auto|opaque|transparent. Homepage resolves the logical credential openai-image server-side, maps the model policy to an allowlisted provider model, and never sends the credential into the App iframe.

Successful responses contain exactly one normalized image at data.image, with mimeType, base64, and an optional revisedPrompt. Provider model IDs, arbitrary URLs, raw upstream bodies, and provider credentials are not accepted or returned.

Use an extension when:

Do not add an extension merely to avoid using an existing general capability.

An App-specific extension should document:

The App-specific requirement belongs beside the App's source and distribution. Homepage integration requirements should also be reflected in the shared App/bridge requirement before the host changes.

An App may declare an explicit app-owned Local Storage extension when the App remains the canonical owner of a domain history while Homepage must render a lightweight host surface even when the App iframe is unloaded. The Image Generator is the current example.

The manifest declares distribution.extensions.appOwnedHistory with schema version 1, the history key app.image-generator.history.v1, the reference key app.image-generator.references.v1, and the metadata key app.image-generator.metadata.v1. Homepage reads only this declaration, validates the exact App slug, exact instanceId, and schema version, and does not migrate or reinterpret the App's stores.

The App emits homepage/app/image-generator/history-changed with its exact instanceId, schemaVersion, and numeric revision. Homepage sends homepage/app/image-generator/history-command to the active matching instance with command: refresh|select|open and an entryId for selection/opening. Host-side actions such as preview, download, prompt copy, favorite, delete, and clear may operate on the declared stores while the App is unloaded; after a host mutation, Homepage sends refresh to a loaded matching instance.

The App owns history entries, references, builder snapshots, and metadata. Homepage owns only the host presentation and validated coordination. When metadata.hasGenerated is true, the Images Preferences box remains available after the App is unloaded; it is closed by default when the App is hidden and open by default while the matching App is embedded. Unsupported hosts ignore the extension and the App continues to work in its own surface.

Use this compact structure for a new App-specific requirement:

Maps extends the general contract with navigation-list hosted Preference items, route-navigation, route-painted, route-failed, route-navigation-state, route API warning adaptation, and route-readiness/lifecycle coordination.

These are intentionally Maps-specific host behaviors, not baseline requirements for another App. Homepage does not provide a generic extension framework for them yet; that work is deferred until another App has a comparable host-coordination need.

When debugging a local integration, follow the main integration workflowmain integration workflow and use the local test contextslocal test contexts for the URLs. Then run this diagnostic loop:

The current workspace commands are:

sh [v nowrap] Homepage Builder local loop make codex-dev make generate make test

These are Homepage Builder commands. App Coder runs the App's own test suite with the App workspace's tooling.

The published asset route currently uses Cache-Control: no-store. The App entry and assets are served from the authored distribution; App source, tests, documents, and logs are not public runtime assets.

For an App with slug maps:

The alias resolves through the same Frontend runtime; it is not a second App copy. Current App routes are public when the deployment is public. Gated App behavior belongs to the separate access-control contract.

These Maps routes keep provider details and credentials on the server. The future API offering will be authoritative for route schemas, errors, caching, rate limits, and provider behavior.

The Maps extension keeps provider-specific behavior inside the Maps/API contract. The general Apps contract only needs the ownership and user-visible outcome:

The Maps API implementation owns provider selection, required request headers, upstream timeouts, fallback policy, and provider diagnostics. Those details belong in the Maps/API documentation and the future API offering, not in the general Apps contract.

The App receives authored values as config, saved values as preferences, and the generated instanceId through homepage/app/config. It contributes Route navigation and Map settings through homepage/app/preferences, then uses the Maps extension messages when the route is ready.

Maps-specific behavior remains in the Maps distribution README and requirements. This section explains why the App is a useful reference; it is not a replacement for Maps documentation.

These are follow-ups, not current App requirements: