name	Space Widgets
description	Create, patch, inspect, and remove widgets in the current space
metadata	{"placement":"system","when":{"tags":["space:open"]},"loaded":{"tags":["space:open"]}}

Use this skill for widget work in the current open space

storage

~/spaces//space.yaml = space meta + live layout
~/spaces//widgets/.yaml = widget meta + renderer
~/spaces//data/ and assets/ = widget-owned files
~/spaces//scripts/ = current-space shared JS modules loaded through context.import("scripts/...")

transient

Current Space Widgets in _____transient lists id|name|col|row|cols|rows|state|render status
Current Widget appears after patchWidget(), renderWidget(), or reloadWidget()
Current Widget is one envelope with rendered↓ for stripped live HTML and source↓ for the numbered readback

main helpers

listWidgets()
readWidget(id)
seeWidget(id, full=false)
patchWidget(id, { name?, cols?, rows?, col?, row?, metadata?, edits? })
renderWidget({ id, name, cols, rows, metadata?, renderer })
reloadWidget(id)
reposition(), removeWidget(...), removeWidgets(...), removeAllWidgets()
rearrangeWidgets(...), toggleWidgets(...), repairLayout(), rearrange(), reload(options?)

catalog and readback

Prefer space.current.* for widget work in the current open space
Current Space Widgets is the live layout summary. Use it before rediscovering ids manually
Use listWidgets() when you need the compact widget catalog. It returns: widgets (id|name|description)↓ example|Example|expanded, 4x3 widget
That catalog is plain text, not JSON. Do not expect widgets, items, or other object fields from it
If the user already named the target widget clearly, for example snake, tetris, or minesweeper, do not ask which widget. Read that widget directly by id or display name
On the next turn, read the visible id row directly, for example snake-game|Snake|... means use readWidget("snake-game")
Use that id for readWidget(), seeWidget(), patchWidget(), and reloadWidget(). Name is fallback only
readWidget() returns the numbered source directly in _____framework result↓
when widget YAML carries metadata, readWidget() includes a compact metadata: ... line before renderer↓
seeWidget() returns the current rendered widget HTML directly in _____framework result↓
seeWidget(id) strips script/style tags, inline handlers, class lists, ids, and data attrs by default
Use seeWidget(id, true) only when you explicitly need the full live innerHTML
Current Widget format after a write or reload↓ rendered↓

Hello

source↓ id: example name: Example cols: 4 rows: 3 renderer↓ 0 async (parent, currentSpace, context) => { 1 console.log("hello"); 2 }

Patch numbers come only from numbered renderer lines after renderer↓ inside source↓
Do not copy displayed line numbers into patch content
In prepared input, optional example turns may appear before live history, _____user = human, _____framework = runtime output, and _____transient = trailing current-space widget context

staged turns

listWidgets(), readWidget(), and seeWidget() are discovery calls. If the next step depends on them, end the execution there
If Current Space Widgets or _____framework already showed the widget id you need, skip another discovery call and move to the next step
After readWidget() or seeWidget(), patch on the next turn, not in the same JS block
After patchWidget(), renderWidget(), or reloadWidget(), use the refreshed Current Widget on the next turn if another edit is needed: rendered↓ for what mounted and source↓ for the next patch
Start every execution block with one short sentence saying the immediate step
Put that sentence on its own line. Then put _____javascript alone on the next line
Do not execute silently
Do not send only a staging sentence such as Checking widget source or Loading widget source. If you announce a widget read, list, patch, reload, or render step, the same message must execute it
After a successful patch or render that satisfies the request, stop and answer normally. Do not keep making more visual tweaks unless the user asked for another iteration or the runtime reported failure
After a successful patch or render, the next assistant turn should usually be the final user-facing answer. Do not output another promise line such as Updating... or Applying... without execution
Never answer with raw JS or a code fence after a widget error. Either send a proper execution message or a normal user-facing answer

examples Checking widget catalog _____javascript return await space.current.listWidgets()

Reading the widget source _____javascript return await space.current.readWidget("tetris-game")

Seeing the current rendered widget HTML _____javascript return await space.current.seeWidget("tetris-game")

After the catalog already showed snake-game, reading Snake source _____javascript return await space.current.readWidget("snake-game")

User asked for the snake widget, reading it directly _____javascript return await space.current.readWidget("snake")

bad Checking the current widget source

bad _____javascript return await space.current.readWidget("snake-game")

bad Which widget should I change?

bad const widgets = await space.current.listWidgets(); const snake = widgets.widgets.find(...)

bad return await space.current.readWidget("snake-game") return await space.current.patchWidget("snake-game", ...)

bad return await space.current.patchWidget("snake-game", ...) // success came back return await space.current.patchWidget("snake-game", ...)

bad Updating the snake widget background now Applying the color edits now

patch vs rewrite

Use patchWidget() for bounded edits to an existing renderer
Use renderWidget() for new widgets or full rewrites
patchWidget() is not a whole-renderer rewrite API. Do not use broad guesses like 0-999
Use name, cols, rows, col, row, and metadata for widget metadata changes. Use edits only for renderer lines
Preferred small-edit shape: [{ find, replace? }]
find must be one exact unique snippet copied from readWidget() output or from Current Widget source↓
Omit replace on a find edit to delete that snippet
Line-edit shape also works: [{ from, to?, content? }]
from and to are inclusive zero-based renderer line numbers
Omit to to insert before from
Omit content on a ranged line edit to delete
Common line aliases like line, startLine/endLine, range, text, and replace are tolerated, but prefer the canonical shapes above
Do not mix exact find edits and line edits in the same call
Do not overlap edits
The runtime applies edits from higher line numbers down to lower ones
If you build edits programmatically, parse the numbered renderer lines from readWidget() output or Current Widget source↓. Do not use widget.split("\n") array indexes as patch coordinates
If patchWidget() or renderWidget() says No files were written, the old widget file is still the source of truth. Fix and retry

example exact snippet patch _____javascript return await space.current.patchWidget("snake-game", { edits: [ { find: "parent.style.background = '#6f8f54';", replace: "parent.style.background = '#5f7f3f';" } ] })

write and reload behavior

readWidget() returns the numbered source readback
seeWidget() returns rendered HTML
patchWidget(), renderWidget(), and reloadWidget() return short status strings and refresh Current Widget in _____transient with both rendered↓ and source↓
Helpers also emit plain-text console status
Do not parse status strings. The execution output is enough
If a write or reload reports a render failure, keep fixing the widget from Current Widget source↓ before claiming success
Use reloadWidget(id) when you want an explicit rerun without changing source

renderer rules

Prefer async (parent, currentSpace, context) => { ... }
Render into parent
Use const mod = await context.import("scripts/utils.js") when several widgets need shared state, widget-to-widget communication, or other space-global functionality
context.import(...) resolves relative to the current space root, so copied or imported spaces keep working without hardcoded space ids, titles, or folder names
context.paths.scripts is the current space scripts folder
If several widgets need the same live shared state, import the same scripts/... module from each widget so they share one module instance on that space page
For very large or complex widgets, keep the renderer small and move substantial logic into scripts/*.js modules
If an imported module needs widget helpers or state, export functions that receive context instead of hardcoding globals or space ids
Do not add outer wrapper padding just to inset content. The widget shell already provides that spacing
Default widget card surface is #101b2d (rgba(16, 27, 45, 0.92)). Do not add another full-card background unless the content truly needs its own stage
Use light text and UI elements by default because widgets sit on that dark surface
For markdown-heavy output, use space.utils.markdown.render(text, parent)
If a widget should show a website, search page, URL, live web page, or browser-like surface that the agent may need to inspect or control, use <x-browser src="google.com"></x-browser> or create an x-browser element in DOM
Add controls="true" to x-browser only when the widget needs its own address bar and navigation controls; omit it or use controls="false" for a frameless embedded browser
Do not use <iframe> for general web browsing widgets. Iframes are not registered browser surfaces, so space.browser, injected browser actions, and last-interacted browser content will not work through them
Use an iframe only for a provider-specific embed that is intentionally not a controllable browser surface, such as a YouTube embed
For external HTTP reads, use fetch(url) or space.fetchExternal(url). Do not hardcode third-party CORS proxy services; the runtime already retries blocked origins through /api/proxy
Use space.proxy.buildUrl(url) only when you specifically need a same-origin proxied URL string for a non-fetch consumer
Max widget size is 24x24
Pick a reasonable size. Do not default to oversized cards
Return a cleanup function if you attach listeners, timers, or other long-lived effects
Do not patch unrelated page DOM
Do not use global plain-key listeners that interfere with chat. Require widget focus or use modified shortcuts

flow

listWidgets() if you need the live catalog
readWidget(id) for any existing widget you will change
seeWidget(id) only when you need the live rendered DOM rather than source
Next turn: patchWidget(id, ...) or renderWidget(...)
Next turn if needed: use the refreshed Current Widget, then continue