# /v1/index.txt
# platform: 1
# updated: 2026-09-09

== Required reading ==

This index is a table of contents, not the documentation. Before writing any
code, fetch every file below and read each one in full, in this order. Do not
write from this index alone, from the summary embedded in a prompt, or from
memory of these docs: an app written that way fails the host's validation on
icon names, prop values and payload shapes, and every failure costs the user a
round trip.

1. https://aistudio.l13s.cc/v1/quickstart.txt
   One annotated app, then persistence, a list and a second tab.
2. https://aistudio.l13s.cc/v1/state.txt
   State model, action names, payload shapes, async natives, timers, onLoad.
3. https://aistudio.l13s.cc/v1/components.txt
   Every node type: props, defaults, allowed values, children rules.
4. https://aistudio.l13s.cc/v1/styling.txt
   The only color, font, weight and spacing values that exist.
5. https://aistudio.l13s.cc/v1/native.txt
   Native namespaces: signatures, payload shapes, limits.
6. https://aistudio.l13s.cc/v1/icons.txt
   The verified SF Symbol names. Every icon name in the file comes from here.
7. https://aistudio.l13s.cc/v1/checklist.txt
   Self-review list to complete as the last step before delivering.
8. https://aistudio.l13s.cc/v1/changelog.txt
   Dated additions and the minimum host build each one needs.

One-shot alternative: https://aistudio.l13s.cc/v1/full.txt holds this index,
the eight files above, the four optional category files and the examples in one
page (about 170 KB). Many fetch tools truncate or summarize a page that long.
If the copy you receive does not end with the See also list, it was cut off:
fetch the eight files above one by one instead. If full.txt (or this text)
reached you complete, every file is already in front of you; read each one
there in full rather than fetching.

Worked examples, complete and validated by the host:
https://aistudio.l13s.cc/v1/examples/01-counter.js
https://aistudio.l13s.cc/v1/examples/02-list-persistence.js
https://aistudio.l13s.cc/v1/examples/03-tabs-navigation.js
https://aistudio.l13s.cc/v1/examples/04-camera-assets.js
https://aistudio.l13s.cc/v1/examples/05-countdown-timer.js
https://aistudio.l13s.cc/v1/examples/06-picker-computed.js
https://aistudio.l13s.cc/v1/examples/07-remote-data.js
https://aistudio.l13s.cc/v1/examples/08-secure-backend.js
https://aistudio.l13s.cc/v1/examples/09-device-realtime.js
Read the one closest to the requested app before writing; read more when the
app combines their features.

== Extended capabilities ==

Seven more native namespaces are optional and live in four category files
under /v1/native/. They are not part of the required reading: fetch a
category file only when the app's scope needs one of its namespaces, read
it in full before using them, and skip it otherwise. Never declare a
capability the app does not use, and never use a namespace whose file you
have not read. Every extended function follows the rules in native.txt
(manifest declaration, { then, fail } for async calls, { error } on
failure).

network   https://aistudio.l13s.cc/v1/native/network.txt
          native.http, native.websocket: web APIs and your own backend over
          HTTPS, file downloads, live connections. Also required for
          Image { url } (remote images).
auth      https://aistudio.l13s.cc/v1/native/auth.txt
          native.auth, native.secrets: OAuth 2.0 sign-in with PKCE, a
          Face ID / Touch ID gate, user-entered API keys kept in the
          Keychain.
images    https://aistudio.l13s.cc/v1/native/images.txt
          native.assets and the Image url prop: inspect, list and remove
          stored assets, import base64 image data, save an asset to Photos.
device    https://aistudio.l13s.cc/v1/native/device.txt
          native.system, native.location: open https/mailto/tel links,
          locale and appearance info, a connectivity hint, a one-shot
          location fix.

Declaring "http" or "websocket" shows a network badge on the app; there is
no runtime consent prompt. HTTPS and WSS only. fetch() and XMLHttpRequest
do not exist.

== Overview ==

Micro-app platform, version 1. A micro app is a single JavaScript file that runs
inside a native iOS host app; the host renders the app's view tree as real
SwiftUI controls and gives it a small set of native capabilities. The file
declares a manifest, an init() function that returns the initial state, an
update() function that returns the next state for an action, and a view()
function that turns state into a tree of nodes built with h(). There is no DOM,
no module system and no build step: the only APIs are h(), the nodes listed in
components.txt, the tokens in styling.txt, the native namespaces in native.txt
and, when declared, the optional namespaces in the /v1/native/ category files,
console.*, and the timer functions. Network access exists only through
native.http and native.websocket, declared in the manifest. These documents are
the complete contract; anything not described in them does not exist on the
platform.

== Contract ==

const manifest = {
  platform: 1,                 // required, must be 1
  name: "Tally",               // required, shown in the library
  icon: "number",              // required, an SF Symbol name from icons.txt
  category: "Utilities",       // Utilities | Productivity | Health | Finance | Fun | Learning | Creativity |
                               // Food | Home | Travel | Social | Work | Developer | Media | Mindfulness | Other
  capabilities: ["store"],     // native namespaces the app uses; [] if none
};

function init() { return { count: 0 }; }                 // initial state, JSON-serializable
function update(state, action, payload) { return state; } // pure, synchronous, returns a NEW state
function view(state) { return h("Text", { text: "Hi" }); } // pure, returns exactly one root node
function onLoad(state) { return state; }                 // optional, runs once after init(), for native.store

Rules that always apply:
- Exactly one JavaScript file, ES2022 syntax, no imports, no exports, no JSX, no
  require(), no fetch() or XMLHttpRequest (network goes through native.http and
  native.websocket, declared in the manifest), no document, no window.
- h(type, props, children) builds nodes. type is a node type from components.txt.
  children is an array, a single node, or omitted. Text is never implicit: use
  h("Text", { text: "..." }).
- update() never mutates state; it returns a new object ({ ...state, x: y }).
- Every native.<namespace> the code touches must be listed in manifest.capabilities.
- native is not available at the top level of the file or inside init(); read the
  store in onLoad(state).
- Async natives (camera, photos, files.import, clipboard.read, and the extended
  http, websocket.connect, auth, secrets.prompt, assets.fromBase64,
  assets.saveToPhotos and location.current) take { then, fail } action names and
  dispatch their result later; update() stays synchronous.
- Every child of a ForEach carries a unique id prop.
- Every icon, symbol, toolbar icon and manifest.icon value is an SF Symbol name
  taken from icons.txt. A name that does not exist on iOS 26 fails validation
  and a name outside icons.txt is flagged; never invent a name or guess a
  variant beyond the .fill suffix that icons.txt describes.

== Output format ==

When an AI is asked to produce a micro app, the deliverable is the whole file in
one single fenced code block and nothing else:

  ```javascript
  const manifest = { ... };
  ...the entire file...
  ```

The block opens with a ```javascript line and closes with a ``` line. Nothing
goes outside it: no explanation before or after, no notes, no "here is your
app", no second code block and no partial snippets. The first line inside the
fence is "const manifest = {" and the last line closes the view() function or
the last helper. For a revision, deliver the complete revised file inside that
one block, not a diff.

== Files ==

Lookup guide for after the required reading: where to go back to while
writing. It is not a substitute for reading every file.

quickstart.txt   One annotated counter app, then persistence, a list and a
                 second tab added in three steps. The shapes to copy.
state.txt        State model: immutability, action and payload conventions, async
                 natives, timers, onLoad and persistence, the ForEach onDelete
                 contract, common mistakes.
components.txt   Every node type with props, defaults, allowed values, children
                 rules and examples. The only props and values that exist.
styling.txt      Color, font, weight and spacing tokens; padding and frame forms;
                 modifier order; dark mode; what is deliberately unavailable.
native.txt       The core native namespaces (store, haptics, clipboard, share,
                 camera, photos, files, date, toast): signatures, payload
                 shapes, limits; and the Extended capabilities pointer list.
native/          The four optional category files, fetched only when the scope
                 needs them: network.txt (http, websocket), auth.txt (auth,
                 secrets), images.txt (assets, Image url), device.txt (system,
                 location).
icons.txt        The verified SF Symbol names, grouped by purpose. The only
                 source for icon, symbol and manifest.icon values.
checklist.txt    Self-review list to run before delivering the file.
changelog.txt    Dated additive changes within platform 1 and the minimum host
                 build that supports each.
examples/        Complete validated apps:
                 01-counter.js, 02-list-persistence.js, 03-tabs-navigation.js,
                 04-camera-assets.js, 05-countdown-timer.js, 06-picker-computed.js,
                 07-remote-data.js, 08-secure-backend.js, 09-device-realtime.js
full.txt         All of the above in one file; see Required reading for when
                 to use it.

Where to look things up while writing, after reading everything once:
- A prop name, default or allowed value: components.txt.
- A token name: styling.txt.
- A payload shape or a then/fail flow: state.txt, then native.txt.
- An icon name: icons.txt, nowhere else.
- A native signature or limit: native.txt.
- A network, auth, asset, system or location signature: the category file
  under native/.
- Before delivering: checklist.txt, every item.

== Checklist ==

Run checklist.txt as the last step before delivering. Every item is checked by
the host's validator when the user pastes the file, so a miss costs a round
trip.

== Changelog ==

Platform 1 changes are additive and dated in changelog.txt together with the
minimum host build that supports them. Docs for platform 1 stay at /v1/ forever;
a breaking change would publish /v2/ and leave /v1/ online.

See also:
https://aistudio.l13s.cc/v1/index.txt
https://aistudio.l13s.cc/v1/quickstart.txt
https://aistudio.l13s.cc/v1/state.txt
https://aistudio.l13s.cc/v1/components.txt
https://aistudio.l13s.cc/v1/styling.txt
https://aistudio.l13s.cc/v1/native.txt
https://aistudio.l13s.cc/v1/icons.txt
https://aistudio.l13s.cc/v1/checklist.txt
https://aistudio.l13s.cc/v1/changelog.txt
https://aistudio.l13s.cc/v1/full.txt