Build your first Arcane application

This guide explains the smallest browser-context development path. It assumes you are an authorized contributor with a working private checkout. It does not register a native application or create a release.

Prerequisites

1. Complete Developer setup.
2. Read the Application-building SOP in full.
3. Choose a short lowercase application ID, such as hello-arcane.
4. Decide what the application lets a person do and which, if any, Arcane capabilities it needs.

1. Write the capability decision

Before creating files, answer:

1. What user-facing behavior is needed?
2. Could another Arcane application use the same mechanism?
3. Which wording, rules, routes, data, and workflow are specific to this application?
4. Can the reusable mechanism be separated through configuration, events, adapters, slots, providers, or record mapping?

Search arcane/components, arcane/modules, arcane/entities, arcane/css, example, and similar applications before adding a new implementation. Reuse or extend a compatible shared contract instead of copying it into your application.

2. Create the application surface

A small application normally contains:

apps/hello-arcane/
├── arcane-package.json
├── hello-arcane.css
├── index.html
├── manifest.json
└── modules/
    └── HelloArcaneApp.js

Keep application-specific labels, routes, policy, schema, and orchestration here. Put generally useful interaction, state, validation, or service behavior in the matching shared arcane/ layer.

3. Start from the Arcane theme

The document must establish the repository root as its URL base, then load shared layers before application styles. Without the base element, paths beginning with ./arcane/ would resolve beneath apps/hello-arcane/ and fail:

<base href="../../">
<link rel="stylesheet" href="./arcane/css/theme.css?v=1">
<link rel="stylesheet" href="./arcane/css/primitives.css?v=1">
<link rel="stylesheet" href="./apps/hello-arcane/hello-arcane.css?v=1">
<script type="module" src="./arcane/modules/ThemeBootstrap.js?v=1"></script>

Use Arcane theme variables for surfaces, text, actions, borders, focus, status, spacing, and radii. Write new literal colors with rgb(...) or rgba(...). Preserve light, dark, system, and saved user-theme behavior.

Use semantic HTML, labels, keyboard-operable controls, visible focus, useful empty and error states, and text alternatives from the first version.

4. Keep the module observable

Use named functions and callbacks so errors and stack traces identify the operation. Validate inputs and make failure visible. Do not call native tools directly from the page; use only declared Arcane application APIs available to the current host and application identity.

5. Declare the browser package

The package manifest declares the application's contents. A minimal static package follows this shape:

{
  "schemaVersion": 1,
  "id": "hello-arcane",
  "displayName": "Hello Arcane",
  "version": "0.1.0",
  "entry": "index.html",
  "strategy": "static",
  "security": {
    "connectOrigins": [],
    "frameOrigins": [],
    "mediaOrigins": []
  },
  "include": ["hello-arcane.css", "index.html", "manifest.json", "modules"],
  "exclude": [],
  "shared": ["browser-runtime"]
}

The current shared packager still requires the empty security record for schema-1 compatibility. It is temporary compatibility shape, not authorization for security or hardening; ordinary behavior keeps secure at its false default. List only files the browser package needs. Do not include repository roots, credentials, private data, caches, or generated development evidence.

6. Package the selected application

From the repository root:

npm run app:package -- hello-arcane

The command packages only this browser-context application under dist/hello-arcane. Do not hand-edit generated output or describe it as a native or production release. Run tests or checks only when the user explicitly requests them or a selected release artifact requires them.

7. Treat native registration as a separate boundary

Adding an application to a native machine bundle requires its own catalog, capability, packaging, host, and platform work. Do not infer native installation from a successful browser package.

Definition of done

• The capability decision is recorded.
• Shared behavior is reused or placed in arcane/; application policy remains in apps/hello-arcane/.
• Arcane theme and appearance preferences load in the required order.
• The interface is keyboard-operable and exposes meaningful errors and status.
• Every requested capability is declared.
• Content and results remain complete without app-owned caps or clipping.
• Any deferred native, accessibility, or release work is stated accurately.

Related pages

• Application packaging
• Developer command reference
• Code style
• Debugging