Fichiers communautaires GitHub, badges npm/CI et section Contributing

.github/CODE_OF_CONDUCT.md

@@ -0,0 +1,84 @@
+
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported privately to the maintainer by opening a [GitHub security advisory](https://github.com/pasquelin/map3D/security/advisories/new) — the project's only private channel. All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.1, available at [https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at [https://www.contributor-covenant.org/faq][FAQ]. Translations are available at [https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

.github/CONTRIBUTING.md

@@ -0,0 +1,112 @@
+# Contributing to map3d
+
+Thanks for taking the time. This page is the short version of what the project expects;
+the long version lives in [`CLAUDE.md`](../CLAUDE.md) and [`docs/ARCHITECTURE.md`](../docs/ARCHITECTURE.md).
+
+> 🇫🇷 Le code source, les commentaires et la JSDoc de ce dépôt sont **en français**.
+> La documentation utilisateur est bilingue (`docs/fr/` et `docs/en/`). Les issues et les PR
+> sont acceptées dans les deux langues.
+
+## 1. Before you open a pull request
+
+- **Open an issue first** for anything that changes the public API or adds a feature. The library
+  is a real-time rendering engine with a deliberate architecture — a well-meant patch that fights it
+  costs more to review than to write.
+- **Read the license.** map3d is published under [PolyForm Noncommercial 1.0.0](../LICENSE).
+  By contributing you agree that your contribution is licensed under those same terms and that the
+  copyright holder of the project remains Alban Pasquelin. Commercial use requires a separate license.
+
+## 2. Setting up
+
+The package manager is **pnpm** (see `pnpm-workspace.yaml`). Node **≥ 22.13**.
+
+```bash
+pnpm install
+pnpm dev:example      # runs examples/react — the live playground
+```
+
+The example reads `VITE_CESIUM_ION_TOKEN` from `examples/react/.env` to load Google
+Photorealistic 3D Tiles. Without a token it falls back to the built-in ellipsoid globe, which is
+enough for most work.
+
+## 3. Branching — `develop` is the integration branch
+
+`main` is the protected release branch; **features branch off `develop` and are merged back into
+`develop` by pull request**. Releases are cut from `main` by pushing a `vX.Y.Z` tag.
+
+One feature = one branch = **one git worktree**. The working tree *and the git index* are shared
+between sessions of the same clone, so two people (or two agents) working in the same folder will
+step on each other's staged files:
+
+```bash
+git worktree add ../map3D-feat-x -b feat/x develop
+cd ../map3D-feat-x
+# … commits on feat/x …
+git push -u origin feat/x        # → open a PR against develop
+git worktree remove ../map3D-feat-x
+```
+
+Stage by explicit path (`git add <path>`), never `git add -A`.
+
+## 4. The gate — `pnpm validate`
+
+One command has to be green before you push. CI replays exactly this on every PR:
+
+```bash
+pnpm validate
+```
+
+It runs, in order: `site:check` · `labels:doc:check` · `llms:check` · `licences:check` ·
+`typecheck` · `typecheck:example` · `lint` · `format:check` · `test`.
+
+Useful pieces on their own:
+
+| Command | What it does |
+| --- | --- |
+| `pnpm typecheck` | `tsc --noEmit` |
+| `pnpm test` | Vitest, jsdom, tests colocated as `src/**/*.test.ts` |
+| `pnpm exec vitest run src/core/fetchPolicy.test.ts` | a single test file |
+| `pnpm lint` / `pnpm format` | ESLint / Prettier |
+| `pnpm llms` | regenerates `llms-full.txt` from `docs/en/` |
+| `pnpm labels:doc` | regenerates the generated label tables in `LABELS.md` |
+
+## 5. House rules
+
+These are not stylistic preferences — a PR that breaks them will be sent back.
+
+- **Never guess.** Separate what you verified in the repo from what you assumed. If a source is not
+  there, ask rather than invent it.
+- **Everything is config.** No hard-coded value, no hard-coded string. Behaviour, colour, label and
+  threshold go through `config` / `theme` / `labels` or a prop.
+- **Full React on the host side.** The public API is components, props and hooks — never a forced
+  imperative access.
+- **`any` is a build error.** `strict`, `noUncheckedIndexedAccess`, `noUnused*` are on. Ignored
+  parameters are prefixed with `_`.
+- **`type`, never `interface`.**
+- **Prettier**: no semicolons, single quotes, `printWidth: 120`, `trailingComma: all`.
+- **Comments explain the *why*** — the trap, the constraint, the decision — never paraphrase code.
+- **Zero allocation in the frame loop.** Read (`update`) and write (`project`) passes stay separate;
+  don't break marker pooling.
+- **The "latest ref" pattern is deliberate** (~97 uses). Several React Compiler rules are disabled on
+  purpose in `eslint.config.js`. Do not "fix" those into React state.
+- **Public entry point is `src/index.ts`.** Anything the host must use is re-exported there.
+- **Every surface is mounted internally by `<Map>`** (`MapSurfaces.tsx`), never by the host app.
+  `children` of `<Map>` are reserved for host-specific overlays.
+
+## 6. A feature is not finished without
+
+1. **Docs in both languages** — `docs/fr/` *and* `docs/en/`, same file names, in the same commit.
+2. **`llms.txt` / `llms-full.txt` regenerated** (`pnpm llms`) whenever the English docs or the API move.
+3. **The example updated** — every new public API is wired into `examples/react/`.
+4. **`CHANGELOG.md`** — add your entry under `## [Non publié]`.
+5. **Tests** next to the code, `*.test.ts`.
+
+## 7. Commits and pull requests
+
+- One logical change per commit; write the message in French or English, in the imperative.
+- The PR description says **what** changes and **why**, and links the issue.
+- CI must be green. PRs are squash- or rebase-merged into `develop`; delete the branch afterwards.
+
+## Reporting a security issue
+
+Do **not** open a public issue — see [SECURITY.md](SECURITY.md).

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,72 @@
+name: 🐛 Bug report
+description: Something in the library behaves differently from what the docs say.
+title: '[bug] '
+labels: ['bug']
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for the report. 🇫🇷 Le français est bienvenu.
+
+        Please check the [documentation](https://github.com/pasquelin/map3D#readme) and the
+        [open issues](https://github.com/pasquelin/map3D/issues) first.
+        **Security issue? Don't post it here** — see [SECURITY.md](https://github.com/pasquelin/map3D/security/policy).
+  - type: textarea
+    id: what
+    attributes:
+      label: What happens
+      description: What you observed, and what you expected instead.
+    validations:
+      required: true
+  - type: textarea
+    id: repro
+    attributes:
+      label: Reproduction
+      description: >
+        Minimal steps, or the smallest `<Map>` / `MapEngine` snippet that shows it. A link to a fork
+        of `examples/react` is the fastest path to a fix.
+      render: tsx
+    validations:
+      required: true
+  - type: input
+    id: version
+    attributes:
+      label: map3d version
+      placeholder: '0.6.0'
+    validations:
+      required: true
+  - type: input
+    id: env
+    attributes:
+      label: Environment
+      description: React, three.js, browser, OS.
+      placeholder: 'React 19.1, three 0.170, Chrome 130, macOS 15'
+    validations:
+      required: true
+  - type: dropdown
+    id: basemap
+    attributes:
+      label: Basemap in use
+      options:
+        - Google Photorealistic 3D Tiles (Cesium Ion token set)
+        - Ellipsoid globe fallback (no token)
+        - Flat 2D — Google
+        - Flat 2D — self-hosted XYZ
+        - Not relevant
+    validations:
+      required: true
+  - type: textarea
+    id: logs
+    attributes:
+      label: Console output
+      description: Errors or warnings, if any. Redact your API keys.
+      render: shell
+  - type: checkboxes
+    id: checks
+    attributes:
+      label: Checks
+      options:
+        - label: I'm on the latest published version, or I checked the [CHANGELOG](https://github.com/pasquelin/map3D/blob/main/CHANGELOG.md).
+          required: true
+        - label: I searched the existing issues.
+          required: true

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,14 @@
+blank_issues_enabled: false
+contact_links:
+  - name: 📖 Documentation
+    url: https://github.com/pasquelin/map3D#readme
+    about: Guides and API reference, in English and French.
+  - name: 🕹️ Live demo
+    url: https://pasquelin.github.io/map3D/
+    about: Try the library in the browser before filing an issue.
+  - name: 🔒 Report a security vulnerability
+    url: https://github.com/pasquelin/map3D/security/advisories/new
+    about: Private disclosure — never open a public issue for a vulnerability.
+  - name: 💼 Commercial license
+    url: https://github.com/pasquelin/map3D/discussions
+    about: map3d is PolyForm Noncommercial; commercial use needs a separate license from the author.

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,48 @@
+name: ✨ Feature request
+description: Propose a new capability or an API change.
+title: '[feat] '
+labels: ['enhancement']
+body:
+  - type: markdown
+    attributes:
+      value: |
+        🇫🇷 Le français est bienvenu.
+
+        map3d is an imperative three.js engine driven declaratively by React, and **everything is
+        config**: no hard-coded value, no hard-coded string. Proposals that fit that grain get built
+        fastest — see [ARCHITECTURE.md](https://github.com/pasquelin/map3D/blob/main/docs/ARCHITECTURE.md).
+  - type: textarea
+    id: problem
+    attributes:
+      label: The problem
+      description: What are you trying to do that the library makes hard or impossible today?
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed API
+      description: What it would look like from the host app — props, config keys, theme or labels entries, hooks.
+      render: tsx
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: What you tried instead
+      description: Workarounds, other libraries, or why an existing option doesn't cover it.
+  - type: dropdown
+    id: area
+    attributes:
+      label: Area
+      options:
+        - Engine / camera / tiles
+        - Markers & clusters
+        - Drawing editor
+        - Relations & routing
+        - Symbols (MIL-STD-2525D)
+        - Search / lens / pedestrian
+        - Theme, labels or config
+        - React API (components, props, hooks)
+        - Documentation
+        - Other
+    validations:
+      required: true

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,25 @@
+## What and why
+
+<!-- What this changes, and the reason. Link the issue: Closes #123 -->
+
+## Type of change
+
+- [ ] Fix (no public API change)
+- [ ] Feature / API change — in `0.x` a minor version may break the API, documented in `CHANGELOG.md`
+- [ ] Documentation only
+- [ ] Internal (build, CI, tooling)
+
+## Checklist
+
+- [ ] Branched off **`develop`** and targeting `develop` (`main` is the release branch)
+- [ ] `pnpm validate` is green locally
+- [ ] Tests added or updated next to the code (`*.test.ts`)
+- [ ] Docs updated in **both languages** (`docs/fr/` **and** `docs/en/`)
+- [ ] `llms.txt` / `llms-full.txt` regenerated if the English docs or the API moved (`pnpm llms`)
+- [ ] New public API wired into `examples/react/`
+- [ ] `CHANGELOG.md` entry under `## [Non publié]`
+- [ ] No `any`, no hard-coded value or string (everything through `config` / `theme` / `labels` or a prop)
+
+## Screenshots / recording
+
+<!-- For anything visual. Before / after helps. -->