refactor: remove per-type module.py and simplify plugin wiring

docs/examples/item-type-sample/README.md

@@ -7,7 +7,6 @@ This is a reference layout for adding a new server item type plugin.
 - `definition.py`: static metadata/defaults/schema constants.
 - `validator.py`: `validate_update(item, next_params)` normalization and validation.
 - `actions.py`: `use_item(item, nickname, clock_formatter)` runtime behavior.
-- `module.py`: thin exported surface combining the three files.
 - `plugin.py`: registration payload consumed by plugin auto-discovery.
 
 Use this folder as a copy template when creating a real item under:

docs/examples/item-type-sample/module.py

@@ -1,20 +0,0 @@
-"""Counter item plugin module surface."""
-
-from __future__ import annotations
-
-from .actions import use_item
-from .definition import (
-    CAPABILITIES,
-    DEFAULT_PARAMS,
-    DEFAULT_TITLE,
-    DIRECTIONAL,
-    EDITABLE_PROPERTIES,
-    EMIT_RANGE,
-    EMIT_SOUND,
-    LABEL,
-    PROPERTY_METADATA,
-    TOOLTIP,
-    USE_COOLDOWN_MS,
-    USE_SOUND,
-)
-from .validator import validate_update

docs/examples/item-type-sample/plugin.py

@@ -2,10 +2,11 @@
 
 from __future__ import annotations
 
-from . import module
+from ..plugin_helpers import build_item_module
+from . import actions, definition, validator
 
 ITEM_TYPE_PLUGIN = {
     "type": "counter",
     "order": 25,
-    "module": module,
+    "module": build_item_module(definition, validate_update=validator.validate_update, use_item=actions.use_item),
 }

docs/item-schema.md

@@ -49,7 +49,7 @@
 
 - Persisted state stores only instance data.
 - Global/type-level properties are loaded from server registry in `server/app/item_catalog.py`.
-- Per-type use/update validation and message behavior are implemented in per-item modules under `server/app/items/types/*/module.py`, discovered via plugins in `server/app/items/types/*/plugin.py`.
+- Per-type use/update validation and message behavior are implemented in per-item modules under `server/app/items/types/*/definition.py`, `validator.py`, and `actions.py`, discovered via plugins in `server/app/items/types/*/plugin.py`.
 - Client-side add/edit metadata is consumed from `welcome.uiDefinitions` via `client/src/items/itemRegistry.ts` (no local fallback definitions).
 - End-to-end add-item template: `docs/item-type-template.md`.
 

docs/item-type-template.md

@@ -11,7 +11,6 @@ When adding a new item type:
   - `definition.py` for metadata/constants
   - `validator.py` for `validate_update(item, next_params)`
   - `actions.py` for `use_item(item, nickname, clock_formatter)`
-  - `module.py` as thin exported surface
   - `plugin.py` for registration
 
 2. Server plugin file
@@ -20,11 +19,9 @@ When adding a new item type:
   - `order`
   - `module`
 
-3. Shared item-type unions
-- Add the type in:
-  - `server/app/models.py`
-  - `client/src/network/protocol.ts`
-  - `client/src/state/gameState.ts`
+3. Shared type acceptance
+- Item type ids are string-based in protocol/state models.
+- For generic new types, no enum/union list updates are required.
 
 4. Client runtime behavior (optional)
 - Default: no item-specific client module needed.
@@ -34,14 +31,19 @@ That is enough for a first working item type.
 
 ## Reference Sample Folder
 
-See `docs/examples/item-type-sample/` for a complete copyable folder with all five files.
+See `docs/examples/item-type-sample/` for a complete copyable folder.
 
-## Minimal `module.py` Example
+## Minimal `plugin.py` Example
 
 ```py
-from .actions import use_item
-from .definition import LABEL, TOOLTIP, EDITABLE_PROPERTIES, CAPABILITIES, USE_SOUND, EMIT_SOUND, USE_COOLDOWN_MS, EMIT_RANGE, DIRECTIONAL, DEFAULT_TITLE, DEFAULT_PARAMS, PROPERTY_METADATA
-from .validator import validate_update
+from ..plugin_helpers import build_item_module
+from . import actions, definition, validator
+
+ITEM_TYPE_PLUGIN = {
+    "type": "counter",
+    "order": 25,
+    "module": build_item_module(definition, validate_update=validator.validate_update, use_item=actions.use_item),
+}
 ```
 
 ## Checklist Before Commit

docs/item-types.md

@@ -197,14 +197,12 @@ For a full copy/paste example with plain-English explanation, see `docs/item-typ
    - `definition.py` (defaults/capabilities/metadata/options)
    - `validator.py` (`validate_update`)
    - `actions.py` (`use_item`)
-   - `module.py` (thin exported surface)
 2. Server plugin: add `server/app/items/types/<item_type>/plugin.py` exporting `ITEM_TYPE_PLUGIN` with:
    - `type`
    - `order`
    - `module`
    The server auto-discovers plugins at boot, so no central registry edit is needed.
-3. Server models: extend `ItemType` literals in `server/app/models.py` and any packet enums that list item types.
-4. Client protocol/state types: update item-type unions in `client/src/network/protocol.ts` and `client/src/state/gameState.ts`.
+3. Server/client protocol/state models are now string-based for item type ids; for generic types no enum/union list updates are required.
 5. Client runtime behavior: add `client/src/items/types/<item_type>/behavior.ts` only if custom client runtime is needed (for example piano mode).
 6. Tests: add or update server tests under `server/tests/` for use/update validation, unknown-key stripping, and `uiDefinitions` completeness.