← Public packages
@hypercubed/kody-os
Minimal shared Human/Agent OS shell — ReKindle-style blank slate for browser-first use.
Files
/**
* Browser-safe rendering helpers for data-driven apps.
*
* ZERO imports that execute at runtime (types only): the shell can bundle or
* inline this without kody:/node: imports. These helpers only build HTML
* strings from a definition + state snapshot; all mutation still goes through
* server-side `act()`. The UI submits a plain GET form (edge-safe on the
* package-app subdomain); the POST route remains for API clients.
* Server-rendered; JS may enhance it.
*
* ES2019 ceiling: no ?. and no ?? in this file.
*/
import type { AppDefinition, AppState, AppSummary } from './types.ts'
/** Escape runtime values before placing them in HTML. */
export function escapeHtml(value: string): string {
return value.replace(
/[&<>"']/g,
function (character: string): string {
if (character === '&') return '&'
if (character === '<') return '<'
if (character === '>') return '>'
if (character === '"') return '"'
return '''
},
)
}
function str(value: unknown): string {
if (value === undefined || value === null) return ''
return String(value)
}
function isRecord(value: unknown): value is Record<string, unknown> {
return value !== null && typeof value === 'object' && !Array.isArray(value)
}
/** Read one bundle file as a string, or undefined when absent. */
function bundleFile(def: AppDefinition, path: string): string | undefined {
var raw = def as unknown as Record<string, unknown>
if (!isRecord(raw['bundle'])) return undefined
var files = (raw['bundle'] as Record<string, unknown>)['files']
if (!isRecord(files)) return undefined
var content = (files as Record<string, unknown>)[path]
return typeof content === 'string' ? content : undefined
}
/**
* Inline bundle-relative asset references so the page carries no external
* bundle assets: `<script src="app.js"></script>` becomes an inline script,
* `<link rel="stylesheet" href="style.css">` becomes an inline style.
* References with no matching bundle file are dropped, never fetched.
* Absolute URLs are left untouched (validation keeps bundles self-contained).
*/
function inlineBundleAssets(entry: string, def: AppDefinition, used: string[]): string {
var withScripts = entry.replace(
/<script\b([^>]*?)\bsrc\s*=\s*["']([^"']+)["']([^>]*)>\s*<\/script\s*>/gi,
function (whole: string, pre: string, src: string): string {
var content = bundleFile(def, src)
if (content === undefined) return ''
used.push(src)
return '<script>' + content + '</script>'
},
)
return withScripts.replace(
/<link\b([^>]*?)\bhref\s*=\s*["']([^"']+)["']([^>]*?)\/?>/gi,
function (whole: string, pre: string, href: string): string {
if (whole.toLowerCase().indexOf('stylesheet') === -1) return whole
var content = bundleFile(def, href)
if (content === undefined) return ''
used.push(href)
return '<style>' + content + '</style>'
},
)
}
/**
* Render a bundle definition's entry HTML inlined for the app panel.
* Only assets the entry explicitly references (`<script src>` /
* `<link rel="stylesheet" href>`) execute: unreferenced `.js`/`.css`
* files are never appended (that append was loader magic executing code
* the author never referenced, so it is removed — see bundle-files).
* Extra `.html` files are ignored. References with no matching bundle
* file are dropped, never fetched, as the fail-closed fallback for
* already-stored definitions. Throws when the stored entry is missing
* or unreadable so callers can degrade gracefully.
*
* When `actionBase` is given, the container carries it as
* `data-action-base` so bundle scripts can resolve action URLs against the
* owning app instead of the current page path. When `packageRef` is
* given, the container also carries it as `data-package-ref` so bundle
* scripts can name the running package in agent prompts instead of
* deriving it from the host.
*/
export function renderBundleContent(def: AppDefinition, actionBase?: string, packageRef?: string): string {
var entry = bundleFile(def, 'index.html')
if (typeof entry !== 'string' || entry === '') {
throw new Error('bundle "' + def.id + '" has no readable entry')
}
var used: string[] = ['index.html']
var inlined = inlineBundleAssets(entry, def, used)
var baseAttr =
typeof actionBase === 'string' && actionBase !== ''
? ' data-action-base="' + escapeHtml(actionBase) + '"'
: ''
var refAttr =
typeof packageRef === 'string' && packageRef !== ''
? ' data-package-ref="' + escapeHtml(packageRef) + '"'
: ''
return '<div class="bundle" data-bundle="' + escapeHtml(def.id) + '"' + baseAttr + refAttr + '>\n' + inlined + '\n</div>'
}
/**
* The app's help text from `ui.help`, or undefined when the app defines
* none: absent, a non-string (only possible in a stored definition that
* predates validation), or empty / whitespace-only. Canonicalization
* already drops the empty forms at install time; this keeps rendering
* defensively correct for stored definitions.
*/
export function helpTextFor(def: AppDefinition): string | undefined {
if (!def || !def.ui) return undefined
var help = def.ui.help
if (typeof help !== 'string' || help.replace(/\s+/g, '') === '') return undefined
return help
}
/**
* The title-bar help box: the literal text `?` in the shared box look,
* opening the JS help dialog. Rendered immediately left of the expand
* box on an app header; the caller decides whether help exists.
* A <button> (not a link): opening help writes no fragment, changes no
* URL, and never navigates — the client toggles the dialog in place.
* The glyph rides in an .os-help-glyph span, absolutely centered over the
* shared square, so it reads centered on every font's metrics.
*/
export function renderHelpButton(id: string): string {
return '<button type="button" class="os-help" data-help-open="help-dialog-' + escapeHtml(id) + '" aria-label="Help" title="Help"><span class="os-help-glyph" aria-hidden="true">?</span></button>'
}
/**
* The per-app help dialog: server-rendered, hidden by default, opened by
* the shell client in place (no fragment, no navigation). Plain text
* only — the help string is escaped, never interpreted, and line breaks
* are preserved by CSS (`white-space: pre-wrap`). No route, no storage.
* The dialog carries `hidden` until the client opens it; closing restores
* the opener underneath with no URL change, so overlay and expanded state
* are untouched. The box holds a plain header line (`{app} - Help`),
* the help text, and a Close button, centered with a double border.
*/
export function renderHelpDialog(id: string, title: string, help: string): string {
// The `dialog-` / `heading-` infixes keep the two identifiers disjoint:
// the dialog for app `heading-foo` (`help-dialog-heading-foo`) can
// never equal the heading for app `foo` (`help-heading-foo`), which
// the old shared `help-` prefix allowed. Button and dialog agree.
var dialogId = 'help-dialog-' + escapeHtml(id)
var headingId = 'help-heading-' + escapeHtml(id)
return (
'<div class="os-help-dialog" id="' +
dialogId +
'" role="dialog" aria-modal="true" aria-labelledby="' +
headingId +
'" hidden>\n' +
'<h2 class="os-help-heading" id="' +
headingId +
'">' +
escapeHtml(title) +
' - Help</h2>\n' +
'<p class="os-help-body">' +
escapeHtml(help) +
'</p>\n' +
'<p class="os-help-close"><button type="button" data-help-close>Close</button></p>\n' +
'</div>'
)
}
/**
* Render one app's bare content on the single render path: the bundle UI,
* then every state field, then one plain form per UI action. No wrapper
* element of its own — the shell's `<section class="app">` (see
* `renderAppPanel`) is the single box on app pages, modal overlays, and
* (later) widgets, so content renders identically in every placement.
* There is no template branch: every unified app ships bundle files.
*
* Forms use GET because Kody's edge rejects cross-origin POSTs to a package-app
* subdomain; some browsers and embedded views report a null origin even for a
* same-origin form. Authentication rides the HttpOnly session cookie;
* no credential travels in a form, link, or redirect.
*/
/** Render the JSON state seed for one app section (Phase 2, decided 2026-10-30).
* The seed is a <script type="application/json"> element carrying the full
* durable state, rendered BEFORE the bundle HTML so it is present at
* bundle-script time — the 2026-10-30 Scribe probe proved the span readout
* is not present at bundle-script time, only by DOMContentLoaded. Escaping
* <, >, & and U+2028/U+2029 as \u escapes keeps the JSON from breaking
* out of the script element; JSON.parse on the bundle side restores it.
* Dual-channel migration: the span readout below is still rendered, so
* span-reading bundles keep working until ported to the bridge. */
export function renderStateSeed(def: AppDefinition, state: AppState): string {
var json = JSON.stringify(state)
.replace(/</g, '\\u003c')
.replace(/>/g, '\\u003e')
.replace(/&/g, '\\u0026')
.replace(/\u2028/g, '\\u2028')
.replace(/\u2029/g, '\\u2029')
return '<script type="application/json" data-kody-state-seed="1" data-app-id="' + escapeHtml(def.id) + '">' + json + '</script>'
}
export function renderAppSection(def: AppDefinition, state: AppState, appBasePath: string, packageRef?: string): string {
var bundleHtml: string
try {
bundleHtml = renderBundleContent(def, appBasePath + '/apps/' + def.id, packageRef)
} catch (err) {
bundleHtml = '<p>This bundle could not be displayed. The stored definition is damaged; reinstall it with add_app.</p>'
}
var seedHtml = renderStateSeed(def, state)
var hideState = def.ui.hideState === true
var fieldNames: string[] = Object.keys(def.stateSchema.fields)
var hiddenAttr = hideState ? ' hidden' : ''
var fields = fieldNames
.map(function (field: string): string {
var value = str(state[field])
return '<p data-field="' + escapeHtml(field) + '"' + hiddenAttr + '>' + escapeHtml(field) + ': ' + '<span>' + escapeHtml(value) + '</span></p>'
})
.join('\n')
var actions = def.ui.actions || []
var forms = actions
.map(function (entry): string {
return (
'<form class="app-action" method="GET" action="' +
escapeHtml(appBasePath + '/apps/' + def.id) +
'">' +
'<input type="hidden" name="action" value="' +
escapeHtml(entry.action) +
'" />' +
'<button type="submit">' +
escapeHtml(entry.label) +
'</button></form>'
)
})
.join('\n')
return seedHtml + '\n' + bundleHtml + '\n' + fields + '\n' + forms
}
/**
* Render the single app panel box: title bar, body with bare section content,
* and an optional back link (omitted when backHref/backLabel are empty).
* Pass withHeader=false on full app pages, where the shell chrome already
* names the app; overlays keep the header. Defaults to current behavior.
* Used by the app page and the modal overlay alike.
*/
export function renderAppPanel(
def: AppDefinition,
state: AppState,
appBasePath: string,
backHref: string,
backLabel: string,
error?: string,
withHeader?: boolean,
closeHref?: string,
expandHref?: string,
packageRef?: string,
): string {
var title = escapeHtml(def.ui.title || def.name)
var content = renderAppSection(def, state, appBasePath, packageRef)
var errHtml = error ? '<p role="alert">Error: ' + escapeHtml(error) + '</p>\n' : ''
var back =
backHref !== '' && backLabel !== ''
? '<p class="app-back"><a href="' + escapeHtml(backHref) + '">' + escapeHtml(backLabel) + '</a></p>\n'
: ''
var closeBtn =
typeof closeHref === 'string' && closeHref !== ''
? '<a class="os-box" href="' + escapeHtml(closeHref) + '" aria-label="Close"></a>'
: ''
var expandBtn =
typeof expandHref === 'string' && expandHref !== ''
? '<a class="modal-expand" href="' + escapeHtml(expandHref) + '" aria-label="Open ' + title + ' full page"></a>'
: ''
// On an app page the shell titlebar is the only header (withHeader=false),
// so the shell chrome owns the help box and dialog; the panel renders the
// help box only when it draws a header itself (modal overlays).
var helpBtn = withHeader !== false && helpTextFor(def) !== undefined ? renderHelpButton(def.id) : ''
var header =
withHeader === false
? ''
: '<h2 class="app-titlebar' + (closeBtn !== '' ? ' has-close' : '') + (expandBtn !== '' ? ' has-expand' : '') + (helpBtn !== '' ? ' has-help' : '') + '">' + closeBtn + '<span class="app-title-plate"><span class="app-title-text">' + title + '</span></span>' + helpBtn + expandBtn + '</h2>\n'
return (
'<section class="app" data-app-id="' +
escapeHtml(def.id) +
'" aria-label="' +
title +
'">\n' +
header +
'<div class="app-body">\n' +
errHtml +
content +
'\n</div>\n' +
back +
'</section>'
)
}
/**
* Render a modal overlay for one modal-capable app: a `:target`-revealed panel
* holding the same single app panel as the app page, plus a close box that
* hides it again and an expand box that opens the full app page (mirroring
* the widget expand box on the home screen). The outer element is a `div`
* so the overlay markup contains exactly one `section.app`. Fully present
* in server-rendered HTML.
*
* When the app defines help, the `[?]` box joins the panel titlebar and the
* help dialog is rendered as this section's second element, right after the
* overlay. The dialog opens via the shell client with no URL change, so
* opening help leaves the overlay (and any expanded layout) exactly as it
* was; closing help returns focus to the opener, never navigating.
*/
export function renderOverlaySection(def: AppDefinition, state: AppState, appBasePath: string, packageRef?: string): string {
var panel = renderAppPanel(def, state, appBasePath, '', '', undefined, undefined, '#apps', appBasePath + '/apps/' + def.id, packageRef)
var overlay =
'<div class="overlay" id="app-' +
escapeHtml(def.id) +
'" aria-label="' +
escapeHtml(def.ui.title || def.name) +
'">\n' +
'<div class="overlay-panel">\n' +
panel +
'\n</div>\n</div>'
var help = helpTextFor(def)
if (help === undefined) return overlay
return overlay + '\n' + renderHelpDialog(def.id, def.ui.title || def.name, help)
}
/** True when the app's default open mode is the modal overlay (fragment link + inline section). */
export function isModalApp(app: AppSummary): boolean {
return app.openAs === 'modal'
}
/** Inline SVG icons were sanitized at validation; detect the stored variant. */
function looksLikeSvg(value: string): boolean {
return value.replace(/^\s+/, '').toLowerCase().indexOf('<svg') === 0
}
function tileItem(app: AppSummary, appBasePath: string, wide?: boolean): string {
var label = escapeHtml(app.label)
var rawIcon = app.icon || '#'
var icon = looksLikeSvg(rawIcon) ? rawIcon : escapeHtml(rawIcon)
var description = typeof app.description === 'string' ? app.description : ''
var titleAttr = ' title="' + escapeHtml(description) + '"'
var iconHtml = '<span class="tile-icon" aria-hidden="true">' + icon + '</span>'
var textHtml =
wide === true
? '<span class="tile-text"><span class="tile-label">' +
label +
'</span><span class="tile-desc">' +
escapeHtml(description) +
'</span></span>'
: '<span class="tile-label">' + label + '</span>'
return (
'<li' + (wide === true ? ' class="tile-wide"' : '') + '><a class="tile" href="' +
escapeHtml(isModalApp(app) ? appBasePath + '/apps/' + app.id + '?touch=1' : appBasePath + '/apps/' + app.id) +
'"' + titleAttr + '>' +
iconHtml +
textHtml +
'</a></li>'
)
}
function tilesList(apps: AppSummary[], appBasePath: string, wide?: boolean): string {
var items: string[] = []
for (var i = 0; i < apps.length; i++) {
items.push(tileItem(apps[i], appBasePath, wide))
}
return '<ul class="tiles">\n' + items.join('\n') + '\n</ul>'
}
/** Render the Pinned section (omitted when empty by the caller). */
export function renderPinnedSection(apps: AppSummary[], appBasePath: string): string {
return (
'<section class="category" id="pinned" aria-label="Pinned">\n' +
'<div class="section-head"><h2>Pinned</h2></div>\n' +
tilesList(apps, appBasePath, true) +
'\n</section>'
)
}
/** Render the Recent section with a Clear control (omitted when empty by the caller). */
export function renderRecentSection(apps: AppSummary[], appBasePath: string, formBase?: string): string {
return (
'<section class="category" id="recent" aria-label="Recent">\n' +'<div class="section-head"><h2>Recent</h2>' +
'<form method="GET" action="' +
escapeHtml(typeof formBase === 'string' && formBase !== '' ? formBase : appBasePath + '/') +
'" class="section-clear">' +
'<input type="hidden" name="clear" value="1" />' +
'<button type="submit">Clear</button></form></div>\n' +
tilesList(apps, appBasePath) +
'\n</section>'
)
}
/** Edit-mode entry point, shown only when at least one app is installed.
* The caller decides availability: an all-hidden registry still offers
* Edit, even though its visible All list is empty. A GET form matches the
* Clear control, so both header actions render as the same button. */
export function editAppsLink(appBasePath: string, formBase?: string): string {
var base = typeof formBase === 'string' && formBase !== '' ? formBase : appBasePath + '/apps'
return (
'<form method="GET" action="' +
escapeHtml(base) +
'" class="section-edit">' +
'<input type="hidden" name="edit" value="1" />' +
'<button type="submit">Edit</button></form>'
)
}
/** Render the All-apps section in browse mode. The Apps page is a launcher:
* the All apps header carries the Edit link (to Edit mode) when at least one
* app is installed. */
export function renderAllSection(
apps: AppSummary[],
appBasePath: string,
formBase?: string,
hint?: string,
editAvailable?: boolean,
): string {
var list = tilesList(apps, appBasePath)
var editLink = editAvailable === true ? ' ' + editAppsLink(appBasePath, formBase) : ''
return (
'<section class="category" id="apps" aria-label="Apps">\n' +'<div class="section-head"><h2>All apps</h2>' + editLink + '</div>\n' +
(typeof hint === 'string' && hint !== '' ? '<p class="empty-hint">' + escapeHtml(hint) + '</p>\n' : '') +
list +
'\n</section>'
)
}
/** Monochrome line icon for one Edit toggle. Strokes follow the button's
* text color, so the icon inverts with the pressed state. */
function editToggleIcon(param: string): string {
if (param === 'pin') {
return (
'<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">' +
'<path d="M12 17v5"/><path d="M9 10.76a2 2 0 0 1-1.11 1.79l-1.78.9A2 2 0 0 0 5 15.24V16a1 1 0 0 0 1 1h12a1 1 0 0 0 1-1v-.76a2 2 0 0 0-1.11-1.79l-1.78-.9A2 2 0 0 1 15 10.76V6h1a2 2 0 0 0 0-4H8a2 2 0 0 0 0 4h1z"/>' +
'</svg>'
)
}
if (param === 'hide') {
return (
'<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">' +
'<path d="M9.88 9.88a3 3 0 1 0 4.24 4.24"/><path d="M10.73 5.08A10.43 10.43 0 0 1 12 5c7 0 10 7 10 7a13.16 13.16 0 0 1-1.67 2.68"/><path d="M6.61 6.61A13.526 13.526 0 0 0 2 12s3 7 10 7a9.74 9.74 0 0 0 5.39-1.61"/><line x1="2" x2="22" y1="2" y2="22"/>' +
'</svg>'
)
}
return (
'<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">' +
'<path d="M15 21v-8a1 1 0 0 0-1-1h-4a1 1 0 0 0-1 1v8"/><path d="M3 10a2 2 0 0 1 .709-1.528l7-5.999a2 2 0 0 1 2.582 0l7 5.999A2 2 0 0 1 21 10v9a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2z"/>' +
'</svg>'
)
}
/** One state toggle for an Edit row: an icon-only submit button. Its
* aria-checked and pressed appearance carry the current state; the hidden
* `want` field submits the opposite value, so no JavaScript is required. */
function editToggleForm(formBase: string, param: string, id: string, label: string, isOn: boolean): string {
return (
'<form method="GET" action="' +
escapeHtml(formBase) +
'" class="edit-toggle edit-control edit-control-' +
escapeHtml(param) +
'">' +
'<input type="hidden" name="edit" value="1" />' +
'<input type="hidden" name="' +
escapeHtml(param) +
'" value="' +
escapeHtml(id) +
'" />' +
'<input type="hidden" name="want" value="' + (isOn ? '0' : '1') + '" />' +
'<button type="submit" role="switch" aria-checked="' +
(isOn ? 'true' : 'false') +
'" aria-label="' +
escapeHtml(label) +
'" class="edit-toggle-btn' +
(isOn ? ' edit-toggle-btn-on' : '') +
'">' +
editToggleIcon(param) +
'</button></form>'
)
}
/** Render the Apps Edit section: one row per installed app, every
* installed app including hidden ones, alphabetical by label with id
* as tie-break, each row with Pin/Unpin, Hide/Unhide, and Add to
* home/Remove from home as plain GET forms through the /apps
* mutation route, 303-ing back to ?edit=1. Pinned/Recent stay tiles;
* only this section lists rows. No JavaScript is required. */
export function renderEditSection(
apps: AppSummary[],
pinnedIds: string[],
hiddenIds: string[],
homepageIds: string[],
appBasePath: string,
formBase?: string,
): string {
var base = typeof formBase === 'string' && formBase !== '' ? formBase : appBasePath + '/apps'
var sorted = apps.slice()
sorted.sort(function (a, b): number {
var al = a.label.toLowerCase()
var bl = b.label.toLowerCase()
if (al < bl) return -1
if (al > bl) return 1
if (a.id < b.id) return -1
if (a.id > b.id) return 1
return 0
})
var items: string[] = []
for (var i = 0; i < sorted.length; i++) {
var app = sorted[i]
var rawIcon = app.icon || '#'
var icon = looksLikeSvg(rawIcon) ? rawIcon : escapeHtml(rawIcon)
var isPinned = pinnedIds.indexOf(app.id) !== -1
var isHidden = hiddenIds.indexOf(app.id) !== -1
var isHome = homepageIds.indexOf(app.id) !== -1
var controls =
editToggleForm(base, 'pin', app.id, 'Pinned', isPinned) +
editToggleForm(base, 'hide', app.id, 'Hidden', isHidden) +
editToggleForm(base, 'home', app.id, 'On home', isHome)
items.push(
'<li class="edit-row"><span class="edit-main">' +
'<span class="edit-icon" aria-hidden="true">' +
icon +
'</span>' +
'<span class="edit-label">' +
escapeHtml(app.label) +
'</span></span>' +
(app.description ? '<span class="edit-desc">' + escapeHtml(app.description) + '</span>' : '') +
'<span class="edit-controls">' +
controls +
'</span>' +
'</li>',
)
}
return (
'<section class="category" id="apps-edit" aria-label="Edit apps">\n' +
'<div class="section-head"><h2>Edit apps</h2><form method="GET" action="' + escapeHtml(base) + '" class="section-done"><button type="submit">Done</button></form></div>\n' +
'<ul class="edit-list">\n' +
items.join('\n') +
'\n</ul>\n</section>'
)
}
/**
* Render a plain list of installed apps (fallback content).
* The shell's preferred home rendering is its own themed tile grid.
*/
export function renderHomeTiles(apps: AppSummary[], appBasePath: string): string {
if (apps.length === 0) return '<p>No apps yet.</p>'
return (
'<ul>\n' +
apps
.map(function (app: AppSummary): string {
var mark = app.icon ? app.icon + ' ' : ''
return (
'<li><a href="' +
escapeHtml(appBasePath + '/apps/' + app.id) +
'">' +
escapeHtml(mark + app.label) +
'</a></li>'
)
})
.join('\n') +
'\n</ul>'
)
}
/**
* Render one dashboard widget: the app's own compact view (same bare content
* as the app page) with live state, action forms that PRG back to `/`,
* up/down reorder controls, and a link to the full app page.
*
* `index`/`total` position the widget in homepage order; boundary buttons
* render disabled. Fully present in server-rendered HTML.
*/
export function renderWidgetSection(
def: AppDefinition,
state: AppState,
appBasePath: string,
index: number,
total: number,
error?: string,
packageRef?: string,
): string {
var title = escapeHtml(def.ui.title || def.name)
var content = renderAppSection(def, state, appBasePath, packageRef)
var errHtml = error ? '<p role="alert">Error: ' + escapeHtml(error) + '</p>\n' : ''
var upDisabled = index <= 0 ? ' disabled' : ''
var downDisabled = index >= total - 1 ? ' disabled' : ''
return (
'<section class="widget" data-app-id="' +
escapeHtml(def.id) +
'" aria-label="' +
title +
'">\n' +
'<h2 class="app-titlebar"><span class="app-title-plate"><span class="app-title-text">' +
title +
'</span></span><a class="widget-expand" href="' +
escapeHtml(appBasePath + '/apps/' + def.id) +
'" aria-label="Expand ' +
title +
'" title="Expand"></a></h2>\n' +
'<div class="app-body">\n' +
errHtml +
content +
'\n</div>\n' +
'<div class="widget-controls">\n' +
'<form method="GET" action="' +
escapeHtml(appBasePath + '/') +
'" class="widget-move move-left">' +
'<input type="hidden" name="home" value="' +
escapeHtml(def.id) +
'" /><input type="hidden" name="move" value="-1" />' +
'<button type="submit" class="widget-arrow" aria-label="Move ' +
title +
' left"' +
upDisabled +
'><span class="wa-mark wa-left" aria-hidden="true"></span></button></form>\n' +
'<form method="GET" action="' +
escapeHtml(appBasePath + '/') +
'" class="widget-move move-right">' +
'<input type="hidden" name="home" value="' +
escapeHtml(def.id) +
'" /><input type="hidden" name="move" value="1" />' +
'<button type="submit" class="widget-arrow" aria-label="Move ' +
title +
' right"' +
downDisabled +
'><span class="wa-mark wa-right" aria-hidden="true"></span></button></form>\n' +
'</div>\n</section>'
)
}
/**
* Shared empty-state help block (empty-install + mini-apps-user-facing).
* Rendered by the Apps page when no apps are installed and by
* Home when the homepage is empty and no apps are installed at all.
* One block, not two copies, so the two pages cannot silently diverge.
* Prompts are plain selectable text in gate-hint code blocks — no copy
* button, no Clipboard API (on-device Scribe test: navigator.clipboard
* writeText/readText are denied with NotAllowedError).
* appBasePath is accepted so call sites pass the same context as the
* other renderers; the help text currently contains no links.
*
* The built-in Help page passes `omitClosing: true`: the closing line
* ("Once an app is installed...") is true of the first-run empty
* state, not of the Help page itself. Empty Home / empty Apps keep it.
*/
/**
* The full package reference for agent prompts: @owner/leaf. The owner
* is the subdomain of the Kody host (hypercubed in hypercubed.kody.run);
* the leaf is the mount (the first path segment of the base path). On a
* non-Kody host (local mock, localhost) there is no owner, so the bare
* leaf is the reference. Mirrors the Store bundle's storePackageSlug.
*/
export function packageRefForHost(host: string, appBasePath: string): string {
var leaf = 'kody-os'
if (appBasePath) {
var base = appBasePath.charAt(0) === '/' ? appBasePath.slice(1) : appBasePath
var slash = base.indexOf('/')
var first = slash === -1 ? base : base.slice(0, slash)
if (first) { leaf = first }
}
var suffix = '.kody.run'
if (host && host.length > suffix.length && host.slice(host.length - suffix.length) === suffix) {
var owner = host.slice(0, host.length - suffix.length)
if (owner) { return '@' + owner + '/' + leaf }
}
return leaf
}
export function renderEmptyHelp(appBasePath: string, opts?: { omitClosing?: boolean; packageRef?: string }): string {
// The full @owner/leaf reference when the caller supplies it (the
// shell derives it from the request host + mount); otherwise the
// bare leaf from the mount, as before.
var slug = 'kody-os'
if (opts && typeof opts.packageRef === 'string' && opts.packageRef !== '') {
slug = opts.packageRef
} else if (appBasePath) {
var base = appBasePath.charAt(0) === '/' ? appBasePath.slice(1) : appBasePath
var slash = base.indexOf('/')
var first = slash === -1 ? base : base.slice(0, slash)
if (first) { slug = first }
}
var ops = 'Read package:' + slug + '#OPERATIONS.md'
var block =
'<p>No apps installed yet. This shell starts empty \u2014 nothing is installed until you add it. Pick a path below. Copy a prompt into a Kody-connected agent.</p>\n' +
'<h3>Add your own apps</h3>\n' +
'<p class="gate-hint"><code>' + ops + ', then add a new app: Name: [display name]; What it does: [describe what it should do]</code></p>\n' +
'<h3>Remove an app</h3>\n' +
'<p class="gate-hint"><code>' + ops + ', then remove this app: [app id]</code></p>\n' +
'<h3>Install the App Catalog</h3>\n' +
'<p class="gate-hint"><code>' + ops + ', then install this app: https://github.com/Hypercubed/kody-os/tree/main/catalog/app-store</code></p>\n'
if (opts && opts.omitClosing === true) return block
return block + '<p>Once an app is installed your apps show up on the Apps page.</p>'
}
/**
* Render the widget dashboard grid. An empty homepage list renders one of
* two honest empty states: the shared empty help block when no apps
* are installed at all, or a short Add-to-home message when apps are
* installed but none are on Home.
*/
export function renderDashboard(widgets: string[], appBasePath: string, hasApps: boolean, packageRef?: string): string {
if (widgets.length === 0) {
if (hasApps === true) {
return (
'<section class="dashboard dashboard-empty" aria-label="Home">\n' +
'<p class="empty-hint">Add some to Home from the Apps page. Open Apps, tap Edit, and use Add to home on a row. They appear here live.</p>\n' +
'</section>'
)
}
return (
'<section class="dashboard dashboard-empty" aria-label="Home">\n' +
renderEmptyHelp(appBasePath, packageRef ? { packageRef: packageRef } : undefined) +
'\n</section>'
)
}
return '<div class="widgets" role="list">\n' + widgets.join('\n') + '\n</div>'
}