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(...). Verify 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 is a positive inventory. A minimal static package follows this shape:

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

List only files the browser package needs. Do not include repository roots, credentials, private data, caches, or generated development evidence.

6. Verify the selected application

From the repository root:

npm run demo:check -- hello-arcane
npm run check

The selected demo check packages and verifies only this browser-context application. Review the generated dist/hello-arcane inventory; do not hand-edit it or describe it as a native or production release.

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 verification 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 and bounded.
• Focused tests and npm run check pass.
• Any deferred native, security, accessibility, or release work is stated accurately.

Related pages

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