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

== 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 and the examples in one page (about 110 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
Read the one closest to the requested app before writing; read more when the
app combines their features.

== 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 network, 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, console.*, and the timer functions. These documents
are the complete contract; anything not described here 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(), 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) 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 native namespaces (store, haptics, clipboard, share, camera,
                 photos, files, date, toast): signatures, payload shapes, limits.
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
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.
- 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